Claude Code CI/CD設定ガイド: GitHub Actionsで安全に自動化する

Claude Codeに「CI/CDを作って」と頼むだけなら、数分でYAMLは出てきます。問題は、そのYAMLが本番運用に耐えるかです。Pull RequestでSecretsを見せていないか、失敗したテストを無視していないか、デプロイが人間の承認なしに本番へ流れないか。ここを詰めないまま自動化すると、便利なはずのAIが事故の入口になります。

この記事では、Claude Codeを「YAML生成係」ではなく、CI/CD設計のレビュー相手として使います。CIは継続的インテグレーション、つまり変更のたびにlint、型チェック、テスト、ビルドを自動で確認する仕組みです。CDは継続的デリバリーまたはデプロイで、検証済みの変更を安全に環境へ届ける仕組みです。gateは「ここを通らないと次へ進めない条件」、SecretsはAPIキーなどの秘密情報、OIDCは長期キーを置かずに短命トークンでクラウドへ入る認証方式、と考えると理解しやすくなります。

公式情報は必ず確認してください。Claude Code Actionの現在の入力やv1移行はClaude Code GitHub Actions公式ドキュメント、GitHub Actionsの構文はWorkflow syntax、権限はGITHUB_TOKEN permissions、SecretsはGitHub Secrets reference、本番承認はDeployments and environmentsを基準にします。この記事の例は2026年6月3日時点で、GitHub-hosted runnerを前提にactions/checkout@v6とactions/setup-node@v6を使います。self-hosted runnerが古い場合は、先にrunnerバージョンを確認してください。

Claude Codeに渡すCI/CDの境界線

最初に決めるべきことは、どこまでをAIに任せ、どこからを人間が承認するかです。Claude Codeはリポジトリを読んで、ワークフローを編集し、失敗ログから修正案を出せます。ただし、Secretsの参照、本番デプロイ、権限拡張、pull_request_targetの利用、rollback判断は人間の責任で扱います。

おすすめの境界線は次の通りです。

領域	Claude Codeに任せること	人間が決めること
PRチェック	lint、型チェック、テスト、ビルドのYAML作成	必須チェック、対象ブランチ、merge条件
PRレビュー	差分のリスク指摘、テスト不足のコメント	修正採用、例外判断、承認
デプロイ	staging用workflow、環境変数名、rollback手順案	本番承認、Secrets登録、リリース可否
障害復旧	ログ分類、原因候補、再実行コマンド	rollback実行、顧客影響判断、事後対応

Claude Codeに依頼するときは、次のように安全条件を先に書きます。

このリポジトリのCI/CDを設計してください。
目的はPull Request品質ゲート、stagingデプロイ、Claude Codeレビュー、本番rollbackです。

制約:
- GITHUB_TOKENはjobごとに最小権限にする
- forkからのPull RequestではSecretsを使わない
- pull_request_targetを使う場合は、なぜPR headをcheckoutしないのか説明する
- 本番デプロイはGitHub Environmentのapprovalを通す
- ANTHROPIC_API_KEYやDEPLOY_TOKENをログに出さない
- 生成するYAMLはそのまま.github/workflows/に置ける形にする

最後に、想定される失敗例、検証コマンド、rollback手順も書いてください。

この依頼文の狙いは、Claude Codeを「作るモード」だけで走らせないことです。harness、つまりエージェントの足場として、権限、入力、禁止事項、検証方法を固定してから実装させます。CLAUDE.mdにチームのルールを書いておくとさらに安定します。詳しくはCLAUDE.mdベストプラクティスも合わせて読んでください。

ユースケース1: Pull Request品質ゲート

最初に作るべきCIは、PRごとの品質ゲートです。lint、型チェック、テスト、ビルドを通した変更だけをmainへ入れます。Node.jsのバージョン差で壊れることもあるため、ここではNode.js 22と24のmatrixを使います。matrixは条件表から複数jobを作る仕組みです。

# .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

このworkflowは、npm testとnpm run buildが存在する一般的なNode.jsプロジェクトならそのまま動きます。lintとtypecheckは--if-presentを付けているため、まだscriptがないプロジェクトでもCI全体は落ちません。ただし本番運用では、Claude Codeに「このリポジトリのpackage.jsonを見て、存在するscriptだけに合わせて整理して」と依頼し、不要な--if-presentを外す方が良いです。存在しない検証を通ったことにしてしまうのは、よくある落とし穴です。

テスト設計そのものはClaude Codeテスト戦略で扱っています。CIの役割はテストを賢くすることではなく、合格しない変更を止めることです。

ユースケース2: Claude CodeのPRレビューを安全に入れる

Claude Code ActionをPRレビューに入れると、変更範囲、テスト不足、Secrets露出、危険なGitHub Actions構文を自動で見つけやすくなります。ただし最初から自動修正まで任せる必要はありません。まずは「読んでコメントする」だけに絞ります。

