scaffold-github-cloud-agent-environment

scaffold-github-cloud-agent-environment

対象リポジトリを、Copilot クラウドエージェントが変更をビルドおよび検証できる状態にします。まずリポジトリとセッションの証拠を確認し、プラットフォームの仕様が不明確、古い、または変更されている場合は、関連する GitHub 公式ドキュメントを参照してください。

意思決定ツリー

ユーザーは何を求めていますか？

• .github/workflows/copilot-setup-steps.yml がまだ存在しない場合： リポジトリを監査し、未解決のプラットフォーム上の前提を確認して、計画を作成し、重大な阻害要因を解消してから、ワークフローをプレビューして生成します。
• copilot-setup-steps.yml ファイルは存在するものの、内容が不十分、古い、または誤っている場合： ワークフローと失敗の証拠を調べ、カスタム手順を維持しながら、根拠のある最小限の修正を行います。再生成するのは、差分をプレビューし、復元可能なバックアップを確保したうえで、意図的に置き換える場合に限ります。
• ワークフロー生成後にエージェントの実行が失敗する、または予期しない動作をする場合： まず doctor モードを実行し、セッションログの証拠とリポジトリの事実から、修正がリポジトリ内で必要か GitHub の設定で必要かを特定してから、証拠で裏付けられる内容だけを修正します。
• ユーザーが説明または計画だけを求めている場合： 未解決の疑問に必要なリファレンスのみを読み、ワークフローを生成せずに回答します。

クイックリファレンス

タスク	アクション
不確かなプラットフォーム仕様を確認する	references/live-docs.md から関連する公式 URL を選択します
対象リポジトリを監査する	scripts/audit_project.sh /path/to/project を実行します
リポジトリの事実に基づいて計画を作成する	python3 scripts/suggest_plan.py --project /path/to/project を実行します
生成されるワークフローをプレビューする	意図的に書き込む前に python3 scripts/render_setup_workflow.py --project /path/to/project --plan /path/to/plan.json --stdout を実行します
既存のセットアップを診断する	python3 scripts/doctor.py --project /path/to/project --symptom "describe the failure" --json を実行します
ファイルを書き込む前に確認すべきリポジトリに関する質問を把握する	references/project-analysis.md を読みます
エコシステム固有の依存関係手順を選ぶ	references/patterns.md を読みます
症状と修正方法の対応を確認する	references/doctor-mode.md を読みます

必須のワークフロー

1. 安定した既知の修正については、リポジトリのファイル、インストール済みツールのヘルプやバージョン情報、およびセッションログを使用します。これらの情報が不十分、古くなっているように見える、またはプラットフォームの仕様が変わる場合は、関連する公式ドキュメントを確認します。修正のたびにすべてのページを取得する必要はありません。
2. 手順、ランナー、環境に関する前提を決める前に、リポジトリを監査します。
3. リポジトリ内の修正と GitHub の設定に関する修正を区別します。
   • リポジトリ内：.github/workflows/copilot-setup-steps.yml、.github/copilot-instructions.md、パッケージマネージャーのセットアップ、LFS のチェックアウト、サービスコンテナー
   • 設定レベル：ランナーのポリシー、ファイアウォールの許可リスト、ワークフローの承認、copilot 環境のシークレットまたは変数
4. プロジェクト固有の判断は、レンダラーの中に埋め込まず、プラン JSON に記載します。
5. 重要な曖昧さはまずリポジトリの証拠から解消し、作業を妨げる問題がある場合は的を絞った質問をします。助言的な選択は、安全な作業を妨げる要因とせず、前提として記録します。妨げとなり得る問題には、次のものがあります。
   • リポジトリが Windows を示唆しているものの、要件が明確でない
   • 複数のパッケージマネージャーやツールチェーンが競合している
   • プライベートレジストリや社内ホストが存在する
   • セルフホストランナーまたはより大規模なランナーが必要となる可能性がある
   • テストが GitHub Actions の services では明らかに表現できないサービスに依存している
6. ワークフローの基点は .github/workflows/copilot-setup-steps.yml とし、ジョブ名は copilot-setup-steps の1つだけにします。
7. そのジョブでは、ドキュメントに記載されたキーのみを使用します。組み込みの許可リストは steps、permissions、runs-on、services、snapshot、timeout-minutes です。許可リストを拡張する前に、関連する仕様変更を確認してください。レンダラーは、プラットフォームがサポートするすべてのキーに対応しているわけではありません。
8. セットアップ手順の失敗は、ハードストップではなく、環境の劣化として扱います。ドキュメントによると、Copilot は残りのセットアップ手順をスキップし、その時点で利用可能な環境を使って処理を続行します。
9. デフォルトでは、決定論的な依存関係のインストールと、利用可能な環境に必要な範囲で制限したコード生成または準備を行います。通常、CI のライフサイクル全体を重複させないでください。ビルドと検証のコマンドは、リポジトリの手順書で提示します。
10. doctor モードでは、まずセッションログと観測された症状を確認します。ログやリポジトリの事実に裏付けられていない修正を推測しないでください。

仕様の根拠

