エージェントが GitHub API とワークフローと対話する方法

  • 5 分

AI エージェントは、開発作業の実行方法を変更しています。 エージェントは、リポジトリ内を手動で移動したり、コードを記述したり、コマンドを実行したりするのではなく、GitHub内で直接操作して、最初から最後までタスクを完了できます。

GitHubでは、複数のレイヤーを介したエージェント駆動型の作業がサポートされます。 エージェントは、GitHub APIを使用してリポジトリの状態を読み取り、アクションを実行できます。また、GitHub Actionsワークフローを使用し、制御されたランナーで自動化を実行し、GitHubエージェンティックワークフローを用いてMarkdownで上位レベルのリポジトリタスクを記述し、厳重なガードレールの下でコーディングエージェントを使用して実行できます。 エージェントは、GitHubをバイパスするのではなく、ブランチ、プル要求、問題、自動化など、開発者が使用するのと同じシステムで動作します。

このユニットでは、次の内容について説明します。

  • エージェントが API を介してGitHubと対話する方法
  • エージェントがワークフローを実行環境として使用する方法
  • リポジトリの変更の作成と管理方法
  • GitHubでの完全なエージェント実行フローの外観

エージェントがGitHubと対話する方法

Copilotクラウド エージェントなどのGitHubエージェントは、定義済みのリポジトリとブランチ コンテキスト内で動作します。 たとえば、問題やプロンプトを使用してタスクを割り当てると、エージェントはそのリポジトリ内で作業を開始します。

エージェントは次のことができます。

  • リポジトリを調査して理解する
  • タスクを完了するために必要な変更を計画する
  • 新しいブランチでコードを変更する
  • レビュー用の pull request を開く

エージェントは、API やワークフローなどのGitHubプラットフォーム機能を使用して、これらのアクションを実行します。

これらのアクションは、リポジトリ イベント (プッシュやプル要求など) によってトリガーしたり、スケジュールに従って実行したり、時間の経過と同時にリポジトリ タスクを継続的に自動化するエージェントワークフローを通じて調整したりできます。

GitHub API を使用したアクションの実行

GitHubは、システムがプログラムでリポジトリと対話できるようにする API を提供します。

API を使用すると、次のようなアクションが可能になります。

  • ブランチとコミットの作成
  • リポジトリ データの読み取り
  • プルリクエストを開いて更新する
  • ワークフローのトリガー

すべての API 要求は、個人用アクセス トークン、GitHub アプリ トークン、ワークフローで提供されるGITHUB_TOKENなどのトークンを使用して認証する必要があります。

これにより、エージェントが実行するすべてのアクションがアクセス許可によって制御され、監査可能になります。

エージェントがリポジトリに変更を作成する方法

エージェントが変更を加えると、開発者と同じワークフローに従います。 一般的なシーケンスは次のようになります。

  1. ベース ブランチを選択する
  2. 新しい作業ブランチを作成する
  3. ファイルを変更または作成する
  4. 変更をコミットする
  5. pull request を開く

Git 参照、リポジトリの内容、プル要求の操作など、これらの手順ごとに個別の API 操作があります。

つまり、エージェントアクションはGitHubの標準開発モデルと完全に一致しています。

GitHub Actionsを実行レイヤーとして使用する

エージェントは、コンピューター上でタスクを直接実行しません。 代わりに、GitHubは、GitHub Actionsを利用したワークフローを通じて実行環境を提供します。

ワークフローは、イベントに応答してジョブを実行する YAML で定義されたプロセスです。

エージェントは次のワークフローに依存します。

  • テストを実行する
  • 変更を検証する
  • 自動化タスクの実行
  • アプリケーションを展開する

Copilotクラウド エージェントは、GitHub Actionsを利用した環境で動作します。つまり、ワークフローはエージェント実行の基盤を形成します。

従来のワークフローとエージェント ワークフロー