# .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

ここで重要なのはgithub.event.pull_request.head.repo.full_name == github.repositoryです。forkからのPRではSecretsを渡さない前提にして、Claude Code Actionも走らせません。外部contributorのPRもレビューしたい場合は、Secrets不要の静的チェックと、人間が許可した後に動く別workflowに分けます。pull_request_targetは便利ですが、PR側の未信頼コードをcheckoutして実行すると危険です。Claude Codeに提案されたら、なぜ必要なのか、どのコードをcheckoutするのか、Secretsが見えるのかを必ず説明させてください。

権限を広げる前に、Claude CodeセキュリティベストプラクティスとGitワークフローで、branch protection、必須レビュー、差分確認の流れを固定しておくと安全です。

ユースケース3: stagingとproductionのデプロイゲート

次はCDです。mainへ入ったらstagingへ自動デプロイし、本番は手動実行か承認付きEnvironmentを通します。GitHub EnvironmentにSecretsを置くと、stagingとproductionで別のDEPLOY_TOKENを使えます。本番EnvironmentにRequired reviewersを設定すれば、workflowが勝手に本番へ進むことを防げます。

# .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時はstagingまで進みます。本番はworkflow_dispatchで手動実行したときだけ進みます。さらにproduction Environment側で承認者を設定しておけば、最終判断を人間に戻せます。小規模プロダクトでは、この設計だけでも「mainへmergeした瞬間に本番事故」という失敗を大きく減らせます。

落とし穴は、stagingとproductionで同じSecret名を使うこと自体ではありません。どのEnvironmentのSecretが読まれるかを理解せずに、repository secretへ全部入れてしまうことです。本番トークンはproduction Environmentにだけ置き、PR workflowから読めない場所に隔離してください。

ユースケース4: 失敗復旧とrollbackを先に作る

CI/CDは成功時の道だけ作っても不十分です。ビルドが壊れた、staging確認後にバグが見つかった、本番後にエラー率が上がった、というときに戻す手順が必要です。Claude Codeはログを読ませると原因候補を出してくれますが、rollbackを実行する権限は人間の手元に残します。

# .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

rollback workflowは「壊れたら戻せる」だけでなく、リリース前レビューにも効きます。Claude Codeに「このdeploy.ymlとrollback-production.ymlを読んで、rollback不能な依存、DB migration、キャッシュ破棄、環境変数差分を指摘して」と頼むと、見落としが減ります。障害時のログ整理はビルドエラー切り分けループが近いテーマです。

本番導入前のチェックリスト

CI/CDを導入するときは、workflowの完成度だけで判断しないでください。実務で効くのは、GitHub側の保護設定、Secretsの置き場所、失敗通知、rollbackの責任者まで含めた運用です。Claude CodeにはYAMLだけでなく、この運用表もレビューさせます。

まずbranch protectionを確認します。mainへ直接pushできる人を減らし、ci、claude-pr-review、必要ならE2Eやsecurity scanをrequired status checksにします。Claude Codeが作ったworkflowが緑でも、GitHub側で必須チェックに入っていなければ、mergeを止める力はありません。ここは初心者がよく見落とす点です。

次にSecretsのscopeを確認します。ANTHROPIC_API_KEYはClaude Code Action用、DEPLOY_TOKENはdeploy用です。役割が違うSecretを同じ名前で使い回すと、漏えい時の影響範囲が読みにくくなります。repository secretに置くもの、staging Environmentに置くもの、production Environmentに置くものを表にして、Claude Codeに「このSecretはどのworkflowから読めるか」を説明させると整理しやすくなります。

三つ目は通知です。CIが失敗しても誰も見なければ意味がありません。小さなチームならGitHubのrequired checkだけで始めても構いませんが、production deployの失敗、rollback workflowの実行、Claude Codeレビューの失敗は、Slackやメールなどチームが実際に見る場所へ通知する設計にします。通知が多すぎると無視されるため、PRごとのlint失敗とproduction deploy失敗を同じ重さで鳴らさないことも大切です。

四つ目はコストと実行時間です。Claude Code ActionはAPI利用コスト、GitHub Actionsはrunner分数を使います。全PRで重いE2Eを回すのではなく、PRではunit testとbuild、mainではstaging deploy、手動ではproductionとrollback、というように段階を分けます。Claude Codeにも--max-turnsを設定し、reviewの目的をCI/CD安全性に絞ると無駄な往復を減らせます。

最後に、運用開始前に一度だけ「わざと失敗させる」テストをします。lintを壊したPR、存在しないSecret、失敗するdeploy script、rollback対象SHAの入力ミスを試し、どのjobが赤くなるか、誰が気づくか、どのログをClaude Codeへ渡すかを確認します。本番障害のときに初めて失敗画面を見るチームは、復旧判断が遅れます。

Claude Codeにレビューさせる観点

