GitHub Agentic Workflows（gh-aw）徹底ディープダイブ — 自然言語で書く「Continuous AI」の全貌

1. はじめに

GitHub Actions の YAML ワークフローは、決められた手順を毎回同じ形で実行する仕組みです。しかし「Issue のトリアージ」や「ドキュメントの追従」のように、状況に応じて判断が必要なタスクは、従来の YAML では表現しづらいのが実情でした。

GitHub Agentic Workflows（gh-aw） は、この種のタスクを自然言語 Markdown で記述し、コーディングエージェントに実行させる GitHub Next 発のテクニカルプレビューです。本記事では、アーキテクチャ・セキュリティ設計・CLI コマンド・コスト・導入手順までを一次情報に基づいて整理します。

TL;DR

• GitHub Agentic Workflows（gh-aw） は、エージェントの振る舞いを自然言語 Markdown で書き、GitHub Actions のワークフロー（.lock.yml）にコンパイルして、コーディングエージェントで実行する仕組み。GitHub Next 発のテクニカルプレビュー（GitHub × Microsoft Research × Azure Core Upstream）[^how-they-work]。
• ねらいは Continuous AI ＝ CI/CD のように AI をソフトウェア開発プロセスへ継続的に組み込むこと。CI/CD を置き換えず補完する[^continuous-ai]。
• .md が編集対象の source of truth、.lock.yml がコンパイル済み実体。gh aw compile で生成し、両方をコミットする[^how-they-work]。
• エンジンは Copilot（既定）/ Claude / Codex / Gemini を差し替え可能。トリガーは標準の GitHub Actions 仕様（schedule の cron を含む）＋ gh-aw 独自拡張[^engines-ref][^frontmatter-ref]。
• セキュリティは 多層防御。エージェントは既定で read-only、書き込みは safe-outputs 経由でスコープ付き別ジョブが実行。ネットワークは AWF（Agent Workflow Firewall） で egress 制御し、脅威検知ジョブが書き込み前に出力を AI 分析する[^security-arch]。
• コストは Copilot 既定で 1 実行あたり約 2 premium requests（エージェント本体＋ガードレール）。max-ai-credits などで上限管理できる[^how-they-work]。

2. GitHub Agentic Workflows とは

GitHub Agentic Workflows（以下 gh-aw）は、「望む結果を平易な Markdown で記述し、それをリポジトリの自動ワークフローとして追加すると、GitHub Actions 上のコーディングエージェントが実行してくれる」という仕組みです。従来の YAML ワークフローが「決められた手順を毎回まったく同じに実行する」のに対し、gh-aw は AI が文脈を解釈し、状況に応じて判断・生成する agentic（自律的判断を持つ） な実行を、Actions のインフラ（権限・ログ・監査・サンドボックス）の上で行います。

GitHub はこの方向性を Continuous AI と呼びます。CI/CD が統合・デプロイを継続的に自動化したのと同様に、AI をソフトウェアコラボレーションへ継続的に織り込む、という位置づけです。重要なのは、CI/CD を置き換えるものではなく補完する点です。ビルド・テスト・リリースといった決定論的パイプラインはそのままに、「トリアージ」「ドキュメント追従」「継続的なテスト改善」など、従来の YAML では表現しづらい主観的・反復的なタスクを担います。

gh-aw は GitHub Next の研究から始まり、現在は GitHub 公式組織 github/gh-aw で テクニカルプレビューとして公開されています（MIT ライセンス、GitHub・Microsoft Research・Azure Core Upstream の協働）。

従来のリポジトリ自動化との位置づけの違いは次の通りです。

本番利用の注意: テクニカルプレビューであり、リソース制限・ツールの信頼性・評価・安全性に「鋭いエッジ」が残ります。低リスクなタスクから、最小権限で慎重に導入するのが前提です。

3. アーキテクチャ全体像

gh-aw の核心は「自然言語 → GitHub Actions へのコンパイル」です。

