GitHub Agentic Workflowsとは？Markdownで書く自動化をAIに任せる仕組み

この記事のまとめ

GitHub Agentic Workflowsは、Markdownで記述した自動化の指示をGitHub Actionsのワークフローへ変換して実行する仕組みです。GitHub Nextのオープンソースプロジェクトとして一般提供が開始され、Issueのトリアージやログ調査など、推論を要する作業をコーディングエージェントに任せられます。ここでは3つの重要ポイントに絞って要点を整理します。

自然言語の指示でエージェントが文脈を読み取って動きますが、トリガーや権限、安全な出力などのガードレールはフロントマターで設定します。
リポジトリ権限はデフォルトで読み取り専用となっており、書き込みは宣言済みのsafe-outputsを経由し、脅威検出スキャンを経てから反映されます。
コストはActionsの実行時間とAIエンジンの推論コストで構成され、AI Creditsという共通指標で一括管理できます。

GitHub Agentic Workflowsとは

仕組みと従来の自動化との違い

GitHub Agentic Workflowsは、Markdownで定義した自動化をGitHub Actionsのワークフローとして実行する、AI搭載のリポジトリ自動化機能です。一言で言えば、「自然言語で書いた指示書をAIが読んで、Actionsを動かす」仕組みです。

固定のif-thenルールで稼働する従来の自動化と異なり、エージェント型ワークフローはコーディングエージェントを活用して状況を把握します。状況を適切に評価し、自然言語の指示に沿って有用なアクションを提案する点が根本的に違います。従来のYAMLベースのActionsは「何をするか」を逐一書く必要がありましたが、Agentic Workflowsは「何を達成してほしいか」を書けば、エージェントが手順を補完します。

従来のワークフローが定型の作業手順をそのままなぞるのに対し、文脈に応じた推論によって指示を柔軟に実行する点が特徴です。なおトリガー、権限、安全な出力といったガードレールは、引き続きフロントマターで定義します（参照*1）。

当プロジェクトは、従来のCI/CDを置き換えるのではなく補完するものとして設計されています。ビルド、テスト、デプロイといった定型作業は通常のActionsに任せ、課題のトリアージ、プルリクエストのレビュー、CI失敗の調査、ドキュメントの保守、依存関係の分析、リポジトリのレポート作成など、状況判断が必要な作業をエージェントに委託します（参照*2）。私がAI活用の現場で繰り返し目にする構図と同じです。「正解が決まっている仕事はツールに、判断が必要な仕事は知性に」という分担です。

一般提供の内容と利用条件

GitHub Nextのオープンソースプロジェクトとして、GitHub Agentic Workflowsの一般提供が正式に開始されました。

エージェント型ワークフローを導入すれば、GitHub Actionsの実行環境内でコーディングエージェントを動かせます。Issueのトリアージ、CI失敗の分析、ドキュメントの更新、テストの作成といった、高度な推論を伴うタスクの自動化が可能です。

提供範囲はgithub.comのGitHub Free、Team、Enterpriseとなっています。なお、デフォルトのGitHub Copilot CLIエンジンでワークフローを動かす場合は、Copilotライセンスが必要です（参照*3）。

自動化の処理内容は、自然言語で記述したMarkdownファイル内に定義します。GitHub Agentic Workflowsがそれを標準的なActionsのYAMLへとコンパイルします。

GitHub Actions基盤上で稼働するため、既存のランナーグループや各種ポリシー制約をそのまま適用可能です。各ワークフローを動かすエンジンには、GitHub Copilotのほか、独自のコーディングエージェントも選択できます（参照*3）。

対応エンジンと必要な準備

利用を始めるにあたって必要なものは3つあります（参照*1）。

対象リポジトリで有効化されたGitHub Actions
GitHub Copilot、Anthropic Claude、OpenAI Codex、Google GeminiといったAIエンジン（エージェント）のアカウント
導入済みで認証が完了しているGitHub CLI

ワークフローは異なるエンジン間でも移植可能です。Claude、Codex、Gemini、Piなどで動かす場合は、ワークフローのフロントマターにある engine: の指定を書き換え、対象エンジンの認証シークレットを登録します。ただし engine.agent や engine.harness などのエンジン固有オプションは移植できない仕様です（参照*4）。

ワークフローの書き方と実行の流れ

フロントマターとMarkdown本文の役割

ワークフローの定義ファイルは、構成を設定するフロントマターと、指示を記述するMarkdown本文の2要素から構成されます。

