プロンプト一文で完結。GitHub Agentic Workflowsでイシューの自動ラベリングをAIエージェントに任せてみた

はじめに

先日、Claude Codeのスケジュールタスクを使ったイシュートリアージを書きました。自然言語のプロンプトだけでGitHubイシューの定期操作を実現できるという内容です。

https://dev.classmethod.jp/articles/claude-code-scheduled-tasks-github-triage/

同じことは、GitHubのエコシステムでも、現在テクニカルプレビューの GitHub Agentic Workflows を利用することで実現できます。

https://github.github.com/gh-aw/

GitHub Agentic Workflowsは、マークダウンでワークフローを記述すると、AIエージェントとしてタスクを自動実行する仕組みです。

ソフトウェア開発ライフサイクル(SDLC)にAIを組み込み、CI/CD のように、自動化とチーム開発を加速させる。GitHubはこれを「Continuous AI」と呼んでいます。

https://github.blog/ai-and-ml/automate-repository-tasks-with-github-agentic-workflows/

本記事では、GitHub Agentic Workflowsを用いて、GitHubのイシューを毎日トリアージする方法を紹介します。

AIエージェントにはGitHub Copilotを利用します。GitHub Copilotの代わりにClaude CodeやCodexなども利用することもできます。

GitHub Agentic Workflowsの処理の流れ

GitHub Agentic Workflowsは以下のステップで登録します。

1. .github/workflows/ にワークフローを記述した markdown ファイルを置く(例: foo.md)
2. gh aw compile で markdown ファイルをGitHub Actions用YAMLファイル(foo.lock.yml)にコンパイル
3. ワークフローが利用するAIエージェント用のシークレットを登録

ポイントは、markdown 形式のエージェンティックワークフローファイルをGitHub ActionsのYAMLファイルにコンパイルすることであり、GitHub Actionsの実行の観点では、何も変わっていません。

以降のセクションで、各ステップを詳しく見ていきます。

ワークフローを追加

.github/workflows/ 以下にワークフローを記述した markdown ファイルを置きます。

マークダウンファイルは、以下のように2つのパートがあります。

1. --- で囲まれたYAML形式のフロントマター(設定など)
2. markdown 形式の自然言語で記述した指示

---
on: ...
permissions: ...
tools: ...
engine: ...
---
# Natural Language Instructions
Analyze this issue and provide helpful triage comments...

ファイルの拡張子は .md ですが、前半はYAML形式です。

フロントマターの主なフィールドは以下の通りです。

• description: ワークフローの説明
• on: トリガー条件(cron、手動実行、イシュー作成時)
• permissions: GitHub APIへのアクセス権限
• safe-outputs: エージェントの出力制限
• engine: 使用するAIエンジン(現在はcopilot)

YAML エリアの engine フィールドは大事です。ここではAIエージェントの種類を指定します。

https://github.github.com/gh-aw/reference/auth/

後述のように、コンパイル時にエンジンごとに異なる変数で展開され、それぞれの名前のリポジトリシークレットを登録します。

本文は 自然言語でエージェントへの指示を記述するだけ です。

今回は triage.md という名前で以下の内容のファイルを作成しました。

---
description: |
  このワークフローは、新規にオープンされたイシューに対して、最適なラベルを自動的に割り当てます。

on:
  workflow_dispatch:
  issues:
    types: [opened]
permissions:
  contents: read
  actions: read
safe-outputs:
  add-labels:
    max: 2
engine: copilot
---

# Issue Triage Assistant

オープン状態のイシューにラベルがなければ適切なラベルを付与してください

gh aw compile で .md を .yml にコンパイル

GitHub Agentic Workflowsの肝は、markdownで記述したワークフローを、従来のGitHub ActionsのワークフローYAMLファイルにコンパイルする点です。
このコンパイル処理は、GitHub CLIの拡張機能として実現されています。

gh extension install github/gh-aw
gh aw compile

実行例です

$ gh aw compile
✓ .github/workflows/triage.md (52.4 KB)
✓ Compiled 1 workflow(s): 0 error(s), 0 warning(s)

$ find .github
.github/
├── aw/
│   └── actions-lock.json   # Actionsバージョンのロックファイル
└── workflows/
    ├── triage.md            # ソース(自分で書いたマークダウン)
    └── triage.lock.yml      # 生成されたワークフロー(GitHub Actionsが実行)

