GitHubのエージェント型ワークフローの作成

リポジトリのニーズに合わせてカスタマイズされた、AI を利用したカスタム自動化を構築します。

この記事で

メモ

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

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

コーディング エージェント (推奨) を使用して GitHub エージェント型ワークフロー を作成することも、手動で作成することもできます。 ワークフローは、構成用の YAML frontmatter と AI エージェントの自然言語命令を含む、 .github/workflows/ のマークダウン ファイルです。

エージェントワークフローを作成するには、markdown でワークフローを定義し、それを .lock.yml ファイルにコンパイルし、両方のファイルをコミットしてから、 GitHub Actions トリガーまたは GitHub CLIを介して実行します。

この記事では、ワークフローの作成、更新、再利用という主要なタスクについて説明します。 技術的な詳細と追加のパターンについては、 GitHub エージェント型ワークフロー ドキュメント サイトを使用してください。

前提条件

開始する前に、以下の項目があることを確認します:

  • AI アカウント: GitHub Copilot、 Anthropic Claude、 OpenAI Codex、Google Gemini

  • 書き込みアクセス権がある GitHub リポジトリ

  • GitHub Actions リポジトリに対して有効

  • GitHub CLI (gh) v2.0.0 以降がインストールおよび認証されている

    バージョンを確認するには、 gh --versionを実行します。 認証するには、次のコマンドを実行します。

    gh auth login --scopes repo,workflow

  • GitHub エージェント型ワークフロー用のGitHub CLI拡張機能がインストールされています:

    gh extension install github/gh-aw

    バージョン 2.90.0 以降 GitHub CLI 使用している場合は、 gh aw コマンドを実行すると、拡張機能がまだインストールされていない場合は、自動的にインストールするように求められます。

Authentication

選択した AI エンジン (コーディング エージェント) で認証を設定するには、次の 2 つの方法があります。

内蔵のGITHUB_TOKENを使用する

ヒント

組織所有のリポジトリで GitHub Copilot を使用する場合は、このセクションの組み込みの GITHUB_TOKEN アプローチを強くお勧めします。

組織所有のリポジトリでGitHub Copilotを使用している場合は、GitHub Actionsではなく、GITHUB_TOKENの組み込みpersonal access tokenを使用できます。 これにより、ワークフローの使用料が組織に直接請求され、Copilotリクエスト用のpersonal access tokenシークレットを管理する必要がなくなります。 これを設定するには:

  1. 組織の管理者は、Copilot 設定で、まだ有効になっていない場合はポリシー「組織に課金される Copilot CLI の使用を許可する」を有効にする必要があります。
  2. 組織に請求するワークフローの場合は、ワークフロー のフロントマッター copilot-requests: writeにpermissionsを配置します。

組織の課金を有効にする

GitHub Copilot ポリシー設定で、"組織に課金される Copilot CLI の使用を許可する" を有効にする必要があります。 "Copilot CLI" ポリシーが既に有効になっている場合、課金ポリシーは既定で有効になっています。

  1. GitHub の右上隅にあるプロフィール画像をクリックしてから、[ Your organizations] をクリックします。

  2. 組織をクリックして選択します。

  3. Organization 名の下で、[ Settings] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウン メニューを選び、 [設定] をクリックします。

    組織のプロファイルのタブのスクリーンショット。 [設定] タブが濃いオレンジ色の枠線で囲まれています。

  4. サイドバーで[ Copilot]、[ ポリシー]の順にクリックします。

  5. [Copilot CLI] を有効にし、[組織に請求された Copilot CLI の使用を許可する] を有効にします。

組織にワークフローの料金を請求する

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

permissions:
  contents: read
  copilot-requests: write

personal access tokenまたは API キーの使用

個人用リポジトリまたはサードパーティの AI エンジンの場合は、 personal access token または API キーを格納するリポジトリ シークレットを作成する必要があります。 GitHub Copilot、シークレットは COPILOT_GITHUB_TOKEN であり、そこには細粒度の personal access token が格納されます。

gh aw add-wizardを使用する場合は、そのシークレットの作成を求めるメッセージがセットアップ フローによって表示されます。 GitHub Web インターフェイスから、または手動でエージェント ワークフローを作成する場合は、まず、GitHub Actions UI または CLI でGitHubを使用して、リポジトリのgh aw secrets set シークレットにシークレットを自分で追加する必要があります。 手順については、 認証リファレンスを参照してください。