フロントマターは — で囲まれたYAML形式です。ここではワークフローの起動タイミング、権限、許可する書き込み操作などを指定します。Markdown本文側には、AIエージェントに実行させる自然言語の指示を記述します（参照*1）。

日次レポートの構成例では、フロントマターに on: daily を指定し、permissions に contents: read、issues: read、pull-requests: read、copilot-requests: write を列挙します。さらに network: defaults、tools の github 配下に toolsets: [default]、safe-outputs に create-issue を設定します。本文には Daily Repo Status Report という見出しのもと、Issue、プルリクエスト、ディスカッション、コード変更といった直近の動向を調査する指示を記載します（参照*1）。

コンパイルから実行までの手順

作成から実際の実行までは、ファイル定義、コンパイル、コミット、実行という4つのステップで進みます（参照*1）。

まず、YAMLフロントマターとMarkdown形式の指示を含んだ .md ファイルを作成します。
次に、そのMarkdownワークフローファイルを、GitHub Actions形式のワークフローファイルである .lock.yml へコンパイルします。
続いて両方のファイルをリポジトリのデフォルトブランチへコミットしプッシュします。
最後に、設定したトリガー経由やリポジトリのウェブUIから、通常のActionsワークフローと同様に実行します。GitHub CLIから手動実行することも可能です。

なお、ロックファイルの整合性には配慮が必要です。ワークフローのロックファイル（.lock.yml）がソースとなるMarkdownファイル（.md）と一致していない場合、GitHub Actionsで処理されるワークフローに最新設定が反映されなくなります（参照*5）。

主なCLIコマンド

日々の開発・運用作業では、初期化、コンパイル、実行、デバッグの各コマンドを必要に応じて使い分けます。

リポジトリをエージェント型ワークフロー向けに初期化するコマンドは gh aw init です。ワークフローのロックファイルを生成する際は gh aw compile [workflow-name] を用います。ワークフローの実行は gh aw run <workflow-name> –ref REVIEWED_REF で行いますが、debug-agentic-workflow.md に準拠して許可され、人のレビューを通過している場合に限定して実行することが求められます（参照*6）。

実行状況の詳細を追跡したい場合のために、デバッグ用コマンドも提供されています。gh aw logs [workflow-name] –repo HOST/OWNER/REPO や gh aw audit <run-url> を活用することで、ワークフローの挙動をデバッグできます（参照*6）。

向いているタスクとCI失敗分析の型

推論が必要なタスクの例

エージェント型ワークフローが得意とするのは、文脈の解釈や原因調査が求められる作業です。逆に言えば、ルールが完全に決まっていて例外が存在しない作業には、従来のActionsのほうが向いています。

自動化の適用例としては、投稿されたIssueの内容を読み取って分類し、種別や優先度に応じたラベルを付与する作業が挙げられます。このほか、CI失敗時の原因調査と修正案の提示、リポジトリ現況レポートの日次・週次作成、コード修正に合わせたドキュメントの保守、テストカバレッジの向上施策などが想定されています（参照*1）。

出力の受け渡し方法もあらかじめ定まっています。エージェント型ワークフローは、Issue、コメント、プルリクエストなど人がレビューできる成果物を生成します。最終的な承認やマージ作業は、引き続き人間側の判断で管理します（参照*1）。この設計は重要で、AIが「候補を生成する」段階と、人間が「承認する」段階を明示的に分けているからこそ、業務に組み込みやすくなっています。

CI失敗分析ワークフローの構成

CI失敗の分析では、ログの精査から原因の切り分け、情報の記録までを3つの手順で進めます（参照*7）。

まず対象の実行結果を調べてジョブ一覧を取得します。
次に失敗したジョブのログを抽出し、最も早い段階で失敗したジョブ、および二次的なエラーではなく根本的な初発エラーに着目して調査を進めます。後続のエラーは単なる派生結果の可能性があるためです。
そのうえで失敗ジョブとステップ名、主要エラーメッセージ、関連ファイルパス、該当行番号、テスト名、依存バージョン、発生タイミングなどの情報を記録します。

指示の書き方にも配慮が盛り込まれています。ログに基づいて根本原因と付随的な症状を明確に区別し、不確かな推測を確定事実として提示しないよう指示します。確信度は高・中・低の3段階で示させ、判断が曖昧な場合はどのような証拠があれば立証できるかを説明させます（参照*7）。AIに「わからないことはわからないと言え」と明示するのは、プロンプト設計の基本です。この点が抜けると、AIは尤もらしい誤情報を堂々と提示します。

