Claude CodeのGitHub Actionsを組織に導入 — Appとシークレットを一括設定

クイックセットアップも手動セットアップも、設定できるのは1リポジトリずつです。数十のリポジトリがある組織でGitHub Appのインストールとシークレット登録を繰り返すと、手間がかかるうえに、ローテーション漏れの温床にもなります。

組織展開で動かすのは3つの単位です。GitHub Appのインストール、認証情報の置き場所、ワークフローファイルの配り方を、リポジトリ単位から組織単位へ引き上げます。この中で選択を誤ると後から直しにくいのは、2つ目の認証情報です。先に認証方式の選び方から見ます。

前提として、GitHub組織のオーナー権限(GitHub Appのインストールと組織シークレットの追加ができる権限)が必要です。単一リポジトリでの動作確認がまだなら、先にClaude CodeをGitHub Actionsに組み込むでワークフロー自体の挙動を確かめてください。展開後に問題が出たとき、原因が組織設定なのかワークフローなのかを切り分けやすくなります。

Claude GitHub Appとclaude-code-actionの関係

検索でよく並ぶ「Claude GitHub App」と「claude-code-action」は別物です。

• Claude GitHub App: GitHubに入れるアプリ。リポジトリの読み書きをClaudeに許す窓口で、組織またはリポジトリにインストールします
• claude-code-action(anthropics/claude-code-action): ワークフローから呼ぶGitHub Action。Claude Codeをジョブの中で動かします

GitHub Appは組織で1回、ActionはリポジトリごとにワークフローとしてClaudeを呼びます。組織への入れ方は手順1にあります。

1リポジトリへの入れ方と/install-github-appの手順はClaude GitHub Appのインストール手順にあります。ここでは組織単位で入れる場合を扱います。なお/install-github-appが使えるのはgithub.comのリポジトリだけです。

組織で共有する認証方式はどれを選ぶか

組織で使える認証情報は3種類あります。違いは「誰の枠で動くか」と「静的な秘密を保存するか」です。

OAuthトークンはPro・Max・Team・Enterpriseのプランで使えます。個人の手元でCLIを動かす検証には便利ですが、組織の共有シークレットにするとジョブの認証がその1人のサブスクリプションに依存します。組織で共有するなら、APIキーかfederationの二択と考えると迷いません。

手元のClaude Code v2.1.287でclaude setup-token --helpを実行すると、説明は次の1行でした(claude --helpにも同じコマンドが並びます)。

claude setup-token --help

Usage: claude setup-token [options]
 
Set up a long-lived authentication token (requires Claude subscription)
 
Options:
  -h, --help  Display help for command

説明に「Claude subscriptionが必要」とあるとおり、このトークンはサブスクリプションを前提にしたものです。APIキーを組織で使う場合、この手順は通りません。

手順1: Claude GitHub Appを組織にインストールする

Claude GitHub Appは、リポジトリの画面ではなく組織のインストール画面から追加します。対象は「すべてのリポジトリ」か「選択したリポジトリの一覧」のどちらかです。新しいリポジトリを自動的に含めたいなら全体、対象を明示的に管理したいなら一覧にします。

インストール後も、組織の設定画面から対象リポジトリをいつでも増減できます。ここで済むのはGitHub Appの認証範囲を組織でそろえるところまでで、ワークフローファイルはリポジトリごとに置く必要があります。

手順2: 認証シークレットを組織で1回だけ登録する

APIキーを組織レベルのActionsシークレットとして登録すれば、各リポジトリへのコピーは要りません。画面からでもGitHub CLIでも登録できます。

GitHub CLIのgh secret set --orgは、可視範囲を指定しないとprivateリポジトリだけに公開されます。全リポジトリに見せるなら--visibility all、特定のリポジトリだけなら--reposで挙げます。

gh secret set --org your-org ANTHROPIC_API_KEY --repos repo-a,repo-b

--reposはカンマ区切りで、ghのマニュアルの例(--repos repo1,repo2,repo3)と同じ書き方です。公開リポジトリでもClaudeを動かす場合は、可視範囲が既定のままだと届かない点に注意が要ります。

前提も2つあります。GitHub Freeの組織では、組織シークレットをprivateリポジトリから使えません。また、ghで組織シークレットを扱うには、admin:orgスコープの追加認可が要ります(gh auth login --scopes "admin:org")。