未解決のプラットフォームに関する疑問は、該当する GitHub 公式ドキュメントのページで解決してください。以下は参照先のディレクトリであり、必読リストではありません。

• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-firewall
• https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/configure-runner-for-coding-agent
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/troubleshoot-cloud-agent
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/track-copilot-sessions
• https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/configuring-agent-settings
• https://docs.github.com/en/copilot/tutorials/cloud-agent/get-the-best-results
• https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions

更新情報を絞り込んで確認する方法と、更新を提案する手順については、references/live-docs.md を参照してください。組み込みの例に記載されたバージョン、ランナーラベル、キーの許可リスト、制限値は、その時点のスナップショットであり、永続的なアップグレード要件ではありません。

プロジェクト分析ルール

copilot-setup-steps.yml を作成または置き換える前に、次の項目を確認してください。

• .github/workflows/copilot-setup-steps.yml がすでに存在するかどうか
• パッケージマネージャー、ロックファイル、ツールチェーンのバージョンファイル
• CI ワークフローと、既存のランナー選択
• .github/copilot-instructions.md、.github/instructions/**/*.instructions.md、AGENTS.md、CLAUDE.md、GEMINI.md
• Git LFS の使用状況を確認するための .gitattributes
• .devcontainer/、Dockerfile、Compose ファイル、サービス要件
• .npmrc、.yarnrc.yml、pip.conf、.pypirc、.cargo/config.toml、nuget.config、settings.xml などのプライベートレジストリ設定ファイル
• Windows 限定または内部ネットワークに関する兆候

まず scripts/audit_project.sh を実行し、完全なチェックリストと質問項目が必要な場合は references/project-analysis.md を読んでください。

決定的な作業とヒューリスティックな作業

次の項目は決定的にしてください。

• ワークフローのパスとジョブ名
• 検証済みプラットフォーム契約に対応する、明示的にサポートされたジョブキー
• 上限が定められたタイムアウト（同梱のベースラインで規定されている最大値は 59 です。レンダラーはこの値を強制しません）
• 手動テストと PR テストを容易にする検証トリガー
• 最小権限の permissions
• リポジトリで Git LFS が明らかに使われている場合の LFS の有効化
• ワークフローの欠落、ジョブ名の誤り、未サポートのジョブキー、チェックアウトの欠落、設定のみが原因で失敗するケースに対する doctor のチェック

次の項目はヒューリスティックな判断に委ねつつ、その前提を明示してください。

• リポジトリに適したランナー戦略
• ワークフローでセットアップするツールチェーンの数
• 具体的な依存関係のインストールコマンド
• サービスコンテナを services で安全に表現できるかどうか
• リポジトリレベルまたは組織レベルでファイアウォールやランナーの変更が必要かどうか

ヒューリスティックな判断が正確性や安全性に大きく影響する場合は、その項目を questions に追加し、該当する変更を適用する前に解決してください。未解決のブロッカーを残したラベル付きプレビューは作成できますが、デプロイ可能な推奨案ではありません。ブロッカーではない前提は assumptions または notes に記載してください。

再実行時のルール

このスキルをプロジェクトに対して再度実行する場合：

• 根拠が不十分または古い場合や、プラットフォームに依存する契約が変更される場合は、関連する公式ドキュメントを再確認してください。
• 既存の計画が引き続き適切だと決めつけず、リポジトリを再監査してください。
• カスタムステップ、コメント、リポジトリのピンを保持する、最小限のパッチを優先してください。レンダラーは既存のワークフローにマージせず、ワークフロー全体を置き換えます。出力を事前に確認するには --stdout を使い、意図的に置き換える前に復元可能なバックアップを作成してください。計画の mode は上書きを防ぐ仕組みではありません。
• 更新のたびに、必須のジョブ名とパスを維持してください。
• 競合するセットアップファイルを追加するより、弱いセットアップの改善を優先してください。
• ユーザーが実際のエージェント実行での失敗を報告した場合は、まず doctor モードを使ってください。

スキャフォールドのルール

• 汎用的な名前のセットアップワークフローではなく、.github/workflows/copilot-setup-steps.yml を作成します。
• copilot-setup-steps という名前のジョブを、必ず1つだけ設定します。
• そのジョブでは、サポートされているジョブキーのみを使用します。
• timeout-minutes は59以下にします。
• ユーザーが明示的に、より実行頻度の低い検証方法を希望している場合を除き、ワークフローファイルを対象とする workflow_dispatch、push、pull_request トリガーを追加します。
• ワークフローでリポジトリをチェックアウトする場合は、contents: read を追加します。
• リポジトリで Git LFS を使用している場合は、リポジトリの固定バージョンに準拠した互換性のある actions/checkout のバージョンで lfs: true を有効にします。同梱の @v5 の例は過去のデフォルトであり、恒久的なプラットフォーム要件でも、アップグレードの指示でもありません。
• 独自の fetch-depth の値に依存しないでください。現行のドキュメントによると、Copilot がこの値を上書きします。
• セルフホストランナーでは、統合ファイアウォールを無効にし、ドキュメントに記載されている GitHub および Copilot のホストを許可するよう、ユーザーに求めます。
• Windows ランナーでは、統合ファイアウォールが Windows と互換性がないため、ネットワーク制御を明示的な設計判断として扱います。
• 認証情報やシークレット値をインラインで記述しないでください。シークレットとエージェント全体に適用する変数は、GitHub のドキュメントに記載されている環境／設定の仕組みを通じて設定します。シークレットではないセットアップ定数には、ドキュメントに記載されているワークフローの env の場所を使用できます（ヘルパーはステップレベルの env をサポートしています）。制限付きのセットアップジョブ許可リストが、ジョブレベルの env のサポートを意味するわけではありません。
• Copilot に明確なビルド、テスト、検証コマンドが必要な場合は、.github/copilot-instructions.md を補足ファイルとして用意します。