ワークフローの作成

エージェント型ワークフローを作成するには、CLI コーディング エージェントまたは VS Code を使用することをお勧めします。 これにより、ワークフローを作成、コンパイル、コミットするための 1 つのガイド付きパスが提供されます。

CLI コーディング エージェントまたは VS Code の使用

  1. GitHub CLI GitHub エージェント型ワークフロー拡張機能 (gh aw) を使用して、エージェント作成用にリポジトリを初期化します (リポジトリでの初回セットアップに推奨)。

    gh aw init

    これにより、エージェント ワークフローの作成に関連するスキル、手順、およびカスタム エージェントが追加されるため、コーディング エージェントはワークフローをより効果的に作成および編集できます。

  2. リポジトリのコンテキストでコーディング エージェントを開始します (たとえば、 Copilot CLI (コパイロット CLI) または VS Code エージェント モード)。

  3. agentic-workflows スキルについて説明し、目的のワークフローを説明するプロンプトを入力します。

    Copilot prompt
    /agentic-workflows Create a new workflow that creates a daily report on
recent activity in the repository, delivered as
an issue.

  4. エージェントはワークフローを作成し、 GitHub CLIを使用してワークフローをコンパイルします。

  5. ワークフローを確認し、エージェントにファイルのコミットとプッシュを依頼します。

  6. [ GitHub Actions ] タブから、または GitHub CLI を実行してワークフローをトリガーします。

    gh aw run YOUR-WORKFLOW-NAME

その他の作成方法

エージェント ワークフローを作成することもできます。

ワークフロー構造リファレンス

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

セクションPurpose
YAML frontmatterトリガー (on)、アクセス許可、安全な出力、AI エンジンを定義します。
Markdown 本文ワークフローの実行時に AI エージェントが従う自然言語の指示。

主要なフロントマッター フィールド:

フィールドDescription
onイベント トリガー ( GitHub Actions トリガーと同じ構文)。
permissionsエージェントに付与されたリポジトリのアクセス許可。 既定値は read-all です。
safe-outputsエージェントが実行できる書き込み操作 ( create-issue、 add-comment、 create-pull-requestなど)。
engine使用する AI エンジン (copilot が既定値です。 claude、 codex、 gemini もサポートされています)。

frontmatter の完全なリファレンスについては、 GitHub エージェント型ワークフロー frontmatter のドキュメントを参照してください。

エージェント ワークフローの例

次の例は、リポジトリの週次発行アクティビティ レポートを簡略化しています。

---
on: weekly on monday

permissions:
  issues: read
  copilot-requests: write

network: defaults

tools:
  github:
    toolsets: [issues]

safe-outputs:
  create-issue:

---

# Weekly issue activity report

Review issue activity from the last 7 days in this repository.

Create a GitHub issue that includes:

- Total issues opened and closed this week.
- The top recurring themes from issue titles and descriptions.
- A short list of notable issues that still need attention.
- Two or three actionable recommendations for maintainers.

Keep the report concise and action-oriented.

ワークフローの更新

既存のワークフローを更新するには:

  1. .github/workflows/でワークフロー マークダウン ファイルを編集します。

  2. 再コンパイルしてロック ファイルを更新します。

    gh aw compile

  3. 更新された両方のファイルをコミットしてプッシュします。

  4. pull request を開き、 GitHub Actions チェックを確認します。

詳細な編集ガイダンスについては、「 ワークフローの編集」を参照してください。

ワークフローの再利用

アクセスできる外部リポジトリからワークフローをインポートすることもできます。 たとえば、次の githubnext/agenticsからワークフローを追加できます。

gh aw add-wizard githubnext/agentics/daily-repo-status

非対話型セットアップの場合は、 gh aw add を使用し、必要に応じてバージョンをピン留めできます。

ワークフローをインポートすると、GitHub CLIsource:値が frontmatter に格納されるため、後でgh aw updateを使用してアップストリームから更新できます。

信頼できるソースからのみワークフローをインポートし、リポジトリに追加する前にワークフローの動作を確認します。 private: trueマークされたワークフローは、他のリポジトリにインポートできません。

インポートされたワークフローを更新すると、 GitHub CLI はローカルの変更を保持しようとします。 マージの競合がある場合は、それらを解決し、 gh aw compile 再度実行します。

詳細については、「 ワークフローの再利用」を参照してください。

次のステップ