GitHub Agentic Workflows (gh aw) の使い方｜実際に試した導入手順・権限・費用と、Claude Code を直接動かす構成との違い

GitHub Agentic Workflows (gh aw) とは

GitHub Agentic Workflows は、Markdown で書いた指示を GitHub Actions のワークフローに変換し、AI エージェントに実行させる仕組みです。コマンドは gh CLI の拡張機能 gh aw として配布されており、開発は github/gh-aw で行われています。公式ドキュメントの作成は GitHub Next と Microsoft Research です。

この記事は、2026 年 9 月 30 日時点の最新の安定版 v0.89.21 で、記事の管理に使う 2 本のワークフローと、ネットワーク制限を確かめる 1 本を実際に書き、試用リポジトリで実行した記録をもとにしています。公式ドキュメントの説明と、手元で確かめた結果は書き分けます。gh そのものの導入と認証は GitHub CLI (gh) の基本にまとめています。

先に結論を 3 つ書きます。

• 拡張機能を入れたら、gh aw compile と gh aw trial で最初の 1 本を試せます。手元の実行は 1 回 4〜6 分、AI Credits は 16〜48 AIC 程度でした
• エージェントのジョブは読み取り権限だけで、Issue やコメントへの書き込みは別のジョブが行います。コンパイル後の .lock.yml で確かめられます
• Claude は API キーか WIF、Codex は API キーが必要です。Claude のサブスクリプションのトークンは使えません

Markdown と .lock.yml の 2 ファイルで構成する

ワークフローは .github/workflows/<名前>.md に書きます。先頭の frontmatter で起動条件 (on)・権限 (permissions)・AI エンジン (engine)・使えるツール (tools)・通信先 (network)・書き込みの種類 (safe-outputs) を宣言し、本文に AI への指示を日本語や英語の文章で書きます。

gh aw compile を実行すると、同じディレクトリに <名前>.lock.yml が生成されます。中身は通常の GitHub Actions のワークフローで、先頭には「DO NOT EDIT」と、生成に使った gh-aw のバージョンが書かれます。.md と .lock.yml は両方コミットします。

公式 FAQ によると、本文 (AI への指示) は実行時に読み込まれるため、直しても再コンパイルは要りません。frontmatter はコンパイル時に .lock.yml へ埋め込まれるので、変えたら gh aw compile をやり直します。

通常の GitHub Actions との役割分担

公式は、GitHub Agentic Workflows を既存の CI/CD の置き換えではなく、補強と位置づけています。線の引き方は次のとおりです。

2026 年 9 月 30 日時点の状態

2026 年 2 月 13 日に技術プレビューとして公開され、6 月 11 日にパブリックプレビューになりました。GitHub Docs にも「public preview and subject to change」と書かれており、一般提供の発表は 9 月 30 日時点で見つかりません。

リリースの間隔は短く、9 月 30 日時点で最新の安定版は v0.89.21、その後にプレリリースの v0.90.0 が出ています。README には、v0.83.3 以上 v0.85.4 未満の版をセキュリティ上の脆弱性のため撤回したと書かれています。「Use it with caution, and at your own risk.」という注意書きもあります。チームで使うなら、版を固定して入れるほうが安全です。

始める前に確かめる前提条件

手元の環境と GitHub 側の設定

Quick Start に書かれている前提は次のとおりです。

1. gh CLI v2.0.0 以上が入っている
2. gh auth login --scopes repo,workflow で、workflow のスコープまで認証している
3. 対象のリポジトリに書き込み権限がある
4. リポジトリで GitHub Actions が有効になっている
5. 作業端末が Linux・macOS・WSL のいずれか

認証済みの gh に workflow のスコープを後から足すなら、gh auth refresh -s workflow を実行します。

公式 FAQ によると、macOS のランナーは使えず、Linux のランナーを使うよう案内されています。macOS のランナーはコンテナのジョブに対応しておらず、エージェントのサンドボックスを作れないためです。

