Clarify limitations of `copilot-setup-steps` concerning call of reusable workflows

[KubaZ]

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?

https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment

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 in copilot-setup-steps.
• Only inline steps are supported; shared setup logic must be inlined or extracted into a composite action (using uses inside a steps entry) 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

• Configure the development environment – GitHub Docs
• Reusing workflows – GitHub Docs
• Creating a composite action – GitHub Docs

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.