🤖 技術調査 - GitHub Agentic Workflows

調査日: 2026-06-13 / 対象: github/gh-aw（GitHub Agentic Workflows, 2026-06-11 public preview）
Issue 番号・状態は 2026-06-13 に gh api で一次照合済みです。

概要

GitHub Agentic Workflows（gh-aw） は、AI エージェントの作業を「チャット」から「GitHub Actions の権限境界の中」へ移す仕組みです。エンジニアは .github/workflows/<name>.md に、frontmatter（トリガー・権限・エンジン・ツール・出力ポリシー）と自然言語 Markdown 本文（エージェントへの指示）を書きます。これを gh aw compile（gh 拡張 CLI）が hardened な GitHub Actions YAML（<name>.lock.yml）へトランスパイルし、実行は通常の GitHub Actions runner 上で行います。2026-06-11 に public preview へ昇格しました（GitHub Next 由来の研究プロトタイプが起点。リポジトリは github/gh-aw、約 4,600 star、2026-06-13 取得）。

この二層構造（自然言語 DSL としての .md と Actions ランタイムの .lock.yml）の核心は、独自実行基盤を新設せず既存 Actions のイベント・権限・runner・課金にそのまま乗る点にあります。gh aw compile は決定論的なトランスパイラです。.lock.yml は通常の GitHub Actions ワークフローとして、PR レビュー・CODEOWNERS・runner group 設定をそのまま継承します。

最大の主張は "secure by default" です。エージェント本体のジョブは read-only に固定されます。書き込み（issue・PR・コメント・ラベル等）は permissions に直接与えず safe-outputs: に宣言し、write 権限を持つ別の下流ジョブが決定論的に検証してから実行します。この intent（エージェント＝意図生成・信頼しない）と execution（下流ジョブ＝検証して実行）の分離に、zero-secret sandbox・Agent Workflow Firewall（AWF）・post-execution threat detection を重ね、プロンプトインジェクションや機密持ち出しの被害範囲を構造的に絞り込みます。

本機能の位置づけは「エージェントを新基盤ではなく既存 CI/CD の権限境界に閉じ込める」という問題意識と一致します。ただし GitHub 自身が「非決定的なエージェントは core CI/CD に不適合」と明言し、additive 用途（issue triage・依存更新・ドキュメント生成等）にカーブアウトしています。「strict reproducibility を要する core build/release への適用は推奨しない」と docs で明示している点には留意が必要です。

特徴

• コンパイル方式（自然言語 DSL から hardened Actions YAML へ）: .github/workflows/<name>.md を gh aw compile が .lock.yml へ決定論的にトランスパイル。.lock.yml が commit 対象かつ実行対象で、md 編集のたびに再コンパイルが必要。独自ランタイムを持たず Actions runner にそのまま乗る方式。
• read-only 既定と safe-outputs による intent/execution 分離: エージェントジョブは read-only で動作し、直接リポジトリを変更しない。書き込み操作は safe-outputs: に宣言した種類・件数上限（max:）・対象スコープ（target:）内でのみ、下流の検証ジョブが適用。Filter Operations から Volume Limits、Content Sanitization の 3 段パイプラインを通過した artifact だけが GitHub に反映。
• zero-secret sandbox: LLM トークンは isolated API proxy 経由、認証材料は MCP Gateway の別 trusted container に隔離。エージェントコンテナは chroot jail に閉じ込め、host filesystem は read-only マウント、機密パスは tmpfs でマスク。エージェントは secret に一切触れない設計。
• Agent Workflow Firewall（AWF）: エージェントコンテナを Docker network に束縛し、iptables で HTTP/HTTPS を Squid proxy へリダイレクト。network: frontmatter の domain allowlist で egress を制限し exfiltration を防止。SSL bump で URL パス単位まで制御可能。
• post-execution threat detection: エージェントジョブ完了後、出力を artifact にバッファし、別の検知ジョブが AI で秘密漏洩・悪意コードパターン・ポリシー違反を解析。脅威を検知したら write が外部化される前にワークフローを停止。
• マルチエンジン対応（Copilot / Claude / Codex / Gemini）: engine: フィールドで AI エンジンを選択。既定は GitHub Copilot CLI（copilot-requests: write で PAT 不要、組織 Copilot 課金に集約）。Claude・OpenAI Codex・Google Gemini CLI を同一 Markdown フォーマットで差し替え可能。
• GitHub MCP ツール統合（18 toolsets）: tools.github.toolsets: で GitHub MCP の toolsets を指定（既定有効は context / repos / issues / pull_requests / users の 5 種）。web-fetch / bash / playwright / cache-memory 等のビルトインも利用可。カスタム MCP は stdio・Docker・HTTP の 3 方式。
• AI Credits ガードレール: per-run 予算 max-ai-credits（既定 1000 AIC = $10、enforced）で自動停止。日次ローリング max-daily-ai-credits は省略時は無効でフォールバック 5000 AIC（$50）のため明示設定が推奨。1 AIC = $0.01。
• 標準 Actions への乗り入れ: コンパイル後の .lock.yml は通常の GitHub Actions ワークフローのため、既存の runner group・CODEOWNERS・Actions ポリシー・Actions minutes 課金・audit log がそのまま機能。
• Public preview の位置づけ: 研究プロトタイプ（2025-08）から Technical Preview（2026-02-13）、Public Preview（2026-06-11）。公式 FAQ は "in Public Preview and may change significantly" と明記。GA 日程は公式未記載（2026-06-13 時点）。