手元では版を固定して入れ、gh aw doctor で認証とリポジトリの状態を確かめました。CLI リファレンスでの版の固定は gh extension install github/gh-aw@v0.89.21 の形で書かれています。手元では --pin を使いました。

gh extension install github/gh-aw --pin v0.89.21
gh aw version
gh aw doctor

gh aw doctor は、gh の認証、リポジトリの存在、所有者が組織か個人か、作業ツリーがクリーンかを順に確かめ、「Setup repository checks passed」で終わりました。

AI エンジンごとの認証

主な組み込みのエンジンと、必要な認証は次のとおりです (Engines リファレンス)。

Copilot は、2026 年 6 月 11 日の changelog で個人アクセストークンが不要になりました。組織が所有するリポジトリでは、permissions に copilot-requests: write を書くと、実行ごとの GITHUB_TOKEN で推論し、費用が組織に請求されます。組織側で「Allow use of Copilot CLI billed to the organization」のポリシーを有効にしておく必要があります。このポリシーは、既存の「Copilot CLI」ポリシーを有効にしていれば最初から有効です。

手元でも差を確かめました。copilot-requests: write を書かずにコンパイルすると、個人のトークンを COPILOT_GITHUB_TOKEN としてシークレットに登録する前提の .lock.yml になります。書くと、.lock.yml の中の COPILOT_GITHUB_TOKEN に ${{ github.token }} が渡されるようになり、シークレットの登録が要らなくなりました。なお、今回の試用リポジトリは個人のアカウントが所有するもので、組織への請求の流れまでは確かめていません。Copilot の課金の仕組みそのものは GitHub Copilot の課金の変更で扱っています。

Claude エンジンは、Claude のサブスクリプションのトークン (CLAUDE_CODE_OAUTH_TOKEN) に対応していません。Quick Start には、このトークンは黙って無視され、トークンに触れない認証エラーで失敗すると書かれています。

FIXIT

Claude のサブスクで CI を回してる人は、そのままでは移せないってこと？

Kaname

運用に乗せるなら、Claude は API キーの従量課金が前提です。費用の見積もりから組み直すことになります。

FIXIT

今回は何で試したの？

Tsumiki

手元では、シークレットを登録せずに動く Copilot で試しました。

実際に試した 2 本のワークフロー

題材には、このサイトの記事の管理を選びました。どちらも記事を書き換えず、Issue かコメントを 1 件出すだけのワークフローです。

gh aw init で作られたもの

最初に gh aw init --no-mcp --no-agent を実行しました。MCP とエージェント用のファイルを省くオプションを付けた結果、作られたのは次の 2 つだけでした。

• .gitattributes (.lock.yml を生成物として扱う設定が 1 行)
• .github/skills/agentic-workflows/SKILL.md (ワークフローの作成や修正の依頼を、gh-aw リポジトリの手順書へ振り分けるルーター用のスキル)

週 1 回、再確認が要る記述を Issue にまとめる

1 本目は、記事の中の「2026 年 9 月 30 日時点」のような時点つきの事実や、「続報で公表する予定」のような続報待ちの記述を拾い、再確認が要るものを Issue 1 件にまとめるワークフローです。frontmatter は次のとおりです。

---
on:
  schedule: weekly
 
permissions:
  contents: read
  copilot-requests: write
 
engine: copilot
 
network: defaults
 
safe-outputs:
  create-issue:
    title-prefix: "[続報の再確認] "
    close-older-issues: true
---

本文では、拾う記述の 2 種類、優先度の付け方 (続報待ちは記事の更新から 14 日以上、時点つきの事実はその日付から 90 日以上)、Issue の書き方、載せるものがなければ Issue を作らずに終えることを指示しています。close-older-issues: true で、前の週の Issue は新しい Issue を作るときに閉じられます。

PR のコメントで呼び出す根拠チェック

2 本目は、記事の PR に /check-claims とコメントすると、変更された記事から根拠のない主張を洗い出してコメントするワークフローです。

---
on:
  slash_command:
    name: check-claims
    events: [pull_request_comment]
 
