こんにちは、Androidエンジニアの @syarihu です

GitHub が提供する Agentic Workflows（以下 gh-aw）は、公式ブログで「意図駆動型のリポジトリ自動化を構築するコーディングエージェント」と紹介されており、Markdown でワークフローを記述するだけで AI エージェントが GitHub Actions 上で動作するという、非常に魅力的なコンセプトのツールです。

公式ブログを読むと、「Markdown を書くだけでシンプルに AI ワークフローが構築できる」という期待をもちます。しかし、実際に導入してみると、次のような現実がありました。

Markdown を書く → コンパイルして 1,000 行を超える YAML が生成される
生成された YAML を自分で Git 管理しなければならない
コンパイラのバグで、生成された「DO NOT EDIT」と書かれた YAML ファイルを手動修正しないと期待どおりに動作しないことがある
gh-aw のアップデートのたびに手動修正が上書きされ、同じ作業を繰り返す

本記事では、この「期待と現実のギャップ」を中心に、実際の運用経験から見えてきた課題と今後の方針について共有します。

なお、gh-aw は 2026 年 2 月時点でテクニカルプレビュー段階（本記事の検証時点では v0.50.2）であり、ほぼ毎日アップデートが入っています。破壊的変更も頻繁に含まれるため、本記事で取り上げている挙動や問題はすでに変わっている可能性があります。記事中のバージョン番号を参考に、最新の状況は公式ドキュメントで確認してください。

1. GitHub Agentic Workflows の概要

gh-aw の基本的な仕組みと、公式ブログが紹介する機能について概説します。

gh-aw とは

gh-aw は、GitHub が提供する AI エージェントワークフローのフレームワークです。従来の GitHub Actions では YAML でワークフローを記述しますが、gh-aw では Markdown ファイルにフロントマターとプロンプトを記述し、gh aw compile コマンドで実行可能な YAML（.lock.yml）にコンパイルするという仕組みを取っています。

GitHub が想定するユースケース

公式ブログでは、gh-aw の活用領域として次の 6 つが紹介されています。

継続的トリアージ: Issue の自動要約・ラベル付け・ルーティング
継続的ドキュメント作成: README をコード変更に同期
継続的コード簡素化: コード改善の反復的検出
継続的テスト改善: テストカバレッジの評価と追加
継続的品質維持: CI 失敗の調査と修正提案
継続的レポーティング: リポジトリ健全性のレポート生成

主な特徴

gh-aw には次のような特徴があります。

Markdown でワークフローを記述: YAML を直接書く必要がなく、フロントマターで設定、本文にプロンプトを定義
セキュリティ機能: 公式ブログでは「デフォルトで読み取り専用権限で実行」と強調されており、サンドボックス化された実行環境、ツールの許可リスト、ネットワーク分離、プロンプトインジェクション攻撃への対策が実装されている
Safe Outputs: エージェントの書き込み操作（PR コメントなど）を制御・制限する仕組み。PR は自動マージされず、人間のレビューが必須
複数 AI エンジン対応: GitHub Copilot（デフォルト）、Anthropic の Claude、OpenAI の Codex、Google の Gemini から選択可能。Copilot 利用時は各実行で通常 2 つのプレミアムリクエストを消費

ワークフローの構成

gh-aw のワークフローは大きく 2 つのファイルで構成されます。

.md ファイル（ソース）: 開発者が編集するファイル。フロントマターに設定、本文にプロンプトを記述
.lock.yml ファイル（生成物）: gh aw compile で自動生成される GitHub Actions ワークフローファイル。「DO NOT EDIT」と明記されている

フロントマターでは次のような設定が可能です。

---
description: |
    Checks the impact of dependency updates from Renovate PRs.

on:
    bots:
        - "renovate[bot]"
    pull_request:
        types: [ opened, labeled ]

if: |
    github.event.pull_request.user.login == 'renovate[bot]'

permissions: read-all

safe-outputs:
    add-comment:
        max: 1

tools:
    github:
        toolsets: [ default ]
    bash:
        - gh
    web-search:
    web-fetch:

engine:
    id: claude
    model: claude-haiku-4-5