公式のクイックセットアップを使った場合は、Claude Codeがすでに持っているAPIキーを再利用し、リポジトリにANTHROPIC_API_KEYシークレットがあれば残すかどうかを尋ねる動きになります。組織展開では、この「リポジトリごとのシークレット」が個別コピーとして残らないよう、あとで組織シークレットに一本化する前提で扱います。

手順3: ワークフローをどう配るか

ワークフローファイルは、組織シークレットのようには共有されません。配り方は2通りです。

再利用可能なワークフローを作るときは、呼び出される側にworkflow_callを宣言し、受け取るシークレットを書きます。ここを書き忘れると、呼び出し側から渡しても受け取れません。

on:
  workflow_call:
    secrets:
      anthropic_api_key:
        required: true
 
jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.anthropic_api_key }}

各リポジトリ側のファイルは、数行になります。

name: Claude
on:
  issue_comment:
    types: [created]
 
jobs:
  claude:
    uses: your-org/shared-workflows/.github/workflows/claude-review.yml@main
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    secrets:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

呼び出し側にもpermissionsを書いているのには理由があります。GitHubのドキュメントは、再利用可能なワークフローの連鎖では権限を維持するか減らすことしかできず、増やせないと説明しています。呼び出される側だけにid-token: writeを書いても、呼び出し側が与えていなければ足りなくなる可能性があるため、両側にそろえておくと衝突しません。permissionsとactions/checkoutは、Claude Code公式の基本例を基にした組み合わせです。actions: readは、ClaudeがCIの実行結果を読むための権限です。リポジトリのファイルを読み書きさせるなら、checkoutのステップが要ります。実際の権限は利用する機能に合わせて見直してください。

シークレットの渡し方は、上のように1つずつ明示する方法のほかに、呼び出し側でsecrets: inheritを使えば全シークレットを引き継げます。引き継ぎにすると呼び出される側のonに宣言がなくても参照できますが、渡す範囲が見えなくなるので、明示列挙のほうが監査しやすくなります。なお、環境(environment)のシークレットは呼び出し側から渡せません。呼び出される側のジョブにenvironmentを書くと、渡したシークレットではなく環境のシークレットが使われます。

長期シークレットを持たないfederationの設定

APIキーを保存すること自体を避けたいときは、claude-code-actionのworkload identity federation(WIF)を使います。ワークフローのGitHub OIDCトークンを、短命のAnthropicアクセストークンに交換する仕組みで、キーを作る・置く・ローテーションする作業そのものがなくなります。

federationは、ワークフロー側の入力を埋める前に、Claude Console側で次の準備が要ります。Anthropic組織の管理者権限が必要で、場所はConsoleのSettings → Workload identityです。

ルールは、サブジェクトの接頭辞(末尾の*で前方一致)に加え、repository_ownerやrefなどのクレームの完全一致も条件にできます。設定した条件はすべて通る必要があります。リポジトリごとにルールを分けるか、組織名までの接頭辞で1本にまとめるかが設計の分かれ目です。

組織全体をまとめて許すと設定は少なくなりますが、対象が広くなります。組織名までの接頭辞だけにすると、refの条件がない限り、フォークからのpull_request実行も一致します。PRを出せる人なら誰でもトークンを得られる状態です。クレームにref: refs/heads/mainとrepository_ownerを加えて絞ります。照合仕様の詳細は、公式のWorkload Identity Federationのドキュメントにあります。

ワークフロー側で渡す入力は次の4つです。

• anthropic_federation_rule_id: 連合ルールのID(fdrl_...)
• anthropic_organization_id: AnthropicのOrganization ID
• anthropic_service_account_id: サービスアカウントID(svac_...)。連合ルールがすでにサービスアカウントを対象にしているため、省略できる扱いです
• anthropic_workspace_id: ワークスペースID(wrkspc_...)。連合ルールが単一のワークスペースを対象にしていれば省略できます

これらは識別子であって認証情報ではないため、ワークフローファイルやリポジトリ変数に直接書けます。組織シークレットに入れる必要はありません。

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write # OIDCトークンの取得に必須
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_federation_rule_id: fdrl_xxxxxxxxxxxx
          anthropic_organization_id: 00000000-0000-0000-0000-000000000000
          anthropic_service_account_id: svac_xxxxxxxxxxxx

federationには、設定画面の入力だけでは気づきにくい挙動が3つあります。

