Set up GitHub Copilot’s development environment before the cloud agent starts by adding a workflow file at .github/workflows/copilot-setup-steps.yml. According to GitHub’s documentation, the steps in its single copilot-setup-steps job run in GitHub Actions before Copilot starts working, so you can preinstall tools and dependencies.

Applies to: GitHub Docs, “Configure the development environment for agents on GitHub Actions”, as published on October 31, 2026. Last checked: October 31, 2026.

The setup steps file applies only when Copilot runs on GitHub Actions. GitHub says it doesn’t apply to sessions that run in a cloud sandbox (GitHub Docs).

On this page

Create the setup workflow

A copilot-setup-steps.yml file looks like a normal GitHub Actions workflow file, but must contain a single copilot-setup-steps job. This is GitHub’s example, copied from its documentation:

name: "Copilot Setup Steps"

# Automatically run the setup steps when they are changed to allow for easy validation, and
# allow manual testing through the repository's "Actions" tab
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
  copilot-setup-steps:
    runs-on: ubuntu-latest

    # Set the permissions to the lowest permissions possible needed for your steps.
    # Copilot will be given its own token for its operations.
    permissions:
      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission.
      # If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
      contents: read

    # You can define any steps you want, and they will run before the agent starts.
    # If you do not check out your code, Copilot will do this for you.
    steps:
      # ...

GitHub says to customize this to fit your own project, including its language(s), its dependencies and the workflow triggers you need; for example, you wouldn’t typically run on both push and pull_request.

Preinstall dependencies

To install tools or dependencies before Copilot starts work, add steps to the copilot-setup-steps job. GitHub’s example for a TypeScript project:

# ...

jobs:
  copilot-setup-steps:
    # ...

    # You can define any steps you want, and they will run before the agent starts.
    # If you do not check out your code, Copilot will do this for you.
    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

Any value set for the fetch-depth option of actions/checkout is overridden, which GitHub says allows the agent to roll back commits on request while mitigating security risks.

Put it on the default branch

GitHub says the copilot-setup-steps.yml workflow won’t trigger unless it’s present on your default branch. The file runs as a normal GitHub Actions workflow when it changes, and the result shows alongside other checks in the pull request that creates or modifies it. Once it is merged into the default branch, you can run the workflow manually from the repository’s Actions tab to check that it works (GitHub Docs).

What you can configure

In this file you can only customize these settings of the copilot-setup-steps job; GitHub says changes to other settings are ignored:

  • steps
  • permissions
  • runs-on
  • services
  • snapshot
  • timeout-minutes (maximum value: 59)

To use larger GitHub-hosted runners, set runs-on to the label and/or group for those runners. For self-hosted runners, GitHub recommends ephemeral, single-use runners, requires network controls and specific allowed hosts, and says Copilot cloud agent’s integrated firewall must be disabled because it is not compatible with self-hosted runners. Copilot cloud agent is only compatible with Ubuntu x64 and Windows 64-bit runners. Read the larger runners and self-hosted runners sections before changing a runner or firewall setting.

Check failures in the session log

When Copilot starts work, your setup steps run and updates show in the session logs. If any setup step fails by returning a non-zero exit code, GitHub says Copilot skips the remaining setup steps and begins working with the current state of its development environment (GitHub Docs).

If setup does not appear to run, compare your repository with the requirements above: the file path, the single copilot-setup-steps job, the file on the default branch, and a session that runs on GitHub Actions rather than in a cloud sandbox.

For how the cloud agent works from issues to pull requests, see GitHub Copilot cloud agent; for review, see GitHub Copilot code review.