入力データの取り扱いに関する原則も明記されています。ログ、Issue本文、コミットログ、リンク先コンテンツなどは信頼できないデータとみなし、そこに紛れ込んだ指示に従ったり、抽出したコードを安易に実行したりしないよう制御します（参照*7）。これはプロンプトインジェクション対策の発想で、外部から入ってくるデータと、自分が与えた指示を明確に分離する設計です。Webアプリのサニタイズと同じ問題意識が、LLMの世界でも必要になっています。

自リポジトリ向けにカスタマイズする手順も整備されています。ci-doctorは標準でmainブランチ上のCIワークフロー失敗を監視するため、用途に応じて on.workflow_run.workflows や on.workflow_run.branches を調整します。修正後は gh aw compile を実行し、Markdownワークフローと生成されたロックファイルの両方をデフォルトブランチへコミットします（参照*8）。

導入時の始め方

導入初期は、設定を段階的に検証しながら、権限や出力先を必要最小限に絞って運用を始めるのが推奨アプローチです。私がAI導入支援の現場で常に言うことと同じで、「まず小さく動かして、動作を確認してから拡張する」という原則です。

ワークフローを有効化する前に、トリガー、AIエンジンの認証、利用ツール、ネットワークアクセス、各種権限、安全な出力の定義を点検します。Markdownソースを gh aw compile でコンパイルし、.md ファイルと生成された .lock.yml ファイルの両方を入念に確認します。そのうえで、タスク遂行に必要な範囲内で最も限定された権限と出力設定から使い始めることが推奨されます（参照*4）。

紹介記事によると、CI Doctorは失敗したワークフローを分析して診断用のIssueを作成する役割を担います。このワークフローの実績として、提案された13件のPRのうち9件が実際にマージされ、マージ成功率は69%に達したと報告されています（参照*9）。母数が小さいため単純に一般化はできませんが、「AIが提案し、人間が判断してマージする」というフローが実際に機能しているデータとして参考になります。

安全に動かすための仕組み

多層的な保護の中身

セキュリティ対策として、権限制限、出力検証、シークレット分離、スキャン、実行環境の分離といった多層防御が講じられています。

デフォルトで読み取り専用とする設計原則があり、明示的に権限を付与しない限り、リポジトリへのアクセス権限は読み取り専用に維持されます。Issue作成、コメント投稿、PR作成などの変更操作は、フロントマターに宣言した検証済みの safe-outputs 経由でのみ実行可能です。

機密性の高い認証情報はエージェント本体に直接渡されず、分離された後続ジョブ内で安全に管理されます。また脅威検出機構として、エージェントが提案した出力は書き込み実行前に不審・危険な変更がないかスキャンされます（参照*1）。

実行基盤側にも分離設計が施されています。エージェントは整合性フィルターの基準に沿ってGitHubデータにアクセスし、Agent Workflow Firewallで保護されたサンドボックス環境内のコンテナで実行されます。生成物はsafe outputsプロセスによって検証され、専用の脅威検出ジョブがすべての変更適用前に事前スキャンを行います（参照*3）。

プロンプトインジェクションのリスク

エージェントはIssue本文やプルリクエストの説明、コメントなどを読み込んで推論するため、そこに潜む悪意ある指示に誘導されるリスクが研究で指摘されています。これはLLMを外部入力と接続した時点で避けられない問題で、「便利にするほど攻撃面が広がる」というトレードオフです。

ある実態調査では、276リポジトリの1,248ファイル、20,841コミットに伴う差分、294ファイルから抽出された288組の指示ラベルを分析しました。その結果、調査対象ワークフローの93%以上でタスク、出力、制約、プロセスに関する指示が含まれていた反面、プロンプトインジェクション対策を明示していたものはわずか9.4%にとどまりました（参照*10）。

脆弱性の実態を検証した別の研究もあります。10,792リポジトリで運用される実エージェント型ワークフロー13,392件に検査ツールTaintAWIを適用したところ、519件の潜在的脆弱性が検出されました。そのうち496件は想定脅威モデル下で悪用可能であることが実証され、検出の適合率は95.6%に上りました（参照*11）。

なお、これらは特定の分析対象とワークフローを調査した結果であり、調査母数や採用された解析手法の前提条件を踏まえた参考データです。ただ、「93%のワークフローでプロンプトインジェクション対策が明示されていない」という数字は、現場での認識の甘さを示す指標として重く受け止めるべきだと思います。