• anthropic_api_keyやclaude_code_oauth_tokenを同じ設定に残すと、静的な認証情報が優先され、federationは使われません。移行中に旧シークレットの行を消し忘れると、federationのつもりが従来のキーで動き続けます
• OIDCトークンのaudienceは既定でhttps://api.anthropic.comです。連合ルールの期待audienceはこの値にそろえるか、照合しない設定にします。ルールが別のaudienceを要求するときだけanthropic_oidc_audienceで上書きします
• インラインコメントの分類機能(classify_inline_comments)は、anthropic_api_keyを必要とします。federationではこの分類が省かれ、確認されていないインラインコメントがそのまま投稿されます

この仕組みはClaude APIを直接呼ぶワークフローで使うWIFをGitHub Actionsと連携すると同じOIDCトークン交換を土台にしています。claude-code-action経由では入力を渡すだけで済み、交換のAPI呼び出しを自分で書く必要はありません。ただしgithub_tokenを自前で指定していても、federationの交換にはid-token: writeが別途必要です。付け忘れると交換に失敗します。

GitHub Appの権限と、権限を絞りたいとき

Claude GitHub Appは、Claude Code GitHub Actionsだけでなく、Code Reviewやクラウドセッション(Claude Code on the web)のauto-fixとも共通です。1つのGitHub Appには権限セットが1つしかないため、Actionsしか使わなくても、使わない権限が含まれます。インストール時に付与される権限は次のとおりです。

インストール時に受け入れるのは全権限のセットで、一部だけを選んで受け入れることはできません。セキュリティ審査で「Actionsが使う権限だけにしたい」と求められたら、Contents・Issues・Pull requestsの3権限でカスタムGitHub Appを自作する選択肢があります。作り方はclaude-code-actionのセットアップガイドにあります。ただしカスタムAppが担えるのはClaude Code GitHub Actionsだけで、Code Reviewとweb上のauto-fixは公式のAppが必要です。Claude Codeコードレビューを使う組織は、この選択肢は取れません。

権限セットは機能の追加に先立って変わることがあります。新しい権限が必要になると、GitHubが組織オーナーに承認を求め、承認するまでインストールは古い権限のまま動きます。たとえばActionsがReadからRead/Writeに変わる場面では、承認前はワークフロー実行の閲覧しかできず、承認後に再実行ができるようになります。承認しないままだと、新しい機能が古い権限のまま動き続けます。

組み込みをやめる手順

組み込みを外すときの順序は次のとおりです。

クラウドプロバイダー連携の構成はGitHub Actions Bedrock連携に分けてあります。企業のセキュリティレビューでデータの取り扱いや保持期間を問われたら、Anthropicのデータ利用とセキュリティのドキュメントが一次情報になります。

組織展開で起きやすいつまずき

症状から原因を探す順に並べます。

ジョブが認証エラーで落ちる。OAuthトークンを組織シークレットにしていないか確かめます。トークンは発行した個人のサブスクリプションに紐づくので、共有には向きません。federationに切り替えたのに落ちるなら、前述のとおりid-token: writeがないか、旧シークレットを残していないかを疑います。起動直後に検証エラーで失敗するときは、claude-code-actionでAJV検証エラーが起きたときの切り分け方の手順で原因を絞れます。

シークレットを消したのに課金が続く。シークレットの削除はワークフローからの参照を切るだけで、APIキー自体はConsoleで削除するまで有効です。Console側の削除は、キーをほかの用途に流用していないかを確認してから行います。

再利用可能なワークフローに渡したはずのシークレットが空になる。呼び出される側のon.workflow_call.secretsに宣言がないか、名前が呼び出し側のsecrets:の左辺と食い違っています。左辺は呼び出される側での名前、右辺は呼び出し側のシークレットです。

組織のシークレットが公開リポジトリで見えない。 gh secret set --orgで可視範囲を指定せずに登録すると、privateリポジトリだけが対象です。

GitHub Appの権限とは別に、Coworkのクラウドセッションでは、git pushが認可済みのリポジトリ範囲に制限されることがあります。該当する場合はCoworkのgit push拒否エラーで扱っています。

まとめ

組織展開で後戻りしにくいのは、認証方式の選択です。共有するならAPIキーかfederationで、OAuthトークンは使わない構成にしておくと、あとから個人依存を剥がす作業が要りません。federationを選ぶ場合は、旧シークレットの行を残さず、Console側の準備を終えてからワークフローを配ります。