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 をデフォルトにします。
13. network: は最小権限で設定します。コンパイラーが対応している場合は、個別のレジストリドメインより node、python、github などのエコシステム識別子を優先します。
14. strict mode とインストール済み CLI が、ワークフローで依然として必要なカスタムドメインを拒否する場合は、ファイアウォールを広く緩和するのではなく、決定的なセットアップ手順で外部ソースを事前取得し、ローカルファイルをエージェントに渡します。
15. 実行時に ${{ steps.<id>.outputs.* }} のプレースホルダーがエージェントから参照できる Markdown 本文に渡されることを前提にしないでください。プロンプトの指示が実行時の値に依存する場合は、セットアップ中にその値を決定的なローカルファイルに書き込み、エージェントにそのファイルを読むよう指示します。
16. リポジトリが共有ロジックやオーケストレーションから実際に恩恵を受ける場合に限り、インポート済みまたは再利用可能なワークフローを使用します。
17. 動的な入力セットに対する定期的な処理では、再利用可能な GH-AW ワーカーと、検出およびマトリックスへの展開を行う決定的な YAML ラッパーを優先します。
18. マトリックスから再利用可能な GH-AW ワーカーを呼び出す場合、デフォルトの共有ワークフローレベルの concurrency group をそのまま使用しないでください。入力マトリックスまたはプロンプトの識別情報をキーにした明示的な concurrency group を設定し、GitHub の「実行中 1 件・保留中 1 件」という concurrency の動作によって並列実行がキャンセルされないようにします。
19. frontmatter、インポート、またはその他のコンパイル時設定を変更した後は、ワークフローを再コンパイルします。
20. Markdown 本文のみを変更し、GitHub.com 上でワークフローを直接編集する場合は、本文の変更だけを理由に再コンパイルしないでください。
21. ワークフローがそのパスのファイルを意図的にチェックインして使用する場合を除き、ローカルでのコンパイル、検証、試行の間、.github/aw/ は一時的な GH-AW のランタイムおよびコンパイラーの作業領域として扱います。 ステップ 4：リポジトリの前提条件と認証を設定する
22. リポジトリを初めてセットアップする前に、references/authoring.mdを読みます。
23. リポジトリが GH-AW の作成用に設定されておらず、ユーザーが永続的なセットアップを希望する場合は、gh aw initを実行します。
24. gh aw secrets bootstrapまたはgh aw secrets setを使って、エンジンのシークレットを設定します。
25. Copilot エンジンの認証には、COPILOT_GITHUB_TOKENを使います。
26. Copilot を実行する場合は、COPILOT_GITHUB_TOKENにきめ細かい PAT を使います。一般的なgho_... OAuth トークンはシークレットチェックを通過しても、実際の Copilot 実行には失敗することがあります。
27. gh aw trialを使う場合は、ホストリポジトリにも必要なエンジンのシークレットが設定されていることを確認します。論理リポジトリまたはソースリポジトリのシークレットは、一時的なホストリポジトリや再利用可能なホストリポジトリに自動的にコピーされません。
28. 拡張機能のアップグレード後や再インストール後は、gh aw versionを再確認して、リポジトリのガイダンスとコンパイラの動作を一致させます。
29. 決定論的なラッパーが再利用可能なワーカーを呼び出す場合は、呼び出し元のワークフローの権限を、ネストされたワーカーが要求するactions、contents、pull-requestsのスコープと同等以上にします。そうしないと、エージェントの実行開始前に実行が失敗することがあります。
30. ワークフローでリポジトリをまたぐ読み取りや書き込み、Projects へのアクセス、リモート GitHub ツールモード、高度なセーフ出力が必要な場合は、GitHub App またはカスタム GitHub トークンを使います。
31. リポジトリがパブリックで、ワークフローが信頼できない外部コンテンツを調査する場合は、そのタスクが明示的に低リスクなパブリックワークフローでない限り、ロックダウンと承認の制御を維持します。

ステップ 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 のロックダウンモードがそのコンテンツをブロックしていないか確認してください。