#43246·docs

Add a note for copilot-setup-steps.yml and using with a merge queue

Author: jonstacksCreated Mar 6, 2026Updated Sep 10, 2026
Labelscontentnever-stalegithub_actionsWaiting on contributor

Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment#customizing-copilots-development-environment-with-copilot-setup-steps

What part(s) of the article would you like to see updated?

Somewhat related to #42379

In the github docs, it says that you can add the following to you copilot-setup-steps.yml file:

yaml
name: "Copilot Setup Steps"

## Background
# 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

While this works, I've found that if you use a merge queue then using the above configuration results in your workflow running every time a PR is added to the merge queue. We are use the larger, custom image GitHub hosted runners and this results in unnecessary runs & costs.

github/copilot-sdk was the first public GitHub repo I found that had the same issue(although this one is just using default ubuntu-latest runners). It helped me figure out that behavior wasn't unique to our setup

Proposed Content Update

I'd like to update the docs to either add an inline comment with commented out code or add a little inline note about if using a merge queue. This is what ended up working for us:

yaml
name: "Copilot Setup Steps"

# Automatically run when changed so setup issues surface immediately.
# Also allows manual testing via the "Actions" tab.
on:
  workflow_dispatch:
  push:
    branches-ignore:
      - 'gh-readonly-queue/**'
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    branches:
      - main
    paths:
      - .github/workflows/copilot-setup-steps.yml

Additional information

No response