従来のGitHub Actions ワークフローは、通常、決定論的で YAML で定義されています。各ステップ、トリガー、条件を明示的に指定します。 GitHub エージェント ワークフローは、リポジトリの自動化のために異なるモデルを追加します。 Markdown で目的の結果を記述し、フロントマッターでガードレールを定義し、GitHub Actionsのコーディング エージェントを使用してその意図を実行できます。 これらは、トリアージ、レポート、ドキュメントのメンテナンス、CI エラー分析、コードの改善など、オープンエンドの有界リポジトリ タスクに最適です。 CI/CD パイプラインを置き換えるのではなく、GitHubが「継続的 AI」と表現するものでこれを拡張します。

エージェント ワークフローが異なる理由は何ですか

GitHub Agentic ワークフローには、次の 2 つの主要な部分があります。

  • トリガー、アクセス許可、ツール、安全な出力などの構成のための Frontmatter
  • 自然言語でジョブを記述する Markdown 命令

Markdown は意図を表し、フロントマッターは境界を定義します。 その後、ワークフローは、GitHub Actions実行されるロック ファイルにコンパイルされます。

on: schedule: daily
permissions: contents: read issues: read pull-requests: read
safe-outputs: create-issue: title-prefix: "[repo-status] " labels: [report]
tools: github:

Daily Repository Status Report
Create a daily report for maintainers.
Include:
Recent activity (issues, PRs, commits)
Key highlights and risks
Recommended next steps
Keep the report concise and link to relevant issues and pull requests.

この例では、frontmatter (--- 間) によって、ワークフローの実行方法とタイミング、アクセスできる内容、および許可されるアクションが定義されています。

次の Markdown は、ワークフローの意図を自然言語で定義します。 エージェントはこの意図を解釈し、構造化された出力を生成し、制御されたレビュー可能な手順を通じて適用されます。

各ステップを明示的に定義する従来のGitHub Actions ワークフローとは異なり、エージェント ワークフローは結果の記述に重点を置きます。 エージェントは、フロントマッターで定義されている制約内で目標を達成する方法を決定します。

ワークフローのトリガーとインタラクション

ワークフローは複数の方法でトリガーできます。

  • 自動的にプッシュやプルリクエストなどのイベントを通じて行う
  • workflow_dispatch イベントを手動で使用する
  • GitHub API を使用したプログラムによる

エージェントは、これらのトリガーに依存してタスクを実行したり、リポジトリの更新後に変更を検証したりできます。

各ワークフロー実行は、分離された環境でジョブを実行し、一貫性のある安全な実行を保証します。

エージェント セッション中の動作

エージェント セッションは、監視可能で対話型です。

セッション中は、次のことができます。

  • セッション ログを使用して進行状況を監視する
  • エージェントが実行しているアクションを確認する
  • フィードバックを提供するか、タスクを調整する
  • 最終的な pull request を確認する

エージェントはフィードバックに基づいて適応し、タスクが完了するまで作業を続けます。

エンド ツー エンドのエージェント実行フロー

すべてをまとめると、GitHubとの一般的なエージェントの相互作用は次のようになります。

  1. タスクは、問題、チャット、または CLI を使用して割り当てられます
  2. エージェントがリポジトリとベース ブランチを選択する
  3. エージェントはコードベースを分析し、変更を計画します
  4. API 操作は、ブランチとコミットを作成するために使用されます
  5. pull request が開かれている
  6. ワークフローを実行して変更を検証またはデプロイする
  7. ユーザーが更新プログラムを確認、承認、または要求する

このフローにより、すべてのエージェント アクティビティが次のことが保証されます。

  • リポジトリ範囲に限定
  • アクセス許可によって制御される
  • ワークフローを通じて実行される
  • 表示およびレビュー可能

重要なポイント

GitHub上のエージェントは、プラットフォームの外部では動作しません。 アクセス許可を適用し、実行環境を提供し、プル要求によるコラボレーションを有効にする API、ワークフロー、リポジトリ構造を介して対話します。

次に、エージェントがGitHubを超えて追加のツールやサービスに接続できるようにすることで、モデル コンテキスト プロトコル (MCP) によってこれらの機能がどのように拡張されるかについて説明します。