Skip to content

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.

In short
  • 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 workflowComposite action
What it isA YAML file, very similar to any standard workflow fileAn action containing a bundle of workflow steps
Where it livesA single file in .github/workflows of a repositoryA repository or a directory with an action.yml
How it is calledBy its file, with uses: at the job level, not from a stepBy its repository or directory, as a step
JobsCan contain multiple jobsDoes not contain jobs
In the logEach step is logged in real timeLogged as one step, even if it contains several
SecretsCan use secretsCannot use secrets
NestingA maximum of ten levels of workflowsUp to 10 composite actions in one workflow
MarketplaceCannot be publishedCan 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 needUse
The whole pipeline is the same in many repositoriesA reusable workflow
Several jobs, or a different machine type from the caller'sA reusable workflow
A few steps that always go together, such as set up and cacheA composite action
You want to publish it to the MarketplaceA composite action
You want people to start a new workflow from a templateA workflow template
You must make every repository run itA 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.

Check your plan

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?

LimitIn GitHub's words, shortened
NestingUp to ten levels: the top-level caller and up to nine levels of reusable workflows. No loops.
Unique reusable workflowsAt most 50 from one workflow file, counting nested ones.
Keywords on the calling jobOnly name, uses, with, secrets, strategy, needs, if, concurrency, permissions and cache-mode.
envA 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.
SecretsPassed only to the workflow called directly: in a chain A, B, C, C gets what B passes it.
PermissionsThe GITHUB_TOKEN permissions can be kept or reduced down the chain, never raised.
RunnersGitHub-hosted runners are assigned by the caller's context and billed to the caller.
Workflow file sizeA 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

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.

Move your CI onto our runners with one line

Change one line, watch your own build, then decide.

Connect GitHub

Card required. You pay only for the minutes your jobs run.

.github/workflows/ci.yml
jobs: test:removed: runs-on: ubuntu-latestadded: runs-on: runnersio-4vcpu-ubuntu-2604 steps: - uses: actions/checkout@v4 - run: make testadded: build:added: runs-on: runnersio-32vcpu-ubuntu-2604