【ITニュース解説】From Markdown to Guarded Automation: Build Your First GitHub Agentic Workflow

GitHub Agentic Workflowsは、ソフトウェア開発における自動化をさらに進化させる新しい仕組みである。これまで、ソフトウェア開発で繰り返し行う作業を自動化するツールとして「GitHub Actions」が広く使われてきた。GitHub Actionsでは、どのような手順で自動化を行うかをYAMLという形式のファイルに記述する必要があったが、Agentic Workflowsでは、人間が日常的に使う「自然言語」（例えば日本語や英語）で指示を記述できるようになる。これにより、より柔軟で直感的な自動化が可能になる一方、従来の自動化が持つ「信頼性」や「予測可能性」を損なわないよう、厳重な安全対策が施されている点が大きな特徴だ。

Agentic Workflowsを利用する開発者は、まずMarkdownという簡易的なマークアップ言語でタスクの内容を記述する。このMarkdownファイルには、タスクの説明や、エージェントが従うべき具体的な手順などが書かれる。さらに、ファイルの冒頭部分（Front Matterと呼ばれる）には、ワークフローが実行される条件、使用を許可するツール、アクセス権限、ネットワーク接続の制約、使用できるAIの計算リソースの予算など、自動化の「境界線」を明確にするための設定が記述される。このMarkdownソースは、専用のツールによって従来のGitHub Actionsのワークフローファイル（YAML形式）にコンパイルされ、GitHub上で実行可能な形となる。

例えば、今回のニュース記事で紹介されているのは「CI（継続的インテグレーション）の失敗を分析し、原因を診断して解決策を提案する」というワークフローである。CIは、開発者がコードを更新するたびに自動的にテストやビルドを行う仕組みで、ソフトウェアの品質を保つ上で非常に重要だ。しかし、CIが失敗した場合、その原因を特定するのは手間がかかる作業となることがある。このAgentic Workflowは、CIが失敗した時に自動的に起動し、失敗した実行ログや関連するファイルなどを読み取り専用のGitHubツールを使って詳細に分析する。そして、最も可能性の高い診断結果と、その解決策、検証ステップをGitHubの「Issue」（課題管理のチケット）として提案するというものだ。

このワークフローは、いきなり本番環境でIssueを作成するのではなく、最初は「Staged Mode（ステージングモード）」という安全なモードで実行される。Staged Modeでは、エージェントが分析を行い、Issueのタイトルや本文を提案するところまで実行されるが、実際にリポジトリにIssueが作成されることはない。提案された内容はGitHub Actionsの実行サマリーに表示されるだけなので、開発者は実際の変更を伴わずに、エージェントの分析結果や提案の品質をレビューできる。これにより、エージェントの動作を安心して確認し、必要に応じて調整を加えることが可能となる。このワークフローは、Markdown形式の「ソースファイル」と、それをコンパイルして生成されたGitHub Actionsの「ロックファイル」（YAML形式）の2つのファイルで構成され、どちらもバージョン管理システムに登録されることで、どのような意図でどのような自動化が行われるのかが明確になる。

Agentic Workflowsを利用するには、いくつかの準備が必要となる。具体的には、GitHubリポジトリ、GitHub Actionsが有効になっている既存のCIワークフロー、コマンドラインからGitHubを操作するためのGitHub CLI、そしてAIの推論機能を利用するためのGitHub Copilotのアクセス権などだ。特にCopilotのアクセスについては、組織での課金体系を利用するか、個人のアクセス権限トークンを設定するかで方法が異なるため、適切な設定が求められる。

エージェント型ワークフローにおいて最も重要な要素の一つが「セキュリティ」である。自然言語による指示は柔軟性をもたらすが、ログやコミットメッセージ、リポジトリ内のファイルなどには、悪意のある指示（プロンプトインジェクション）が含まれる可能性があり、エージェントが誤った判断を下したり、意図しない操作を行ったりするリスクがある。そのため、Agentic Workflowsでは、自然言語の指示とは別に、ワークフローの動作を厳しく制限する多層的な「ガードレール」が設けられている。

具体的には、以下のような対策が講じられている。まず、ワークフローが起動する「トリガー」を特定の条件（例：特定のCIワークフローが失敗した場合のみ）に限定する。次に、エージェントが操作できる「権限」を読み取り専用に厳しく制限する。さらに、利用できる「ツール」もGitHubが提供するアクションやリポジトリの機能に限定し、外部への「ネットワーク」アクセスも必要最小限に留める。エージェントが生成する「出力」も、例えば「Issueを最大1つ作成する」といったように構造化され、数が制限される。そして、前述のStaged Modeのように、最初は「ロールアウト」をプレビューに留めることで、実際に変更が適用される前に人間がレビューする機会を設ける。加えて、ワークフローの実行時間やAIの計算リソースに「予算」を設定し、無限に実行されることを防ぐ。

