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 ciKeep 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: trueCopilot 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
- GitHub Copilot custom instructions
- Adding MCP servers to GitHub Copilot
- GitHub Copilot CLI permissions: --allow-tool, --deny-tool, --allow-all-tools and trusted directories
- GitHub Copilot custom agents: .github/agents/*.agent.md profiles, tools and frontmatter
- GitHub Copilot code review settings: automatic PR reviews, rulesets, effort level and approvals
- GitHub Copilot hooks: .github/hooks/*.json for Copilot CLI and the cloud agent
- Run GitHub Copilot CLI with copilot -p in scripts and CI (2026)
- GitHub Copilot prompt files in VS Code: .github/prompts/*.prompt.md slash commands
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 →