timeout-minutes: 15
---

コンパイルすると、この約 40 行のフロントマターから 1,000 行を超える lock.yml が生成されます。生成される YAML には、次のような複数のジョブが含まれます（v0.50.2 時点の構成であり、バージョンによって変わる可能性があります）。

pre_activation: トリガー元のメンバーシップ確認とアクティベーション判定
activation: プロンプトの構築・テンプレート展開・バリデーション
agent: AI エージェントの実行（sandbox 内）と threat detection（エージェントの挙動分析）
safe_outputs: エージェントの出力をもとに書き込み操作を実行
conclusion: ワークフロー全体の結果まとめ

期待と現実のギャップ

公式ブログの紹介だけ見ると、次のようなシンプルなフローを期待します。

.md ファイルを書く → gh aw compile → ワークフローが動く

確かに、フロントマターとプロンプトの記述は簡単です。しかし、実際の運用フローはこうなります。

.md ファイルを書く → gh aw compile → 1,000 行を超える .lock.yml が生成される
→ .lock.yml を Git にコミットして管理する → ワークフローが動く（かもしれない）
→ 期待通りに動かない場合は .lock.yml を読んで原因を調査する
→ フロントマターで直せない → .lock.yml を手動修正する → 動く
→ gh-aw がアップデートされる → 再コンパイルする → 手動修正が消える → 最初に戻る

特に重要なのは、生成された 1,000 行を超える lock.yml を自分で Git 管理しなければならないという点です。gh-aw はこのファイルを「DO NOT EDIT」と明記していますが、コンパイラが正しく動作しない場合は編集せざるを得ません。そして、コンパイラのバージョンが上がるたびに生成結果が変わるため、差分の確認と手動修正の再適用が必要になります。

「YAML を書かなくていい」はずが、実際には Markdown と YAML の両方を理解して管理する必要があるのが現状です。

2. 実際に作ったワークフロー：Renovate 依存関係影響度チェック

ここでは、実際に構築した gh-aw ワークフローの内容と、導入の背景を紹介します。

背景

gh-aw のテクニカルプレビューが公開されたとき、何かこれを活用できるワークフローがないかと考えていました。私たちの Android プロジェクトでは Renovate を使って依存関係を自動更新していますが、Renovate が PR を作成するたびに、その更新が安全かどうかを人手で確認する必要がありました。この確認作業は AI エージェントとの相性がよさそうだと考え、gh-aw の最初の活用先として選びました。

公式ブログで紹介されている 6 つのユースケースのうち、「継続的レポーティング」にもっとも近い活用方法です。

ワークフローの処理フロー

ワークフローは次の流れで処理を実行します。

トリガー: Renovate が PR を作成 or renovate-impact-check ラベルが付与されたとき
差分解析: PR の diff から更新された依存関係とバージョン変更を抽出
リリースノート調査: Web 検索で各依存関係の公式リリースノートやチェンジログを調査
コードベース影響分析: プロジェクト内で該当依存関係がどこで使われているかを検索し、破壊的変更の影響を評価
レポート投稿: 影響度（低/中/高）とマージ判定を含むレポートを PR コメントとして投稿
ラベル削除: 再実行用の renovate-impact-check ラベルを削除（次回のために）

実際の出力例

エージェントが投稿するレポートは次のような構成です。

このように、各依存関係について影響度・主な変更点・破壊的変更の有無・必要な対応を整理した形式で報告されます。レビュアーはこのレポートを参考に、マージ判断を効率的に行えます。

gh-aw に期待したこと

gh-aw を試すにあたって、次の点に魅力を感じていました。

Markdown でプロンプトを書くだけという手軽さに魅力を感じた
GitHub 公式ツールとしての信頼性
Safe Outputs によるエージェントの書き込み制御
公式ブログで紹介されているセキュリティ機能（サンドボックス、ネットワーク分離、threat detection）への期待

エンジンの選択

gh-aw は複数の AI エンジンに対応しており、エンジンによって認証方法やコスト体系が異なります。