permissions:
  contents: read
  pull-requests: read
  copilot-requests: write
 
engine: copilot
 
tools:
  github:
    toolsets: [pull_requests, repos]
  bash: [cat, grep, find, wc]
 
network: defaults
 
safe-outputs:
  add-comment:
    max: 1
    hide-older-comments: true
---

本文では、探すものを 4 種類に分けました。出典のない数字、主体と根拠のない一般化、実績の記事と食い違う数字、リンク先の資料より強い言い切りです。直し方は提案させず、「このコメントは自動の一次チェックです。見落としも誤検知もあります。」と添えさせています。

bash を 4 つのコマンドに絞ったのは、公式の指針に合わせたためです。gh-aw がワークフローを書くエージェント向けに用意しているツールと権限の手引きは、PR のコメントのような信頼できない入力を読むワークフローでは、[find, cat, grep, wc, jq] のような狭い許可リストにするよう求めています。信頼できない入力を読まない定期実行なら ["*"] でもよい、という線引きです。

コンパイル後の .lock.yml でジョブと権限を読む

gh aw compile の結果は「Compiled 2 workflows: 2 succeeded, 0 warnings」でした。生成された check-claims.lock.yml のジョブは次の 6 つです。ワークフロー全体の permissions は空で、権限はジョブごとに付いています。

agent と detection には、GitHub の権限とは別に copilot-requests: write が付きます。agent のジョブには、直近 24 時間の AI Credits が上限を超えていたら実行しない条件も入っていました。エージェントのステップ自体の制限時間は既定で 20 分です。

slash_command は、issue_comment (created・edited) を起動条件とするワークフローに変換されていました。定期実行の schedule: weekly は cron: "5 9 * * 1" (UTC。日本時間では月曜 18:05) に変換され、手動実行用の workflow_dispatch が自動で足されています。公式の説明では、定期実行の時刻は負荷を分散するためにずらして決められます。

gh aw trial で試用リポジトリに流す

いきなり本番のリポジトリで実行せず、gh aw trial で試しました。--clone-repo を付けると、個人アカウントに非公開のリポジトリを作り、元のリポジトリの中身を複製して、そこで実行します。--dry-run で表示された手順は次のとおりです。

1. 非公開のホストリポジトリを作る
2. 元のリポジトリの中身を複製する
3. 試すワークフロー以外のワークフローをすべて無効にする
4. 試すワークフローを入れてコンパイルする
5. 実行する
6. ホストリポジトリを消さずに残す

実行前に確認の入力を求められます。入力できない環境では「confirmation failed」で止まったので、スクリプトから流すなら CLI リファレンスにある --yes を付けます。実行が終わると、safe outputs に渡された内容 (Issue のタイトルと本文など) がそのまま端末に表示されます。書き込みの中身を確かめてから本番に入れられるのが、trial を使う利点です。

試用で止まった場面

手元で止まったのは次の 4 か所です。起きた順に並べます。

1. 1 回目の trial は、試用リポジトリを作った後、中身の複製で git が「unable to get password from user」と返して止まりました。git の認証が対話を求めたためです。次の実行からは、その実行だけ環境変数で gh を git の認証ヘルパーに指定しました (git の設定ファイルは変えていません)
2. 2 回目は、複製とワークフローの無効化までは進みましたが、相対パスで渡したワークフローのファイルが見つからないと返されました。CLI リファレンスの例は ./workflow.md の形ですが、v0.89.21 の手元では通りませんでした。3 回目に絶対パスで渡すと、最後まで進みました
3. check-claims は、--logical-repo で元のリポジトリとして振る舞わせて入れました。trial からの手動起動は、必須の入力 issue_number がないとして HTTP 422 で失敗しました。gh workflow run で issue_number を渡して手動で実行すると、6 つのジョブがすべて skipped になりました
4. 試用リポジトリに PR を作り、/check-claims とコメントして起動すると、エージェントのジョブのチェックアウトが「Not Found」で失敗しました。--logical-repo を外して入れ直し、試用リポジトリ自身を対象にすると、同じ PR へのコメントでの起動が成功しました (中身は最初に --clone-repo で複製済みです)