構造

システムコンテキスト図

コンテナ図

コンポーネント図（Agent ジョブ内部）

コンポーネント図（safe-outputs パイプライン）

データ

概念モデル

情報モデル

Workflow トップレベルの主要フィールドを示します。

Engine ブロックの主要フィールドを示します。

GitHub MCP の 18 toolsets と既定有効 5 種を示します。

SafeOutput の主要種別と既定上限を示します。

AICredit の課金モデルを示します。

構築方法

前提と拡張インストール

gh aw は gh の拡張機能として動作します。先に GitHub CLI をインストールし認証を済ませます。

brew install gh   # macOS
gh auth login

# gh 拡張としてインストール
gh extension install github/gh-aw
gh aw version

初期化と最初のワークフロー作成

# リポジトリを agentic workflows 用にセットアップ
gh aw init

# 新規ワークフローの雛形を生成
gh aw new my-workflow

# 公開リポジトリからサンプルを追加
gh aw add githubnext/agentics/ci-doctor

Secret の設定

エンジン別に必要な secret を登録します。

# 個別設定
gh aw secrets set ANTHROPIC_API_KEY

# 不足 secret を自動検出してプロンプト
gh aw secrets bootstrap

エンジン別の必要 secret を示します。

frontmatter で secret を渡す例を示します。

engine:
  id: claude
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

コンパイルとコミット運用

.github/workflows/<name>.md から <name>.lock.yml（hardened Actions YAML）を生成します。.md を編集するたびに必ず再実行します。.lock.yml が実際に Actions を動かすファイルで、.md は人間向け DSL です。

# 全ワークフローをコンパイル
gh aw compile

# コンパイルせず全リンターで検証（lock 生成なし）
gh aw validate

.md（ソース）と .lock.yml（コンパイル済み）の両方をコミット対象にします（.lock.yml を .gitignore に入れない）。

git add .github/workflows/my-workflow.md .github/workflows/my-workflow.lock.yml
git commit -m "add: issue triage agentic workflow"
git push

サンプルファイル本文冒頭にも After editing run 'gh aw compile' とコメントが埋め込まれています。.md と .lock.yml のドリフト（#27140, CLOSED）は既知の運用負債のため、CI で gh aw validate を自動実行してズレを検出することを推奨します。

利用方法

ワークフロー定義ファイルの構造

.github/workflows/<name>.md は frontmatter（YAML）と自然言語 Markdown 本文の 2 部構成です。

.github/workflows/
  issue-triage.md       ← 作者が書く DSL
  issue-triage.lock.yml ← gh aw compile が生成する実行 YAML

frontmatter の主要フィールドを示します。

ワークフロー定義サンプル

スケジュール起動のバッチ Issue Triage の例を示します（githubnext/agentics より引用）。

---
description: |
  Scheduled daily triage that processes untriaged issues in batches.

name: Daily Issue Triage

on:
  schedule: daily
  workflow_dispatch:

permissions: read-all

network: defaults

safe-outputs:
  add-labels:
    target: "*"
    max: 500
  add-comment:
    target: "*"
    max: 100
  set-issue-type:
    target: "*"
    max: 100
  close-issue:
    target: "*"
    state-reason: "not_planned"
    max: 50

tools:
  web-fetch:
  github:
    toolsets: [issues, labels]
    min-integrity: none

timeout-minutes: 60
---

# Daily Issue Triage

You are a batch triage assistant for GitHub issues. Your task is to find untriaged issues in **${{ github.repository }}** and triage them one by one. ...

## Step 1: Find untriaged issues
Use the `search_issues` tool to find open issues that need triage.
Query: `repo:${{ github.repository }} is:issue is:open no:label`

