WordPress 编码标准

GitHub Actions 工作流规范

💡 云策文档标注

概述

GitHub Actions 工作流运行在权限较高的软件供应链环境中,可以访问仓库密钥、推送代码、创建发布、发布软件包并与外部服务交互,因此工作流文件中的安全弱点可能带来严重后果。WordPress 在 .github/workflows 目录中使用 Actionlint 与 Zizmor 两个互补的 lint 工具,帮助维护工作流文件的质量与安全。

关键要点

  • Actionlint 侧重正确性:语法校验、表达式类型检查、action 与可复用工作流的输入校验、shell 脚本语法检查等常见错误检测。它在 PR 和推送主干分支时运行,失败结果与单元测试、编码规范检查一样以 check 形式报告,检查失败必须先修复才能合并。
  • Zizmor 侧重安全:检测模板注入、权限过大、危险触发器、未固定版本的依赖、凭据持久化等数十种安全弱点。结果上报 GitHub Code Scanning(Security → Code Scanning 标签页,仅管理员可见);PR 中新引入的错误与警告会使 code scanning 检查失败,并在相关文件与行上给出内联标注;已有问题作为基线,修复或忽略前不影响新 PR。
  • 本地运行:两个工具均可通过各操作系统的包管理器或 Docker 镜像安装。在仓库根目录执行 actionlint 与 zizmor .(注意末尾的点);使用 GH_TOKEN=$(gh auth token) zizmor . 可启用在线审计(检查已知存在漏洞的 action 与仿冒提交)。本地报告的某些问题可能在仓库 Code Scanning 设置中被忽略,若本地发现的问题未出现在 Code Scanning 结果中,请确认其是否已被忽略。
  • 模板注入:不要把 ${{ }} 表达式直接写入 run: 块,因为表达式在脚本执行前即被解析,攻击者控制其值即可注入任意 shell 命令(加引号也无法防护)。应通过 env 传值,使其作为数据处理;在 actions/github-script 中同样通过 env + process.env 读取,而非在脚本体内使用模板表达式。
  • 危险触发器:pull_request_target 与 workflow_run 在基础仓库上下文中运行并可访问仓库密钥;若检出 PR 的 head ref 并执行其中代码,攻击者便能以密钥权限执行任意代码。除非工作流确实需要密钥才能对 PR 操作(如评论、管理标签),否则应避免使用;绝不检出 head ref 后运行其代码,确有必要时用行内注释说明该触发器在此上下文中为何安全。
  • 最小权限:每个工作流文件都应包含顶层 permissions: {} 声明不授予任何权限,再由各 job 声明其所需的特定权限;完全省略 permissions 声明并不够。
  • 凭据持久化(artipacked):actions/checkout 默认持久化凭据以便后续 git 操作认证,若检出目录被作为 artifact 上传或内容外泄,凭据会随之泄露。除同一 job 后续步骤确实需要认证的 git 操作(如推送提交)外,应始终设置 persist-credentials: false;确需持久化时显式设为 true 并附注释,以便意图清晰可审计。
  • 环境文件操纵:当输入受用户控制时,向 $GITHUB_ENV 或 $GITHUB_PATH 写入是危险的,攻击者可注入任意环境变量或向 PATH 前置路径。只写入完全由工作流控制的值,不得写入源自 PR 内容、issue 正文、提交信息等用户可控输入的值;确需处理用户输入时,先校验与清洗。
  • 未固定版本(unpinned uses):所有第三方 action 必须固定到完整 commit SHA,而非 tag 或分支(tag 可被移动或删除,导致引用悄然指向不同的、可能恶意的代码)。SHA 后应保留版本注释以便阅读,更新 action 时同时更新 SHA 与版本注释。
  • 缓存投毒:在生成发布产物的流程中使用 GitHub Actions 缓存存在风险,攻击者可在另一个工作流中投毒缓存,进而向发布内容注入恶意内容。构建并发布软件包或发布产物的流程应避免使用 actions/cache 或内置缓存;确有必要时,应严格收窄 cache key 并在使用前校验缓存内容。

代码示例

# 模板注入:通过 env 传值,使表达式作为数据而非代码
- name: Print title
  run: echo "Title: ${PR_TITLE}"
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}

# 最小权限:顶层空权限 + 各 job 按需声明
permissions: {}

jobs:
  lint:
    runs-on: ubuntu-latest
    permissions:
      contents: read

# 固定到完整 commit SHA,并保留可读的版本注释
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
  with:
    persist-credentials: false

📄 原文内容

GitHub Actions workflows operate in a highly privileged software supply chain environment. Workflows can access repository secrets, push code, create releases, publish packages, and interact with external services. A security weakness in a workflow file can have severe consequences.

WordPress uses two complementary linting tools to help maintain the quality and security of workflow files in the .github/workflows directory: Actionlint and Zizmor. This page documents the tools and how contributors should address errors or warnings that they report.

Actionlint

Actionlint is a static checker for workflow files. It focuses primarily on correctness: syntax validation, type checking for expressions, validation of inputs for actions and reusable workflows, syntax checking of shell scripts, and other common mistakes. See the Actionlint documentation for details.

Actionlint runs on pull requests and on pushes to the main branches on the wordpress-develop repo. It reports its findings as check results, just like the unit test and coding standards workflows. A failing Actionlint check must be fixed before the changes in the PR can be committed.

Zizmor