Doctor モード

Doctor モードは、スキャフォールドの作成後に実際の障害が発生した場合や、既存のセットアップに問題が疑われるリポジトリを対象とします。

python3 scripts/doctor.py --project /path/to/project --symptom "what failed" --json を実行し、検出結果をもとに次の対応を判断します。

• ローカルのワークフロー修正：copilot-setup-steps.yml を最小限修正します。再生成するのは、レビュー済みの置き換えを行う場合のみです。
• リポジトリ設定の修正：ファイアウォールまたはワークフロー承認の設定を更新します。
• 組織設定の修正：ランナーのデフォルト設定またはリポジトリのオーバーライドポリシーを変更します。
• セッションの調査：ファイルを変更する前に、現在のセッションログを確認します。

症状の対応表については references/doctor-mode.md を、わかりにくい落とし穴については references/gotchas.md を参照してください。

提案するソースの更新

古くなったガイダンスが証拠から判明した場合は、該当する記述、現在の公式ソースと適用されるバージョン／日付、変更案、回帰チェックを記録します。メンテナンスが作業範囲に含まれる場合に限り、正規のソースパッケージを編集します。それ以外の場合は、提案を報告し、インストール済みのコピーを黙って変更しないでください。承認された仕様変更については、ドキュメントとヘルパーの動作を併せて調整し、最小権限、シークレットの取り扱い、リポジトリの固定バージョンを維持します。生成結果を前提にする前に、ヘルパーの検証済みの制限を references/scaffold-layout.md で確認してください。

読み方ガイド

必要な情報	参照先
公式 URL と更新方針	references/live-docs.md
手順やランナーを選ぶ前に確認する内容	references/project-analysis.md
生成ファイルの構成とプラン JSON の形式	references/scaffold-layout.md
エコシステムのセットアップパターンと質問が必要な場合	references/patterns.md
セッションログを基にしたトラブルシューティング	references/doctor-mode.md
デフォルトブランチ、ファイアウォール、ワークフロー承認、ランナーの落とし穴	references/gotchas.md

運用スクリプト

• scripts/audit_project.sh は対象リポジトリを調査し、環境に関係する情報を JSON 形式で報告します。
• scripts/suggest_plan.py はリポジトリの情報から、前提、手動設定、質問を含むプランの草案を作成します。
• scripts/render_setup_workflow.py は明示的なプランから .github/workflows/copilot-setup-steps.yml を生成または更新します。
• scripts/doctor.py は既存のセットアップの問題を診断し、リポジトリの変更と GitHub 設定の変更を区別します。
• scripts/validate.py は構造、相互参照、必須のサポートファイルをチェックします。
• scripts/test_skill.py は一時リポジトリを使って、軽量な構文チェックと統合チェックを実行します。

注意点

1. ワークフローが有効になるのは、デフォルトブランチに存在する場合のみです。フィーチャーブランチに正しいファイルがあっても、実際の Copilot の実行では機能しません。
2. 現行のドキュメントによると、copilot-setup-steps ジョブで適用されるのは steps、permissions、runs-on、services、snapshot、timeout-minutes のみです。追加のジョブキーは有効に見えても無視される場合があります。
3. セットアップのステップがゼロ以外の終了コードで終了すると、Copilot は残りのセットアップステップをスキップし、そのまま続行します。
4. セルフホストランナーを使用するには、リポジトリ設定で統合ファイアウォールを無効にする必要があります。
5. Windows ランナーは統合ファイアウォールと互換性がありません。
6. 組織レベルのランナーポリシーによって、リポジトリで指定した runs-on が気付かないうちに上書きされることがあります。
7. Copilot がプッシュしても、GitHub Actions のワークフローは自動実行されません。実行には、人による承認か、自動実行を許可するリポジトリ設定が必要です。
8. actions/checkout の fetch-depth は Copilot のプラットフォームの動作によって上書きされるため、カスタムの浅いクローン深度に依存しないでください。
9. ファイアウォールが適用されるのは、Actions アプライアンス内でエージェントが起動したプロセスのみです。セットアップステップや MCP サーバーは保護されません。
10. リポジトリがプライベートレジストリや内部ホストに依存している場合、通常は YAML の編集だけではなく、copilot 環境シークレットまたは変数と、ファイアウォールまたはランナーの変更を組み合わせることが根本的な解決策です。