用 Claude Code 进阶 GitHub Actions：权限、OIDC、cache 与 matrix CI

GitHub Actions 做到“push 后运行测试”并不难。真正难的是：只给必要权限、避免旧提交浪费 CI 时间、让 cache 不复用过期依赖、部署时不暴露长期云密钥，并且把 Claude Code 的自动化限制在可审查的范围内。

这篇文章把 Claude Code 当作工作流设计助手，而不是简单的 YAML 生成器。下面的示例都是完整 GitHub Actions 文件，可以复制后按项目替换少量值。更重要的是，每个 job 都要能说明自己为什么需要这些权限、能读取哪些 secret、遇到 fork pull request 时会怎么处理。

本文参考了 GitHub 官方文档中的 workflow syntax、GITHUB_TOKEN permissions、AWS OIDC、dependency caching、concurrency，以及 Claude Code GitHub Actions。

设计全貌

进阶 GitHub Actions 不是把自动化堆得更多，而是把风险范围缩小。失败要能定位，权限要窄，旧任务要能取消，生产部署要保留人工确认。

flowchart LR
  PR["Pull request"] --> Gate["matrix test and lint"]
  Gate --> Cache["lockfile cache"]
  Gate --> Claude["Claude Code review"]
  Gate --> Deploy["OIDC deploy"]
  Deploy --> Env["GitHub environment approval"]
  Env --> AWS["AWS role"]

先解释几个术语。matrix 是“条件表”，例如用 Node.js 22 和 24 分别在 Ubuntu、Windows 上测试。OIDC 是 OpenID Connect，用短期身份令牌从 GitHub Actions 换取 AWS 等云服务的临时凭证，避免把长期 access key 放在 GitHub Secrets 里。concurrency 是同类任务的并发控制，可以取消旧提交上的检查。permissions 是 GITHUB_TOKEN 的权限清单。

具体场景

第一个场景是 pull request 质量门禁。lint、类型检查和测试在多个 Node.js 版本与操作系统上运行，可以提前发现 Windows 路径问题、Node 版本差异和 lockfile 漂移。

第二个场景是 staging 部署。main 通过后，GitHub Actions 通过 OIDC 承担一个 AWS IAM role，不使用静态 access key。生产环境再加 GitHub Environment 审批，避免自动化独自发布。

第三个场景是 monorepo 的共通检查。多个 package 重复 Node setup、install 和 test 时，用 reusable workflow 能防止十几个 YAML 中只有一个还停在旧 action 版本。

第四个场景是 Claude Code 辅助 PR review。开始时只让它读取差异并写 review comment，不要一上来就给自动修改和 push 权限。

给 Claude Code 的提示词

先让 Claude Code 说明约束，再让它写 YAML。

Design GitHub Actions for this repository.
The goals are pull request quality gates, staging deployment, and Claude Code review.

Constraints:
- Use least-privilege GITHUB_TOKEN permissions.
- Use OIDC for AWS. Do not store long-lived AWS access keys in Secrets.
- Include package-lock.json in dependency cache keys.
- Assume secrets are not available on forked pull requests.
- If pull_request_target is suggested, explain why PR head code is not checked out.
- Produce GitHub Actions YAML that is valid as written.

End with concrete failure cases and verification steps.

这样写的好处是，Claude Code 必须解释安全判断，而不是只给一份看似能运行的模板。

PR 质量门禁

下面使用 actions/checkout@v6 和 actions/setup-node@v6。截至 2026 年 6 月，这是当前主要版本。GitHub 托管 runner 通常可以直接使用；如果你们使用 self-hosted runner，要先确认 runner 版本满足这些 action 的要求。

