Home / Blog / Workflows and migration
How do I share workflow logic: reusable workflows or composite actions?
Reusable workflows share a whole pipeline; composite actions share a bundle of steps. GitHub's comparison in one table, the limits, working YAML for each, and how to require one.
Use a reusable workflow to share a whole pipeline: it can hold several jobs and its jobs choose their own machine type. Use a composite action to share a bundle of steps that run inside the caller’s job and appear in its log as one step. A workflow template is a starting place that does some or all of the work of writing a workflow, not a shared workflow. A chain of reusable workflows can be ten levels deep, and one workflow file can call 50 unique ones.
- A reusable workflow shares a pipeline of one or more jobs; a composite action shares steps that run inside the caller's job.
- A chain of reusable workflows can be ten levels deep, and one file can call 50 unique ones.
- Secrets pass only to the directly called workflow, and a composite action cannot use secrets itself.
- Pin the caller to a commit SHA so every repository runs the same YAML.
- An organisation ruleset can require a workflow; it ignores paths and branch filters on the events it supports.
GitHub documents all three, across several pages and none that decides between them. This post puts the comparison in one table, the limits in another, and a working caller and callee for each of the two you will use most. The GitHub statements are from its pages, read on the date this post was last checked; the actionlint results are ours.
How do reusable workflows and composite actions differ?
| Reusable workflow | Composite action | |
|---|---|---|
| What it is | A YAML file, very similar to any standard workflow file | An action containing a bundle of workflow steps |
| Where it lives | A single file in .github/workflows of a repository | A repository or a directory with an action.yml |
| How it is called | By its file, with uses: at the job level, not from a step | By its repository or directory, as a step |
| Jobs | Can contain multiple jobs | Does not contain jobs |
| In the log | Each step is logged in real time | Logged as one step, even if it contains several |
| Secrets | Can use secrets | Cannot use secrets |
| Nesting | A maximum of ten levels of workflows | Up to 10 composite actions in one workflow |
| Marketplace | Cannot be published | Can be published |
The table is adapted from GitHub’s page, with rows merged and cells shortened: Reusing workflow configurations. Two sentences on that page decide most cases. If the steps need a different machine type from the caller’s job, use a reusable workflow. And since a composite action cannot contain jobs, a pipeline with two jobs is a reusable workflow by definition.
Which should I use?
| You need | Use |
|---|---|
| The whole pipeline is the same in many repositories | A reusable workflow |
| Several jobs, or a different machine type from the caller's | A reusable workflow |
| A few steps that always go together, such as set up and cache | A composite action |
| You want to publish it to the Marketplace | A composite action |
| You want people to start a new workflow from a template | A workflow template |
| You must make every repository run it | A reusable workflow, required by an organisation ruleset |
How do I write and call a reusable workflow?
The file goes in .github/workflows of the repository, directly: subdirectories of that folder are not supported. It must list workflow_call under on. Inputs and secrets are declared there, and an output is declared on the workflow and set from a job’s output.
name: Node CI
on:
workflow_call:
inputs:
node-version:
required: false
type: string
default: "22"
secrets:
npm-token:
required: false
outputs:
tested-sha:
description: The commit that was tested
value: ${{ jobs.test.outputs.sha }}
jobs:
test:
runs-on: ubuntu-24.04
timeout-minutes: 15
outputs:
sha: ${{ steps.sha.outputs.sha }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: ${{ inputs.node-version }}
cache: npm
- run: npm ci
env:
NPM_TOKEN: ${{ secrets.npm-token }}
- run: npm test
- id: sha
run: echo "sha=$GITHUB_SHA" >> "$GITHUB_OUTPUT"
The caller uses it at the job level, not in a step. Pin the reference to a SHA: GitHub says that way everyone who reuses the workflow always runs the same YAML, and that for a tag or branch you must be sure you can trust that version of the workflow. The SHA below is a placeholder.
name: CI
on:
pull_request:
permissions:
contents: read
jobs:
node:
uses: example-org/ci-workflows/.github/workflows/node-ci.yml@0123456789abcdef0123456789abcdef01234567 # v1.2.0
with:
node-version: "24"
secrets:
npm-token: ${{ secrets.NPM_TOKEN }}
report:
needs: node
runs-on: ubuntu-24.04
steps:
- run: echo "tested ${{ needs.node.outputs.tested-sha }}"
Both files pass actionlint 1.7.12, which checks each as a workflow and does not fetch the repository named in uses; we have not run them on GitHub. In the same organisation or enterprise, secrets: inherit passes every secret to the directly called workflow instead of naming them. If the reference is not a SHA and you re-run the whole workflow, it uses the workflow from that reference again, while re-running failed jobs uses the commit from the first attempt.
How do I write and call a composite action?
A composite action is an action.yml in the root of a repository or in a directory. Each run step needs a shell, which a workflow step does not, and the action reads its inputs from the inputs context. As the table says it cannot use secrets itself, so the caller passes any value it needs in as an input.
name: Set up Node with a cache
description: Install Node and restore the package cache
inputs:
node-version:
description: Node version
required: false
default: "22"
runs:
using: composite
steps:
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: ${{ inputs.node-version }}
cache: npm
- run: npm ci
shell: bash
name: CI
on:
pull_request:
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: example-org/ci-actions/setup-node-cached@0123456789abcdef0123456789abcdef01234567 # v1.0.0
with:
node-version: "22"
- run: npm test
The caller is a workflow and passes actionlint 1.7.12; the action.yml parses as YAML and follows GitHub’s metadata reference, and we have not run either on GitHub. The action sits in the directory setup-node-cached of a repository, so the caller names that path. The whole bundle, set up, cache and install, is one step in the caller’s log.
Can another repository use a private repository’s workflow?
Yes, once its repository allows it. A private caller can use private and public reusable workflows; a public caller can use only public ones. For an organisation’s private repository, open Settings, then Actions, then General, and under Access choose “Accessible from repositories in the ‘ORGANIZATION-NAME’ organization”. GitHub warns that outside collaborators on the other repositories can then indirectly reach the private one and can read the logs of runs that use it. Nested workflows must all be reachable by the first caller, or the run fails.
How do I make every repository run a shared workflow?
Offering is not enforcing. A workflow template only puts a copy in a repository when someone creates a workflow, and a reusable workflow runs only when something calls it. To require one, use an organisation ruleset with the rule “Require workflows to pass before merging”. Three details from GitHub’s page matter. The workflow must trigger on pull_request, pull_request_target or merge_group, and any filters on those events, such as paths and branches, are ignored. The rule blocks direct pushes, so it belongs only on branches that change through pull requests. And “Evaluate” mode reports results before you enforce.
Sources differ on who can use the rule. GitHub’s 2023 announcement said GitHub Enterprise Cloud customers; its current pages say the rule is set at the organisation or enterprise level, and that organisation rulesets are for customers on GitHub Team or GitHub Enterprise. Open your organisation’s ruleset settings to see whether the rule is offered to you.
What are the limits of reusable workflows?
| Limit | In GitHub's words, shortened |
|---|---|
| Nesting | Up to ten levels: the top-level caller and up to nine levels of reusable workflows. No loops. |
| Unique reusable workflows | At most 50 from one workflow file, counting nested ones. |
| Keywords on the calling job | Only name, uses, with, secrets, strategy, needs, if, concurrency, permissions and cache-mode. |
| env | A workflow-level env in the caller is not passed to the called workflow, and the called workflow's env is not visible to the caller: use outputs. |
| Secrets | Passed only to the workflow called directly: in a chain A, B, C, C gets what B passes it. |
| Permissions | The GITHUB_TOKEN permissions can be kept or reduced down the chain, never raised. |
| Runners | GitHub-hosted runners are assigned by the caller's context and billed to the caller. |
| Workflow file size | A workflow file over 500 KB does not start runs. |
Two traps are worth a line each. If a workflow reused from a different repository uses actions/checkout, GitHub says it checks out the repository that hosts the caller workflow, not the one that holds the called workflow. And a called workflow reads the caller’s name from github.workflow, so a concurrency group built from it and shared by caller and callee, with cancel-in-progress: true, makes the callee cancel the caller. Give the two groups different values. The limits post has the other quotas, and the security hardening post says why to pin to a SHA. To check a workflow you have written, the free workflow checker reads it in your browser. If the shared jobs are to run on a different runner, change the one runs-on line in the reusable workflow and follow the switching checklist; for a first workflow to share, the small-team setup is a starting point. Build times measured on GitHub’s runner and on ours are on our faster GitHub Actions runners, measured page.
Sources
- Reusing workflow configurations (concepts) (docs.github.com)
- Reusing workflow configurations (reference) (docs.github.com)
- Reuse workflows (docs.github.com)
- Metadata syntax reference (docs.github.com)
- Creating a composite action (docs.github.com)
- Sharing actions and workflows with your organization (docs.github.com)
- Available rules for rulesets (Enterprise Cloud view) (docs.github.com)
- Creating rulesets for repositories in your organization (docs.github.com)
- Enforcing code reliability by requiring workflows with GitHub repository rules (GitHub blog, 11 October 2023) (github.blog)
- Actions limits (docs.github.com)
Frequently asked questions
What is the difference between a reusable workflow and a composite action?
A reusable workflow is a workflow file with its own jobs, called at the job level. A composite action is an action.yml of steps, run as one step inside the caller's job. Only a reusable workflow can contain jobs or choose a different machine type.
How many levels can reusable workflows be nested?
Up to ten: the top-level caller and up to nine levels of reusable workflows, with no loops. One workflow file can call at most 50 unique reusable workflows, nested ones included. Composite actions can nest up to 10 in one workflow.
Can a composite action use secrets?
GitHub's comparison says it cannot use secrets itself, so the calling workflow passes any value the action needs as an input. A reusable workflow can use secrets, passed by name or with secrets: inherit within an organisation.
How do I require every repository to run a shared workflow?
Use an organisation ruleset with the rule Require workflows to pass before merging. The workflow must trigger on pull_request, pull_request_target or merge_group, and GitHub ignores any filters on those events. Check that your plan offers the rule.