• .md（source of truth）: 人間が編集する自然言語ワークフロー。frontmatter（YAML 設定）＋ Markdown 指示。
• .lock.yml（コンパイル済み）: gh aw compile が生成する GitHub Actions ワークフロー。スキーマ検証・式の安全性チェック・アクションの SHA ピン留め・セキュリティスキャンを経てセキュリティ強化された実体。両ファイルをコミットする。
• 実行エンジン: Actions ランナー上でコーディングエージェント（既定は Copilot CLI）が指示を解釈し、ツールと権限の範囲で実行する。

「YAML の代わりに Markdown を書く」だけでなく、Actions のエコノミクス（リポジトリ中心・チームで可視・監査可能・シークレット・環境・トリガー・ジョブ制御）をそのまま継承するのが設計思想です。

4. ワークフローの構造 — frontmatter と自然言語

各ワークフローは 2 部構成です。以下は公式の「デイリーリポジトリレポート」の例です。

---
on:
  schedule: daily

permissions:
  contents: read
  issues: read
  pull-requests: read

safe-outputs:
  create-issue:
    title-prefix: "[repo status] "
    labels: [report]

tools:
  github:
---

# Daily Repo Status Report

メンテナー向けのデイリーステータスレポートを作成してください。

含める内容:

- 直近のリポジトリ活動（issue / PR / discussion / release / コード変更）
- 進捗トラッキング、ゴールのリマインド、ハイライト
- プロジェクト状況と推奨事項
- メンテナーが取るべき次アクション

簡潔にまとめ、関連する issue / PR にリンクしてください。

• frontmatter（--- の間の YAML）: トリガー・権限・ツール・許可された出力を明示的に宣言する。
• Markdown 指示: やってほしいことを自然言語で書く「意図（intent）」。

「意図は Markdown、境界（トリガー・権限・ツール・出力）は前もって明示」という分離が、柔軟さと安全さを両立させます。主要なフロントマター要素は次の通りです。

5. トリガー（on:）— スケジュールとイベント

on: は標準の GitHub Actions 構文をそのまま使えます。push / pull_request / issues / schedule（cron）/ workflow_dispatch などに加え、gh-aw 独自の安全・承認制御が追加されています。

代表的な gh-aw 拡張:

• schedule: schedule: daily のような簡易表記に加え、標準の cron（- cron: "0 9 * * 1"）も利用可能
• stop-after:: 期限を過ぎたらトリガーを自動的に無効化（暴走・コスト暴発の防止）
• roles:: ワークフローを起動できるリポジトリロールを制限（既定 [admin, maintainer, write]）
• reaction:: トリガー元の issue/PR に絵文字リアクションを付与
• status-comment:: 開始／完了コメント（実行へのリンク付き）を投稿
• manual-approval:: 環境保護ルールによる手動承認を要求
• コマンドトリガー: slash_command（/foo）や label_command（ラベル付与で起動）による ChatOps 的な起動
• skip-if-match: / skip-if-no-match:: 検索クエリの一致有無で実行をスキップ

---
on:
  schedule:
    - cron: "0 9 * * 1" # 毎週月曜 9:00 UTC
  stop-after: "2026-12-31"
  roles: [admin, maintainer]
---

イベント本文（issue タイトルや PR 本文）はサニタイズを経てからエージェントへ渡されます（後述のセキュリティ参照）。

6. エンジン（engine:）— Copilot / Claude / Codex / Gemini

gh-aw はエンジン非依存です。engine: と対応するシークレットを設定するだけで、自然言語ワークフローを書き換えずにエンジンを差し替えられます。

このほか実験的に crush / opencode / pi もサポートします。engine: を省略すると既定の Copilot が使われます。

拡張構成では、モデル指定・CLI バージョンのピン留め・カスタムエンドポイント（GHEC/GHES の api-target）・BYOK（外部 LLM プロバイダーへのルーティング）なども可能です。

---
engine:
  id: copilot
  model: gpt-5 # 省略時はエンジン既定
  version: "0.0.422" # 再現性のためピン留め
---