name: pr-quality-gate

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: pr-quality-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: node-${{ matrix.node }}-${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [22, 24]

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

      - name: Test
        run: npm test

测试 job 只需要 contents: read。concurrency 会在同一分支有新提交时取消旧检查。cache 绑定到 package-lock.json，比直接缓存 node_modules 更稳，因为后者容易受操作系统和 native module 影响。

用 OIDC 部署到 AWS

安全做法是先在 AWS 中信任 GitHub OIDC provider，再创建权限很窄的 IAM role，并在 trust policy 中限制 repository、branch 或 environment。workflow 侧仍然需要 id-token: write，否则 GitHub 无法生成 OIDC token。

name: deploy-staging

on:
  workflow_dispatch:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

concurrency:
  group: deploy-staging
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    environment: staging

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/claude-code-github-actions-staging
          aws-region: ap-northeast-1

      - name: Verify caller identity
        run: aws sts get-caller-identity

      - name: Deploy
        run: |
          npm ci
          npm run build
          echo "Deploy command goes here"

请替换 role ARN、region 和部署命令。本番环境应使用独立 environment 和 required reviewers。

可复用工作流

如果多个 workflow 重复同一套 Node 检查，可以抽成 reusable workflow。它像共通函数，但 secret 不会自动全部传入，必须显式设计。

# .github/workflows/reusable-node-check.yml
name: reusable-node-check

on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "24"

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install
        run: npm ci

      - name: Check
        run: |
          npm run lint
          npm run typecheck
          npm test

调用侧如下。

# .github/workflows/ci.yml
name: ci

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  node-check:
    uses: ./.github/workflows/reusable-node-check.yml
    with:
      node-version: "24"

不要把真实差异硬塞进一个巨大 reusable workflow。如果不同 package 的 install 或 test 命令不同，让 Claude Code 区分“共通 setup”和“package 专属步骤”。

Claude Code PR 审查

Claude Code Action v1 使用 anthropics/claude-code-action@v1、prompt 和 claude_args。不要复制旧的 @beta 或 direct_prompt 示例。

name: claude-pr-review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Claude Code review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request as a senior engineer.
            Focus on security, broken tests, unnecessary permissions, and missing verification.
            Do not modify files. Leave concise review comments only.
          claude_args: |
            --max-turns 5

这个例子会跳过 fork PR，因为其中通常拿不到 repository secret。需要支持 fork 时，应设计一个不暴露 secret、也不以高权限运行外部代码的低信任流程。

常见失败

最危险的是在 pull_request_target 中 checkout PR head。这个事件更接近 base repository 的权限，如果直接运行外部 fork 的代码，就可能把 secret 和写权限暴露给不可信代码。

第二个失败是为了调试而打印 secret。GitHub 会 mask 很多精确 secret 值，但派生字符串、JSON 包装、base64 文本和第三方工具 debug log 不一定安全。给 Claude Code secret 名称和用途，不要给真实值。

第三个失败是 cache key 太宽。key: node-cache 这种固定 key 会在 lockfile 变化后继续复用旧依赖。使用 cache-dependency-path 或 hashFiles('**/package-lock.json')。

第四个失败是 matrix 膨胀。两个 OS 乘两个 Node 版本还合理；三个 OS、四个 runtime、八个 package 就是 96 个 job。PR 只跑代表组合，nightly 再跑大范围组合。

第五个失败是忽略 action major 更新。2026 年的官方 action 已陆续迁移到新的 Node runtime。使用 self-hosted runner 的团队，应该先升级 runner，再升级 workflow。

收益导线

更安全的 CI 会直接影响收入相关页面：落地页、付费模板、结账流程、课程内容和 lead form 都可以用更小的 PR 发布。个人开发者可以从免费 Claude Code cheatsheet开始。团队如果需要基于真实 repository 设计 permissions、OIDC、Claude Code review、branch protection 和 monorepo CI，可以使用 Claude Code 培训与咨询。

相关阅读：CI/CD pipeline setup、Git workflow、testing strategy、security best practices。

实测结果

本文把 MDX 中的 fenced YAML 示例提取出来，并用 YAML parser 做了语法检查。on、permissions、concurrency、matrix、reusable workflow、OIDC deployment 和 Claude Code Action v1 的结构都能被解析。实际运行前，请替换 AWS role ARN、npm scripts、environment 名称和 ANTHROPIC_API_KEY secret。