$ wc -l .github/workflows/*
    1030 .github/workflows/triage.lock.yml
      27 .github/workflows/triage.md
    1057 total

triage.lock.yml が agentic workflow をもとに GitHub Actions 向けにコンパイルされたロックファイルです。

30行弱が1000行強に膨れ上がっています。
1000行ものワークフローファイルは書くのも大変ですし、メンテナンスするのはさらに大変です。

量が膨大なため、コンパイル後のロックファイル(.lock.yml) 全体はこちらのリンクにあります。

https://gist.github.com/quiver/7d4a77e0b7909d3acf5137feee3af894

AIエージェントのシークレット登録(GitHub Copilot用のPATの作成)

エージェンティックワークフローはAIエージェントと連動します。
YAMLの engine フィールドで指定したAIエージェントをGitHub Actionsから呼び出せるように、シークレットをリポジトリのシークレットに登録します。

GitHub Copilotの場合、fine-grained Personal Access Token(PAT)を作成し、登録します。

https://github.com/settings/personal-access-tokens/new から以下の設定でトークンを作成してください。

• Token name: Agentic Workflows Copilot
• Expiration: 90 days
• Resource owner: 自分のアカウント
• Repository access: "Public repositories"(次のCopilot用Permissions のため)
• Permissions → Copilot Requests: Read-only

PAT は2種類あります。

Classic PAT(ghp_...)は使えず、fine-grained PAT(github_pat_...)のみ対応しています。

ワークフローの実行

このワークフローは新規イシュー起票時に呼び出され、実行が完了すると、ラベルが付与されます。

GitHub Actions の agent summary -> Agentic Conversionの日本語のログからも、期待通り動作していることがわかります。

• Agent: Issue #36 is open and has no labels. The title is "APIキーの管理を環境変数に変更"
• Agent: Issue #36「APIキーの管理を環境変数に変更」はラベルなし。内容はAPIキーを環境変数で管理する機能改善なので enhancement ラベルを付与します。
• Agent: Issue #36 に enhancement ラベルを付与しました。ラベルなしのオープンイシューは他にありませんでした。

Conversation のログ全体も共有します。

Conversation:

Agent: Let me analyze the open issues in the repository and add labels to any that don't have labels.

✓ report_intent(intent: Triaging open issues)

✓ github-list_issues(owner: quiver, repo: demo, state: OPEN, perPage: 100)

✓ github-issue_read(method: get, owner: quiver, repo: demo, issue_number: 36)

Agent: It seems the GitHub API access is restricted. Let me try the search approach.

✓ github-search_issues(query: repo:quiver/demo is:..., perPage: 100)

Agent: Issue #36 is open and has no labels. The title is "APIキーの管理を環境変数に変更" (Change API key management to environment variables). This is clearly an enhancement/feature request. Let me check what labels are available in the repository.

✓ github-get_label(owner: quiver, repo: demo, name: enhancement)

✓ github-search_issues(perPage: 10, query: repo:quiver/demo is:...)

Agent: Issue #36「APIキーの管理を環境変数に変更」はラベルなし。内容はAPIキーを環境変数で管理する機能改善なので `enhancement` ラベルを付与します。

✓ safeoutputs-add_labels(item_number: 36, labels: [enhancement])

Agent: Issue #36 に `enhancement` ラベルを付与しました。ラベルなしのオープンイシューは他にありませんでした。

Statistics:
  Turns: 7
  Tools: 7/7 succeeded
  Tokens: 154,373 total (153,507 in / 866 out)

セキュリティ機構

GitHub Agentic Workflowsには、エージェントの振る舞いを制御する3つのセキュリティ機構があります。

• permissions — ワークフローがGitHub APIに対して持つ権限(従来のGitHub Actionsと同じ)
• tools — エージェントが利用できるツールと、エージェントに渡されるコンテンツの信頼度フィルタリング
• safe-outputs — エージェントが実行できる書き込みアクション(ラベル付与、コメント追加など)の種類と回数の上限

permissions

通常のGitHub Actionsのpermissionsと同じ仕組みです。

permissions:
  contents: read
  actions: read

トリアージのワークフローであれば、読み取り権限だけで十分です。ラベル付与やコメント追加は後述の safe-outputs 経由で行われるため、issues: writeは不要です。

ここで読み取った情報は、次に説明するintegrity filteringを経てエージェントに渡されます。

tools と integrity filtering

toolsセクションでは、エージェントが利用可能なツール(GitHub API、bash、Web検索など)を指定できます。

なかでも重要なのが tools.github.min-integrity です。これはエージェントに渡されるコンテンツの信頼度によるフィルタリングを制御します。permissionsがAPIアクセスの可否を制御するのに対し、min-integrityはAPIで取得した情報のうちエージェントが実際に参照できる範囲を制御します。この挙動は、パブリックリポジトリとプライベートリポジトリで異なります。

5段階のレベルがあり、厳しい順に以下の通りです。

エージェントに渡す権限が不足すると、以下のようなエラーが発生しました。

Agent: オープンイシューが2件（#2, #3）見つかりましたが、いずれも整合性ポリシー（integrity policy）によりコンテンツの読み取りがブロックされました（必要レベル: approved、実際のレベルが不足）。

• https://github.github.com/gh-aw/reference/github-tools/
• https://github.github.com/gh-aw/reference/integrity/

パブリックリポジトリ

permissions:
  contents: read
  issues: read
  actions: read
  pull-requests: read
tools:
   github:
     min-integrity: none

プライベートリポジトリ

permissions:
  contents: read
  actions: read

※ デフォルト任せ

safe-outputs

safe-outputsは、エージェントに書き込みアクションを許可し、同時にその種類と回数を制限する仕組みです。エージェント自体はread-onlyで動作し、構造化された出力を通じて書き込みをリクエストします。実際の書き込みは別の権限制御されたジョブが実行します。

agents run read-only and request actions via structured output, while separate permission-controlled jobs execute those requests

利用可能なアクションと、デフォルトの上限は以下の通りです。

今回のトリアージワークフローでは、ラベリングが目的なので、add-labelsのみ有効にしています。

safe-outputs:
  add-labels:
    max: 2

add-labels を付け忘れると、エージェントは問題をロギングします。

Agent: Looking at the available tools, I have safeoutputs-add_comment but I don't see a label-adding tool.
The only write tool available is safeoutputs-add_comment, so I can't programmatically add labels to issues.
I should add a comment suggesting the enhancement label instead.
I need to use the safeoutputs-missing_tool to report that I don't have the capability to add labels to the issue.

公式ブログが示すContinuous AIのユースケース

公式ブログでは以下の6つのユースケースが紹介されています。

• Continuous Triage: イシューの自動分類とラベル付与(本記事で検証した内容)
• Documentation: ドキュメントの自動生成・更新
• Code Simplification: コードの簡素化・リファクタリング
• Test Improvement: テストカバレッジの改善
• Quality Hygiene: コード品質の維持
• Reporting: レポートの自動生成

今回検証したイシュートリアージはContinuous Triageに該当します。

まとめ

GitHub Agentic Workflowsを使い、自然言語でワークフローを記述する方法を紹介しました。

ポイントは、マークダウンファイルで定義されたワークフローが、GitHub ActionsのYAMLファイルにコンパイルされ、GitHub Actionsの強力なエコシステムに帰着することです。

処理する主体はGitHub Actions上で動作するエージェントのため、エージェントに対するセキュリティ機構がしっかり用意されているのには感心しました。

AIエージェントをGitHub Actionsで動作させている人は多いと思います。プロンプトで完結するようなシンプルな処理の場合、初手からGitHub ActionsのYAMLですべてを記述するよりは、GitHub Agentic Workflows のフレームワークの中でコアとなる処理だけを定義したほうが、より安全に実現できそうです。

テクニカルプレビューの段階ですので、今後の機能追加にも期待したいところです。

参考資料

• GitHub Agentic Workflows
• Automate repository tasks with GitHub Agentic Workflows
• Claude CodeのスケジュールタスクからGitHub Actions無しでGitHubのイシューを定期操作してみた | DevelopersIO
• https://github.github.io/gh-aw/reference/safe-outputs/
• https://github.github.io/gh-aw/reference/tools/