運用で押さえる確認事項

多層的な保護が備わっていても、人間が関与し続けることが求められます。セキュリティ対策は「あれば安心」ではなく、「あっても監視は続ける」という前提で運用するのが正しい姿勢です。

プロジェクトのメンテナーが提示する留意事項は一貫しています。サンドボックス化や最小権限の設計が施されていても、これらのワークフローは常に慎重に取り扱い、人間のチェック体制を維持すべきという点です（参照*2）。

過去のバージョン管理においても教訓となる事例が存在します。セキュリティ上の脆弱性発覚に伴い、GitHubはバージョン0.83.3から0.85.4までのリリースを自主的に廃止措置としました。公式ドキュメントでも、人間による最終監督と自己責任原則の重要性が繰り返し強調されています（参照*2）。

ワークフローを有効化する際は、トリガー、AIエンジン認証、利用ツール、通信設定、各種権限、安全な出力項目を確認します。コンパイル完了後は、.md と .lock.yml の双方が意図どおり更新されているかを目視で点検します（参照*4）。

コストと利用上の注意

運用にかかる総費用は、Actionsの実行時間とAIエンジンによる推論コストの2要素で構成されます。

エージェント型ワークフローの利用コストは、ジョブ実行に伴うGitHub Actionsの消費時間と、連携させたAIエンジンの推論利用料の合算となります。推論コストのモニタリングや複数エンジンにまたがる予算管理を容易にするため、GitHub Agentic WorkflowsではAI Credits（AIC）という共通単位が採用されています。換算基準は1 AIC = 0.01米ドルです（参照*1）。

AICの数値特性についても正しく理解しておく必要があります。AICの数値は概算見積もりであり、プロバイダーから届く実際の請求額と完全に一致しないケースがあります。最終的な支払額は各プロバイダーの管理ダッシュボードで確認する仕様です。コスト管理ツールとしての利便性はありますが、予算計画には余裕を持たせておくのが現実的です。

また、フロントマターで max-ai-credits を指定すれば、1回の実行で消費する推論量に上限を設けられます。標準設定の上限値は、1回の実行につき1,000 AICとなっています（参照*1）。

費用予測を支援する機能も拡充されています。CLIコマンド gh aw forecast は実験的段階を終えて正式機能となりました。脅威検出クレジットや月ごとの範囲にも対応し、AIクレジットの支出をより詳しく把握できるようになっています（参照*3）。

おわりに

GitHub Agentic Workflowsは、Markdownに記述した自然言語の指示を .lock.yml へコンパイルし、GitHub Actions基盤上でコーディングエージェントに自動実行させる枠組みです。トリガー設定や各種権限、safe-outputsの範囲はフロントマターで宣言し、リポジトリ権限は標準で読み取り専用に保たれます。「AIに何をさせるか」を自然言語で定義し、「どこまで許可するか」を構造的に宣言するという二層設計は、AI業務導入の観点からも理にかなっています。

導入にあたっては、トリガー、認証、ツール、ネットワーク、権限、安全な出力などの設定を念入りに確認し、要求を満たす最も絞り込んだ権限設定から着手することが推奨されます。サンドボックスや権限分離が整っていても、人間がレビューと監視を続ける必要があります。AIは候補を生成する道具であり、承認の責任は人間が持つという原則は、どのAIツールにも共通する基本です。この仕組みが現場に定着するかどうかは、技術的な完成度よりも、チームがその原則を守り続けられるかにかかっています。

監修者

安達裕哉（あだちゆうや）

デロイトトーマツコンサルティングにて品質マネジメント、人事などの分野でコンサルティングに従事しその後、監査法人トーマツの中小企業向けコンサルティング部門の立ち上げに参画。大阪支社長、東京支社長を歴任したのち2013年5月にwebマーケティング、コンテンツ制作を行う「ティネクト株式会社」を設立。ビジネスメディア「Books&Apps」を運営。
2023年7月に生成AIコンサルティング、およびAIメディア運営を行う「ワークワンダース株式会社」を設立。ICJ2号ファンドによる調達を実施(1.3億円)。
著書「頭のいい人が話す前に考えていること」が、95万部（2026年6月時点）を売り上げる。
（“2023年・2024年上半期に日本で一番売れたビジネス書”（トーハン調べ／日販調べ））