エンター­プライズ／Azure Foundry OpenAI 連携や BYOK では、資格情報は AWF の API プロキシ側に隔離され、エージェントコンテナにはダミーキーのみが見える設計になっています。

7. ツールと MCP

tools: は、エージェントが使える GitHub API 呼び出し・bash コマンド・ブラウザ操作・MCP サーバーを宣言します。ツールは Model Context Protocol（MCP） 経由で提供されます。

---
tools:
  github:
    toolsets: [default] # GitHub の読み取り系ツールセット
  edit: # ファイル編集
  bash: ["gh issue comment", "npm test"] # 許可コマンドを allowlist
  web-fetch:
  web-search:
---

• github:: GitHub の読み取り操作（issue/PR/コミット検索など）。ツールセット単位で有効化
• bash:: 実行を許可するコマンドのallowlist（明示したものだけ）
• edit: / web-fetch: / web-search: / playwright: など組み込みツール
• MCP サーバー: mcp-servers: で外部 MCP（例: Notion）をコンテナとして追加し、allowed: で使えるツールを絞り込み

MCP サーバーは隔離コンテナで実行され、ツールフィルタリングで公開操作を限定します。危険な操作（例: delete_repository）はブロックし、必要なもの（例: issue_read, search_code）だけを許可します。

エージェントの egress（外部通信） は network: の allowlist で制御します。エコシステム識別子（defaults / node / python など）とカスタムドメインを列挙し、firewall: true で AWF（後述）による遮断を有効化します。

---
network:
  firewall: true
  allowed:
    - defaults # 基本インフラ
    - node # npm エコシステム
    - "api.example.com" # 追加で許可するドメイン
---

8. safe-outputs — 書き込み権限分離の中核

gh-aw のセキュリティ設計で最も重要なのが safe-outputs です。エージェント本体は書き込み権限を一切持たず read-only で動作し、create-issue や create-pull-request などの書き込みは、エージェント完了後に**別ジョブ（スコープ付き最小権限）**が実行します。

---
permissions:
  contents: read # エージェントは読み取りのみ
safe-outputs:
  create-issue:
    title-prefix: "[triage] "
    labels: [needs-triage]
  add-comment:
  create-pull-request:
---

仕組みはこうです。エージェントの「やりたい書き込み」は即時に適用されず、いったん成果物（artifact）としてバッファされます。その後、設定された決定論的なフィルタ列（件数などの構造的制約・ポリシー適用・シークレット混入のサニタイズ）を通過し、最後の段でのみ外部へ反映されます。これにより、エージェントが完全に乗っ取られても、リポジトリを直接書き換えることはできません。

そして重要な運用原則として、PR は自動マージされません。人間が必ずレビュー・承認します。

9. セキュリティアーキテクチャ — 多層防御

gh-aw は「暗黙の信頼より明示的な制約」を貫く defense-in-depth（多層防御） を採用します。脅威モデルは「コンテナ等のユーザーレベル構成要素が侵害され、与えられた権限内で任意に振る舞う敵」を想定します。信頼は 3 層に整理されます。

9.1 ジョブ実行フロー

各ステージ境界でセキュリティチェックが挟まります。

主要な防御コンポーネント:

• AWF（Agent Workflow Firewall）: エージェントをコンテナ化し、iptables で HTTP/HTTPS を Squid プロキシへリダイレクト。network.allowed のドメイン allowlistで egress を制御し、データ持ち出しを防ぐ。host バイナリを使うための chroot モードも提供。
• MCP Gateway: MCP サーバーを隔離コンテナで起動し、通信を信頼境界内に閉じ込める。
• 脅威検知ジョブ: エージェント完了後、バッファされた出力・パッチ・コンテキストをセキュリティ特化プロンプトの AI（＋任意で Semgrep / TruffleHog 等）で分析。シークレット漏洩・悪性パッチ・ポリシー違反を検知したら書き込み前にワークフローを失敗させる。
• コンテンツサニタイズ: 外部由来テキストを正規化（@mention 無効化、<script> → (script) 変換、HTTPS 以外の URI ブロック、Unicode 正規化、0.5MB/65k 行の上限など）。プロンプトインジェクション対策の要。
• integrity filtering: 著者の信頼レベル・マージ状態でエージェントが見られる GitHub コンテンツを制限（public repo では min-integrity: approved が自動適用）。
• シークレット冗長化（redaction）: 成果物アップロード前に /tmp/gh-aw を走査し、シークレット値をマスク（if: always() で失敗時も保護）。
• コンパイル時セキュリティ: スキーマ検証・式の allowlist・アクション SHA ピン留め・スキャナ（actionlint / zizmor / poutine）。strict モードでは write 権限やワイルドカードドメイン等を拒否。

