GitHub Actionsのパラメータとclaude_argsの渡し方 — Claude Code

Claude CodeをGitHub Actionsで動かすアクションanthropics/claude-code-actionでは、認証やトリガーはwith:直下の専用パラメータで、--modelや--allowedToolsなどのCLI引数はclaude_argsという1つのパラメータで渡します。迷ったら、claudeコマンドのオプションならclaude_args、それ以外なら専用パラメータです。

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

anthropics/claude-code-actionの設定は、同じwith:ブロックに並んでいても効く層が2つあります。

導入自体の手順はClaude CodeをGitHub Actionsに組み込むにあります。ワークフローYAMLのonやjobsをClaude Codeに書かせる手順は別の記事で扱っています。

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

公式ページが「よく使う」として挙げるのは12個です。表にはトリガー許可のallowed_non_write_usersとallowed_botsも加えています。

この表は一部で、リポジトリの設定リファレンスにはコミット署名やbase_branchなど、さらに多くの入力が載っています。全件はusage.mdが最新です。

use_bedrock・use_vertex・use_foundryは、同時に有効にできるのは1つだけです。複数をtrueにすると、アクションはエラーで止まります。リポジトリのvalidate-env.tsにCannot use multiple providers simultaneouslyのメッセージがあります。

3つのクラウド経路の認証設定はGitHub Actions Bedrock連携に個別にあります。「SDK execution error」で落ちる場合は専用の対処記事を見てください。

claude_argsでCLI引数を渡す書き方

claude_argsは、公式ページの例のように1行の文字列でも、ブロックリテラル(|)による複数行でも書けます。フラグごとに行が分かれる複数行のほうが、差分が追いやすくなります。

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

公式ページが共通の引数として挙げるのは次の5つです。

• --max-turns: 会話ターン数の上限
• --model: 使うモデル。省略するとClaude Codeの既定モデルが使われる
• --mcp-config: MCPサーバー設定ファイルへのパス
• --allowedTools: 許可するツール。--allowed-toolsという別名でも通る
• --debug: デバッグ出力を有効にする

ローカルの claude --help と見比べる

CLI引数はclaudeコマンドのオプションと同じものなので、手元のclaude --helpで書式を確かめられます。v2.1.287で出力を確認したところ、折り返しを詰めると次のとおりでした。

--allowedTools, --allowed-tools <tools...>
    Comma or space-separated list of tool names to allow (e.g. "Bash(git *) Edit")
--model <model>
    Model for the current session. Provide an alias for the latest model
    (e.g. 'fable', 'opus', or 'sonnet') or a model's full name.
-d, --debug [filter]
    Enable debug mode with optional category filtering (e.g., "api,hooks" or "!1p,!file")

ここから読み取れる点が3つあります。

• --allowedToolsはカンマ区切りだけでなく空白区切りでも書けます。ツール名にパターンを含めるBash(git *)の形も使えます
• --modelにはエイリアス(sonnetなど)も完全なモデル名も渡せます。公式ページの例は完全名のclaude-sonnet-5です
• --debugはapi,hooksのようにカテゴリを絞れ、!1pのように除外の指定もできます

一方、v2.1.287のclaude --helpの出力に--max-turnsは並んでいません。CLIリファレンスの表には「print modeのみ」の引数として載っており、上限に達するとエラーで終了すると書かれています。公式ページが共通引数の筆頭に挙げる--max-turnsでも、手元のヘルプには出ないことがあります。引数の存否を--helpだけで判断せず、リファレンスの表と突き合わせてください。

旧キーはどこへ移ったか

v0.x時代の入力をそのままwith:直下に残すと、v1では非推奨の扱いになります。リポジトリのusage.mdは、主な旧入力の移行先を次のように示しています。

--append-system-promptは既定のプロンプトに追記し、--system-promptは丸ごと置き換えます。custom_instructionsは同名のCLI引数を持たないので、--custom-instructionsのようなフラグを探しても見つかりません。移行の全体像はClaude CodeをGitHub Actionsに組み込むのv1移行の節にまとめています。

誰の発言でRunが始まるか

トリガーの条件は、promptの有無で決まるモードと、そのさらに手前の2つのチェックの二段になっています。

自動実行モードの注意点が1つあります。プレーンテキストのpromptでは、シェルやGitHub APIを使う権限が最初はありません。必要なツールはclaude_argsの--allowedToolsか、settingsのpermissions.allowで与えます。スキルを呼び出す場合は、スキル側のallowed-toolsが与えるツールを使えます。

