Claude CodeでGitHub Actionsを高度化する実践ガイド: 権限、OIDC、cache、matrix

GitHub Actionsは「pushしたらテストする」だけならすぐ作れます。難しいのは、PRごとの無駄な実行を止め、秘密情報を漏らさず、複数環境を確認し、デプロイだけは人間が判断できる形にするところです。

Claude Codeに「CIを作って」とだけ頼むと、動くけれど危ないYAMLが出ることがあります。だからこの記事では、Claude Codeをコード生成係ではなく、ワークフロー設計のレビュー相手として使います。初心者でもコピペで試せるGitHub Actions YAMLを置きながら、権限、OIDC、cache、matrix、concurrency、secretsの落とし穴をまとめます。

公式情報はGitHub Docsの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などに短期トークンで入る認証方式です。長期のAWS access keyをGitHub Secretsに置かずに済みます。concurrencyは同じ種類の実行を同時に走らせない制御です。permissionsはGITHUB_TOKENに与える権限の明細です。

Claude Codeに渡すときは、この4点を先に伝えます。

• PRでは読み取り中心にし、書き込み権限を必要なjobだけに限定する
• AWS deployはOIDCを使い、長期credentialを置かない
• cache keyはlockfileを含め、古い依存関係を使い回さない
• forkからのPR、pull_request_target、secrets表示をリスクとして扱う

具体的なユースケース

一つ目は、PR品質ゲートです。lint、type-check、unit testをNode.jsとOSの組み合わせで動かします。Windowsだけ壊れるpath処理、Node.js 24だけ出る警告、lockfileのズレを早めに見つけられます。

二つ目は、AWS staging deployです。mainに入ったらAWS IAM roleをOIDCで引き受け、手元のaccess keyを使わずにデプロイします。本番はGitHub Environmentのapprovalを挟むと、AIや自動化が勝手に公開する事故を減らせます。

三つ目は、monorepoの共通チェックです。複数packageで同じNode setup、install、testを繰り返すなら、reusable workflowに切り出します。コピペしたYAMLが10個に増えると、1個だけ古いsetup-nodeが残るような運用事故が起きます。

四つ目は、Claude CodeによるPRレビュー補助です。Claude Code Actionをすべての権限付き自動修正に使うのではなく、最初は「差分を読み、危険な箇所をコメントする」役割に絞るのが実務では安全です。

Claude Codeへの依頼文

Claude Codeには、いきなりYAMLを書かせるより、まず制約を明文化させます。

このrepositoryのGitHub Actionsを設計してください。
目的はPR品質ゲート、staging deploy、Claude Codeレビューです。

制約:
- GITHUB_TOKENは最小権限にする
- AWSはOIDCを使い、長期access keyをSecretsに置かない
- cache keyはpackage-lock.jsonを含める
- fork PRではsecretが使えない前提で設計する
- pull_request_targetを使う場合は、PR headをcheckoutしない理由を説明する
- 生成するYAMLはGitHub Actionsでそのまま使える構文にする

最後に、想定される失敗例と確認コマンドも書いてください。

この依頼文は「作って」ではなく「制約を守って設計して」と言っています。Claude Codeは便利ですが、secretsやdeploy権限の責任は人間に残ります。

PR品質ゲート

まずは通常のPull Requestで使う品質ゲートです。actions/checkout@v6とactions/setup-node@v6は2026年6月時点の新しいmajorです。GitHub-hosted runnerならそのまま使えますが、self-hosted runnerでは対応runner versionが必要です。古いrunnerを使っているチームは、いきなりv6へ上げず、runner更新を先に確認してください。

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

ポイントはpermissions: contents: readです。テストだけならrepositoryへの書き込み権限は不要です。concurrencyは同じbranchにpushし直した古いPRチェックを止めます。matrixのfail-fast: falseは、1つ失敗しても他のOSやNode.jsの結果を見たいときに向いています。最短で止めたいprojectならtrueにします。

cacheはpackage-lock.jsonに紐づけています。node_modulesを丸ごとcacheすると、OS差やpostinstallの副作用で壊れることがあります。npmならsetup-nodeのcache: npmから始めるほうが保守しやすいです。

OIDCでAWSへ安全にdeployする

次はstaging deployです。GitHub Docsでは、AWSにGitHubのOIDC providerを登録し、IAM roleのtrust policyでtoken.actions.githubusercontent.com:subを絞る構成が案内されています。workflow側だけを貼ってもAWS側のtrust policyが広いと危険なので、repository、branch、environmentを条件に入れてください。

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"

