github / github/docs

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

Open
#44,493 3 comments 2 reactions 0 assignees View on GitHub
content copilot never-stale
Dominant language
TypeScript
Stars
20.8k
Forks
68.7k
Avg merge
12h 24m
Merged PRs (30d)
105

Description

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.