実行結果と費用の実測

4 回の実行を gh aw audit <run-id> で確かめた結果です。net-probe は、次の章で扱うネットワーク制限を確かめるために書いたワークフローで、2 回流したうちの 2 回目の数字を載せています。check-claims の 2 行目は、後で述べる除外の条件を指示に足してから、同じ PR にもう一度コメントして起動したものです。エンジンはいずれも Copilot CLI v1.0.87、モデルの指定は auto でした。

トークンは入力と出力の合計で、キャッシュからの読み込みは含みません。Cost Management によると、1 AIC は 0.01 米ドルです。4 回の推論費用は、およそ 0.16〜0.48 米ドルでした。これとは別に Actions の実行時間がかかり、公開リポジトリでは無料、非公開のリポジトリでは契約に応じて課金されます。

出力の質

recheck-dated-facts の Issue には、続報待ちの記述が 3 件、90 日以上前の時点つきの料金の記述が 2 件、ファイル名・行番号・更新日つきで並びました。指示した形式どおりで、手で直す箇所はありませんでした。

check-claims は、費用相場を扱う自社の記事を対象に、4 種類の見出しの下へ 33 項目を並べました。うち 1 項目は数字が一致していることの確認なので、指摘は 32 項目です。本物の問題も拾っています。実績記事との数字の食い違いや、主体の書かれていない一般化です。

一方で、本文で「目安」と断っている数字まで「出典がない」として拾っていました。そこで、指示に除外の条件を 3 つ書き足しました。文中で「目安」「試算」「仮定」「例」と断った数字、表の直前の文や表の見出しで「目安」などと断った表の中の数字、記事自身が架空の例と明記したサンプルの数字です。

書き足した後の指示で同じ PR にもう一度コメントすると、箇条書きは 16 項目に減りました (うち 1 項目は「該当なし」)。「目安」と断った表の数字は挙がらなくなっています。その一方で、1 回目に拾えていた実績記事との数字の食い違いが、2 回目は「該当なし」になりました。除外を強めると、誤検知と一緒に見落としも増えたことになります。どちらも 1 回ずつの実行なので、この傾向が毎回出るかまでは分かりません。

gh aw audit は、2 回とも check-claims について「上位のモデルが要らない実行かもしれない」として、engine.model に gpt-4.1-mini か claude-haiku-4-5 を指定するよう勧めていました。費用を下げるなら、最初に試す価値のある設定です。

FIXIT

1 回 0.5 ドルもしないなら、全部の PR で回してもいいんじゃない？

Tsumiki

実際に試すと、費用より指摘の精度のほうが先に気になりました。

FIXIT

精度って、見落としのこと？

Tsumiki

逆で、エージェントが拾いすぎるんです。ただ、除外の条件を足すと今度は見落としが出ました。

既定の上限と、費用を左右するもの

Cost Management には、既定の上限が次のように書かれています。

1 回の上限は frontmatter の max-ai-credits、1 日の上限は max-daily-ai-credits で変えられます。公式 FAQ によると、失敗した実行は自動でやり直されません。費用を左右するのは起動の回数で、Issue や PR のイベントで起動するワークフローは、イベントの数だけ実行されます。今回の 2 本を、週 1 回の定期実行と、コメントで呼んだときだけの実行にしたのはそのためです。

権限と安全の仕組み

エージェントは読むだけ、書き込みは safe outputs の別ジョブ

コンパイル後のジョブのつながりを図にすると、次のようになります。

flowchart LR
  A["pre_activation<br/>起動前の確認"] --> B["activation<br/>起動・反応"]
  B --> C["agent<br/>読み取りのみ"]
  C --> D["detection<br/>出力の検査"]
  D --> E["safe_outputs<br/>書き込み (Issue・コメント)"]
  E --> F["conclusion<br/>結果の報告"]

