action-validator 是一个独立的工具，用于对定义 GitHub Actions 和 Workflows 的 YAML 文件进行 "代码检查"。它通过检查它们与已发布的 JSON 架构，确保它们格式良好，并确保在 paths / paths-ignore 中使用的任何 glob 至少匹配 repo 中的一个文件。

action-validator 的预期用途是在 Git 预提交钩子等类似情况下。

安装

我们可以以多种方式安装 action-validator。

预构建的二进制文件

GitHub 发布版 中有一些预构建的二进制文件——只需下载并将它们放在您的路径中。如果您的平台没有可用的二进制文件，请告诉我，我会看看我能做什么。

使用 cargo

如果您已安装 Rust 工具链，则运行 cargo install action-validator 应该会为您提供最新版本。

使用 asdf

如果您是 asdf 工具 的支持者，则可以使用它来安装和管理 action-validator

asdf plugin add action-validator
# or
asdf plugin add action-validator https://github.com/mpalmer/action-validator.git

安装/配置 action-validator

# Show all installable versions
asdf list-all action-validator

# Install specific version
asdf install action-validator latest

# Set a version globally (on your ~/.tool-versions file)
asdf global action-validator latest

# Now action-validator commands are available
action-validator --help

使用 NPM

Node 用户可以使用 NPM 安装最新版本

ℹ️ @action-validator/core 包可以直接在 Node.js 应用程序中使用。

npm install -g @action-validator/core @action-validator/cli --save-dev

从仓库构建

如果您想本地构建，您需要

1. 在某个位置签出 git 仓库；

2. 通过运行 git submodule init && git submodule update 获取 SchemaStore 子模块；

3. 安装一个 Rust 工具链；然后

4. 运行 cargo build。

用法

非常简单：只需将文件传递给程序

action-validator .github/workflows/build.yml

使用 action-validator -h 查看更多选项。

注意

action-validator 的预期用途是在 pre-commit 钩子中，因此它假定它是在仓库根目录下运行的。如果您从仓库的子目录运行它，或者更糟糕的是，完全在仓库外部运行它，Glob 检查将会非常糟糕。

在 GitHub Action 中

action-validator 可以在 GitHub Action 中作为 pull request 作业运行。请参阅此存储库中的 actions 作业，在 QA 工作流程 中，作为如何在 GitHub 工作流程中使用 action-validator + asdf 的示例。这可能会显得有些冗余（毕竟，一个动作必须有效，GitHub 才能运行它），但这个作业将确保您所有其他动作也都是有效的。

使用 pre-commit

更新您的 .pre-commit-config.yaml

repos:
- repo: https://github.com/mpalmer/action-validator
  rev: v0.5.1
  hooks:
    - id: action-validator

Pre-commit 钩子示例

在目标仓库的 .git/hooks 目录中创建一个可执行文件： touch .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit 并粘贴以下示例代码

#!/bin/bash
if ! command -v action-validator >/dev/null; then
  echo "action-validator is not installed."
  echo "Installation instructions: https://github.com/mpalmer/action-validator"
  exit 1
fi
echo "Running pre-commit hook for GitHub Actions: https://github.com/mpalmer/action-validator"
scan_count=0
for action in $(git diff --cached --name-only --diff-filter=ACM | grep -E '^\.github/(workflows|actions)/.*\.ya?ml$'); do
  if action-validator "$action"; then
    echo "✅ $action"
  else
    echo "❌ $action"
    exit 1
  fi
  scan_count=$((scan_count+1))
done
echo "action-validator scanned $scan_count GitHub Actions and found no errors!"

此脚本将在对目标仓库的每次提交时运行，无论 github action yaml 文件是否被提交，如果存在 linting 错误，将阻止任何提交。

# All action-validator linting errors must be resolved before any commit will succeed.
$ echo "" >> README.md && git add README.md && git commit -m "Update read-me"
Running pre-commit hook for GitHub Actions: https://github.com/mpalmer/action-validator
Validation failed: ValidationState {
    errors: [
        Properties {
            path: "",
            detail: "Additional property 'aname' is not allowed",
        },
    ],
    missing: [],
    replacement: None,
}
❌ .github/workflows/ci.yaml
Fatal error validating .github/workflows/ci.yaml: validation failed


# Fix error and try again
$ echo "" >> README.md && git add README.md && git commit -m "Update read-me"
Running pre-commit hook for GitHub Actions: https://github.com/mpalmer/action-validator
✅ .github/workflows/ci.yaml
✅ .github/workflows/release.yml
action-validator scanned 2 GitHub Actions found no errors!
[main c34fda3] Update read-me
 1 file changed, 2 insertions(+)

NPM

如果您已经按照 NPM 安装说明 进行操作，您可以按如下方式运行 action validator CLI

npx action-validator <path_to_action_yaml>

或者，如果您已全局安装了该软件包

action-validator <path_to_action_yaml>

Node API

可以使用以下方式使用 Node API 验证 action 和 workflow 文件

⚠️ 目前 Node API 不支持 glob 验证。

import { readFileSync } from "fs";
import { validateAction, validateWorkflow } from "@action-validator/core";

// Validate Action
const actionSource = readFileSync("action.yml", "utf8");
const state = validator.validateAction(actionSource);
const isValid = state.errors.length === 0;

// Validate Workflow
const workflowSource = readFileSync("workflow.yml", "utf8");
const state = validator.validateWorkflow(workflowSource);
const isValid = state.errors.length === 0;

贡献

请参阅 CONTRIBUTING.md。

许可证

除非另有声明，否则本仓库中的所有内容均受以下版权声明保护

Copyright (C) 2021  Matt Palmer <[email protected]>

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License version 3, as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.