10. CLI コマンド

gh 拡張として提供され、主なコマンドは次の通りです。

# 拡張のインストール
gh extension install github/gh-aw

# .md → .lock.yml へコンパイル（スキーマ検証・SHA ピン留め・スキャン込み）
gh aw compile
gh aw compile --watch                      # 編集を監視して自動再コンパイル
gh aw compile --actionlint --zizmor --poutine  # 追加スキャナを有効化

# 外部リポジトリからワークフローを追加
gh aw add

# 手元から実行・観測
gh aw run                                  # 手動実行
gh aw logs                                 # 実行ログ・トークン使用量の取得と分析
gh aw audit <run-id>                       # 特定実行の詳細調査（プロンプト・ネットワーク等）
gh aw status                               # ワークフローの健全性・一覧

gh aw logs / gh aw audit は、agent_output.json（AI の判断・アクション）、prompt.txt（生成プロンプト）、aw.patch（コード差分）、エンジンログ、ファイアウォールログといったアーティファクトを通じた観測を可能にします。

11. コストとガードレール

gh-aw は実行時にコーディングエージェントを使うため課金が発生します。Copilot を既定設定で使う場合、1 実行あたり典型的に 2 premium requests（エージェント本体の作業に 1、safe-outputs のガードレールチェックに 1）を消費します。モデル選択で調整可能です。

コスト・暴走対策のガードレール:

• max-ai-credits:（既定 1000）: AWF の AI クレジット予算。80/90/95/99% でステアリング警告。-1 で無効化
• max-daily-ai-credits:: ワークフロー単位の 24 時間キャップ。超過時はエージェントジョブをスキップし issue で通知
• max-turns:（既定 500）: 全エンジン共通の AWF 呼び出し上限（invocation cap）。加えて Claude はネイティブの反復（turn）制御に、Copilot は max-continuations（autopilot）に対応
• timeout-minutes:（既定 20）: ジョブの実時間上限
• stop-after:: 期限後にトリガーを自動無効化

12. 設計パターン（〜Ops）

公式ドキュメントは再利用可能な設計パターンを多数提供します。用途に応じて選び、リミックスできます。

代表的なユースケースは、継続的トリアージ、ドキュメント追従、コード簡素化 PR、テストカバレッジ改善、CI 失敗の調査と修正提案、リポジトリの健全性レポートなど、「反復的・協調的・監査可能で、単純なヒューリスティックでは表せない」タスクです。

13. 他のスケジュール実行手段との使い分け

前記事で挙げた 4 つのスケジュール実行手段の中で、gh-aw は「チームで監査可能な Continuous AI」に位置づけられます。

「素の Actions YAML に Copilot/Claude CLI を直接埋め込む」方法もありますが、その場合エージェントに必要以上の権限を与えがちです。gh-aw は既定 read-only ＋ safe-outputs により、より強い制約・明確なレビューポイント・強力な統制を提供します。

14. 導入手順

# 1) gh 拡張をインストール
gh extension install github/gh-aw

# 2) ワークフローを作成（AI に作らせるのが簡単）
#    お気に入りのコーディングエージェントに以下を依頼:
#    「メンテナー向けのデイリーレポートを作るワークフローを生成して。
#      https://github.com/github/gh-aw/blob/main/create.md の手順を使って」
#    → .github/workflows/daily-repo-status.md が生成される

# 3) コンパイルして .lock.yml を生成
gh aw compile