CI/CDのレビューでは「YAMLが正しいか」だけを見ても足りません。Claude Codeには、差分、権限、Secrets、失敗時の人間の行動まで含めて確認させます。たとえば「このworkflowでproduction secretがPRから読める経路はあるか」「pull_request_targetを使わずに同じ目的を達成できるか」「rollback対象のcommitが古い依存でbuild不能になる可能性はあるか」「deployment approvalを回避できるpathはないか」といった質問です。

Masaが記事運用や小さなプロダクトで試した範囲では、Claude Codeは構文ミスの発見より、運用上の前提抜けを見つける用途で特に役立ちました。たとえば、build jobにはtimeoutがあるのにdeploy jobにはtimeoutがない、stagingとproductionで同じSecret名なのにEnvironmentが分かれていない、rollback workflowはあるが現在のproduction SHAを記録していない、といった地味な問題です。こうした問題はYAMLだけを眺めても見逃しやすいので、Claude Codeに「壊れた日の運用目線」でレビューさせる価値があります。

導入順序も大切です。最初の週はPR品質ゲートだけを必須にし、既存の失敗を洗い出します。二週目にClaude Codeの読み取りレビューを足し、コメントが多すぎる場合はpromptを絞ります。三週目にstaging deployを自動化し、productionはまだ手動のままにします。最後にEnvironment承認、production deploy、rollbackを追加します。この順番なら、CIが赤い理由、Claude Codeの指摘の質、deploy scriptの安定性を一つずつ確認できます。いきなり全部を入れると、どこで壊れたのか分からず、チームがCI/CDそのものを信用しなくなります。

もう一つの現実的な判断は、すべてをGitHub Actionsに入れないことです。大きなDB migration、外部決済の切り替え、DNS変更、顧客データを触る一括処理は、workflowから実行できても、最初はrunbookと人間のダブルチェックを残します。Claude Codeには「これは自動化してよい作業か、それとも手順書だけに留めるべきか」を質問します。自動化の目的は人間を消すことではなく、繰り返し作業を安定させ、危険な判断を見える場所へ出すことです。

この判断基準を先に置くと、便利さより安全性を優先した会話になり、導入後の手戻りも確実に減ります。

具体的な失敗例と対策

一つ目の失敗は、pull_request_targetでPRのコードをcheckoutしてしまうことです。このイベントはbase repositoryの権限で動くため、未信頼のコードとSecretsが近づきます。使うなら、PR本文やラベルの確認など、PR headを実行しない処理に限定します。

二つ目は、permissions: write-allを入れることです。動くかもしれませんが、壊れたときの影響範囲が広すぎます。最初はcontents: readだけにし、PRコメントが必要ならpull-requests: writeを足す、deployment作成が必要ならdeployments: writeを足す、という順にします。

三つ目は、Secretsをログに出すことです。echo $DEPLOY_TOKENのような確認は絶対にしません。Claude Codeにも「Secretsの値を表示しない。存在確認は変数名だけで行う」と明記します。

四つ目は、CIの失敗をClaude Codeに丸投げすることです。ログ全部を貼る前に、最初に失敗した行、直前のコマンド、再現コマンド、期待結果を渡す方が早く直ります。AIに広い自由を与えるほど賢くなるのではなく、原因候補を狭めるほど実務では役に立ちます。

ClaudeCodeLabでの収益化導線

CI/CD記事は収益化と相性が良いテーマです。読者は「試したい」だけでなく、「チームに入れて壊さず運用したい」と考えているからです。個人開発者はClaudeCodeLabの教材・テンプレートから、CLAUDE.md、レビューprompt、CIチェックリストを取り入れるのが始めやすいです。チームでGitHub Actions、Secrets、approval、rollback、Claude Codeレビューをまとめて設計したい場合は、Claude Code研修・相談で既存リポジトリを前提にした導入手順へ落とし込むのが現実的です。

内部リンクとしては、より高度なmatrix、OIDC、cache設計を扱うGitHub Actions高度化ガイド、テストの粒度を決めるテスト戦略、権限やSecretsの事故を防ぐセキュリティベストプラクティスを合わせると、CI/CD導入の流れが一通りつながります。

まとめ

Claude CodeでCI/CDを作る価値は、YAMLを書く時間を減らすことだけではありません。PR品質ゲート、Claude Codeレビュー、stagingデプロイ、本番承認、rollbackを一つの運用としてつなげることに価値があります。安全な自動化は「AIに任せる範囲」と「人間が止める範囲」を先に決めるところから始まります。

この記事で紹介した内容を実際に試した結果、もっとも効果があったのは、最初から本番デプロイを自動化することではなく、PR品質ゲートとClaude Codeの読み取りレビューを先に入れることでした。CIが赤いままの変更を止め、Claude Codeが権限やSecretsの違和感を早めに指摘するだけで、merge前の会話がかなり具体的になります。本番CDはその後で、Environment承認とrollbackを用意してから入れるのが堅実です。