GitHub ActionsのパラメータとCLI引数をClaude Codeで渡す

GitHub Actionsアクションのパラメータ全体像

anthropics/claude-code-actionには2種類の設定経路があります。ワークフローYAMLのwith:ブロックに書くアクションパラメータと、そのうちのclaude_argsという1つのパラメータに文字列として詰め込むCLI引数です。両者は書く場所も効き方も違うのに、同じwith:ブロックの中に混在するため見分けがつきにくくなっています。

アクションパラメータは認証情報やプラグイン設定など、Claude Codeの起動そのものを制御します。CLI引数は--max-turnsや--modelのように、起動したセッションの動作を細かく調整します。この記事ではまずパラメータ一覧を整理し、そのあとでCLI引数の渡し方と使い分けを見ます。導入自体の手順はClaude CodeをGitHub Actionsに組み込むにまとまっているので、そちらを先に済ませてから本記事のリファレンスを使うと迷いません。

with:で渡せるパラメータ一覧

よく使うパラメータは次の14個です。

use_bedrock / use_vertex / use_foundryはいずれか1つだけをtrueにします。3つの経路の認証設定はGitHub Actions Bedrock連携で個別に扱っています。全パラメータの網羅的な入力リストは、claude-code-actionリポジトリの設定リファレンスが最新です。

claude_argsでCLI引数を渡す書き方

claude_argsはYAMLのブロックリテラル(|)で複数行にして渡すのが基本形です。

- uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    prompt: "このPRの変更をレビューしてください"
    claude_args: |
      --max-turns 5
      --model <利用したいモデルのID>
      --mcp-config /path/to/config.json

よく指定するCLI引数は次の5つです。

• --max-turns: 1回の実行で許す会話ターン数の上限
• --model: 使うモデル。省略時はワークフロー実行環境に設定された既定モデルがそのまま使われる。モデル名はclaudeコマンドが受け付ける表記に従うため、指定前にローカルのclaude --helpかモデル一覧で正確な表記を確認しておくと取り違えを防げる
• --mcp-config: MCPサーバー設定ファイルへのパス
• --allowedTools: 許可するツールのカンマ区切りリスト。--allowed-toolsという別名でも同じ意味になる
• --debug: デバッグ出力を有効にする。ワークフローが期待どおり動かないときの一次切り分けに使う

CLI引数はClaude Code CLI本体のオプションと共通です。ローカルのclaude --helpで確認できる引数は、claude_argsの中でそのまま使えます。

github_tokenを自前で渡すべき場面

github_tokenを省略すると、Claude GitHub Appとしての認証で動きます。多くのワークフローはこれで足り、Issue/PRコメントの投稿やPR作成もApp権限の範囲で完結します。

自前のgithub_tokenが要るのは次のような場面です。

• allowed_non_write_usersで書き込み権限のないユーザーにもトリガーを許可したいとき
• 標準のGITHUB_TOKENでコミットを作り、そのコミットで別のワークフローを再トリガーしたいとき(GITHUB_TOKENが作ったコミットはCIの再トリガーにならない制約があるため)
• Claude GitHub App以外のGitHub Appやパーソナルアクセストークンの権限でコメント・コミットを行いたいとき

これらに当てはまらない通常運用では、github_tokenは指定せずApp認証に任せるのがシンプルです。

promptの有無が対話モードと自動実行モードを分ける

promptを空にすると、Claude Code GitHub Actionsは対話モード(Interactive mode)で動きます。trigger_phrase(既定は@claude)をissue・PRコメントやレビュー、新規issueの本文・タイトルで待ち受け、コメント本文そのものを指示文として扱う仕組みです。進行状況と結果はトリガーとなったissueやPRへのコメントとして表示されます。

promptを指定すると自動実行モード(Automation mode)に切り替わります。メンションを待たずに実行され、結果は既定でワークフロー実行ログに出力されます。issueやPRへコメントさせたい場合は、prompt側でその旨を明示し、投稿できるツールを許可しておく必要があります。

定型レビューのように毎回同じ指示を送るジョブはpromptを固定した自動実行モードで書きます。issueコメントで都度違う依頼を投げたい運用は、promptを空のままにする対話モードを使います。1つのワークフローファイルに両方の使い方を混在させると、片方のジョブだけ指示が効かないという事故につながるため、ジョブ単位でどちらか一方に決めておくのが安全です。

trigger_phraseは@claude固定ではなく変更できます。同じリポジトリに複数のレビューbotを導入していて@claudeという語句が競合する場合や、社内の別ツールと表記を揃えたい場合は、trigger_phraseに独自の語句を設定します。変更した場合は、issueテンプレートやREADMEの案内文もあわせて書き換えないと、開発者が既定値の@claudeで呼びかけて反応しないという混乱を招きます。

誰の発言でRunをトリガーできるか

対話モード・自動実行モードのどちらでも、Claudeが動き出す前に2つのチェックが走ります。片方でも弾かれるとRunは失敗します。

