Skip to content
AgentAtlas

copilot-setup-steps.yml: set up the GitHub Copilot cloud (coding) agent environment

How do I preinstall dependencies for the GitHub Copilot coding agent with copilot-setup-steps.yml?

Add .github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps and merge it to your default branch. Its steps run in GitHub Actions before Copilot starts work. GitHub's docs now call this agent Copilot cloud agent.

Rules for the file

  • Path: .github/workflows/copilot-setup-steps.yml
  • It must contain one job named copilot-setup-steps, or Copilot ignores it.
  • It only triggers once it is on your default branch.
  • Only these job keys are honored: steps, permissions, runs-on, services, snapshot, timeout-minutes.
  • timeout-minutes max is 59.
  • If a step exits non-zero, Copilot skips the remaining steps and starts work anyway.

Example for a Node.js project

.github/workflows/copilot-setup-steps.yml

name: "Copilot Setup Steps"

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    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"

      - name: Install JavaScript dependencies
        run: npm ci

Keep permissions minimal. Copilot gets its own token. If you skip checkout, Copilot clones the repo after your steps. Any fetch-depth you set on actions/checkout is overridden.

Test the workflow

The file runs as a normal Actions workflow when it changes, so it shows as a check on the pull request. After merging, run it manually from the repository Actions tab.

Larger or self-hosted runners

Larger runner

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-4-core
  • Only Ubuntu x64 and Windows 64-bit runners are supported. macOS is not.
  • For self-hosted runners, GitHub recommends ephemeral single-use runners (for example ARC), and you must disable the Copilot integrated firewall in repository settings.
  • For Windows, use self-hosted or larger runners with Azure private networking, since the integrated firewall does not support Windows.

Git LFS

Enable LFS

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v6
        with:
          lfs: true

Copilot code review reuses this file by default. You can create copilot-code-review.yml to configure the review environment separately.

Sources

More GitHub Copilot guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →