Clarify limitations of `copilot-setup-steps` concerning call of reusable workflows
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 74/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Quiet
- Tech stack
- github-actions
- Domain
- documentation
Research direction
Start with the linked customize-the-agent-environment article and review its copilot-setup-steps job-property documentation, then compare the reusable-workflow and composite-action references. Document that jobs..uses is unsupported, clarify that inline steps are supported, and include the composite-action workaround; verify the article renders correctly and links remain valid.
Written by the indexing model from the issue text.
Description
Code of Conduct
- I have read and agree to the GitHub Docs project's Code of Conduct
What article on docs.github.com is affected?
What part(s) of the article would you like to see updated?
The documentation for copilot-setup-steps does not explicitly state that calling reusable workflows via jobs.<job-id>.uses is not supported. This causes confusion for users who try to extract shared setup logic into a reusable workflow and reference it from the copilot-setup-steps job.
Current behavior
The copilot-setup-steps.yml documentation lists the job-level properties that can be customized (steps, permissions, runs-on, services, snapshot, timeout-minutes). However, it does not explicitly call out that uses at the job level — which is how GitHub Actions reusable workflows are invoked — is not among the supported properties and will be silently ignored or will cause unexpected behavior.
A user might reasonably author:
jobs:
copilot-setup-steps:
uses: ./.github/workflows/shared-setup.yml
...expecting the reusable workflow to run as part of Copilot's environment setup, only to find it does not work as intended.
Expected behavior
The documentation should explicitly state that:
jobs.<job-id>.uses(reusable workflow calls) is not supported incopilot-setup-steps.- Only inline
stepsare supported; shared setup logic must be inlined or extracted into a composite action (usingusesinside astepsentry) rather than a reusable workflow.
Suggested workaround (to be documented)
Instead of a reusable workflow, users can extract shared setup steps into a composite action and reference it within a step:
jobs:
copilot-setup-steps:
runs-on: ubuntu-latest
steps:
- uses: ./.github/actions/shared-setup # composite action — supported
References
- Dominant language
- TypeScript
- Stars
- 20.9k
- Forks
- 68.8k
- Avg merge
- 15h 4m
- Merged PRs (30d)
- 103
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from github/docs
-
builder persona content
Difficulty 1/5 Under an hour Newbie friendliness 90/100
-
localization
Difficulty 2/5 1-2 days Newbie friendliness 72/100
-
builder persona
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
content localization
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
content localization
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Similar issues
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 91/100
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Automattic/studio#4908 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100