イベント駆動の Issue Triage の例を示します（同じく引用）。

---
on:
  issues:
    types: [opened, reopened]
  reaction: eyes

permissions: read-all

network: defaults

safe-outputs:
  add-labels:
    max: 5
  add-comment:
  set-issue-type:
    max: 1
  close-issue:
    target: "triggering"
    state-reason: "not_planned"
    max: 1

tools:
  web-fetch:
  github:
    toolsets: [issues, labels]
    min-integrity: none

timeout-minutes: 10
---

# Issue Triage
（自然言語でエージェントへの指示を記述）

2 サンプルの対比ポイントを示します。schedule: daily と on: issues: [opened, reopened] でバッチかリアルタイムを切り替えます。reaction: eyes は agentic 拡張で、トリガー issue に 👀 を付けて受領を可視化します。target: "triggering" はトリガー issue のみに対象を絞ります。

トリガーの指定方法

# スラッシュコマンド: コメントで /investigate と書くと起動
on:
  slash_command:
    name: investigate
    events: [issues, issue_comment]

# スケジュール（人間向け表記 or cron 式）
on:
  schedule: daily

# 標準 Actions イベント
on:
  issues:
    types: [opened, reopened]
  workflow_dispatch:

safe-outputs / network / roles の指定例

# safe-outputs: read-only エージェントの唯一の書き込み経路
safe-outputs:
  add-labels:
    target: "*"      # "*" = 全対象 / "triggering" = トリガー元のみ
    max: 5
  add-comment:
    max: 1
  create-pull-request:
    max: 1

# staged モードで dry-run（実際には適用せず step summary に出力）
safe-outputs:
  add-comment:
    staged: true

# network: egress の制御
network:
  allowed:
    - "defaults"
    - "python"

# roles: トリガー許可ロール（完全一致 allowlist）
on:
  issues:
    types: [opened]
    roles: [admin, maintainer, write]

roles: [write] とすると admin もマッチせず拒否されます。roles は完全一致 allowlist であり権限の階層ではありません。通常は [admin, maintainer, write] を明示列挙します。

実行・観測コマンド

# GitHub Actions 上で即時実行してログ URL を返す
gh aw run my-workflow

# ログのダウンロードとツール使用パターン解析
gh aw logs my-workflow

# 1 run の詳細レポート（ターン数・トークン・AIC・safe-outputs の結末）
gh aw audit <run-id>

# 一時 private リポで本番前に試走（本番リポに影響なし）
gh aw trial ./my-workflow.md

# 全ワークフローの有効/無効・スケジュールを表示
gh aw status

段階導入の推奨フロー

gh aw trial（一時 private リポで試走）
  ↓
safe-outputs に staged: true で dry-run
  ↓
本番リポジトリへ限定スコープで投入
  ↓
gh aw audit / gh aw logs でコストと動作を確認しながら max / timeout / credits を調整

運用

コスト管理

AI Credits の単位と既定上限を示します。

# 上限を明示設定する最小 frontmatter 例（-1 無効化は禁止）
max-ai-credits: 1000
max-daily-ai-credits: 5000

# コスト観測コマンド
gh aw audit <run-id>      # ターン数・トークン・AIC・safe-outputs の結末
gh aw forecast <workflow> # 履歴からトークン使用量とコストを予測（experimental）
gh aw outcomes <workflow> # safe-outputs の結末追跡
gh aw logs <workflow>     # ログ DL とツール使用パターン解析

課金は 3 系統が独立します。①AI Credits（推論費、トークン提供アカウント負担で GitHub のスペンド保証なし）、②GitHub Actions 分（runner time）、③エンジン別 API キー。copilot-requests: write を付与すると GITHUB_TOKEN で Copilot 推論を組織課金に集約できます（2026-06-11 同時アナウンス）。

なお 1 AIC = $0.01 は推定コスト指標であり、実請求はトークンを提供した provider 側で確認する必要があります。また max-daily-ai-credits の省略時挙動は公式 docs 内で記述が割れており（Cost Management は 5000 AIC/day default、Frontmatter schema は「省略時は disabled」）、運用上は明示設定を推奨します。

gh-aw は automatic retry を持たないため（1 trigger = 1 run）retry 増幅はなく、コスト乗数は cron 頻度が主要因です。circuit breaker が無い（#28776）ため、高頻度 cron は手動で制御します。

可観測性

# OTLP エンドポイントへトレース送出
observability:
  otlp:
    endpoint: "https://otel-collector.example.com:4318"
    headers:
      Authorization: "${{ secrets.OTEL_AUTH_TOKEN }}"

