GitHub Copilot cloud agent can use self-hosted GitHub Actions runners for a project’s build and test environment. This does not host Copilot’s language model on your machine or create a model-fine-tuning service. It gives the agent a place to run development tools, which can also expose your network and credentials if configured carelessly.
Start with a restricted test repository. GitHub recommends standard hosted runners or ephemeral, single-use self-hosted runners, not a long-lived machine shared with sensitive production work.
Check the Cloud Agent’s Requirements, Not Just Actions Compatibility
Copilot cloud agent currently supports Ubuntu x64 and Windows 64-bit runners. The broader list of operating systems supported by GitHub Actions does not mean macOS or every Linux distribution is supported for the agent. Use the current agent environment guide.
Check paid Copilot access, repository eligibility, Actions access and organization policy. A GitHub Enterprise Server installation alone does not establish access to this GitHub.com cloud-agent workflow. Size CPU, memory and disk for your actual build; there is no universal “Copilot requires 8 GB RAM” rule.
Plan separate costs for your infrastructure, maintenance and applicable Copilot usage. “Self-hosted” is not equivalent to free AI usage or unlimited job time.
Register an Isolated Runner and Limit Its Reach
- Ask the responsible administrator to choose repository, organization or enterprise scope. Create a restricted runner group for the intended repositories rather than assuming a default group is safe.
- For organization registration, open Settings → Actions → Runners → New runner → New self-hosted runner. Select the supported operating system and architecture.
- Use the download and registration commands shown by GitHub at that time. Do not reuse an old tutorial’s binary version or example token. The generated registration token is short-lived and must be kept private.
- For production, implement single-use provisioning with Actions Runner Controller or an appropriate runner scale-set solution. Preserve diagnostic logs securely and rebuild the environment after each job.
Follow the registration guide and runner reference. Fork-triggered code can compromise persistent self-hosted machines; do not expose one broadly to untrusted public pull requests.
Before using it with Copilot, implement your own outbound network restrictions. The agent’s built-in firewall is not compatible with self-hosted runners. Only after equivalent approved controls are in place should an administrator disable that incompatible firewall setting. The environment guide lists the required Actions and Copilot hosts; allowing only api.github.com is insufficient.
Select the Runner for Copilot Cloud Agent
- As an organization owner, open the organization’s Settings → Copilot → Cloud agent.
- Edit Runner type, choose Labeled runner, and enter the approved group and/or label.
- Save the runner selection. Decide whether repositories may override it; disable overrides if centralized routing is required.
Where repository customization is permitted, the relevant job is copilot-setup-steps in .github/workflows/copilot-setup-steps.yml. Its runs-on must target the actual approved label or scale-set name. Merely adding a copilot-runner label to a machine does not route the agent there.
Use GitHub’s runner-policy procedure and the environment guide together. Ordinary CI workflow configuration and cloud-agent setup are related but not interchangeable.
Supply only the secrets the agent needs through the documented Agents secrets/variables mechanism. Do not give a runner broad production credentials just to make setup easier. Preserve human approval for workflows from agent-created pull requests. See cloud-agent guardrails.
Run a Small Verification Job and Diagnose Failures Safely
Use a harmless test task that builds or tests the sample repository. Verify the selected runner, setup output, network access and resulting changes. Confirm that the environment is discarded after use and that logs reach the approved storage destination.
- Queued: check online/idle capacity, exact labels, runner-group access and organization overrides.
- Offline: inspect runner-service and connectivity logs before changing configuration.
- Setup fails: inspect the specific dependency or network error. Check approved host rules and certificate/proxy configuration; do not disable TLS verification.
- Long jobs fail: inspect Actions limits and the workflow’s own timeout. Self-hosted jobs are not unlimited.
Do not delete the runner’s work directory as a generic repair. Preserve evidence, stop affected jobs safely and rebuild an ephemeral runner from the approved image when appropriate.
Official documentation checked: October 14, 2026.