github-agentic-workflows

GitHub Agentic Workflows

手順

ステップ 1：リポジトリの状態を確認する

1. .github/workflows/、.github/agents/、既存の .lock.yml ファイル、および gh aw の使用状況をワークスペースで確認します。
2. Node ランタイムが利用可能な場合は、node skills/github-agentic-workflows/scripts/find-gh-aw-targets.mjs . を実行します。
3. コンパイラーに関わる判断を行う前に gh aw version を実行し、ワークフローの作成手順がインストール済み CLI の動作に合っていることを確認します。
4. リポジトリに候補となるワークフローが複数ある場合は、ユーザーが指定したワークフロー、または現在のイシュー、プルリクエスト、もしくは自動化の対象に最も関連するワークフローを優先します。
5. リポジトリに GH-AW の設定がなく、タスクがエージェント型ワークフローの作成または保守である場合は、編集前に references/authoring.md を読みます。
6. タスクがエージェント型の Markdown ワークフローを使わない、標準的な決定論的 GitHub Actions YAML に限定される場合は、ここで作業を終了し、このスキルが適用されないことを説明します。

ステップ 2：作業モードを選択する

1. タスクを次のいずれかに分類します：リポジトリの設定、新しいワークフローの作成、ワークフローの改訂、別のリポジトリからのワークフローのインストール、セキュリティレビュー、失敗のデバッグ。
2. スケジュールされたレポート、イシューまたは PR のトリアージ、オーケストレーション、エージェントの引き継ぎに関する開始パターンが必要な場合は、references/examples.md を読みます。
3. ワークフローで安全な出力、ネットワークポリシー、認証、ロックダウン、脅威の検出、または実行の可観測性が必要な場合は、references/security-and-operations.md を読みます。
4. ワークフローのコンパイル、インストール、認証、安全な出力の実行、またはツールへのアクセスに失敗した場合は、references/troubleshooting.md を読みます。 ステップ 3：ワークフローのソースを作成または修正する
5. ワークフローの信頼できる唯一の情報源は .github/workflows/<workflow-name>.md に置きます。
6. 新しいワークフローを作成する場合は、基本形として assets/workflow.template.md を使用します。
7. タスクを満たす範囲で、トリガーの対象とリポジトリのロールの範囲を最小限にします。
8. エージェント関連セクション以外で、ワークフローにより広範な GitHub Actions 権限が本当に必要な場合を除き、permissions: は読み取り専用にします。
9. エージェントに直接書き込みアクセスを付与する代わりに、コメント、イシュー、ラベル、PR、エージェントの割り当て、オーケストレーションには safe-outputs: を優先して使用します。
10. safe-output ワークフローでは、アクションが不要な場合に noop を呼び出すようエージェントに指示します。
11. tools: と toolsets: は最小限にし、タスクに必要なものだけにします。
12. タスクで別のエンジンが明示的に必要で、リポジトリがそのエンジンの認証方式に対応済みの場合を除き、デフォルトで engine: copilot を使用します。実験的なマルチプロバイダールーティングには engine: pi を、Copilot SDK モードには copilot-sdk: true を使用します。サードパーティ製エンジン（cursor、kiro、aider、crush、opencode）は gh aw add でインポートできます。
13. network: は最小権限で設定します。コンパイラが対応している場合は、個別のレジストリドメインよりも node、python、github などのエコシステム識別子を優先します。
14. ワークフローがスケジュール実行される場合、または大規模なエージェントのターンを引き起こす可能性がある場合は、max-ai-credits: を設定して、1 回の実行あたりの AI Credits（AIC）消費量が徐々に増加する前に上限を設けます。
15. strict モードとインストール済み CLI が、ワークフローで引き続き必要なカスタムドメインを拒否する場合は、ファイアウォールを広く緩和するのではなく、決定性のあるセットアップ手順で外部ソースを事前取得し、ローカルファイルをエージェントに渡します。
16. 実際の実行で ${{ steps.<id>.outputs.* }} プレースホルダーがエージェントから見える Markdown 本文に渡されることを前提にしないでください。プロンプトの指示が実行時の値に依存する場合は、セットアップ時に決定性のあるローカルファイルへ書き込み、そのファイルを読むようエージェントに指示します。
17. インポート済みワークフローや再利用可能なワークフローは、リポジトリに共有ロジックやオーケストレーションが本当に必要な場合にのみ使用します。
18. 動的な入力の集合を対象に繰り返し実行する作業では、再利用可能な GH-AW ワーカーと、検出およびマトリックスへの展開を行う決定性のある YAML ラッパーを優先します。
19. 再利用可能な GH-AW ワーカーをマトリックスから呼び出す場合、デフォルトの共有ワークフローレベルの concurrency グループをそのまま使用しないでください。マトリックス入力またはプロンプトの識別情報をキーにした明示的な concurrency グループを設定し、GitHub の「実行中 1 件、保留中 1 件」の concurrency 動作によって並行する実行がキャンセルされないようにします。
20. frontmatter、インポート、その他のコンパイル時設定を変更した後は、ワークフローを再コンパイルします。
21. Markdown 本文だけが変更され、ワークフローを GitHub.com 上で直接編集する場合は、本文の変更だけを理由に再コンパイルしないでください。
22. ワークフローでそのパス内のチェックイン済みファイルを意図的に使用する場合を除き、ローカルでの compile、validate、trial の各フローでは .github/aw/ を一時的な GH-AW のランタイムおよびコンパイラ用スクラッチ領域として扱います。 ステップ 4：リポジトリの前提条件と認証を設定する
23. リポジトリを初めてセットアップする前に、references/authoring.md を読みます。
24. リポジトリが GH-AW のオーサリング用に設定されておらず、ユーザーが永続的なセットアップを希望する場合は、gh aw init を実行します。
25. gh aw secrets bootstrap または gh aw secrets set を使って、エンジンのシークレットを設定します。
26. Copilot エンジンの認証には、COPILOT_GITHUB_TOKEN または copilot-requests Actions 権限を使います。
27. Copilot の実行には、COPILOT_GITHUB_TOKEN にファイングレイン PAT を設定します。一般的な gho_... OAuth トークンはシークレットチェックを通過しても、実際の Copilot 実行で失敗することがあります。
28. gh aw trial を使う場合は、ホストリポジトリにも必要なエンジンシークレットが設定されていることを確認します。論理リポジトリやソースリポジトリのシークレットは、一時ホストリポジトリや再利用可能なホストリポジトリに自動的にコピーされません。
29. 拡張機能のアップグレード後や再インストール時には、gh aw version を再確認して、リポジトリのガイダンスとコンパイラーの動作が一致した状態を保ちます。
30. 決定論的なラッパーが再利用可能なワーカーを呼び出す場合、呼び出し元のワークフローの権限を、ネストされたワーカーが要求する actions、contents、pull-requests の各スコープと同等以上にします。そうしないと、エージェントの実行開始前に実行が失敗することがあります。
31. ワークフローでリポジトリをまたぐ読み取りや書き込み、Projects へのアクセス、リモート GitHub ツールモード、または高度なセーフアウトプットが必要な場合は、GitHub App またはカスタム GitHub トークンを使います。
32. リポジトリが公開されており、ワークフローが信頼できない外部コンテンツを調査する場合、タスクが明示的に低リスクの公開ワークフローでない限り、ロックダウンと承認の制御を維持します。