• 書き込み権限チェック: issue・PRイベントでは、トリガーしたユーザーがリポジトリへの書き込み権限を持っている必要があります。権限を持たない特定ユーザーにも許可したい場合はallowed_non_write_usersに列挙し、github_tokenも自前で渡します。scheduleのようにユーザーが起点にならないイベントはこのチェックをスキップします
• 人間アクターチェック: botアクターはallowed_botsに列挙しない限り、あらゆるイベントで拒否されます。bot同士がループでトリガーし合うのを防ぐためです。この判定はschedule実行にも及びます。GitHubはcron実行を「最後にワークフローのcron設定を変更したユーザー」に帰属させるため、そのユーザーがbotアカウントならallowed_botsへの追加が必要です

pluginsとplugin_marketplacesで実行前にツールを揃える

pluginsとplugin_marketplacesを組み合わせると、Claudeが起動する前にプラグインをインストールできます。社内マーケットプレイスのGit URLをplugin_marketplacesに、そこから入れたいプラグイン名をpluginsに列挙する形です。

claude_args: |
  --max-turns 8
plugin_marketplaces: |
  https://github.com/your-org/claude-plugins
plugins: |
  your-org/lint-helper
  your-org/release-notes-writer

複数リポジトリのワークフローで同じプラグイン構成を使い回したいときは、plugin_marketplacesとpluginsをワークフロー側で固定し、settingsにはCLAUDE.mdの参照先や許可ツールなど組織共通のガードレールをJSON文字列で渡す形が組み合わせやすくなります。

settings: |
  {
    "permissions": {
      "allow": ["Bash(npm run lint)", "Edit"]
    }
  }

settingsはこのようなJSON文字列のほか、リポジトリにコミットした設定ファイルへのパスでも渡せます。ファイルパスを指定する形にしておくと、設定の差分がワークフローYAMLではなく通常のファイルのdiffとして見えるため、レビューがしやすくなります。同じ構成を組織全体のリポジトリへ配る手順はClaude CodeのGitHub Actionsを組織全体に導入する手順にまとめています。

パラメータの使い分け早見表

パラメータ設定でよくあるつまずき

v0.x時代のallowed_tools:やdirect_prompt:をそのままwith:直下に書いてしまうのが最も多いつまずきです。v1では個別のトップレベルキーが廃止され、claude_argsの中にCLI引数として集約されています。移行の詳細はClaude CodeをGitHub Actionsに組み込むのv1移行の節で扱っていますが、CLI引数として特に見落としやすいのがcustom_instructions:です。この入力は同名のCLI引数を持たず、claude_argsの中で--append-system-promptに置き換える必要があります。単純に--custom-instructionsのようなフラグ名を探しても見つからず、ここでつまずくケースが目立ちます。

claude_argsをYAMLの1行文字列で書き、複数のフラグをスペースだけで詰め込んでYAMLパースエラーになるケースもあります。ブロックリテラル(|)で改行区切りにすれば、フラグごとに独立した行として扱われて安全です。

use_bedrockやuse_vertexをtrueにしたままanthropic_api_keyも同時に設定すると、どちらが優先されるかが分かりにくくなります。クラウド経由に切り替えるときは、Claude APIキー系のシークレットをワークフローから外しておくと事故を防げます。

anthropic_api_keyやclaude_code_oauth_tokenをワークフローYAMLに直接書き込んでしまうのも見落としがちな事故です。値は必ずGitHub Secretsに登録し、${{ secrets.ANTHROPIC_API_KEY }}のような参照式でパラメータに渡します。ワークフローファイルはリポジトリ内の誰でも読めるため、直書きした瞬間にキーが漏えいします。長期のAPIキー自体を持ちたくない場合は、WIFをGitHub Actionsと連携するのようにOIDCトークン交換に切り替えれば、そもそもシークレット管理の対象から外せます。

まとめ

• with:ブロックのアクションパラメータと、claude_argsに詰め込むCLI引数は別レイヤー
• promptの有無が対話モードと自動実行モードを分け、書き込み権限チェックと人間アクターチェックがその前段で走る
• plugins / plugin_marketplaces / settingsは実行前の環境を揃えるための3点セット
• github_tokenはallowed_non_write_usersを使うときなど限られた場面でのみ自前で渡す
• trigger_phraseは変更でき、変更したらissueテンプレートやREADMEの案内文も忘れずに書き換える
• claude_argsは複数行のブロックリテラルで書くとYAMLパースエラーを避けられる
• クラウド経由(use_bedrock等)とAPIキー系の設定は同時に有効化せず、キーは必ずSecrets経由で渡す

パラメータの意味が分かれば、あとは自分のワークフローに必要な組み合わせを選ぶだけです。認証方式やクラウド経由の詳しい設定は個別記事、組織全体への展開は次に読む記事で扱っています。設定を変えるたびに全パラメータを見直す必要はなく、今回追加・変更したいものだけをこの一覧から探せば十分です。