GitHub のエージェント型ワークフローについて

メモ

GitHub エージェント型ワークフロー are in パブリックプレビュー and subject to change.

エージェント型ワークフローの概要

GitHub エージェント型ワークフローは、マークダウンで定義し、 GitHub Actions ワークフローとして実行する AI を利用したリポジトリ自動化です。固定の if-then ルールを使用した従来の自動化とは異なり、エージェント型ワークフローコーディングエージェントを使用して、コンテキストを理解し、意思決定を行い、意味のあるアクションを実行します。すべて自然言語の指示から行われます。

実際には、定義済みの手順を実行する従来のワークフローと比較します。

エージェントワークフローコンテキスト推論を使用して自然言語命令を実行します。
引き続き、トリガー、アクセス許可、安全な出力など、フロントマッターでガードレールを定義します。

エージェント型ワークフローを使用すると、次のようなタスクを自動化できます。

受信した問題をトリアージし、種類と優先順位でラベル付けする
CI エラーの調査と修正の提案
毎日または毎週のリポジトリの状態レポートの生成
コードの変更に関するドキュメントを最新の状態に保つ
テストカバレッジの向上

使用することで得られる利点エージェント型ワークフロー

反復的なリポジトリ作業を自動化します。問題のトリアージ、CI 調査、ドキュメントの更新、および自然言語でのレポートを定義します。
ワークフローの複雑さを軽減します。すべてのシナリオで複雑な手続き型スクリプトを作成する代わりに、マークダウン命令を記述します。
人によるレビューを組み込む。エージェントワークフローでは、承認とマージを制御しながら、問題、コメント、プル要求などのすぐに確認できる出力を生成できます。
階層型セキュリティを使用してエージェントを実行します。エージェントは、既定で読み取り専用トークンを使用してファイアウォールされたコンテナーで実行されます。書き込みアクションは、定義した宣言済みの "安全な出力" に限定され、エージェントの脅威検出によって確認されます。

Requirements

エージェント型ワークフローを作成して使用するには、次のものが必要です。

GitHub Actions リポジトリに対して有効になっています。
GitHub Copilot、Anthropic Claude、OpenAI Codex、Google Gemini などの AI エンジン (エージェント) を持つアカウント。
GitHub CLI インストールおよび認証済み

エージェント型ワークフローのしくみ

各ワークフローマークダウンファイルには、次の 2 つの部分があります。

Frontmatter ( --- マーカー間の YAML): ワークフローの実行時、ワークフローに与えるアクセス許可、および許可される書き込み操作を構成します。
Markdown 本文: AI エージェントが従う自然言語命令が含まれています。

大まかに言えば、エージェント型ワークフローを作成して使用するプロセスは次のとおりです。

YAML frontmatter や markdown 命令など、エージェントワークフロー .md ファイルを定義します。
マークダウンワークフローファイルを、強化された .lock.ymlGitHub Actions ワークフローファイルにコンパイルします。
両方のファイルをコミットし、リポジトリの既定のブランチにプッシュします。
他の GitHub Actions ワークフローと同様に、トリガーまたはリポジトリの GitHub Web インターフェイスでワークフローを実行します。 GitHub CLIから実行することもできます。

リポジトリの日次状態レポートの問題を作成するワークフローの例を次に示します。

---
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

Review recent activity in the repository, including issues, pull requests, discussions, and code changes.

Create a GitHub issue summarizing what changed in the last 24 hours (merged pull requests, closed issues, and new discussions), any blockers or open questions mentioned in comments, progress toward visible goals, and recommended next steps for maintainers.

Keep the summary concise. Adjust the level of detail based on how much activity occurred.

エージェント型ワークフローの作成と更新の詳細な手順については、GitHubのエージェント型ワークフローの作成を参照してください。

サポートされているコーディングエージェント

GitHub エージェント型ワークフローでは、次のような複数のコーディングエージェントがサポートされます。

GitHub Copilot ( GitHub Copilot プランが必要)
Anthropic Claude
OpenAI Codex
Google Gemini

ワークフロー frontmatter プロパティ engineで使用するエージェントを指定します。各エンジンには、リポジトリで構成された独自の認証シークレットが必要です。 GitHub Copilot は、何も指定されていない場合の既定のエンジンです。

詳細については、エンジンリファレンスを参照してください。

セキュリティガードレール

