Claude Code CI/CD 设置：用 GitHub Actions 安全自动化

让 Claude Code 生成一个 CI/CD workflow 很容易，难的是让它适合真实项目。好的流水线不只是“能跑”。它必须在 Pull Request 阶段挡住坏代码，不把 Secrets 暴露给 fork，不让生产环境在无人确认时自动发布，并且在失败时有清楚的回滚路径。

这篇文章把 Claude Code 当作 CI/CD 设计伙伴，而不是单纯的 YAML 生成器。CI 是持续集成，也就是在代码变化时自动运行 lint、类型检查、测试和构建。CD 是持续交付或部署，把已经验证的代码送到 staging 或 production。gate 可以理解为“必须通过的关卡”。Secrets 是 API key、部署 token 等敏感值。OIDC 是用短期身份令牌访问云服务的方式，可以避免把长期云密钥放进 GitHub Secrets。

落地前请对照官方文档：Claude Code 的 action 用法看 Claude Code GitHub Actions，GitHub Actions 语法看 workflow syntax，权限看 GITHUB_TOKEN permissions，Secrets 看 GitHub Secrets，生产审批看 GitHub Environments。下面的例子按 2026-06-03 的状态使用 GitHub-hosted runner、actions/checkout@v6 和 actions/setup-node@v6。如果你用 self-hosted runner，先确认 runner 版本。

先定义安全边界

不要先问 Claude Code “帮我写 CI/CD”。先告诉它什么可以自动化，什么必须由人决定。Claude Code 可以读仓库、生成 workflow、分析失败日志、提出修复建议。它不应该自己扩大 token 权限、决定生产发布策略、打印 secret、或者在有权限的事件里执行未信任 PR 代码。

区域	适合交给 Claude Code	人类负责
PR 检查	lint、测试、类型检查、构建 workflow	必须通过的检查和 merge 规则
PR review	指出 risky diff、测试缺口、权限问题	是否接受修改
部署	staging/production workflow 草稿	审批策略、Secrets 范围
故障恢复	日志总结、原因候选、回滚步骤	是否真正 rollback

可以先用这样的 prompt：

Design CI/CD for this repository.
The goals are pull request quality gates, staging deployment, Claude Code review, and production rollback.

Constraints:
- Use least-privilege GITHUB_TOKEN permissions per job.
- Do not use secrets on forked pull requests.
- If pull_request_target is suggested, explain why PR head code is not checked out.
- Put production deployment behind a GitHub Environment approval.
- Never print ANTHROPIC_API_KEY, DEPLOY_TOKEN, or other secret values.
- Produce workflow YAML that can be placed under .github/workflows/.

End with failure cases, verification commands, and rollback steps.

这个 prompt 的作用是给 agent 一个 harness，也就是安全的工作框架。项目里最好把同样的规则写进 CLAUDE.md，并结合 CLAUDE.md best practices 固定团队习惯。

用例一：Pull Request 质量门禁

第一个 workflow 应该挡住未验证的 PR。这个例子会运行 lint、typecheck、test 和 build，并用 Node.js 22/24 的 matrix 检查运行时差异。

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

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

permissions:
  contents: read

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

jobs:
  test:
    name: test-node-${{ matrix.node-version }}
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        node-version: [22, 24]
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm

      - run: npm ci
      - run: npm run lint --if-present
      - run: npm run typecheck --if-present
      - run: npm test -- --runInBand

  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: test
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run build

典型 Node.js 项目只要有 npm test 和 npm run build 就能直接跑。lint 和 typecheck 用了 --if-present，适合第一步导入。但长期来看，不要让“缺少测试脚本”被静默跳过。让 Claude Code 读取 package.json，把最终门禁改成明确存在的脚本。测试策略可以继续看 Claude Code testing strategies。

用例二：只读的 Claude Code PR review

Claude Code Action 可以帮助审查 PR：GitHub Actions 权限是否过宽、Secrets 是否可能暴露、测试是否缺失、是否改了不相关文件。第一版建议只让它评论，不让它自动修改。