# 4) 必要なシークレットを追加（エンジンのトークン等）、コミット＆プッシュ
git add .github/workflows/daily-repo-status.md .github/workflows/daily-repo-status.lock.yml
git commit -m "Add daily repo status agentic workflow"
git push

.md（意図）と .lock.yml（実体）の両方をコミットするのがポイントです。以降は Actions が自動実行、または手動トリガーで走ります。

15. ベストプラクティスと制約

ベストプラクティス

• **完璧なプロンプトより「ゴールと望む出力」**に集中する。何が成功かを明確にし、達成方法はエージェントに委ねる
• 低リスクな出力から始める（コメント・ドラフト・レポート → 慣れてから PR 作成）
• コード変更はゴール指向の改善（リファクタ・テスト・簡素化）から。いきなり機能開発はしない
• 人間をループに残す。PR は自動マージせず必ずレビュー
• ワークフロー Markdown をコードとして扱う。小さく保ち、変更をレビューして意図的に育てる
• CI/CD の代替にしない。決定論的パイプラインは YAML のまま、gh-aw は主観的・反復的タスクに使う

主な制約

• Linux ランナー専用（ubuntu-latest など）。AWF が Docker を要するため macOS / Windows ランナーは非対応
• テクニカルプレビュー。仕様・挙動は変化しうる
• public リポジトリでは strict モードが必須（strict: false は public では実行不可）
• 実行時課金あり（前述のコスト管理を活用）

16. まとめ

GitHub Agentic Workflows（gh-aw）は、「自然言語で書く GitHub Actions」という発想で、コーディングエージェントをリポジトリ自動化の中心に据える仕組みです。要点は次の通りです。

• .md（意図）→ gh aw compile → .lock.yml（実体） というコンパイル型。Actions の監査性・権限モデルを継承
• エンジン非依存（Copilot/Claude/Codex/Gemini）で、ワークフローはポータブル
• 既定 read-only ＋ safe-outputs ＋ 多層防御（AWF・MCP Gateway・脅威検知・サニタイズ） により、継続実行を「実験」ではなく「実務」にできる
• Continuous AI として CI/CD を補完し、トリアージ・ドキュメント・テスト・レポートなど反復タスクを自動化

まずは低リスクなレポート系ワークフローを 1 本、最小権限で導入し、gh aw logs / gh aw audit で挙動を観測しながら育てていくのが、失敗の少ない始め方です。

17. 参考情報

17.1 参考リンク

• GitHub Agentic Workflows ドキュメント（github.github.io/gh-aw）
• How They Work
• Security Architecture
• Frontmatter リファレンス
• AI Engines リファレンス
• Safe Outputs リファレンス
• Quick Start
• github/gh-aw（リポジトリ）
• GitHub Blog: Automate repository tasks with GitHub Agentic Workflows
• GitHub Blog: Under the hood — Security architecture of GitHub Agentic Workflows
• GitHub Next: Continuous AI

17.2 脚注（出典詳細）

[^how-they-work]: How They Work — GitHub Agentic Workflows documentation. https://github.github.io/gh-aw/introduction/how-they-work/ （2026-07-01 確認）

[^continuous-ai]: GitHub Next: Continuous AI. https://githubnext.com/projects/continuous-ai/ （2026-07-01 確認）

[^engines-ref]: AI Engines リファレンス — GitHub Agentic Workflows documentation. https://github.github.io/gh-aw/reference/engines/ （2026-07-01 確認）

[^frontmatter-ref]: Frontmatter リファレンス — GitHub Agentic Workflows documentation. https://github.github.io/gh-aw/reference/frontmatter/ （2026-07-01 確認）

[^security-arch]: Security Architecture — GitHub Agentic Workflows documentation. https://github.github.io/gh-aw/introduction/architecture/ （2026-07-01 確認）

この記事の執筆にあたり、AI の支援を受けています。掲載内容は調査日時点の公式ドキュメント（テクニカルプレビュー）に基づきます。仕様は更新される可能性があるため、実装前に最新の公式情報をご確認ください。