gh aw health <workflow>   # 健全性・成功率メトリクス
gh aw domains <workflow>  # 設定済みネットワークドメイン一覧

更新とドリフト管理

# source: を設定すると gh aw update で upstream に追従
source: "githubnext/agentics/workflows/issue-triage.md@main"

gh aw update <workflow>   # upstream の変更を 3-way merge
gh aw fix <workflow>      # 非推奨フィールドを codemod で自動修正
gh aw compile             # md 編集後は必ず再コンパイル
gh aw validate            # lock を生成せず全リンターで検証

@main を source に使うと、.md と解決済み SHA の .lock.yml が非対称になりランタイムエラーになる実例があります（#27407, CLOSED）。更新後は必ず gh aw validate を実行します。

network least-privilege 設定例

# 最小権限の原則: defaults + 必要なエコシステムのみ
network:
  allowed:
    - "defaults"      # GitHub インフラ（git push / Actions API 等）
    - "python"        # PyPI など Python エコシステム

network: "*" や network.allowed: ["*"] は firewall を実質無効化するため禁止します。

ベストプラクティス

additive 用途に限定する

エージェントを権限境界に閉じ込めたとしても、品質ゲートや release gating には使えません。GitHub 自身が公式 blog と docs で "CI/CD needs to be deterministic, whereas agentic workflows are not" / "With agents, the process in between is intentionally non-deterministic" と明言しています。使ってよい用途は issue triage・定期 PR・依存更新・ドキュメント生成です（additive で、失敗しても人間がフォロー可能）。build/test の pass/fail 判定・release 可否判断・deploy gate には使いません。

roles は完全列挙する

roles: は権限の階層ではなく完全一致の allowlist です。[write] だと admin / maintainer はマッチせず拒否されます。通常コントリビューターを許可するなら [admin, maintainer, write] を全列挙します。利用可能ロールは admin / maintainer(=maintain) / write / triage / read / all です。

永続 memory への信頼を最小化する

永続 memory はサニタイザを通らずエージェントプロンプトに注入されます（#28775, OPEN / ASI-06）。悪意ある content が memory に混入するとクロスラン injection が成立します（#28830, OPEN）。memory を有効化する場合は書き込み元 workflow を信頼できるトリガーに限定します。untrusted な入力（外部コントリビューターの issue/PR/comment）が memory に書き込まれうる構成は避けます。memory は参考情報として扱い、必ず現ランタイム情報で検証します。

AI Credits 上限を明示設定する

max-ai-credits は -1 1 行で無効化できます。1 run で 4219 AIC を消費した runaway 実例もあります（#38809, CLOSED）。max-ai-credits と max-daily-ai-credits をすべての workflow で明示設定し、-1（無効化）はレビューなしの frontmatter コミットを禁止するポリシーを設けます。circuit breaker が無い（#28776, OPEN）前提で cron 頻度とクレジット上限を設計します。

段階導入する

gh aw trial（一時 private リポで試走）から safe-outputs を staged: true で dry-run、限定スコープで本番投入、gh aw audit で数回の run を確認してから全体展開、の順で blast radius を確認しながら広げます。

network は最小権限にする

network: "*" や network.allowed: ["*"] は AWF firewall を実質無効化します。network: defaults と必要なエコシステムプリセット（python / node / github）だけを追加し、不要な toolset を tools.github.toolsets で絞ります（既定有効は 5 種）。

トラブルシューティング

.md と .lock.yml のドリフト（#27140, CLOSED / #27407, CLOSED）

• 症状: "Lock file ... is outdated! ... frontmatter has changed" のランタイムエラーが出るが .md を編集した覚えがない。依存コンテナのバージョンが Actions で動いているものと .md の記述が違う。
• 原因: gh aw add ...@main が .md に @main を書き、.lock.yml は解決済み SHA で記録するため非対称になる（#27407）。container バージョン bump が .lock.yml へ自動伝播しない（#27140）。
• 対処: .md の floating ref を固定 SHA に変更し、gh aw compile で再コンパイル、gh aw validate で検証してから .lock.yml を commit。

21,000 文字式上限超過（#20719, CLOSED）

• 症状: Actions の workflow validation でエラーが出る。gh aw compile は成功するが GitHub Actions が workflow を起動しない。
• 原因: 生成された .lock.yml の式が GitHub Actions の 21,000 文字式上限を超える。多数の safe-outputs や mcp-servers を同一 workflow に詰め込むと発生しやすい。
• 対処: workflow を分割して safe-outputs の種類を減らす、mcp-servers の数を削減、不要な toolsets を無効化（tools.github.toolsets: [context, issues] のように最小限に）。