特に重要なのは、AIによる推論プロセス（エージェントが自然言語を解釈し、判断を下す部分）には直接「書き込み」権限を与えないという原則だ。エージェントが何らかの操作（例えばIssueの作成）を提案した場合、その提案は「Safe Output（安全な出力）」と呼ばれる厳格な検証プロセスを経て、別の、必要最小限の権限を持つジョブによって実行される。これにより、エージェントが直接リポジトリの内容を改変するリスクが排除される。また、エージェントには、ログやファイルの内容を「データ」として扱うべきであり、その中に含まれる命令を実行してはならない、といった明確な指示（プロンプト）を与えることも、安全な運用には不可欠だ。

ワークフローを開発・実行する際には、まずGitHub CLIの拡張機能としてgh awツールをインストールし、リポジトリの初期化を行う。その後、先ほど説明したMarkdownファイルを作成し、Front Matterで設定項目を、本文で自然言語の指示を記述する。例えば、onセクションでは監視対象のCIワークフローとブランチを指定し、ifセクションでは失敗時のみに実行される条件を設定する。permissionsセクションではcontents: read（ファイル読み取り）やactions: read（ワークフローデータ読み取り）のように、エージェントが必要とする最小限の権限のみを付与する。toolsセクションで利用可能なGitHubツールセットを限定し、safe-outputsセクションでStaged Modeを有効にし、Issueの作成に関する制約を設定する。

ワークフローの記述が完了したら、gh aw validateコマンドで記述の正当性を検証し、gh aw compileコマンドでMarkdownソースをGitHub ActionsのYAMLファイルにコンパイルする。生成されたYAMLファイルは、エージェントの動作を規定する重要な部分であり、Git diffコマンドなどで変更点を確認し、ソースファイルとロックファイルの両方をバージョン管理にコミットすることが推奨される。

実際にワークフローを試す際には、本番環境ではなく、隔離されたサンドボックス環境で試運転を行うことが推奨される。gh aw trial --dry-runコマンドで設定を確認した後、コンパイルされたワークフローファイルをリポジトリに配置し、監視対象のCIワークフローを意図的に失敗させてみる。そして、Agentic Workflowが期待通りに起動し、正確な診断を行い、ActionsのサマリーにIssueのプレビューが表示されることを確認する。この際、リポジトリに実際にIssueが作成されていないこと、意図しないコードが実行されていないことなども確認すべきだ。成功した場合や、曖昧な失敗の場合にもAgentic Workflowが適切に「noop」（何もしない）と判断するかどうかもテストすることが重要である。

Staged Modeでの試運転を通じて、エージェントの診断能力や行動が期待通りの品質に達していると判断できたならば、いよいよ実運用への移行を検討する。移行の際には、エージェントが常に意図したCI失敗のみをトリガーしているか、診断結果の品質は一貫して高いか、曖昧なケースでは誤った判断を下さずnoopを選択しているか、ログなどに含まれる不正な命令を無視しているか、そして運用コストが予算内に収まっているかなど、いくつかの基準に基づいて慎重に評価を行う。これらの基準をクリアできた場合のみ、Markdownファイルのsafe-outputsセクションにあるstaged: trueをstaged: falseに変更し、再コンパイルしてデプロイすることで、エージェントが実際にGitHub上でIssueを作成する本稼働モードへと移行する。本稼働後も、gh aw logsやgh aw auditコマンドを使って、ワークフローの実行状況やAIのコスト、ツールの利用状況などを継続的に監視することが重要である。

GitHub Agentic Workflowsは、自然言語による柔軟な自動化と、厳格なセキュリティおよび制御を両立させることで、開発者がより効率的かつ安全に作業を進めることを可能にする。Markdownでタスクの意図を明確にし、コンパイルされたYAMLで実際の実行内容をレビュー可能にするとともに、権限、ツール、ネットワーク、出力、予算といった明確な境界線を設定することで、自動化がもたらすリスクを最小限に抑え、信頼性の高いシステムを構築できる。今回紹介されたCI失敗時のトリアージワークフローは、最小限の機能からスタートし、実際のデータでエージェントの推論能力を評価しながら、段階的に信頼できる自動化へと進化させていくための、実践的な第一歩となるだろう。