ステップ 5：検証、コンパイル、実行

1. ワークフローで非推奨のフィールドが使われている場合や、コンパイラーが自動変換可能な差分を指摘した場合は、gh aw fix --write を実行します。
2. ワークフローを準備完了とみなす前に、gh aw validate --strict を実行します。
3. CLI のバージョンが変わった場合や、ワークフローが新しいフロントマターの動作に依存している場合は、gh aw compile --verbose を実行して、警告と生成バージョンの変更を確認できるようにします。
4. 検証に成功した後、gh aw compile を実行し、.md ソースファイルと生成された .lock.yml ファイルの両方をコミットします。
5. リモートディスパッチの動作を検証するには、gh aw run <workflow> --dry-run を使います。特に、ブランチ、トリガー、ワークフローの検出に問題があると思われる場合に有効です。
6. プッシュする前にローカルのワークフローソースを実行する必要がある場合は、gh aw trial ./.github/workflows/<workflow>.md を使います。明示的な ./ パスが重要です。これがないと、CLI が引数をローカルファイルではなくリポジトリ仕様として解析することがあります。
7. 直接実行には、ワークフローのソースまたはロックファイルが対象ブランチに実際に存在する場合に限り、gh aw run <workflow> を使います。
8. 変更後の状態、失敗、コスト、ツールの使用状況、成功傾向を確認するには、gh aw status、gh aw logs、gh aw audit、gh aw health を使います。

ステップ 6：専門的に運用し、改善する