# .github/workflows/claude-pr-review.yml
name: claude-pr-review

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

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

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    if: >
      github.event.pull_request.draft == false &&
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          prompt: |
            Review this pull request as a CI/CD safety reviewer.
            Focus on GitHub Actions permissions, secrets exposure, test coverage,
            deployment gates, rollback risk, and unrelated file changes.
            Do not edit files. Leave concise review comments with evidence.
          claude_args: |
            --max-turns 4

这里的 fork guard 很重要：github.event.pull_request.head.repo.full_name == github.repository 会阻止带 secret 的 workflow 在外部 fork 上运行。如果需要检查外部贡献者 PR，请拆成不需要 Secrets 的静态检查，以及人工批准后才运行的特权 workflow。pull_request_target 更要谨慎，因为它在 base repository 权限下运行。遇到这种建议时，要求 Claude Code 说明为什么需要、checkout 哪份代码、Secrets 是否可见。

权限和 review 流程可以结合 Claude Code security best practices 与 Claude Code Git workflow 一起设计。

用例三：staging 和 production 部署门禁

比较安全的 CD 起点是：main 自动部署到 staging，production 需要手动触发，并通过 GitHub Environment approval。生产 Secrets 放在 production Environment，不要放在所有 workflow 都能接近的 repository secret。

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

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  deployments: write

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build

  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: staging
    env:
      APP_ENV: staging
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run deploy:staging

  deploy-production:
    if: github.event_name == 'workflow_dispatch'
    needs: deploy-staging
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: production
    env:
      APP_ENV: production
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run deploy:production

push 到 main 时只到 staging；production 只有 workflow_dispatch 才会继续。如果 production Environment 设置了 required reviewers，最终发布会回到人类审批。这样能避免“merge 后直接把 bug 发到客户面前”的常见事故。

用例四：先写回滚 workflow

CI/CD 必须有失败路径。上线后才写 rollback 通常太晚。下面的 workflow 让维护者手动输入要重新部署的 commit SHA，并通过 production Environment 审批。

# .github/workflows/rollback-production.yml
name: rollback-production

on:
  workflow_dispatch:
    inputs:
      target_sha:
        description: "Commit SHA to redeploy to production"
        required: true
        type: string

permissions:
  contents: read
  deployments: write

jobs:
  rollback:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment: production
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.target_sha }}

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run build
      - run: npm run deploy:production

把 deploy.yml 和 rollback workflow 一起交给 Claude Code review，重点问：旧 commit 是否还能构建、数据库 migration 是否可逆、staging 和 production 的环境变量是否不同、当前线上 SHA 是否可追踪。失败日志整理可以参考 build error triage loop。

常见坑

第一，permissions: write-all。它会让 workflow 更容易“跑通”，也会让事故半径变大。先从 contents: read 开始，只给 job 能解释清楚的权限。

第二，打印 Secrets。不要为了调试执行 echo $DEPLOY_TOKEN。存在性检查只看变量名和 scope，不看值。

第三，假门禁。--if-present 适合迁移第一天，不适合永远留着。最终 CI 应该明确失败，而不是悄悄跳过。

第四，把整段日志丢给 Claude Code。更好的输入是：第一个失败命令、第一条关键错误、期望行为、本地复现命令。范围越窄，修复越可靠。

变现和下一步

CI/CD 是很适合 ClaudeCodeLab 变现的主题，因为读者通常已经有真实风险：发布、Secrets、团队 review、rollback。个人开发者可以从 ClaudeCodeLab products 取用可复用的 CLAUDE.md、review prompt 和 CI checklist。团队如果要围绕真实仓库设计 branch protection、GitHub Actions、Secrets、审批策略和 Claude Code review，可以从 training and consultation 开始。

下一步建议阅读 Advanced GitHub Actions with Claude Code、testing strategies 和 security best practices。我的实际经验是，先上线 PR quality gate 和只读 Claude Code review，比一开始就做全自动 production deploy 更稳。等团队能读懂失败、处理 review，再加 staging、production approval 和 rollback。