エージェントは Issue やコメントを直接書けません。書きたい内容を「Issue を 1 件作る」「コメントを 1 件書く」という要求として出し、検知のジョブを通った要求だけを safe_outputs のジョブが書き込みます。gh aw audit の記録でも、エージェントが呼んだ書き込み系のツールは safeoutputs.create_issue と safeoutputs.add_comment の 1 回ずつだけでした。

add-comment の max: 1 のように、safe outputs の種類ごとに件数や接頭辞を決められます。エージェントが指示を無視して何件もコメントしようとしても、書き込むジョブの側で止まる設計です。

ネットワーク制限で確かめられたこと

ネットワークの制限を確かめるため、network: defaults のまま bash: [curl] を許可し、3 つの URL へ curl を実行させるワークフロー (net-probe) を 2 回流しました。宛先は、独自のドメイン 2 つと、GitHub のドメイン (raw.githubusercontent.com) です。3 つとも defaults の許可リストには含まれません。

bash: [curl] は、.lock.yml では shell(curl:*) に変換されていました。ところが Copilot エンジンは、URL を含む 3 つの curl をすべて「Permission denied and could not request permission from user」で実行前に拒否しました。コマンドが実行されなかったので、ファイアウォールが通信を止めるところまでは確かめられていません。

代わりに見えたのが、出力側の処理です。safe outputs の Issue の本文で、独自のドメイン 2 つの URL は (fixit.co.jp/redacted) のように伏せ字になり、GitHub のドメインの URL はそのまま残りました。公式の説明では、伏せ字にしない対象には GitHub のドメインが既定で含まれます。公式 FAQ は、safe outputs を書き込む前に、シークレットの秘匿化や URL のドメインでの絞り込みを行うと説明しています。

通信そのものについては、公式の説明では Agent Workflow Firewall (AWF) が network の許可リストにないドメインへの通信を止めます。defaults は証明書の検証などに要る最小限のドメインで、node や python のようなパッケージのレジストリは、必要な分だけ足していきます (Security Architecture)。

人の承認と、エージェントが作った PR の CI

公式 FAQ には、safe outputs を書き込む前に人の承認を挟む方法が載っています。GitHub の Environment に保護ルールを設定し、safe_outputs のジョブが待つ独自のジョブにその Environment を指定します。承認はワークフローの中の判定ではなく GitHub 側の仕組みで強制されるので、エージェントからは操作できません。

公式 FAQ によると、既定の GITHUB_TOKEN で作った PR は CI を起動しません (今回は PR を作るワークフローは試していません)。ワークフローの再帰的な起動を防ぐ、GitHub Actions の仕様です。公式 FAQ は、Contents の読み書き権限を持つ PAT を GH_AW_CI_TRIGGER_TOKEN に設定する方法を案内しています。

設定次第で緩められる点

公式 FAQ は、ワークフローの作者がエージェントに直接の書き込み権限を渡したり、独自のジョブを足したりできると書いています。その場合は safe outputs とは別の信頼境界になり、ここまでの保護は及びません。エージェントのジョブにはシークレットが既定で渡りませんが、作者がエンジンやツールに明示的に渡すこともできます。

安全側の検査は、既定で有効です。gh aw compile --help によると、ワークフローは frontmatter に strict: false と書かない限り strict モードでコンパイルされ、Actions の固定、通信先の設定、safe outputs の使用を強制し、書き込み権限を禁じます。手元の 3 本の .lock.yml も、先頭のメタデータは "strict":true でした。gh aw compile --strict は、frontmatter の strict: false を上書きして、すべてのワークフローに strict モードを強制するオプションです。手元の Claude Code での権限の考え方は Claude Code の権限設定にまとめています。

gh aw の主なコマンド

今回使ったもの、CLI リファレンスの「Day-one commands」に並ぶもの、検査用の validate をまとめました。

gh aw add-wizard githubnext/agentics/repo-status のように公開されているワークフローを追加する方法が、公式の最初の手順です。今回は自前の 2 本を試すため、compile と trial から始めました。

Claude Code を Actions で直接動かす構成との違い