ここでid-token: writeはOIDC tokenを取得するためだけの権限です。repositoryへ書き込める権限ではありません。一方でcontents: readはcheckoutに必要です。Deploy command goes hereは、CDKならnpx cdk deploy、SAMならsam deploy、ECSならimage pushとservice updateに置き換えます。

失敗例は二つあります。id-token: writeを忘れると、AWS認証前にtoken取得で落ちます。逆に、contents: writeやactions: writeを雑に付けると、deploy jobが不要な権限まで持ちます。Claude Codeが広い権限を出してきたら「各permissionが必要な理由を1行ずつ説明して」と追加で聞きます。

Reusable workflowで重複を減らす

同じNodeチェックを複数workflowで使うなら、reusable workflowにします。これは「共通関数」のようなものです。ただしsecretsは自動では全部渡りません。必要な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"

この形にしておくと、setup-nodeのmajor更新やcache方針の変更を1ファイルで済ませられます。反対に、packageごとにinstall commandが違うmonorepoでは、無理に1つへまとめると条件分岐だらけになります。Claude Codeには「共通化すべき部分と、packageごとに残す部分を分けて」と依頼すると判断が安定します。

Claude Code ActionをPRレビューに使う

Claude Code Action v1ではanthropics/claude-code-action@v1とprompt、claude_argsを使います。古い@betaやdirect_prompt前提の記事をコピペしないでください。以下はfork PRではskipし、同一repository内のPRだけで動かす例です。

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

pull-requests: writeとissues: writeはコメントに必要になることがあります。レビューだけならcontents: writeは不要です。自動修正まで任せる場合は、別workflowに分け、branch保護、required review、Environment approvalを組み合わせます。

よくある失敗と対策

一つ目の失敗は、pull_request_targetでPRのheadをcheckoutすることです。pull_request_targetはbase repositoryの権限やsecretに近づきやすいため、外部forkのコードをそのまま実行すると危険です。使うなら、ラベル付けやコメントなど、信頼できないコードを実行しない用途に限定します。

二つ目は、secretsをlogで確認することです。GitHubはsecret値をmaskしますが、加工した文字列、JSONに埋めた値、base64化した値、外部ツールのdebug logまでは安全とは限りません。Claude Codeにsecretの値を渡さず、secret名と用途だけを渡します。

三つ目は、cache keyが広すぎることです。key: node-cacheのような固定keyは、依存関係が変わっても古いcacheを使う原因になります。hashFiles('**/package-lock.json')やcache-dependency-pathでlockfileを含めます。

四つ目は、matrixを増やしすぎることです。OS 3種、Node 4種、package 8個で96 jobになります。PRでは代表環境だけ、本番前のnightlyで広く回すなど、費用と速度を分けます。

五つ目は、action majorを古いまま放置することです。2026年時点では多くの公式actionが新しいNode runtimeへ移っています。self-hosted runnerを使う会社では、workflow更新よりrunner更新が先です。

収益導線とチーム導入

GitHub Actionsの整備は、単なる開発者体験の改善ではありません。CIが早く安全になると、記事更新、教材販売ページ、SaaSの課金導線、問い合わせフォームの修正を小さく出せます。広告や商品リンクがあるサイトほど、壊れたdeployや漏れたsecretは収益に直撃します。

個人で始めるならClaude Code無料チートシートで日常コマンドを固めてください。チームでpermissions、OIDC、Claude Codeレビュー、branch保護、monorepo CIをまとめて設計したい場合は、Claude Code研修・導入相談で実際のrepositoryを前提に整えられます。関連して、基礎から見直すならCI/CDパイプライン構築、Git運用はGitワークフロー実践ガイド、テスト方針はテスト戦略ガイド、権限と秘密情報はセキュリティ対策ガイドも合わせて読むと流れがつながります。

この記事で実際に試した結果

この記事のYAMLは、MDX内のcode fenceから取り出してYAML parserで構文確認しました。on、permissions、concurrency、matrix、reusable workflow、OIDC deploy、Claude Code Action v1の形はGitHub Actionsの構文として読めることを確認しています。実運用では、AWS role ARN、npm scripts、GitHub Environment名、ANTHROPIC_API_KEYの登録状況だけはrepositoryごとに置き換えてから実行してください。