Skip to content
compiler.dev
Start free

What Is a Reusable Workflow in GitHub Actions?

Last updated

A reusable workflow is a GitHub Actions workflow file that other workflows can call as if it were a single job. It declares the workflow_call trigger, takes inputs and secrets, and can return outputs, so teams define a pipeline once and reuse it across repositories.

How it works

The called workflow lists on: workflow_call with optional inputs, secrets and outputs. The caller adds a job with uses: pointing at the file, either in the same repository (./.github/workflows/ci.yml) or another (org/repo/.github/workflows/ci.yml@ref), and passes values with with: and secrets:.

The called workflow runs its own jobs on its own runners. Its runs-on is set inside it, so to move a shared pipeline to faster machines you change one file, not every repository.

A reusable workflow is different from a composite action. A composite action bundles steps inside one job. A reusable workflow bundles whole jobs, with their own runners, matrices and services.

Example

Called workflow, .github/workflows/node-ci.yml in acme/shared:

on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: "22"
    secrets:
      NPM_TOKEN:
        required: false

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
      - run: npm ci && npm test

Caller:

jobs:
  ci:
    uses: acme/shared/.github/workflows/node-ci.yml@v1
    with:
      node-version: "20"
    secrets: inherit

Common mistakes

  • Unpinned references. @main means any push to the shared repo changes every caller. Pin a tag or SHA.
  • Nesting too deep. There is a limit on how many levels of reusable workflows can call each other.
  • Expecting env to pass through. Environment variables set in the caller are not visible in the called workflow. Pass inputs.
  • Secrets not reaching the callee. Pass them explicitly or use secrets: inherit where allowed.
  • Permissions surprises. The called workflow cannot gain more GITHUB_TOKEN permissions than the caller grants.
  • Hiding a matrix build inside it without exposing inputs, so callers cannot tune it.

Reusable workflows also help with consistent concurrency groups and security settings. See securing GitHub Actions for pinning advice.

Related terms

FAQ

Can a private repository share workflows?

Yes, if the repository's Actions access settings allow other repositories in the organization to use them.

How is it billed?

Jobs in the called workflow consume minutes like any other job. Calling adds no separate charge.

What is the difference from a template?

A template is copied. A reusable workflow is referenced, so updates reach callers according to the ref you pinned.

Related