エンジン	API キー	コスト
Copilot（デフォルト）	`COPILOT_GITHUB_TOKEN` が必要	Copilot プレミアムリクエスト消費
Claude	`ANTHROPIC_API_KEY` が必要	Anthropic API 利用料
Codex	OPENAI_API_KEY が必要	OpenAI API 利用料
Gemini	GEMINI_API_KEY が必要	Google API 利用料

Copilot は GitHub のトークンで動作するため外部サービスの API キー管理が不要で、導入ハードルがもっとも低いですが、プレミアムリクエストを消費するため、チームの Copilot 利用状況によっては制約になります。

今回は Anthropic の Claude（claude-haiku-4-5）を選択しました。理由は 3 つあります。

1 つ目は、API キーで直接利用できるため、Copilot のプレミアムリクエスト枠を圧迫せずにコスト管理がしやすいこと。

2 つ目は、依存関係のリリースノートが Renovate の PR 内に含まれない場合に Web Search で調査させたかったためです。Copilot エンジンでも MCP サーバー（Tavily）経由で Web Search を利用する方法に記載されていますが、別途 Tavily の API キーの取得・管理が必要になります。Claude エンジンではフロントマターに web-search: と記述するだけでビルトインの Web Search が利用でき、追加の APIキー管理が不要なため、導入の手軽さを優先して Claude を選択しました。

3 つ目は、モデルのコストです。このワークフローはリリースノートの調査だけでなくコードベース全体への影響度分析も行うため、1 回の実行あたりのトークン消費量がそれなりに大きくなります。Renovate が PR を作成するたびに実行されることを考えると、claude-opus-4-6 のような上位モデルではコストが見合わないため、十分な性能をもちつつコストを抑えられる claude-haiku-4-5 を選びました。

3. 運用で直面した問題

実際に運用を始めると、いくつかの深刻な問題に直面しました。公式ブログが謳う「安全なデフォルト設定」や「Markdown での簡単な記述」とは裏腹に、コンパイラの生成する lock.yml が期待どおりに動作しないケースが複数ありました。

コンパイラの不安定さ

運用期間中（v0.46.0〜v0.49.1）に遭遇した問題の例を挙げます。

concurrency グループの設定が不適切で、ワークフローが自動キャンセルされる: 別のワークフロー（Labeler）が PR にラベルを付与するだけで、実行中のワークフローがキャンセルされ、結果としてどちらも実行されない状態になった
コンパイラのバージョンアップで必要な権限が消える: v0.46.0 では PR コメント投稿に必要な pull-requests: write が自動付与されていたが、v0.47.2 以降で生成されなくなり、コメント投稿が Resource not accessible by integration エラーで失敗するようになった
コンパイラが古い Action バージョンを使用する: actions/download-artifact が v6 で固定されており、リポジトリ内の他のワークフロー（v7）と一致しない。さらに、lock.yml は Git 管理されているため、Renovate がこの差分を検出して v7 へのアップデート PR を毎回作成してくる。しかし lock.yml はコンパイラが生成するファイルなので Renovate で更新しても再コンパイルで元に戻ってしまい、対応しようのない PR が繰り返し作られる状態になった
Bot アカウントがメンバーシップチェックで弾かれる: フロントマターに bots を設定しても、コンパイラが生成するメンバーシップチェックには反映されず、renovate[bot] がワークフローをトリガーできなかった（v0.49.1 で構文変更とともに修正）

これらは一例であり、バージョンが上がるたびに「以前は動いていたものが動かなくなる」「フロントマターの設定が期待どおりに lock.yml に反映されない」という問題が繰り返し発生しています。

フロントマターで制御できない問題

上記の問題に共通するのは、フロントマター（.md）からは制御できず、lock.yml を直接編集するしかないという点です。

たとえば、concurrency の問題はコンパイラが生成するデフォルトの concurrency グループ自体が不適切だったことに起因しており（v0.48.1で修正）、現在はフロントマターフィールドも追加されています。しかし、コンパイラが生成する lock.yml の内容が期待どおりでない場合に、フロントマターから修正する手段が常に用意されているわけではなく、lock.yml を手動編集するしかないケースがあります。lock.yml に「DO NOT EDIT」と明記されているにもかかわらず、手動編集しないと正しく動作しないことがあるのが現状です。