GitHub Actions で AI エージェントを動かすだけなら、anthropics/claude-code-action のように、エージェントの CLI を通常のワークフローから呼ぶ方法もあります。構成の作り方は Claude Code を CI に組み込む方法で扱っています。

このサイトの記事の下書きを作る自前のワークフローも、この形です。Claude Code には記事とリサーチのファイルを書かせるだけにし、コミット・push・PR の作成はエージェントの後の決まった手順が行います。その手順は、変更されたファイルが記事とリサーチのパスに合うかを照合し、ファイルの削除やそれ以外の既存ファイルの変更があれば PR を作らずに止まります。キービジュアルを作る Codex は、ログイン情報を Web を読むエージェントと同じジョブに置かないよう、別のワークフローに分けています。

「エージェントに直接書かせない」という考え方は、safe outputs と同じです。違うのは分ける単位と、周りの仕組みです。

FIXIT

gh aw に移せば、自前の照合の手順は要らなくなるの？

Kaname

手順は減りますが、コンパイルと版の追従が増えます。運用に乗せるなら、どちらも保守する人を決めておくことです。

どちらを選ぶか

判断の分かれ目は次の 4 つです。

• API キーによる従量課金か、Copilot の組織の課金に寄せられるなら、gh aw に移せます。サブスクリプションのトークンで回し続けたいなら、自前の構成のままです
• 公開リポジトリの Issue やコメントのように、第三者が書いた文章をエージェントに読ませるなら、ジョブ単位で分けて検知のジョブを挟む gh aw のほうが守りを固めやすくなります
• 自前の照合スクリプトを保守し続けられるかどうかも判断材料です。gh aw では、同じ役割を仕組みの側が持ちます
• プレビュー版の頻繁な変更を追う余力があるか。版を固定しても、上げるときには変更点を読む必要があります

向いている作業と始める順番

公式ブログは、PR の作成より先に、コメントやレポートのような失敗しても害の小さい出力から始めるよう勧めています。今回試したのは次の 1 と 2 です。

1. Issue にレポートを出す (定期実行)
2. PR や Issue にコメントする (呼ばれたときだけ)
3. PR を作る (マージは人が行う)

レポートとコメントは、内容が外れていても読んだ人が無視すれば済みます。PR を作らせるのは、出力の質と費用の感触をつかんでからで十分です。定期的な作業を AI に任せる方法としては、エディターの中で定期実行を組む VS Code Copilot の Automations もあります。実行する場所が GitHub Actions か、手元のエディターか、という違いです。

FIXIT の構成との対応｜エージェントが書く経路と、リポジトリに書き込む経路を分ける

記事の下書きを作る自前のワークフローとの対応は、Claude Code を直接動かす構成との比較で書いたとおりです。

gh aw は本番のリポジトリには入れず、試用リポジトリで出力と費用を確かめました。gh aw trial は、書き込みの中身を実行後に一覧できる点が、この確かめ方に合っていました。

エージェントの権限設計、課金の寄せ方、CI への組み込みまでを含めた進め方は AI 開発ツール定着支援で伴走しています。

まとめ｜まずレポートを出す 1 本を trial で試す

GitHub Agentic Workflows は、Markdown の指示を .lock.yml に変換し、読み取り専用のエージェントと、権限を絞った書き込みのジョブに分けて実行する仕組みです。2026 年 9 月 30 日時点ではパブリックプレビューで、リリースの間隔が短いため、版を固定して入れるのが安全です。

試すなら、Issue にレポートを出す 1 本を書き、gh aw compile の後に .lock.yml のジョブと権限を読んでから、gh aw trial で試用リポジトリに流してください。手元の実行は 1 回 4〜6 分、推論費用は 0.5 米ドル未満でした。出力の質と gh aw audit の数字を見てから、コメントや PR へ広げるかを決められます。

Claude Code のサブスクリプションで CI を回している場合は、移す前に認証の違いを確かめてください。Claude エンジンは API キーか WIF が前提です。自社の CI にどこまで AI を任せるかの設計から相談したい場合は、お問い合わせからお寄せください。