Reusable Workflows vs Composite Actions in GitHub Actions
Choose between a reusable workflow and a composite action in GitHub Actions: call level, jobs, runners, logging, secrets, limits, and working examples of each.
At a glance
- Last reviewed
- Versions referenced
actions/checkout@v7actions/setup-node@v7org/repo/.github/workflows/lint-test.yml@v1- Reading time
- 4 min read
Code samples are not run in a live repository. See our editorial standards.
On this page
Use a reusable workflow when you need to share whole jobs, including their runners. Use a composite action when you need to share a sequence of steps that run inside a job you already control. A reusable workflow is called at the job level (jobs.<job_id>.uses); a composite action is called as a step (steps[*].uses).
Comparison
| Feature | Reusable workflow | Composite action |
|---|---|---|
| Definition | A single YAML file in .github/workflows/ of a repository |
A repository or directory containing an action.yml file and, optionally, other files |
| Called by | Referencing a specific YAML file | Referencing a repository or directory |
| Call level | Directly in a job (jobs.<job_id>.uses), not from a step |
As a step within a job |
| Jobs | Can contain multiple jobs | Cannot contain jobs |
| Runners | Each job sets its own runs-on |
Runs on the caller job’s runner |
| Logging | Every job and step is logged separately, in real time | Logged as one step in the caller, even if it contains many steps |
| Secrets | Can use secrets | Cannot use secrets directly; pass values as inputs |
| Nesting | Up to ten levels of workflows | Up to 10 composite actions nested in one workflow |
| Marketplace | Cannot be published | Can be published |
Choose by what you need to share
Pick a reusable workflow in these cases:
- The shared logic needs more than one job, or a different machine type than the caller job.
- You want each job and step logged separately.
- The work needs secrets, passed with
secrets:orsecrets: inherit.
Pick a composite action in these cases:
- You want to bundle steps and run them in the middle of an existing job, with other steps before and after.
- You want to publish the action to the Marketplace.
Output handling differs too. You can’t add steps to a job after calling a reusable workflow. Its outputs are available to later jobs through needs. A composite action is a step, so later steps in the same job can use its outputs directly. For a related walkthrough, see Pass Outputs Between GitHub Actions Jobs.
Same lint-and-test logic, both ways
Reusable workflow
The reusable workflow is triggered by workflow_call and brings its own runs-on. Create .github/workflows/lint-test-reusable.yml:
name: Reusable Lint and Test
on:
workflow_call:
inputs:
node-version:
required: true
type: string
jobs:
lint-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: ${{ inputs.node-version }}
- name: Install dependencies
run: npm ci
- name: Run linter
run: npm run lint
- name: Run test suite
run: npm test
Call it from .github/workflows/ci.yml. The uses key sits on the job, and the caller job has no runs-on or steps:
name: CI
on:
push:
branches: [main]
jobs:
call-lint-and-test:
uses: ./.github/workflows/lint-test-reusable.yml
with:
node-version: '20'
For a workflow in another repository, use owner/repo/.github/workflows/lint-test-reusable.yml@v1, where the ref after @ is a tag, branch or commit SHA.
Composite action
A composite action has no runner and no jobs. Every run step needs an explicit shell. Create .github/actions/lint-test/action.yml:
name: Composite Lint and Test
description: Installs dependencies, lints, and runs tests
inputs:
node-version:
description: Node.js version to set up
required: true
runs:
using: composite
steps:
- uses: actions/setup-node@v7
with:
node-version: ${{ inputs.node-version }}
- name: Install dependencies
shell: bash
run: npm ci
- name: Run linter
shell: bash
run: npm run lint
- name: Run test suite
shell: bash
run: npm test
Call it as a step in a job you define:
name: CI
on:
push:
branches: [main]
jobs:
lint-and-test-job:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Run lint and test action
uses: ./.github/actions/lint-test
with:
node-version: '20'
The caller must run actions/checkout first. A local path like ./.github/actions/lint-test is resolved from the checked-out workspace, so without checkout the runner can’t find action.yml.
Common pitfalls
Calling a reusable workflow from a step
A reusable workflow can’t be referenced under steps. Workflow validation rejects it, and the step-level uses is reserved for actions. Move the uses to the job:
# Wrong: a reusable workflow referenced from a step
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: org/repo/.github/workflows/lint-test.yml@v1
# Right: the reusable workflow is the job
jobs:
test:
uses: org/repo/.github/workflows/lint-test.yml@v1
with:
node-version: '20'
If you need the shared logic to run as a step, convert it to a composite action.
Missing shell in a composite action
Each run step in a composite action must declare shell. Omitting it makes the action metadata invalid, so add shell: bash (or another shell) to every run step.
Checkout in a reusable workflow checks out the caller
When a reusable workflow from another repository uses actions/checkout, it checks out the repository that hosts the caller workflow, not the repository that hosts the reusable workflow. Check out the called repository explicitly if you need its files.
Private and internal repositories
For internal or private repositories, the Access policy on the Actions settings page of the called workflow’s repository must allow access from the repositories that contain the callers. Without that, the call fails.
Renamed repositories
GitHub Actions doesn’t follow redirects for actions or reusable workflows. If the owner or repository name changes, workflows that use the old name fail until you update the reference. For a related walkthrough, see Run GitHub Actions Jobs Only When Specific Files Change.
Passing secrets to a composite action
A composite action has no secrets key. Declare an input and pass the secret from the caller:
- uses: ./.github/actions/lint-test
with:
node-version: '20'
registry-token: ${{ secrets.REGISTRY_TOKEN }}
Add registry-token to the action’s inputs as well.
Verify the setup
- Push the caller workflow and open the run in the Actions tab.
- For a reusable workflow, confirm the run graph shows the caller job (
call-lint-and-test) with the called job nested under it, and that each step is listed separately. - For a composite action, confirm the caller job shows one step,
Run lint and test action, and expand it to see the inner steps’ output in that single log. - If a reusable workflow defines outputs under
on.workflow_call.outputs, read them in a later job with${{ needs.<job_id>.outputs.<output_name> }}and print them withechoto confirm the values. - If the workflow doesn’t start at all, check the Actions tab for a validation error on the workflow file. The usual causes are
usesunderstepsfor a reusable workflow or a missingshellin a composite action.
Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.