1. ワークフローを簡素化できるか、小さなワークフローに分割できるか、または共有コンポーネントに変換できるかを検討します。
2. 大規模にイシュー、コメント、プルリクエストを作成するワークフローを初期展開する際は、段階的なセーフアウトプットを優先します。
3. 定期的なメンテナンスでは、インストール済みの gh-aw バージョンを意図的に固定または確認し、場当たり的なコピー＆ペーストではなく、gh aw update または gh aw upgrade を使ってワークフローを更新します。
4. ワークフローのプロンプトは具体的で、範囲が明確で、監査可能なものにします。複数のワークフローで同じルールが必要な場合は、広範な方針を再利用可能なインポートやエージェントファイルに移します。

エラー処理

• gh extension install github/gh-aw が失敗する場合は、references/troubleshooting.md に記載されているスタンドアロンインストーラーの手順を使用してください。
• コンパイルに失敗する場合は、続行する前にフロントマターの構文、非推奨のフィールド、インポート、権限の不一致を修正してください。
• コンパイラーの動作が参照しているドキュメントと一致しない場合は、インストール済みの gh aw version を信頼し、ワークフローの形式を書き換える前に、そのバージョンで検証してください。
• gh aw trial が .github/workflows/<name>.md を無効なリポジトリ指定として拒否する場合は、./.github/workflows/<name>.md のようにローカルパスを明示して再試行してください。
• 再利用可能なワーカーを単独で実行すると成功するのに、ラッパーの実行が起動時に失敗する場合は、ワーカーのロジックを変更する前に、呼び出し元ワークフローの permissions: の継承を調べてください。
• 再利用可能な GH-AW ワーカーのマトリックスで、ほとんどのジョブがすぐにキャンセルされる場合は、まず呼び出されるワークフローの concurrency グループを調べてください。共有のワークフローレベルグループがあると、cancel-in-progress が false でも保留中のジョブがキャンセルされます。
• Validate COPILOT_GITHUB_TOKEN secret のステップでトライアル実行が失敗する場合は、gh secret list -R <host-repo> を使ってホストリポジトリを調べてください。ソースリポジトリのシークレットはトライアルホストに継承されません。
• gh aw trial --force-delete-host-repo-before が失敗する場合は、ホストリポジトリへの管理者権限があること、および現在の GitHub 認証トークンに delete_repo スコープが含まれていることを確認してください。
• 実行中にワークフロープロンプトに未解決のランタイムプレースホルダーが表示される場合は、それらの値を生成されたローカルコンテキストファイルに移し、エージェントにそのファイルを明示的に読み込ませてください。
• ローカルの gh aw compile、gh aw validate、または gh aw trial コマンドによって actions-lock.json やログなどの .github/aw/ ファイルが作成された場合は、リポジトリで意図的に保持しているのでない限り、一時的な生成物として扱い、コミット前に削除してください。
• セーフアウトプットが何もしない場合は、ステージングモードが意図したものかを確認し、書き込みアクションが不要な場合に noop を呼び出すようプロンプトでエージェントに明示的に指示していることを確認してください。
• コンパイル済みのスケジュール済みワークフローのソースに対して gh aw mcp inspect がスケジュール解析の曖昧さに関するエラーで失敗する場合は、まず検査経路の制限として扱ってください。gh aw compile を再実行し、インストール済みワークフローまたは実行ログに基づくデバッグを優先してください。検証とコンパイルがすでに成功している場合は、ワークフロー自体が無効だと決めつけないでください。
• コンパイラーが、以前の例では有効に見えるエンジンフィールドやツール項目を拒否する場合は、インストール済みのスキーマを信頼してください。gh aw v0.58.3 では、Copilot に engine.max-turns はサポートされず、bash は true、false、または許可リストである必要があります。また、ブール値が指定できない箇所では、値のない edit: や web-fetch: キーが受け入れられます。
• URL が (redacted) としてサニタイズされたり、ツールが必要なサービスにアクセスできなかったりする場合は、ファイアウォールを無効にするのではなく、network.allowed を慎重に調整し、許可対象を拡張してください。
• トークンを設定しているのに Copilot の推論が失敗する場合は、PAT の所有者が実際に Copilot のライセンスと推論へのアクセス権を持っていることを確認してください。
• パブリックリポジトリのワークフローで外部コントリビューターのコンテンツが取得されない場合は、ワークフローのロジックを変更する前に、GitHub のロックダウンモードがそのコンテンツをブロックしていないか確認してください。