Clarify limitations of `copilot-setup-steps` concerning call of reusable workflows
- Linguagem predominante
- TypeScript
- Estrelas
- 20.8k
- Forks
- 68.8k
- Merge médio
- 13h 10min
- PRs com merge (30d)
- 111
Descrição
### Code of Conduct
- [x] I have read and agree to the GitHub Docs project's [Code of Conduct](https://github.com/github/docs/blob/main/.github/CODE_OF_CONDUCT.md)
### 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](https://docs.github.com/en/actions/sharing-automations/reusing-workflows) via `jobs..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:
```yaml
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..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](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action) and reference it within a step:
```yaml
jobs:
copilot-setup-steps:
runs-on: ubuntu-latest
steps:
- uses: ./.github/actions/shared-setup # composite action — supported
```
### References
- [Configure the development environment – GitHub Docs](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)
- [Reusing workflows – GitHub Docs](https://docs.github.com/en/actions/sharing-automations/reusing-workflows)
- [Creating a composite action – GitHub Docs](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action)
Guia de contribuição
Direção de pesquisa
Comece pelo artigo vinculado customize-the-agent-environment e revise a documentação da propriedade de job copilot-setup-steps; depois, compare as referências de reusable-workflow e composite-action. Documente que jobs..uses não é compatível, esclareça que inline steps são compatíveis e inclua a solução alternativa com composite-action; verifique se o artigo é renderizado corretamente e se os links continuam válidos.
Escrita pelo modelo de indexação a partir do texto da issue.
Avaliação
- Stack de tecnologia
- github-actions
- Domínio
- documentation
- Tipo de issue
- Documentação
- Dificuldade
- 2/5
- Tempo estimado
- 1-3 horas
- Status de atividade
- Pouca atividade
- Clareza
- Claramente especificada
- Facilidade para iniciantes
- 74/100