runaway エージェント（#38809, CLOSED / #28776, OPEN）

• 症状: 1 run が異常に長時間継続し高額 AIC を消費（実例: 244 turns / 12.3M tokens / 4219 AIC, #38809）。失敗しても次のイベントで起動し続ける（circuit breaker が無い, #28776）。
• 原因: circuit breaker 未実装（時間ベースの stop-after のみ）。max-ai-credits: -1 でガードレールが無効化されている。
• 対処: gh aw disable <workflow> で即時停止し、gh run cancel <run-id> で実行中 run をキャンセル、gh aw audit でコスト確認。

# 予防策
max-ai-credits: 500
max-daily-ai-credits: 2000
timeout-minutes: 15
engine:
  max-turns: 20      # 既定 500 は過大。明示的に絞る
on:
  stop-after: "+7d"
  schedule:
    - cron: "0 9 * * 1"

roles 完全一致の罠（admin が拒否される）

• 症状: /slash-command を打った admin や maintainer が "Permission denied" または無応答。
• 原因: roles: は完全一致の allowlist。[write] だと write のみ一致し admin / maintainer はマッチしない。
• 対処: roles: [admin, maintainer, write] を全列挙する。

AWF firewall escape（#10322, CLOSED / #4840, OPEN）

• 症状: エージェントが allowlist 外のドメインへ通信できてしまう。
• 原因（実証済み・修正済み）: #10322（CLOSED, 2026-01-17）で、safe-outputs の node:lts-alpine コンテナに docker exec で入ると AWF が適用されず外部に無制限 outbound できた。egress policy が全コンテナで一様に適用されていなかった。#4840（OPEN）でコンテナ IP がソースコードにハードコード。
• 対処: gh aw domains <workflow> で network 設定を確認。不審な outbound を発見したら即時 gh aw disable し Issue 報告。network: を least-privilege に保つことが予防策。

cache-memory / repo-memory クロスラン injection（#28775, OPEN / #28830, OPEN）

• 症状: エージェントが以前の run で書いた memory の内容に従って予期しない操作を実行。悪意ある content が memory 経由で連続 run に伝播。
• 原因: #28775（OPEN / ASI-06）で memory コンテンツはサニタイザを通らずプロンプトに注入される。#28830（OPEN）で汚染 run が instruction 形コンテンツを cache-memory に書き、次の run が content validation なしで auto-commit する（GitHub internal pentest が 4 連続日次 run で確認）。
• 対処: 当該 workflow を gh aw disable し、cache-memory の内容をリセット、review 後に再有効化。untrusted な入力を受け取る workflow では cache-memory / repo-memory を無効化する。

preview の破壊的変更（"may change significantly"）

• 症状: gh aw compile の実行時間が急に 2〜3 倍になる。gh aw upgrade 後に workflow が動かない。billing に影響するバグで使用中のリリースが retire 指定される（実例: 0.68.4〜0.71.3）。
• 原因: gh-aw は public preview で「may change significantly」と公式が明言。コンパイラや billing の実装は短期間で大きく変わりうる。
• 対処: retirement 対象バージョンを避けてアップグレード。engine version を明示 pin して破壊的変更を回避。更新前に gh aw trial で動作確認。

engine:
  id: copilot
  version: "0.0.422"   # 既定 "latest" の代わりに明示 pin

まとめ

GitHub Agentic Workflows は、自然言語 Markdown を hardened な GitHub Actions YAML にコンパイルし、AI エージェントを read-only 既定・safe-outputs・sandbox・firewall・threat detection の権限境界に閉じ込める仕組みです。設計思想は「新基盤を作らず既存 CI/CD の権限境界に閉じ込める」という方向で妥当ですが、非決定性ゆえに core CI/CD gating には不適合で、memory 経路の injection や preview の破壊的変更といった限界を理解した上で additive 用途から段階導入するのが現実的です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント
  • GitHub Agentic Workflows docs
  • frontmatter リファレンス
  • engines リファレンス
  • triggers リファレンス
  • tools リファレンス
  • safe-outputs リファレンス
  • network / firewall リファレンス
  • permissions リファレンス
  • AI Credits 仕様
  • CLI セットアップ
  • FAQ
• GitHub
  • 本体リポジトリ github/gh-aw
  • Firewall 実装 github/gh-aw-firewall
  • サンプル集 githubnext/agentics
  • GitHub Next プロジェクトページ
• 記事
  • GitHub Changelog: public preview（2026-06-11）
  • GitHub Changelog: technical preview（2026-02-13）
  • セキュリティアーキテクチャ深掘り
  • 非決定性と CI/CD
    </content>