Zizmor is a security-focused linter for workflow files. It detects template injection vulnerabilities, excessive permissions, dangerous triggers, unpinned dependencies, credential persistence, and dozens of other security weaknesses. See the Zizmor documentation for details.

Zizmor also runs on pull requests and on pushes to the main branches on the wordpress-develop repo and reports its findings to GitHub Code Scanning. This means:

  • Results are available on the Security Code Scanning tab of the repo for users with administrative permission on the repo.
  • Errors and warnings that are newly introduced in a pull request will cause the code scanning check to fail. A “Code scanning results” status check will report failures, with inline annotations on the affected file and line.
  • Existing issues act as a baseline and won’t affect new pull requests until they are fixed or dismissed.

Running locally

If you’re making changes to workflow files in the .github/workflows directory, you can run both linting tools locally before pushing. Actionlint and Zizmor are both available via package managers for all operating systems, as well as via Docker images.

Running Actionlint

From the root of the repository, run:

actionlint

Running Zizmor

From the root of the repository, run (note the trailing period):

zizmor .

To enable the online audits that check for known-vulnerable actions and impostor commits, provide a GitHub token:

GH_TOKEN=$(gh auth token) zizmor .

Some findings that are reported locally may be suppressed in the repository’s Code Scanning settings. If you encounter a locally reported finding that does not appear in Code Scanning results, check whether it has been dismissed.

Addressing common security issues

The following sections cover common findings from Actionlint and Zizmor and how to address them.

For full information, consult the Actionlint documentation and the Zizmor documentation.

Template injection

Template injection occurs when a GitHub Actions expression such as ${{ github.event.issue.title }} is used directly within a run: block. GitHub Actions expressions are interpreted prior to running the script, therefore an attacker who controls the expression value can inject arbitrary shell commands, regardless of whether the expression is wrapped in quotes.

Bad:

- name: Print title
  run: echo "Title: ${{ github.event.pull_request.title }}"

Good:

- name: Print title
  run: echo "Title: ${PR_TITLE}"
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}

When the value is passed through an environment variable, it is treated as data rather than code, preventing injection.

For actions/github-script steps, pass values through the env block and access them via process.env instead of using template expressions in the script body:

Bad:

- uses: actions/github-script@...
  with:
    script: |
      const title = "${{ github.event.pull_request.title }}";

Good:

- uses: actions/github-script@...
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  with:
    script: |
      const title = process.env.PR_TITLE;

Dangerous triggers

The pull_request_target and workflow_run triggers run in the context of the base repository and have access to repository secrets. If a workflow triggered by pull_request_target checks out the pull request’s head ref and runs code from it, an attacker can execute arbitrary code with access to secrets.

  • Avoid pull_request_target or workflow_run unless your workflow genuinely needs access to repository secrets to operate on a pull request (for example, to comment on the PR or manage labels).
  • Never check out the pull request’s head ref (github.event.pull_request.head.ref) in a pull_request_target workflow and then run code from that checkout.
  • If pull_request_target or workflow_run is necessary, document the justification inline with a comment explaining why the trigger is safe in context.

Excessive permissions

Workflow and job permissions should follow the principle of least privilege. Every workflow file should include a top-level permissions: {} block that grants no permissions, with individual jobs declaring only the specific permissions they need. Omitting a permissions declaration entirely is not sufficient.

Bad:

permissions:
  contents: write

jobs:
  lint:
    # This job only reads code, it doesn't need write access.
    runs-on: ubuntu-latest

Good:

permissions: {}

jobs:
  lint:
    runs-on: ubuntu-latest
    permissions:
      contents: read

Artipacked credentials

The actions/checkout action persists credentials by default so that subsequent git operations can authenticate. If the checkout directory is later uploaded as an artifact (or its contents are otherwise exposed), the persisted credentials can be leaked.

Always set persist-credentials: false on actions/checkout unless subsequent steps in the same job genuinely need to perform authenticated git operations (such as pushing commits).

Good:

- uses: actions/checkout@...
  with:
    persist-credentials: false

If the job needs persistent credentials (for example, to push built files), set persist-credentials: true explicitly so the intent is clear and auditable and include an accompanying comment.

GitHub environment manipulation

Writing to $GITHUB_ENV or $GITHUB_PATH from a shell script is dangerous if the input is user-controlled, because an attacker can inject arbitrary environment variables or prepend to PATH.

  • Only write to $GITHUB_ENV or $GITHUB_OUTPUT with values that are fully controlled by the workflow, not with values derived from pull request content, issue bodies, commit messages, or other user-controllable inputs.
  • If you must process user-controllable input, validate and sanitize it before writing to these files.

Unpinned uses

All third-party actions must be pinned to a full commit SHA, not a tag or branch. Tags can be moved or deleted, meaning a tagged reference could silently point to different (potentially malicious) code in the future.

Bad:

- uses: actions/checkout@v6

Good:

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

Always include a version comment after the SHA to make the pinned version human-readable. When updating an action, update both the SHA and the version comment.

Cache poisoning

Using GitHub Actions caching in workflows that produce release artifacts is risky. A cache can be poisoned by an attacker in a separate workflow, allowing the poisoned cache to inject malicious content into a release.

Avoid using actions/cache or built-in caching features in workflows that build and publish packages or release artifacts. If caching is necessary in such workflows, ensure the cache key is scoped tightly and the cache contents are verified before use.