Copilot cloud agent environment

The goal is a repository where Copilot cloud agent can install dependencies and build. Start from repository evidence and, for failures, the session logs. The facts below were checked against GitHub's docs on 2026-11-10; open the relevant page before relying on any of them for a change that depends on it, and report any mismatch instead of silently updating this skill. Pages (all under https://docs.github.com/en/copilot/how-tos/): use-copilot-agents/cloud-agent/customize-the-agent-environment, .../customize-the-agent-firewall, .../troubleshoot-cloud-agent, .../track-copilot-sessions, .../configuring-agent-settings, and administer-copilot/manage-for-organization/configure-runner-for-coding-agent. Job syntax: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions.

Platform contract

• As of 2026-11-10 GitHub's docs say sessions can run in a cloud sandbox, on GitHub Actions, or in a custom environment, and that the setup-steps file, runner and Windows options apply only to sessions on GitHub Actions. Confirm which kind the user's sessions use before editing the file.
• The file is .github/workflows/copilot-setup-steps.yml with exactly one job named copilot-setup-steps. It has no effect for real runs until it is on the default branch.
• Only steps, permissions, runs-on, services, snapshot and timeout-minutes are honoured in that job; other keys look valid and are ignored. timeout-minutes is capped at 59.
• A setup step that exits non-zero does not stop the run: Copilot skips the remaining setup steps and starts work in whatever environment exists.
• Copilot checks the code out itself only after setup finishes, so install steps that read the repo need their own actions/checkout. It overrides fetch-depth, so never depend on a depth. Use lfs: true on checkout when .gitattributes has filter=lfs.
• The integrated firewall is incompatible with self-hosted and Windows runners (the user must disable it and allowlist GitHub and Copilot hosts for self-hosted). It covers only processes the agent starts, not setup steps or MCP servers.
• Organisation owners can force a runner type, silently overriding the repo's runs-on.
• Workflows do not run automatically on Copilot's pushes until a human approves or settings allow it. A "CI did not run" report is usually this, not a broken environment.
• Never inline secrets. Registry auth and proxies go in copilot environment secrets or variables, and the host itself needs a firewall allowlist entry or runner access, so a private registry failure is rarely just a YAML edit.

Choices