skip to content

Copilot cloud agent keeps failing to install packages from your internal registry; how do copilot-setup-steps.yml and the agent firewall fix its environment?

level: seniorimportance: nice to knowfreq 5%

answer

  1. install before the agent starts
  2. one job with a fixed name
  3. must live on the default branch
  4. Agents secrets, not Actions secrets
  5. firewall covers the Bash tool only

basics

~10 s

A .github/workflows/copilot-setup-steps.yml with one copilot-setup-steps job installs dependencies before Copilot cloud agent starts, using an Agents secret for the token. Add the registry to the firewall's custom allowlist for installs the agent runs itself.

solid answer

~50 s

Copilot cloud agent otherwise discovers dependencies by trial and error, and private ones may be unreachable. Put a workflow at `.github/workflows/copilot-setup-steps.yml` with a single job named `copilot-setup-steps`; its `steps` run in GitHub Actions before Copilot starts, and only `steps`, `permissions`, `runs-on`, `services`, `snapshot` and `timeout-minutes` (at most 59) are honoured. The file must be on the default branch. Store the registry token as an **Agents** secret, because the agent does not receive Actions, Codespaces or Dependabot secrets; Agents secrets reach its environment as environment variables. The firewall limits internet access by default with a recommended allowlist; it applies to processes the agent starts through its Bash tool, not to setup steps or MCP server processes, so add the registry domain to the custom allowlist if Copilot must install packages itself. If a setup step fails, Copilot skips the rest and starts working anyway.

code

yaml · 23 lines
yaml
name: "Copilot Setup Steps"
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "20"
          cache: "npm"
      # The registry token is an Agents secret, exposed as an environment variable
      - name: Install dependencies
        run: npm ci

go deeper

for a junior

Recall that .github/workflows/copilot-setup-steps.yml prepares Copilot cloud agent's environment before it starts, in a job that must be called copilot-setup-steps.

for a middle

Explain the rules: default branch only, the few honoured job keys, timeout-minutes up to 59, a failed step skipping the rest, and Agents secrets as the only secrets the agent sees.

for a senior

Diagnose network failures by knowing the firewall covers only the agent's Bash-tool processes, use the custom allowlist narrowly, and plan your own controls when self-hosted runners require the firewall off.

for a principal

Decide at organization level which firewall settings to lock, whether repositories may add custom rules, and which secrets an agent should ever hold.

## The symptom and the cause **Copilot cloud agent** works in an ephemeral development environment **powered by GitHub Actions**. Out of the box it tries to work out your project's dependencies by **trial and error**, which the docs call slow and unreliable, and which can fail outright for **private** packages: the registry needs credentials the agent does not have, or its host is not on the firewall's allowlist. The result is a session that burns its time limit on failed installs and a pull request whose tests never ran. Two features fix this: a **setup-steps workflow** that prepares the environment deterministically, and the **firewall** settings that control what the agent may reach while it works. ## The setup-steps workflow The file lives at `.github/workflows/copilot-setup-steps.yml`. It looks like a normal workflow, with these rules: - It must contain a **single job named `copilot-setup-steps`**; any other name is not picked up. - Only these job settings are honoured: `steps`, `permissions`, `runs-on`, `services`, `snapshot` and `timeout-minutes` (maximum `59`). Anything else is ignored. - It **won't trigger unless it is on the default branch**, so a version on a feature branch does nothing for the agent. - If you do not check out the code, Copilot does it after your steps; any `fetch-depth` you set on `actions/checkout` is overridden. - If a step exits non-zero, Copilot **skips the remaining steps** and starts work with the environment as it is, so check the session log rather than assuming success. - Because it is a real workflow, it runs as a check when you change it, and you can run it from the **Actions** tab to test it. `runs-on` can also move the agent to larger runners or self-hosted runners; the agent supports only Ubuntu x64 and Windows 64-bit runners. ## Credentials: Agents secrets The cloud agent has its own **Agents** secrets and variables, set at repository or organization level under **Secrets and variables > Agents**. They are exposed as **environment variables** in the agent's environment, including to the setup steps, and their values are masked in session logs. Names prefixed `COPILOT_MCP_` go only to MCP servers. The agent does **not** receive Actions, Codespaces or Dependabot secrets, which is the usual reason a token "that CI uses fine" is missing. Secrets once kept in a `copilot` environment in Actions settings were migrated to the Agents type automatically. ## The firewall By default the agent's internet access is **limited by a firewall**. It always allows the hosts Copilot needs to talk to GitHub, and a **recommended allowlist** (operating-system and language package registries, container registries, certificate authorities) is enabled by default. A blocked request adds a warning to the pull request body or a comment, naming the address and the command. | Setting | Where | Notes | |---|---|---| | Enable firewall | Organization or repository **Internet access** tab | Organization can lock it; default "Let repositories decide" | | Recommended allowlist | Same tab | On by default | | Custom allowlist | Repository, if the organization allows repository custom rules | A domain also allows subdomains; a URL limits scheme, host and path | | Organization custom allowlist | Organization | Combined with repository rules; cannot be removed per repository | Its limits matter for this case. The firewall applies **only to processes the agent starts through its Bash tool**; it does not apply directly to MCP server processes or to processes in your setup steps, and it works only inside the GitHub Actions environment. Sophisticated attacks may bypass it, so it is not a complete security boundary. On **self-hosted runners** the integrated firewall is not compatible and must be disabled, and you provide network controls yourself. ## Putting it together 1. Store the registry token as an Agents secret. 2. Add `copilot-setup-steps.yml` with checkout, toolchain setup and the install command, and merge it to the default branch. 3. Run it from the Actions tab and confirm the install step passed. 4. If Copilot must reach the registry during its own work, for example to add a package, add the registry's domain to the repository custom allowlist.

  • The setup steps install packages fine, yet Copilot is blocked when it later runs an install itself. Why the difference?
    The firewall applies to processes the agent starts through its Bash tool, not to processes in configured setup steps. So the setup-step install succeeds while the agent's own install hits the firewall. Add the registry's domain (which also covers its subdomains) or a URL prefix to the repository custom allowlist, provided the organization allows repository custom rules.
  • What changes if you move Copilot cloud agent onto self-hosted runners?
    The integrated firewall is not compatible with self-hosted runners, so you must disable it in repository settings or the agent is blocked; your own network controls replace it. Set `runs-on` in the setup-steps job to the runner label, prefer ephemeral single-use runners, and use only Ubuntu x64 or Windows 64-bit runners.

  • Any job name works in copilot-setup-steps.yml as long as the file is named right.
  • A token stored as an Actions repository secret is available to the cloud agent.
  • If one setup step fails, the whole Copilot session is aborted.
  • The firewall filters every process on the runner, including setup steps and MCP servers.
  • A setup-steps file on a feature branch takes effect for the next session.