v1.0.0 to v1.0.0
25 added, 21 removed. Audit A to A.
---
name: scaffold-github-cloud-agent-environment
description: "Audit and scaffold `.github/workflows/copilot-setup-steps.yml` for GitHub Copilot cloud agent environments. Use for missing or broken setup workflows, runner/firewall/dependency/LFS/proxy issues, or Copilot setup repair. Do NOT use for generic GitHub Actions."
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."
metadata:
version: "1.0.0"
short-description: "Project-aware GitHub Copilot cloud agent environment scaffolder and doctor"
openclaw:
category: "development"
requires:
bins: [bash, jq, git, rg, python3]
references:
- live-docs
- project-analysis
- scaffold-layout
- patterns
- doctor-mode
- gotchas
---
# scaffold-github-cloud-agent-environment
- Audit the target repository first, then scaffold or repair GitHub Copilot cloud agent's development environment around the current live GitHub Docs contract.
+ Make the target repository ready for Copilot cloud agent to build and validate changes. Start with repository and session evidence; consult relevant official GitHub documentation when a platform contract is uncertain, stale, or changing.
## Decision Tree
What is the user asking for?
- No `.github/workflows/copilot-setup-steps.yml` exists yet:
- Verify the live docs, audit the repo, draft a plan, ask only the targeted questions that repo signals cannot answer, then scaffold the workflow.
+ Audit the repo, verify unresolved platform assumptions, draft a plan, resolve material blockers, then preview and scaffold the workflow.
- A `copilot-setup-steps.yml` file already exists but looks thin, stale, or incorrect:
- Audit what is there, compare it to the live docs, choose `refresh` mode, and regenerate a deterministic workflow that preserves the documented contract.
+ Inspect the workflow and failure evidence, then make the smallest justified repair while preserving custom steps. Use regeneration only for a deliberate replacement after previewing the diff and ensuring a recoverable backup.
- Agent runs fail or behave strangely after scaffolding:
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.
- The user only wants explanation or planning:
- Read `references/live-docs.md`, `references/project-analysis.md`, `references/patterns.md`, and `references/doctor-mode.md`, then answer without scaffolding.
+ Read only the references needed for the open question, then answer without scaffolding.
## Quick Reference
| Task | Action |
|------|--------|
- | Verify the live GitHub contract first | Read the URLs in `references/live-docs.md` |
+ | Resolve an uncertain platform contract | Select the relevant official URL from `references/live-docs.md` |
| Audit a target repository | Run `scripts/audit_project.sh /path/to/project` |
| Draft a plan from repo facts | Run `python3 scripts/suggest_plan.py --project /path/to/project` |
- | Render or refresh the workflow | Run `python3 scripts/render_setup_workflow.py --project /path/to/project --plan /path/to/plan.json` |
+ | Preview a generated workflow | Run `python3 scripts/render_setup_workflow.py --project /path/to/project --plan /path/to/plan.json --stdout` before a deliberate write |
| Diagnose an existing setup | Run `python3 scripts/doctor.py --project /path/to/project --symptom "describe the failure" --json` |
| Understand repo questions to ask before writing files | Read `references/project-analysis.md` |
| Choose ecosystem-specific dependency steps | Read `references/patterns.md` |
| Map symptoms to fixes | Read `references/doctor-mode.md` |
## Non-Negotiable Workflow
- 1. Re-check the live official GitHub docs before every real scaffold or repair. Do not trust a stale memory of the feature.
+ 1. Use repository files, installed tool help/version evidence, and session logs for stable known repairs. Consult relevant live official docs when that evidence is insufficient, appears stale, or the platform contract will change; do not fetch every page for every repair.
2. Audit the repository before choosing steps, runners, or environment assumptions.
3. Distinguish repo-local fixes from GitHub settings fixes:
- repo-local: `.github/workflows/copilot-setup-steps.yml`, `.github/copilot-instructions.md`, package-manager setup, LFS checkout, service containers
- settings-level: runner policy, firewall allowlist, workflow approval, `copilot` environment secrets or variables
4. Keep project-specific judgment in the plan JSON, not buried inside the renderer.
- 5. Ask targeted questions when ambiguity matters. Typical blockers are:
+ 5. Resolve material ambiguity from repository evidence first, then ask targeted questions for blockers. Record advisory choices as assumptions rather than blocking safe work. Potential blockers include:
- the repo signals Windows, but the requirement is not explicit
- multiple package managers or multiple toolchains compete
- private registries or internal hosts are present
- self-hosted or larger runners may be required
- tests depend on services that are not obviously expressible as GitHub Actions `services`
6. Keep the workflow anchored to `.github/workflows/copilot-setup-steps.yml` with one job named `copilot-setup-steps`.
- 7. Only rely on documented job keys for that job: `steps`, `permissions`, `runs-on`, `services`, `snapshot`, and `timeout-minutes`.
+ 7. Only rely on documented job keys for that job. The bundled allowlist is `steps`, `permissions`, `runs-on`, `services`, `snapshot`, and `timeout-minutes`; verify relevant contract changes before extending it. The renderer does not implement every platform-supported key.
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.
- 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.
+ 9. Default to deterministic dependency installation plus bounded code generation or preparation needed for a usable environment. Do not duplicate the full CI lifecycle by default. Expose build and validation commands through repo instructions.
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.
- ## Live Docs First
+ ## Contract Evidence
- The official GitHub Docs pages below are the source of truth. Read them before real work:
+ Use the relevant official GitHub Docs page to resolve an open platform question; this is a source directory, not a mandatory reading list:
- `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`
- Use `references/live-docs.md` for the purpose of each URL and the exact moments you must re-open it.
+ Use `references/live-docs.md` for targeted refresh guidance and the proposed-update route. Versions, runner labels, key allowlists, and limits in bundled examples are snapshots, not perpetual upgrade requirements.
## Project Analysis Rules
Before you write or replace `copilot-setup-steps.yml`, inspect:
- whether `.github/workflows/copilot-setup-steps.yml` already exists
- package managers, lockfiles, and toolchain version files
- CI workflows and any existing runner choices
- `.github/copilot-instructions.md`, `.github/instructions/**/*.instructions.md`, `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`
- `.gitattributes` for Git LFS usage
- `.devcontainer/`, Dockerfiles, Compose files, and service requirements
- private-registry config files such as `.npmrc`, `.yarnrc.yml`, `pip.conf`, `.pypirc`, `.cargo/config.toml`, `nuget.config`, or `settings.xml`
- Windows-only or internal-network signals
Run `scripts/audit_project.sh` first, then read `references/project-analysis.md` when you need the full checklist and the question set.
## Deterministic Versus Heuristic Work
Keep these parts deterministic:
- the workflow path and job name
- - the documented job-key allowlist
- - `timeout-minutes` staying at or below `59`
+ - explicit supported job keys for the verified platform contract
+ - a bounded timeout (`59` is the documented maximum in the bundled baseline; the renderer does not enforce it)
- validation triggers for easy manual and PR testing
- low-privilege `permissions`
- LFS enablement when the repo clearly uses Git LFS
- the doctor checks for missing workflow, wrong job name, unsupported job keys, missing checkout, and settings-only failure modes
Allow these parts to stay heuristic, but surface the assumptions:
- which runner strategy fits the repo
- whether the workflow should set up one toolchain or several
- exact dependency install commands
- whether service containers are safe to express in `services`
- whether the repo needs repo-level or org-level firewall or runner changes
- If a heuristic choice can materially change correctness, add it to `questions` and ask the user instead of silently guessing.
+ If a heuristic choice can materially change correctness or safety, add it to `questions` and resolve it before applying the affected change. A labelled preview may retain unresolved blockers; it is not a deployable recommendation. Put non-blocking assumptions in `assumptions` or `notes`.
## Repeat-Run Rules
When the skill is invoked again against a project:
- - Re-verify the live docs before assuming the contract is unchanged.
+ - Re-open relevant official docs when evidence is insufficient or stale, or a platform-sensitive contract will change.
- Re-audit the repo before assuming the existing plan still fits.
- - If the workflow already exists, default to `refresh` mode and back up the current file before replacement.
+ - Prefer a minimal patch that preserves custom steps, comments, and repository pins. The renderer replaces the whole workflow rather than merging it; use `--stdout` to review its output first and keep a recoverable backup before deliberate replacement. A plan's `mode` is not a no-clobber guard.
- Preserve the required job name and path on every refresh.
- Prefer improving a weak setup over adding second competing setup files.
- Use doctor mode first when the user reports failures from a real agent run.
## Scaffold Rules
- Write `.github/workflows/copilot-setup-steps.yml`, not a generic setup workflow under another name.
- Keep exactly one job named `copilot-setup-steps`.
- Only use supported job keys in that job.
- Keep `timeout-minutes` at `59` or lower.
- Add `workflow_dispatch`, `push`, and `pull_request` triggers scoped to the workflow file unless the user explicitly wants a quieter validation pattern.
- Add `contents: read` when the workflow checks out the repository.
- - If the repo uses Git LFS, use `actions/checkout@v5` with `lfs: true`.
+ - If the repo uses Git LFS, enable `lfs: true` on a compatible `actions/checkout` version consistent with repository pins. The bundled `@v5` example is a historical default, not a permanent platform requirement or an instruction to upgrade.
- Do not rely on a custom `fetch-depth` value. The live docs say Copilot overrides it.
- For self-hosted runners, require the user to disable the integrated firewall and allow the documented GitHub and Copilot hosts.
- For Windows runners, treat network controls as an explicit design decision because the integrated firewall is not compatible with Windows.
- - Put secrets and environment variables in the `copilot` environment, not inline in the workflow.
+ - Never inline credentials or secret values. Configure secrets and agent-wide variables through GitHub's documented environment/settings mechanism. Non-secret setup constants may use documented workflow `env` locations (the helper supports step-level `env`); the restricted setup-job allowlist does not imply job-level `env` support.
- Treat `.github/copilot-instructions.md` as a companion file whenever Copilot needs clear build, test, or validation commands.
## Doctor Mode
Doctor mode is for real failures after a scaffold or for repos with questionable existing setups.
Run `python3 scripts/doctor.py --project /path/to/project --symptom "what failed" --json`, then use the findings to decide the next action:
- - local workflow fix: regenerate or patch `copilot-setup-steps.yml`
+ - local workflow fix: minimally patch `copilot-setup-steps.yml`; regenerate only for a reviewed replacement
- repo settings fix: update firewall or workflow-approval settings
- org settings fix: runner defaults or repository override policy
- session investigation: inspect the live session logs before changing files
Read `references/doctor-mode.md` for the symptom map and `references/gotchas.md` for the less obvious traps.
+
+ ## Proposed Source Updates
+
+ When evidence exposes stale guidance, record the affected passage, current official source and applicable version/date, proposed change, and regression check. Edit the canonical source package only when maintenance is in scope; otherwise report the proposal, never silently mutate an installed copy. Reconcile documentation and helper behavior together for an authorized contract change, preserving least privileges, secret handling, and repository pins. See `references/scaffold-layout.md` for verified helper limits before relying on generated output.
## Reading Guide
| Need | Read |
|------|------|
| Official URLs and refresh policy | `references/live-docs.md` |
| What to inspect before choosing steps or runners | `references/project-analysis.md` |
| Generated file layout and plan JSON shape | `references/scaffold-layout.md` |
| Ecosystem setup patterns and when to ask questions | `references/patterns.md` |
| Session-log-led troubleshooting | `references/doctor-mode.md` |
| Default-branch, firewall, workflow-approval, and runner traps | `references/gotchas.md` |
## Operational Scripts
- `scripts/audit_project.sh` inspects a target repo and reports environment-relevant facts as JSON.
- `scripts/suggest_plan.py` turns repo facts into a draft plan with assumptions, manual settings, and questions.
- `scripts/render_setup_workflow.py` renders or refreshes `.github/workflows/copilot-setup-steps.yml` from an explicit plan.
- `scripts/doctor.py` diagnoses existing setup issues and separates repo changes from GitHub settings changes.
- `scripts/validate.py` checks structure, cross-references, and required support files.
- `scripts/test_skill.py` runs lightweight syntax and integration checks against temp repositories.
## Gotchas
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.
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.
3. If a setup step exits non-zero, Copilot skips the remaining setup steps and continues anyway.
4. Self-hosted runners require the integrated firewall to be disabled in repository settings.
5. Windows runners are not compatible with the integrated firewall.
6. Organization-level runner policy can silently override a repository's preferred `runs-on`.
7. GitHub Actions workflows do not run automatically when Copilot pushes unless a human approves them or repository settings allow automatic runs.
8. `actions/checkout` `fetch-depth` is overridden by Copilot's platform behavior, so do not depend on a custom shallow-clone depth.
9. The firewall only applies to processes started by the agent in the Actions appliance. It does not protect setup steps or MCP servers.
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.