GitHub エージェント型ワークフローは、セキュリティを優先して設計されています。

既定では読み取り専用: 明示的に付与しない限り、ワークフローには読み取り専用リポジトリのアクセス許可があります。
安全な出力: 書き込み操作 (問題の作成、コメントの追加、プル要求の開きなど) は、フロントマッターで宣言された検証済みの safe-outputs によってのみ許可されます。
シークレットはエージェントランタイムの外部に保持されます。機密性の高い資格情報は、エージェントに直接公開されるのではなく、分離されたダウンストリームジョブに保持されます。
脅威の検出: 提案された出力は、書き込みアクションが適用される前に、疑わしい変更または安全でない変更がないかスキャンされます。
ファイアウォールによる実行: エージェントは、分離された GitHub Actions 環境で実行されます。
ロールベースのアクセス: ロールベースのアクセス制御を使用して、エージェント型ワークフローをトリガーまたは変更できるユーザーを制限できます。

アーキテクチャの完全なチュートリアルについては、セキュリティドキュメントを参照してください。

使用量と請求

エージェント型ワークフローの合計コストには、次の 2 つの部分があります。

GitHub Actions ワークフロージョブで使用される分数。
構成された AI エンジンからの推論コスト。

推論 GitHub エージェント型ワークフロー、エンジン全体の監視と予算作成の一般的なメトリックとして AI クレジット (AIC) を使用します。 1 AIC = $0.01 USD。

課金の適用方法は、エンジンによって異なります。

既定のGitHub Copilot エンジン: AIC の使用状況は、AI credits課金のGitHub Copilotにマップされます。
サードパーティエンジン: 推論は、そのプロバイダーによって課金されます。

GitHub CLIを使用して、エージェント型ワークフローの使用量と推定コストを確認できます。 gh aw logsを使用して、実行全体の期間、トークンの使用状況、AIC の見積もりなど、最近のワークフロー実行を表示します。 gh aw audit RUN-IDを使用して、トークンの使用状況や推定推論コストなど、1 回の実行をより詳細に検査します。 AIC 値はベストエフォートの見積もりであり、プロバイダーの請求書と完全には一致しない可能性があるため、プロバイダーの課金ダッシュボードで最終的な料金を確認します。

ワークフローのフロントマッターで max-ai-credits を設定して、1 回の実行で推論の使用量を上限にすることもできます。既定の上限は、実行あたり 1,000 AIC です。

GitHub エージェント型ワークフローの課金とコスト最適化のガイダンスの概要については、ドキュメントサイトのGitHub エージェント型ワークフローを参照してください。

組織の課金を有効にする GitHub エージェント型ワークフロー

組織所有のリポジトリ GitHub Copilot エージェントワークフローの場合、組織が GitHub Copilot 計画を持っている場合は、 GitHub Actionsの組み込み GITHUB_TOKENを使用することを強くお勧めします。この方法では、料金は組織に請求され、personal access tokenを使用せずに済みます。

組織に請求するには、次のものが必要です。

組織管理者は、GitHub Copilot ポリシー設定で "Copilot CLI" と "組織に課金される Copilot CLI の使用を許可する" を有効にします。 "Copilot CLI" が既に有効になっている場合、課金ポリシーは既定で有効になっています。
各ワークフローのフロントマッターで、copilot-requests: write オブジェクトの下にpermissionsを含めます。

copilot-requests: writeがワークフローフロントマッターのアクセス許可で設定されている場合、GitHub Actions' トークンがCopilot要求に使用されるため、COPILOT_GITHUB_TOKENは必要ありません。 GitHub Actions トークンに組織からの GitHub Copilot アクセス権がない場合、ワークフローはCopilot要求を送信するときに失敗し、代わりに COPILOT_GITHUB_TOKEN を構成する必要があります。

詳細なセットアップ手順については、組み込みのGITHUB_TOKENの使用を参照してください。

次のステップ

最初のエージェントワークフローを追加するには、最初のエージェント型ワークフローを参照してください。
エージェント型ワークフローの作成と使用の詳細については、GitHubのエージェント型ワークフローの作成を参照してください。
詳細なパターンと例を含む完全なリファレンスドキュメントについては、 GitHub エージェント型ワークフロードキュメントサイトを参照してください。

GitHub のエージェント型ワークフローについて

この記事で