さらに厄介なのは、コンパイラのバージョンアップで問題が修正されることもあれば、新たな問題が発生することもあるという点です。たとえば、権限の問題について gh-aw の GitHub リポジトリには関連 Issue があり、pull-requests: write は不要であるとして close されています。しかし、実際に削除してテストすると同じエラーが再現しました。Issue の結論と実際の挙動が一致しておらず、何が正しい状態なのかの判断も難しい状況です。

メンテナンスコスト

gh-aw はテクニカルプレビュー段階で活発に開発されており、Renovate 経由でのアップデートが 1 日に 1〜2 回来ることもあります。セキュリティを重視して常に最新バージョンに追従しようとすると、アップデートのたびに次の作業が発生します。

Renovate が gh-aw のバージョン更新 PR を作成
gh aw compile で lock.yml を再生成
生成された lock.yml の差分を確認し、手動修正が上書きされていないかチェック
上書きされた手動修正を再適用（現時点で 4 箇所）
新たな問題が発生していないか動作確認

アップデート頻度自体は、Renovate のスケジュール設定で特定の依存関係のアップデート間隔を制御できるため、緩和は可能です。しかし、アップデート頻度を下げたとしても、再コンパイルのたびに手動修正を再適用する作業や、lock.yml 内の Action バージョンがコンパイラによって古いまま固定される問題は解消されません。

さらに、gh-aw で管理するワークフローが増えるほど、コンパイラのバグに当たる確率が上がり、ワークフローごとに異なる手動修正を管理する必要が出てくるため、メンテナンスコストは非線形に増加します。

4. 今後の方針：claude-code-action への移行

運用で見えた課題を踏まえ、今後の方針について述べます。

gh-aw の構造的な課題

ここまで挙げた問題の多くはコンパイラのバグに起因しており、テクニカルプレビュー段階であることを考えれば、ある程度は許容できます。しかし、仮にすべてのバグが修正されたとしても、gh-aw の設計そのものに起因する課題は残ると考えています。

コンパイル生成物を Git 管理させる設計

通常のビルドシステムでは、生成物は .gitignore に入れるか、CI 上でその場で生成するのが一般的です。しかし gh-aw では、CLI が生成するファイルをユーザーが Git 管理しなければなりません。

ファイル	内容
`.github/workflows/*.lock.yml`	GitHub Actions ワークフロー本体
`.github/aw/actions-lock.json`	Action の SHA ピニングキャッシュ。アクション名とバージョンタグを SHA ハッシュにマッピングする

これらは gh aw compile のたびに再生成され、リポジトリにコミットして管理する必要があります。

この設計は、コンパイラのバグとは無関係にいくつかの問題を引き起こします。生成物であるにもかかわらず Git 管理されているため、Renovate のような自動更新ツールが lock.yml 内の Action バージョンを検出してアップデート PR を作成してきます。しかしコンパイラが生成するファイルなので、Renovate で更新しても再コンパイルで元に戻ります。また、コンパイラのバージョンアップで生成結果が変わるため、再コンパイルのたびに差分の確認と手動修正の再適用が必要になります。これらは生成物を Git 管理させる設計から必然的に生じる問題であり、コンパイラの品質が向上しても構造的に解消されません。

抽象化にエスケープハッチがない

concurrency のようにフロントマターフィールドが追加されつつある設定もありますが、コンパイラが生成する lock.yml の内容が期待どおりでない場合に、フロントマターから修正できるとは限りません。lock.yml の一部を上書きする汎用的な仕組みも用意されておらず、フロントマターで書けないことは lock.yml を直接編集するしかなく、抽象化レイヤーとして不完全です。フロントマターのフィールドが段階的に拡充されない限りこの問題は解消されません。

AI 時代における抽象化の価値

