--- title: "GitHub Agentic Workflowsとは：gh awの導入手順・料金・safe-outputs設計【2026年10月GA】" url: "https://www.issoh.co.jp/tech/details/19098/" published: 2026-10-30 updated: 2026-10-30 categories: ["開発"] publisher: "株式会社一創" --- # GitHub Agentic Workflowsとは：gh awの導入手順・料金・safe-outputs設計【2026年10月GA】 GitHub Agentic Workflows（gh aw）は、Markdownで書いた指示をAIコーディングエージェントに実行させ、GitHub Actionsのワークフローとして動かす仕組みです。2026年10月28日に一般提供（GA）となり、Issueの仕分けやCI失敗の調査のように「判断」が要る作業をActionsへ載せられるようになりました。本記事では、gh awのインストールから最初の実行、Issueトリアージを自作する定義例、書き込みを絞るsafe-outputs、Actions分数とAI Creditsの二重課金、`gh aw forecast`による月額の見積もりまでを、公式ドキュメントで確認した値で整理します。 ## まとめ：GitHub Agentic Workflowsの要点と導入前の判断基準 gh awは、YAMLのfrontmatterと自然言語の本文からなる`.md`ファイルを、`gh aw compile`で通常のActions用`.lock.yml`へ変換して実行します。エージェント本体は読み取り専用で動き、Issue作成やコメントなどの書き込みは、frontmatterで宣言したsafe-outputsを別ジョブが代行します。費用はActionsの実行分数と、AIエンジンの推論費用（AI Credits）の2本立てです。 採用の目安ははっきりしています。Issueの仕分け、CI失敗の一次調査、定期レポートのように「誤っても人が直せる出力」を返す作業には向きます。本番デプロイの可否判断や、外部の第三者が書いた文章を大量に読ませる処理には、権限を絞ったうえでも載せません。最初の1本は公式サンプルで動かし、2〜3週間の実行履歴を貯めてから`gh aw forecast`で月額を見積もる順序が安全です。 ## GitHub Agentic Workflowsの仕組みとMarkdownの変換手順 gh awはGitHub Nextが開発するオープンソースのGitHub CLI拡張です。2026年10月30日時点の最新リリースは[github/gh-awのリリース一覧](https://github.com/github/gh-aw/releases)でv1.0.1（10月27日公開）で、1.0系としてGAを迎えました。 ### 通常のActionsとの違いは決定的な処理か判断を伴う処理かの境界 [GitHubのドキュメント](https://docs.github.com/en/copilot/concepts/agent-capabilities/agent-powered-workflows-and-operations/about-github-agentic-workflows)は、事前に決めた手順を実行する通常のActionsと、自然言語の指示を文脈に応じて推論して実行するAgentic Workflowsを対比しています。向く用途として挙がっているのは、Issueのトリアージ、CI失敗の調査、定期レポートの作成です。 ビルドやテストのように毎回同じ結果を出すべき処理は、従来のYAMLのまま残します。Actionsの基本構文から整理したい場合は[GitHub Actionsのできること・使い方と最初のワークフロー](https://www.issoh.co.jp/column/details/3005/)が前提になります。 ### .mdと.lock.ymlの2ファイル構成とコンパイル時に入る検証 ワークフローは`.github/workflows/`に置く`.md`と、そこから生成される`.lock.yml`の2つで1組です。[公式クイックスタート](https://github.github.com/gh-aw/setup/quick-start/)は両方のコミットを求めています。Actionsが実際に読むのは`.lock.yml`なので、`.md`だけを直してプッシュしても動作は変わりません。 [セキュリティアーキテクチャの解説](https://github.github.com/gh-aw/introduction/architecture/)によると、コンパイル時にJSON Schemaの検証、式の安全性チェック、利用するアクションのSHA固定が入ります。`--actionlint --zizmor --poutine`を付ければ外部スキャナーも同時に走る仕組みです。レビューでは`.lock.yml`の差分も必ず見る運用にします。 ### 6つのジョブに分かれる実行の流れと読み取り専用のエージェント 1回の実行は、権限と期限を確かめるPre-Activation、イベント本文を無害化するActivation、AIを動かすAgent、出力を検査するDetection、書き込みを代行するSafe Output、結果をまとめるConclusionのジョブに分かれます。 Agentジョブは読み取り専用で、Issue作成なら`issues: write`、PR作成なら`contents: write`と`pull-requests: write`を持つのはSafe Output側だけです。ただし作成者が足したカスタムステップは「信頼されたコード」として扱われ、GITHUB\_TOKEN以外の認証情報には手が届きます。独自ステップにシークレットを渡す設計は避けます。 ## gh aw拡張のインストールから最初のワークフロー実行までの手順 前提は、書き込み権限のあるリポジトリ、Actionsの有効化、GitHub CLI v2.0.0以上、AIエンジンのアカウントの4点です。実行環境はLinux、macOS、WSL付きWindowsに限られます。 ### gh extension installによるCLI拡張の導入とサンプルの実行 リポジトリのルートで次を順に実行すると、公式サンプル「repo-status」が入り、手動で起動できます。ウィザードの途中でエンジンとシークレットを聞かれます。 ``` # 拡張の導入（gh auth login --scopes repo,workflow でログイン済みであること） gh extension install github/gh-aw # 公式サンプルを追加（.md と .lock.yml が .github/workflows/ に入る） gh aw add-wizard githubnext/agentics/repo-status # 本文やfrontmatterを編集したら再コンパイルして実行 gh aw compile gh aw run repo-status gh aw status ``` サンプルの原文は[githubnext/agentics](https://github.com/githubnext/agentics)にあり、トリアージや依存関係の管理、コードレビューの例も並んでいます。自作の前に、近い例を1本読んでおくと書き方の型がつかめます。 ### エンジン別シークレットの設定とCopilotの組織課金の条件 既定のエンジンはCopilot CLIで、利用にはCopilotライセンスが要ります。Claude、Codex、Geminiも選べ、それぞれ別のシークレットを登録します。 | エンジン（engine値） | シークレット | 課金先 | | ---------------- | ---------------------- | ------------ | | Copilot（copilot） | COPILOT\_GITHUB\_TOKEN | Copilotの課金 | | Claude（claude） | ANTHROPIC\_API\_KEY | Anthropic | | Codex（codex） | OPENAI\_API\_KEY | OpenAI | | Gemini（gemini） | GEMINI\_API\_KEY | Google Cloud | 組織リポジトリでは個人のトークンを置かずに済みます。[課金のリファレンス](https://github.github.com/gh-aw/reference/billing/)の条件は、Copilotポリシーでの組織課金の有効化、frontmatterの`permissions`への`copilot-requests: write`の明記、再コンパイルの3つです。コンパイラはこの権限を自動では足しません。Claudeで`claude login`由来のサブスクリプショントークンは使えない点も注意が要ります。 ## Issueトリアージを自作するfrontmatterの書き方とsafe-outputs ここでは、Issueが起票されたらラベルを付け、不足情報をコメントで尋ねるワークフローを例にします。キー名はすべて公式のfrontmatterリファレンスにあるものです。 ### Issue起票時にラベルとコメントを付けるワークフロー定義の実例 `.github/workflows/issue-triage.md`として保存し、`gh aw compile`を実行します。frontmatterが機械向けの設定、区切り線の下がエージェントへの指示です。 ``` --- on: issues: types: [opened] permissions: contents: read issues: read copilot-requests: write # 組織課金にする場合 engine: copilot tools: github: toolsets: [default] network: defaults max-ai-credits: 200 # 1実行あたりの上限（既定は1000） timeout-minutes: 10 safe-outputs: add-labels: max: 3 add-comment: max: 1 --- # Issue triage 新しく起票されたIssueを読み、既存ラベルから種類（bug / feature / question）を1つ選んで付けてください。 再現手順やバージョンが欠けている場合だけ、何が足りないかを1回コメントで尋ねてください。 推測で原因を断定したり、担当者を割り当てたりはしないでください。 ``` 指示文には「やらないこと」を書きます。エージェントは許された操作の範囲で最大限動こうとするため、禁止事項を書かないと毎回コメントを付けるような振る舞いになりがちです。 ### safe-outputsで書き込みを宣言しmaxで件数を絞る理由 [safe-outputsのリファレンス](https://github.github.com/gh-aw/reference/safe-outputs/)によると、エージェントは「この操作をしたい」という構造化出力を返すだけで、実行は権限を分けたジョブが担います。`safe-outputs:`を書かなかった場合でも`create-issue`が`max: 1`で自動的に有効になる仕様です。不要なら`create-issue: false`で明示的に止めます。 `max`は暴走時の被害上限そのものです。上の例ではラベル3件、コメント1件を超える書き込みは実行されません。PR作成やマージ系の出力は、トリアージ用途では宣言しないのが原則です。 ### networkとAgent Workflow Firewallによる外向き通信の制限 エージェントはコンテナ内で動き、HTTP/HTTPSはiptablesでSquidプロキシに転送されます。通してよい宛先は`network.allowed`に`defaults`、`python`、`node`や個別ドメインで列挙します。 Issue本文に「このURLへ環境変数を送れ」と書き込まれるプロンプトインジェクションを想定すると、宛先を絞る効果は大きくなります。パッケージ取得が要らないトリアージなら`defaults`だけに留め、ドメインの追加はレビュー対象にします。 ## 料金の内訳とgh aw forecastで月額AIクレジットを見積もる方法 費用はActionsの実行分数とAI推論費用の2系統で、請求書でも別々に表示されます。推論の単位はAI Credits（AIC）で、1 AICは0.01米ドルです。 ### Actions分数とAI Creditsの二重課金とジョブごとの所要時間 課金のリファレンスでは、事前ジョブが10〜30秒、agentジョブが1〜15分で、各ジョブに約1.5分のランナー準備時間が加わるとされています。[コスト管理のページ](https://github.github.com/gh-aw/reference/cost-management/)の目安では、週次ダイジェスト（月4回）が月約1分、Issueトリアージ（月20件）が約10分、忙しいリポジトリのPRレビュー（月100回）が約100分です。 分数の単価と無料枠はActions側の料金体系に従います。最新の単価は[GitHub Actionsの料金とドル建て利用枠の解説](https://www.issoh.co.jp/tech/details/16698/)で確認してください。推論費用は、Copilot以外のエンジンなら各プロバイダーの請求に載ります。 ### max-ai-creditsの既定1,000 AICと日次5,000 AICの上限ガード 既定のガードレールは1実行あたり1,000 AIC（10米ドル）、1ワークフロー1日あたり5,000 AIC（50米ドル）です。前者は`max-ai-credits`、後者は`max-daily-ai-credits`で変え、`max-turns`で反復回数も絞れます。脅威検出ジョブには別枠で既定400 AICの上限があります。 タイムアウトの既定はエージェントステップ20分、agentジョブ60分、検出ジョブ10分です。上限に当たると、Copilot利用時は「Authentication failed（HTTP 403）」と認証エラーのような表示になることがあります。課金トラブルを疑う前に上限設定を確認します。 ### gh aw forecastのP50とモンテカルロ予測の読み方と注意点 GAで`gh aw forecast`が実験扱いから外れ、脅威検出の消費と月次の幅も出るようになりました。[forecastの仕様書](https://github.github.com/gh-aw/specs/forecast-specification/)によると、過去30日（`--days`は7か30）の最大100実行を標本に、10,000回のモンテカルロ試行で週次と月次のAICを予測します。 ``` # 現在のリポジトリの全ワークフローを月次で予測 gh aw forecast # 月次の幅（P10〜P90）はJSONにしか出ない gh aw forecast --json | jq '.workflows[] | {workflow_id, monthly_monte_carlo}' ``` 端末の表に出る月次はP50（中央値）だけです。予算申請にはP90を使います。AICの観測が10件未満だとP10とP90の信頼性が低いという警告が出るため、導入直後の数字で月額を約束しないことが肝心です。なお仕様書自体は2026年10月30日時点で「Version 1.0.0, Draft」の表記です。 ## 受託開発の現場から見た業務の採用条件と見送るべきリポジトリの条件 判断の軸は「出力が誤ったとき、誰がいつ気付いて直せるか」です。気付ける仕組みがある作業から載せます。 ### 採用すべき業務はIssue仕分けとCI失敗の一次調査と定期レポート Issueのラベル付け、CIが落ちたときのログ要約、週次の活動レポートは、出力が誤っても人が数秒で直せます。safe-outputsも`add-labels`や`add-comment`で足り、コードへの書き込み権限を渡す必要はありません。月20件規模のトリアージなら、Actions分数は前述の目安で月10分程度に収まります。 コード修正までエージェントに任せたい場合は、Issueを渡してPRを返す[コーディングエージェントの型と主要ツールの比較](https://www.issoh.co.jp/tech/details/7036/)の領分です。gh awの`create-pull-request`はレビュー必須のブランチ保護と組にします。 ### 導入を見送る場面は本番デプロイ判断と外部入力の多い公開リポジトリ 本番デプロイの可否や、リリースノートを根拠にしたバージョン更新の自動マージには使いません。`merge-pull-request`はsafe-outputs上も実験的機能の扱いです。誤りが本番障害に直結する判断を確率的な推論に預ける理由がありません。 誰でもIssueを書ける公開リポジトリで、本文を広く読むワークフローも慎重に扱います。公式サンプルにも、公開リポジトリでは`lockdown: false`にすると第三者の書き込みを読める旨の注記が記載されていますので、設定の確認が必要です。Claude Codeを使う別方式との比較は[Claude Code GitHub Actionsの導入と料金](https://www.issoh.co.jp/tech/details/7094/)にまとめています。社内の業務フローにエージェントを組み込む設計から相談したい場合は、[一創のAIエージェント開発](https://www.issoh.co.jp/service/ai/agent/)で権限設計と費用見積もりを含めて支援しています。 ## よくある質問 導入前によく確認される点を5つにまとめました。 ### GitHub Agentic Workflowsは無料プランでも使えますか？ GAの告知では、github.com上のGitHub Free、Team、Enterpriseで利用できるとされています。ただし既定エンジンのCopilot CLIにはCopilotライセンスが必要です。ClaudeやCodexを選べばCopilot契約は不要ですが、各社APIの従量課金が発生します。Actionsの実行分数は、通常のワークフローと同じくリポジトリ所有者のActions料金体系で計上されます。 ### gh awとClaude Code GitHub Actionsはどう違いますか？ Claude Code GitHub ActionsはAnthropicが提供するActionで、YAMLの中でClaudeを呼び出します。gh awはGitHub製のCLI拡張で、Markdownからワークフロー全体を生成し、safe-outputs、脅威検出、通信の許可リストまでを標準で組み込みます。選べるエンジンはClaudeを含む4種です。書き込み権限を細かく分けたいならgh awが向きます。 ### .lock.ymlを手で編集してもよいですか？ 手で編集しないでください。`.lock.yml`は`gh aw compile`の生成物で、次のコンパイルで上書きされます。設定を変えたいときは`.md`のfrontmatterを直して再コンパイルし、生成された差分をレビューしてから両方をコミットする手順です。コンパイル時にはスキーマ検証やアクションのSHA固定も入るため、手編集はその検証を素通りさせることになります。 ### セルフホストランナーやARCでも動きますか？ GAで、Actions Runner Controller（ARC）のセルフホストランナーとDocker-in-Dockerでの実行に対応しました。ARCでは`runner.topology: arc-dind`を指定し、外向き通信の制御はiptablesではなくDockerネットワークの構成で行われます。社内ネットワークの資源を読ませたい場合の選択肢になりますが、許可リストの設計は自前で確かめる必要があります。 ### 1回の実行で使いすぎないようにするにはどうしますか？ frontmatterの`max-ai-credits`で1実行の上限を、`max-daily-ai-credits`で1日の合計を、`max-turns`で反復回数を絞ります。既定は1実行1,000 AIC、1日5,000 AICです。加えて`user-rate-limit`で、同じ利用者が一定時間内に起動できる回数も制限できます。実行後は`gh aw audit`で実際のトークン消費を確かめます。 ## 関連記事 - [GitHub Actionsとは？できること・使い方と最初のワークフロー、料金と上限](https://www.issoh.co.jp/column/details/3005/)：gh awが土台にするActionsの基本 - [GitHub Actionsの料金｜2026年10月のドル建て利用枠・分単価](https://www.issoh.co.jp/tech/details/16698/)：実行分数の単価と無料枠 - [Claude Code GitHub Actionsの導入と料金](https://www.issoh.co.jp/tech/details/7094/)：Actions上でAIを動かす別方式 - [Coding Agent（コーディングエージェント）とは？](https://www.issoh.co.jp/tech/details/7036/)：Issueから修正PRまで任せる型 - [AIエージェントとは？生成AIとの違い・仕組みと業務に組み込む判断基準](https://www.issoh.co.jp/column/details/12917/)：エージェントを業務に載せる前段の整理 --- 出典: [GitHub Agentic Workflowsとは：gh awの導入手順・料金・safe-outputs設計【2026年10月GA】]()（株式会社一創）