trigger_phraseは変更できます。たとえばリポジトリのusage.mdは/claudeを例に挙げています。公式のトラブルシューティングには、コメントに@claudeが単語として完結して含まれることを確かめる項目があり、@claude-botは一致しない例として書かれています。変えた場合はissueテンプレートやREADMEの案内も合わせます。

Claudeが動き出す前の2つのチェックは、どちらのモードでも走ります。

allowed_botsの値はカンマ区切りで、dependabot[bot],renovate[bot]のように書きます。リポジトリのusage.mdには、'*'で全botを許可する書き方も載っています。公開リポジトリで'*'を使うと、外部のAppがアクションを呼べる可能性があるという警告が付いています。allowed_non_write_usersにも同じく'*'の書き方があり、こちらは「RISKY」と明記され、github_tokenを渡した場合にだけ働きます。

github_tokenを自前で渡す場面と、渡してはいけない場面

github_tokenを省略すると、Claude GitHub Appとして認証されます。usage.mdは「自前のGitHub Appをつなぐときだけ指定する」と書いています。通常のワークフローは、省略したままのApp認証で動きます。

自前の指定が要る主な場面は、次のとおりです。

• allowed_non_write_usersで、書き込み権限のないユーザーにもトリガーを許可するとき
• 自前のGitHub Appをつなぐとき

逆に、ワークフロー標準のGITHUB_TOKENは渡すと逆効果になる場合があります。GitHubはデフォルトのGITHUB_TOKENで作ったコミットに対してワークフローを起動しません。Claudeがpushしたコミットで別のCIが動かないときは、github_token: ${{ secrets.GITHUB_TOKEN }}を外してApp認証に戻すか、カスタムAppのトークンを渡します。あわせて、CI側のトリガーがClaudeのpushで起きるイベント(pushやpull_request)を含んでいるかも確認してください。

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

plugin_marketplacesにマーケットプレイスのGit URLを、pluginsに入れたいプラグインを、どちらも改行区切りで書くと、Claudeの起動前にインストールされます。公式ページの例はこうです。

plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
plugins: "code-review@claude-code-plugins"
claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

pluginsの値はプラグイン名@マーケットプレイス名の形です。@の右は、リポジトリのURLではなく、マーケットプレイス自身のマニフェストに書かれた名前です。URLの末尾を写してyour-org/lint-helperのように書くと、名前が一致しません。

この例のclaude_argsを消してはいけない理由も、公式ページに書かれています。スキル自身のallowed-toolsが同じツールを挙げていても、インラインコメントを投稿するMCPサーバーは、claude_argsの--allowedToolsにそのツールがあるときだけアクションが起動します。

plugin_marketplacesを設定すると、ネイティブインストーラーの警告をclaude-code-actionが見逃し、バイナリ未配置のままマーケットプレイス追加でENOENTになる問題が報告されています。原因と回避策はplugin_marketplacesでバイナリが配置されない原因と対処にあります。

settingsはJSON文字列でもファイルパスでも渡せます。

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

ファイルパスで渡せば、設定の変更がワークフローYAMLではなく通常のファイルの差分に現れます。同じ構成を組織全体のリポジトリへ配る手順はClaude CodeのGitHub Actionsを組織全体に導入する手順にあります。

目的別のパラメータ早見表

資格情報の渡し方

anthropic_api_keyやclaude_code_oauth_tokenは、ワークフローYAMLに直接書かず、GitHub Secretsに登録して${{ secrets.ANTHROPIC_API_KEY }}のような参照式で渡します。YAMLファイルはリポジトリを読める人全員に見えるため、直書きすると、そこに書いた時点で鍵が漏れます。

クラウド経由(use_bedrockなど)に切り替えるときは、anthropic_api_keyが使われないことが公式の表に明記されています。長期のAPIキーを持たない構成にしたい場合は、WIFをGitHub Actionsと連携するのようにOIDCトークン交換へ切り替える方法があります。base_branchに#や()を含むブランチ名を渡すときは、Invalid branch nameエラーの原因と対処法も見ておくと安全です。

まとめ

旧キーがwith:直下に残っているワークフローは、移行表のclaude_args側へ移す箇所から洗い出すと、効いていない設定を見つけやすくなります。