|
| 1 | +--- |
| 2 | +name: scaffold-github-cloud-agent-environment |
| 3 | +description: "Audit a real repository, verify the live GitHub Copilot cloud agent docs, and scaffold or repair `.github/workflows/copilot-setup-steps.yml` for GitHub Copilot cloud agent. Use when a project has no cloud agent environment yet, when an existing Copilot setup workflow needs enrichment or cleanup, or when agent runs fail because of runner, firewall, dependency, LFS, proxy, or workflow-shape issues. Trigger on: GitHub Copilot cloud agent environment, `copilot-setup-steps.yml`, customize agent environment, cloud agent runner, self-hosted runner, larger runner, Copilot setup doctor, fix Copilot agent environment. Do NOT use for generic GitHub Actions work unrelated to Copilot cloud agent, MCP-only setup, or non-GitHub agent platforms." |
| 4 | +compatibility: "Requires: bash, jq, git, rg, and python3. Some fixes live in GitHub repository or organization settings and cannot be applied from the repository alone." |
| 5 | +metadata: |
| 6 | + version: "1.0.0" |
| 7 | + short-description: "Project-aware GitHub Copilot cloud agent environment scaffolder and doctor" |
| 8 | + openclaw: |
| 9 | + category: "development" |
| 10 | + requires: |
| 11 | + bins: [bash, jq, git, rg, python3] |
| 12 | +references: |
| 13 | + - live-docs |
| 14 | + - project-analysis |
| 15 | + - scaffold-layout |
| 16 | + - patterns |
| 17 | + - doctor-mode |
| 18 | + - gotchas |
| 19 | +--- |
| 20 | + |
| 21 | +# scaffold-github-cloud-agent-environment |
| 22 | + |
| 23 | +Audit the target repository first, then scaffold or repair GitHub Copilot cloud agent's development environment around the current live GitHub Docs contract. |
| 24 | + |
| 25 | +## Decision Tree |
| 26 | + |
| 27 | +What is the user asking for? |
| 28 | + |
| 29 | +- No `.github/workflows/copilot-setup-steps.yml` exists yet: |
| 30 | + Verify the live docs, audit the repo, draft a plan, ask only the targeted questions that repo signals cannot answer, then scaffold the workflow. |
| 31 | +- A `copilot-setup-steps.yml` file already exists but looks thin, stale, or incorrect: |
| 32 | + Audit what is there, compare it to the live docs, choose `refresh` mode, and regenerate a deterministic workflow that preserves the documented contract. |
| 33 | +- Agent runs fail or behave strangely after scaffolding: |
| 34 | + Run doctor mode first, use session-log evidence and repo facts to identify whether the fix is in-repo or in GitHub settings, then patch only what the evidence supports. |
| 35 | +- The user only wants explanation or planning: |
| 36 | + Read `references/live-docs.md`, `references/project-analysis.md`, `references/patterns.md`, and `references/doctor-mode.md`, then answer without scaffolding. |
| 37 | + |
| 38 | +## Quick Reference |
| 39 | + |
| 40 | +| Task | Action | |
| 41 | +|------|--------| |
| 42 | +| Verify the live GitHub contract first | Read the URLs in `references/live-docs.md` | |
| 43 | +| Audit a target repository | Run `scripts/audit_project.sh /path/to/project` | |
| 44 | +| Draft a plan from repo facts | Run `python3 scripts/suggest_plan.py --project /path/to/project` | |
| 45 | +| Render or refresh the workflow | Run `python3 scripts/render_setup_workflow.py --project /path/to/project --plan /path/to/plan.json` | |
| 46 | +| Diagnose an existing setup | Run `python3 scripts/doctor.py --project /path/to/project --symptom "describe the failure" --json` | |
| 47 | +| Understand repo questions to ask before writing files | Read `references/project-analysis.md` | |
| 48 | +| Choose ecosystem-specific dependency steps | Read `references/patterns.md` | |
| 49 | +| Map symptoms to fixes | Read `references/doctor-mode.md` | |
| 50 | + |
| 51 | +## Non-Negotiable Workflow |
| 52 | + |
| 53 | +1. Re-check the live official GitHub docs before every real scaffold or repair. Do not trust a stale memory of the feature. |
| 54 | +2. Audit the repository before choosing steps, runners, or environment assumptions. |
| 55 | +3. Distinguish repo-local fixes from GitHub settings fixes: |
| 56 | + - repo-local: `.github/workflows/copilot-setup-steps.yml`, `.github/copilot-instructions.md`, package-manager setup, LFS checkout, service containers |
| 57 | + - settings-level: runner policy, firewall allowlist, workflow approval, `copilot` environment secrets or variables |
| 58 | +4. Keep project-specific judgment in the plan JSON, not buried inside the renderer. |
| 59 | +5. Ask targeted questions when ambiguity matters. Typical blockers are: |
| 60 | + - the repo signals Windows, but the requirement is not explicit |
| 61 | + - multiple package managers or multiple toolchains compete |
| 62 | + - private registries or internal hosts are present |
| 63 | + - self-hosted or larger runners may be required |
| 64 | + - tests depend on services that are not obviously expressible as GitHub Actions `services` |
| 65 | +6. Keep the workflow anchored to `.github/workflows/copilot-setup-steps.yml` with one job named `copilot-setup-steps`. |
| 66 | +7. Only rely on documented job keys for that job: `steps`, `permissions`, `runs-on`, `services`, `snapshot`, and `timeout-minutes`. |
| 67 | +8. Treat setup-step failures as degraded environments, not hard stops. The docs say Copilot skips the remaining setup steps and continues with whatever environment exists at that point. |
| 68 | +9. Default to deterministic dependency installation. Let Copilot discover build and validation commands through custom instructions and repo context, not trial-and-error dependency bootstrapping. |
| 69 | +10. In doctor mode, start with session logs and the observed symptom. Do not guess at fixes that the logs or repo facts do not support. |
| 70 | + |
| 71 | +## Live Docs First |
| 72 | + |
| 73 | +The official GitHub Docs pages below are the source of truth. Read them before real work: |
| 74 | + |
| 75 | +- `https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment` |
| 76 | +- `https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-firewall` |
| 77 | +- `https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-organization/configure-runner-for-coding-agent` |
| 78 | +- `https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/troubleshoot-cloud-agent` |
| 79 | +- `https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/track-copilot-sessions` |
| 80 | +- `https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/configuring-agent-settings` |
| 81 | +- `https://docs.github.com/en/copilot/tutorials/cloud-agent/get-the-best-results` |
| 82 | +- `https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions` |
| 83 | + |
| 84 | +Use `references/live-docs.md` for the purpose of each URL and the exact moments you must re-open it. |
| 85 | + |
| 86 | +## Project Analysis Rules |
| 87 | + |
| 88 | +Before you write or replace `copilot-setup-steps.yml`, inspect: |
| 89 | + |
| 90 | +- whether `.github/workflows/copilot-setup-steps.yml` already exists |
| 91 | +- package managers, lockfiles, and toolchain version files |
| 92 | +- CI workflows and any existing runner choices |
| 93 | +- `.github/copilot-instructions.md`, `.github/instructions/**/*.instructions.md`, `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` |
| 94 | +- `.gitattributes` for Git LFS usage |
| 95 | +- `.devcontainer/`, Dockerfiles, Compose files, and service requirements |
| 96 | +- private-registry config files such as `.npmrc`, `.yarnrc.yml`, `pip.conf`, `.pypirc`, `.cargo/config.toml`, `nuget.config`, or `settings.xml` |
| 97 | +- Windows-only or internal-network signals |
| 98 | + |
| 99 | +Run `scripts/audit_project.sh` first, then read `references/project-analysis.md` when you need the full checklist and the question set. |
| 100 | + |
| 101 | +## Deterministic Versus Heuristic Work |
| 102 | + |
| 103 | +Keep these parts deterministic: |
| 104 | + |
| 105 | +- the workflow path and job name |
| 106 | +- the documented job-key allowlist |
| 107 | +- `timeout-minutes` staying at or below `59` |
| 108 | +- validation triggers for easy manual and PR testing |
| 109 | +- low-privilege `permissions` |
| 110 | +- LFS enablement when the repo clearly uses Git LFS |
| 111 | +- the doctor checks for missing workflow, wrong job name, unsupported job keys, missing checkout, and settings-only failure modes |
| 112 | + |
| 113 | +Allow these parts to stay heuristic, but surface the assumptions: |
| 114 | + |
| 115 | +- which runner strategy fits the repo |
| 116 | +- whether the workflow should set up one toolchain or several |
| 117 | +- exact dependency install commands |
| 118 | +- whether service containers are safe to express in `services` |
| 119 | +- whether the repo needs repo-level or org-level firewall or runner changes |
| 120 | + |
| 121 | +If a heuristic choice can materially change correctness, add it to `questions` and ask the user instead of silently guessing. |
| 122 | + |
| 123 | +## Repeat-Run Rules |
| 124 | + |
| 125 | +When the skill is invoked again against a project: |
| 126 | + |
| 127 | +- Re-verify the live docs before assuming the contract is unchanged. |
| 128 | +- Re-audit the repo before assuming the existing plan still fits. |
| 129 | +- If the workflow already exists, default to `refresh` mode and back up the current file before replacement. |
| 130 | +- Preserve the required job name and path on every refresh. |
| 131 | +- Prefer improving a weak setup over adding second competing setup files. |
| 132 | +- Use doctor mode first when the user reports failures from a real agent run. |
| 133 | + |
| 134 | +## Scaffold Rules |
| 135 | + |
| 136 | +- Write `.github/workflows/copilot-setup-steps.yml`, not a generic setup workflow under another name. |
| 137 | +- Keep exactly one job named `copilot-setup-steps`. |
| 138 | +- Only use supported job keys in that job. |
| 139 | +- Keep `timeout-minutes` at `59` or lower. |
| 140 | +- Add `workflow_dispatch`, `push`, and `pull_request` triggers scoped to the workflow file unless the user explicitly wants a quieter validation pattern. |
| 141 | +- Add `contents: read` when the workflow checks out the repository. |
| 142 | +- If the repo uses Git LFS, use `actions/checkout@v5` with `lfs: true`. |
| 143 | +- Do not rely on a custom `fetch-depth` value. The live docs say Copilot overrides it. |
| 144 | +- For self-hosted runners, require the user to disable the integrated firewall and allow the documented GitHub and Copilot hosts. |
| 145 | +- For Windows runners, treat network controls as an explicit design decision because the integrated firewall is not compatible with Windows. |
| 146 | +- Put secrets and environment variables in the `copilot` environment, not inline in the workflow. |
| 147 | +- Treat `.github/copilot-instructions.md` as a companion file whenever Copilot needs clear build, test, or validation commands. |
| 148 | + |
| 149 | +## Doctor Mode |
| 150 | + |
| 151 | +Doctor mode is for real failures after a scaffold or for repos with questionable existing setups. |
| 152 | + |
| 153 | +Run `python3 scripts/doctor.py --project /path/to/project --symptom "what failed" --json`, then use the findings to decide the next action: |
| 154 | + |
| 155 | +- local workflow fix: regenerate or patch `copilot-setup-steps.yml` |
| 156 | +- repo settings fix: update firewall or workflow-approval settings |
| 157 | +- org settings fix: runner defaults or repository override policy |
| 158 | +- session investigation: inspect the live session logs before changing files |
| 159 | + |
| 160 | +Read `references/doctor-mode.md` for the symptom map and `references/gotchas.md` for the less obvious traps. |
| 161 | + |
| 162 | +## Reading Guide |
| 163 | + |
| 164 | +| Need | Read | |
| 165 | +|------|------| |
| 166 | +| Official URLs and refresh policy | `references/live-docs.md` | |
| 167 | +| What to inspect before choosing steps or runners | `references/project-analysis.md` | |
| 168 | +| Generated file layout and plan JSON shape | `references/scaffold-layout.md` | |
| 169 | +| Ecosystem setup patterns and when to ask questions | `references/patterns.md` | |
| 170 | +| Session-log-led troubleshooting | `references/doctor-mode.md` | |
| 171 | +| Default-branch, firewall, workflow-approval, and runner traps | `references/gotchas.md` | |
| 172 | + |
| 173 | +## Operational Scripts |
| 174 | + |
| 175 | +- `scripts/audit_project.sh` inspects a target repo and reports environment-relevant facts as JSON. |
| 176 | +- `scripts/suggest_plan.py` turns repo facts into a draft plan with assumptions, manual settings, and questions. |
| 177 | +- `scripts/render_setup_workflow.py` renders or refreshes `.github/workflows/copilot-setup-steps.yml` from an explicit plan. |
| 178 | +- `scripts/doctor.py` diagnoses existing setup issues and separates repo changes from GitHub settings changes. |
| 179 | +- `scripts/validate.py` checks structure, cross-references, and required support files. |
| 180 | +- `scripts/test_skill.py` runs lightweight syntax and integration checks against temp repositories. |
| 181 | + |
| 182 | +## Gotchas |
| 183 | + |
| 184 | +1. The workflow only matters once it exists on the default branch. A correct file on a feature branch is still inert for real Copilot runs. |
| 185 | +2. The live docs say only `steps`, `permissions`, `runs-on`, `services`, `snapshot`, and `timeout-minutes` are honored in the `copilot-setup-steps` job. Extra job keys may look valid but be ignored. |
| 186 | +3. If a setup step exits non-zero, Copilot skips the remaining setup steps and continues anyway. |
| 187 | +4. Self-hosted runners require the integrated firewall to be disabled in repository settings. |
| 188 | +5. Windows runners are not compatible with the integrated firewall. |
| 189 | +6. Organization-level runner policy can silently override a repository's preferred `runs-on`. |
| 190 | +7. GitHub Actions workflows do not run automatically when Copilot pushes unless a human approves them or repository settings allow automatic runs. |
| 191 | +8. `actions/checkout` `fetch-depth` is overridden by Copilot's platform behavior, so do not depend on a custom shallow-clone depth. |
| 192 | +9. The firewall only applies to processes started by the agent in the Actions appliance. It does not protect setup steps or MCP servers. |
| 193 | +10. If the repo depends on private registries or internal hosts, the real fix is usually a combination of `copilot` environment secrets or variables plus firewall or runner changes, not only a YAML edit. |
0 commit comments