gh-aw の売りは「YAML を書かなくていい、Markdown だけでいい」という点です。しかし、Claude Code のようなコーディングエージェントが普及した現在、GitHub Actions の YAML を直接書くこと自体がすでに容易になっています。Claude Code に「Renovate の PR が来たらリリースノートを調査してコメントするワークフローを書いて」と頼めば、動作する YAML を直接生成してくれます。gh-aw の抽象化レイヤーが価値をもつには、コンパイラが安定的に正しく動作する lock.yml を出力してくれることが大前提ですが、前述の設計上の課題を踏まえると、抽象化のメリットよりも .md と .lock.yml の 2 つのレイヤーを管理するコストの方が上回っています。

claude-code-action への移行を検討

Anthropic が提供する claude-code-action は、通常の GitHub Actions ステップとして AI エージェントを実行できるアクションです。

比較項目	gh-aw	claude-code-action
ワークフロー記述	Markdown + コンパイラ	通常の YAML
カスタマイズ性	フロントマターで制限される	YAML で完全制御
パーミッション管理	コンパイラ任せ（バグあり）	自分で直接設定
concurrency 設定	フロントマターで一部制御可能だが制約あり	自由に設定可能
Action バージョン管理	コンパイラが決定	自分で管理
セキュリティ機能	ファイアウォール、sandbox、threat detection	GitHub Actions 標準の権限モデル
生成ファイルサイズ	1,000 行を超える lock.yml	必要な分だけ
メンテナンスコスト	再コンパイルのたびに手動修正	通常の YAML メンテナンス

私たちのユースケース（Renovate bot がトリガー、コメント投稿のみ）では、gh-aw のセキュリティ機能は過剰であり、claude-code-action で十分対応可能です。

gh-aw が適しているユースケース

公式ブログが紹介するセキュリティ機能（サンドボックス、ネットワーク分離、threat detection、プロンプトインジェクション対策）が活きるのは、次のようなケースだと考えます。

パブリックリポジトリで外部コントリビュータの入力をトリガーにエージェントが動作する場合
エージェントに広い書き込み権限を付与する必要がある場合
コンプライアンスや監査要件が厳しい環境

逆に、社内リポジトリで信頼できるトリガー（bot や内部メンバー）から実行し、操作が限定的（コメント投稿のみなど）なケースでは、gh-aw の複雑さはメリットよりもコストが上回ります。公式ブログで紹介されている 6 つのユースケースのうち、信頼できるイベントをトリガーとするもの（コード変更に同期したドキュメント更新、CI 失敗の調査など）は、claude-code-action でも同等に実現可能です。

まとめ

gh-aw の「Markdown で AI エージェントワークフローを記述できる」というコンセプトは魅力的です。公式ブログで紹介されているセキュリティ機能や 6 つのアプリケーション領域も、将来的には強力な自動化基盤になる可能性を感じます。

しかし、テクニカルプレビュー段階の現時点では、次のような課題がありました。

コンパイラの信頼性: バージョンアップのたびに生成結果が変わり、以前動いていたワークフローが壊れる
カスタマイズ性の不足: フロントマターで制御できない設定があり、「DO NOT EDIT」の lock.yml を手動編集せざるを得ない
メンテナンスコストの高さ: 高頻度のアップデートに対して毎回手動修正が必要で、ワークフローが増えるほどコストが非線形に増加する
設計上の課題: コンパイル生成物を Git 管理させる設計や、抽象化にエスケープハッチがない点は、コンパイラのバグが修正されても構造的に解消されない

特に、Renovate のような自動更新ツールと組み合わせて常に最新バージョンを維持しようとすると、運用が成り立ちにくい状況です。

今後は claude-code-action への移行を進め、gh-aw については GA リリース後に改めて評価する予定です。コンパイラの安定性に加えて、生成物の Git 管理を不要にする仕組みやフロントマターのエスケープハッチといった設計面の改善も進めば、再び検討の余地はあると思います。しかし現時点では、Claude Code のようなコーディングエージェントを使えば GitHub Actions の YAML を直接書くことも容易であり、不安定な抽象化レイヤーを介するよりも、通常の YAML を直接管理する方が透明性が高くメンテナンスしやすいというのが実感です。

Giftmall Inside Blog

GitHub Agentic Workflows の期待と現実 - テクニカルプレビューを運用して見えた課題