Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 44 ยท GitHub Actions in Practice

Reusable Workflows and Composite Actions

Stop copying YAML between repositories: write reusable workflows with workflow_call and composite actions, pass inputs, secrets and outputs, and version them safely.

The first time you write a good CI workflow, you copy it into the next repository. The third time, you have three slightly different copies, and a fix in one never reaches the others. Copy-paste is the standard way pipelines rot. GitHub Actions gives you two ways to share logic instead: reusable workflows, which share whole jobs, and composite actions, which share a sequence of steps. A third option, JavaScript and Docker actions, is for logic that needs real code.

In this lesson you will learn what each mechanism is for, how inputs, secrets and outputs flow through them, how to version what you share, and how an organization can offer starter templates. The YAML is read-only because it needs GitHub to run. The runnable stand-in implements the part that is easy to get wrong: how a caller's with: values are checked against the inputs a called workflow declares, and how defaults fill the gaps.

Two kinds of reuse

The difference is about the level at which you reuse:

Reusable workflow Composite action
Reuses one or more complete jobs a list of steps
Called with jobs.<id>.uses: a step's uses:
Runs on its own runner(s), chosen by the called workflow the runner of the calling job
Appears in the log as separate job(s) steps inside the caller's job
Can use secrets context yes, when passed in no, pass secrets as inputs
Defined in .github/workflows/name.yml action.yml in any folder
flowchart TD
    subgraph Caller["caller workflow"]
        J1["job: ci<br/>uses: reusable workflow"]
        J2["job: deploy<br/>steps: ... uses: composite action ..."]
    end
    J1 --> RW["called workflow<br/>own jobs, own runners"]
    J2 --> CA["composite action<br/>steps run in this job"]

A reusable workflow replaces an entire job; a composite action is expanded into the steps of the job that calls it.

A useful rule: if you share "a whole pipeline stage" (build, test, publish), use a reusable workflow. If you share "a setup routine that happens inside a job" (install tools, configure credentials), use a composite action.

Reusable workflows

A workflow becomes callable when its on: block includes workflow_call. You declare the contract: which inputs it accepts, which secrets it needs and which outputs it returns.

YAML
# .github/workflows/node-ci.yml  (in the repository acme/shared-workflows)
name: Node CI (reusable)

on:
  workflow_call:
    inputs:
      node-version:
        description: Node.js version to test with
        type: string
        required: false
        default: "22"
      run-lint:
        type: boolean
        default: true
      working-directory:
        type: string
        default: "."
    secrets:
      NPM_TOKEN:
        required: false
    outputs:
      coverage:
        description: Coverage percentage
        value: ${{ jobs.test.outputs.coverage }}

jobs:
  test:
    runs-on: ubuntu-latest
    outputs:
      coverage: ${{ steps.cov.outputs.percent }}
    defaults:
      run:
        working-directory: ${{ inputs.working-directory }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
          cache-dependency-path: ${{ inputs.working-directory }}/package-lock.json
      - run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - if: ${{ inputs.run-lint }}
        run: npm run lint
      - id: cov
        run: |
          npm test -- --coverage
          echo "percent=87" >> "$GITHUB_OUTPUT"

The contract has four pieces:

  • inputs have a type (string, number or boolean), an optional default and a required flag. They are read through the inputs context, as in ${{ inputs.node-version }}.
  • secrets are declared separately. A called workflow can only read secrets that the caller passes in, either one by one or all at once with secrets: inherit.
  • outputs are mapped from job outputs so the caller can use them. Notice the two-step mapping: a step writes to GITHUB_OUTPUT, the job exposes it under outputs, and the workflow exposes the job output under on.workflow_call.outputs.
  • A reusable workflow is an ordinary workflow otherwise: jobs, needs, matrices and permissions all work.

The caller then uses the whole workflow as if it were one job:

YAML
# .github/workflows/ci.yml  (in any repository)
name: CI

on:
  pull_request:

jobs:
  node:
    uses: acme/shared-workflows/.github/workflows/node-ci.yml@v2
    with:
      node-version: "24"
      run-lint: false
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  report:
    needs: node
    runs-on: ubuntu-latest
    steps:
      - run: echo "Coverage was ${{ needs.node.outputs.coverage }}%"

Note what is missing from the job node: there is no runs-on and no steps. A job that calls a reusable workflow can only use a small set of keys, such as uses, with, secrets, needs, if, permissions, strategy and concurrency. The runner is decided inside the called workflow. For a workflow in the same repository, use a relative path such as ./.github/workflows/node-ci.yml (no @ref; it runs at the same commit as the caller).

Reusable workflows can call other reusable workflows, but GitHub limits how deep the nesting may go, so keep the chain short and flat. Check the current limit in the documentation if you design something layered.

Permissions only ever shrink down the chain. A called workflow can use at most the GITHUB_TOKEN permissions that the caller grants. If the called workflow needs packages: write, the calling job (or workflow) must grant it.

Stand-in: resolving inputs for a called workflow

When a caller supplies with: values, GitHub checks them against the declared inputs: unknown inputs are an error, required ones must be present, types must match, and anything missing falls back to its default. This stand-in reproduces those rules on the node-ci.yml contract above, extended with one extra required input, deploy-target, so that the "missing required" rule can be shown. The result is exactly what ${{ inputs.* }} would contain inside the called workflow. (The real service has more rules, for example around expression evaluation in with:; this stand-in covers the core ideas.)

Node.js Validate and resolve workflow_call inputs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The run exits with code 1 because the last scenarios fail validation, just as a called workflow with bad inputs fails before any job starts. Seeing the errors listed together is a good habit to copy when you write your own shared workflows: fail early, say which input is wrong.

Composite actions

A composite action packages steps. It lives in a folder with an action.yml file. It can sit in the same repository (for example .github/actions/setup-app/action.yml) or in its own repository.

YAML
# .github/actions/setup-app/action.yml
name: Set up the app
description: Install Node, restore the cache and install dependencies

inputs:
  node-version:
    description: Node.js version
    required: false
    default: "22"
outputs:
  cache-hit:
    description: Whether the npm cache was restored
    value: ${{ steps.node.outputs.cache-hit }}

runs:
  using: composite
  steps:
    - id: node
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: npm
    - run: npm ci
      shell: bash
    - run: echo "Using Node $(node --version)"
      shell: bash

Differences from a workflow worth remembering:

  • Every run step must declare a shell. Workflows default to bash on Linux, but composite actions require it explicitly.
  • Inputs are read from inputs, but the secrets context is not available. If the action needs a token, make it an input and let the caller pass ${{ secrets.TOKEN }}.
  • A same-repository composite action needs the repository checked out first, because uses: ./.github/actions/setup-app is a path on disk. Put actions/checkout before it.
  • Steps from a composite action are shown as one collapsed step in the log, which keeps the caller's log short but hides detail until you expand it.

Calling it:

YAML
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-app
        with:
          node-version: "24"
      - run: npm test

JavaScript and Docker actions

When shell snippets stop being enough, you can write an action in code. A JavaScript action runs directly on the runner with Node (declared with runs.using: node20 or a newer value, check the docs for the current supported versions), starts fast and works on all runner operating systems. It is built with the @actions/core and @actions/github toolkit packages and committed with its dependencies bundled. A Docker container action packages any language and tooling into an image, at the cost of slower startup and Linux-only runners. Both are defined by an action.yml with inputs and outputs, so callers use them exactly like any other action. Most teams never need to write one: a composite action or reusable workflow covers the common cases.

Versioning what you share

Whatever you publish becomes a dependency of other repositories, so treat it like a library:

  • Tags and major version tags. Publish v2.3.1 and move a v2 tag to point at the newest v2.x.y. Callers who write @v2 get fixes automatically but not breaking changes.
  • Full SHAs. @4f2b1c0... (a full 40-character commit SHA) cannot be moved by anyone, which protects you if the shared repository is compromised. Dependabot can keep SHA pins up to date. This is the recommended style for third-party actions and is covered in Securing Your Pipeline.
  • Branches such as @main change under you without warning. They are convenient inside a single team and risky anywhere else.
  • Access. A private repository that holds reusable workflows or actions must be configured in its settings to allow access from other repositories in the organization.

An organization can also publish workflow templates: files in a special .github repository (under workflow-templates/, with a matching properties file) that appear as starter suggestions when someone clicks "New workflow" in any of the organization's repositories. Templates are copied, not linked, so use them for a good starting point and let the template call a reusable workflow so that the real logic stays in one place.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which sharing mechanism runs on its own runner and appears as separate jobs in the run?

    A job with uses: pointing at a reusable workflow runs the called workflow's own jobs on the runners chosen there. A composite action only adds steps to the calling job.
  2. 2. Why does every run step in a composite action need a shell key?

    Workflows have a default shell per platform, but composite action steps must declare one explicitly.
  3. 3. A composite action needs an API token. How should it receive it?

    The secrets context is not available in composite actions. The caller passes the secret as an input, and GitHub still masks it in logs.
  4. 4. Which reference gives callers the strongest guarantee that the code they run cannot change?

    Branches and tags can be moved by anyone with write access. A full commit SHA identifies one immutable snapshot.
  5. 5. A caller job has uses: ./.github/workflows/deploy.yml and also tries runs-on: ubuntu-latest. What is wrong?

    Jobs that call reusable workflows only support a limited set of keys. The runner is chosen by the jobs inside the called workflow.

Summary

  • Share whole jobs with reusable workflows (on: workflow_call) and sequences of steps with composite actions (runs.using: composite).
  • A reusable workflow declares a contract of typed inputs, secrets and outputs; the caller supplies them with with: and secrets: (or secrets: inherit).
  • A calling job has no runs-on or steps; the called workflow runs on its own runners.
  • Composite actions run inside the calling job, need an explicit shell for every run step and cannot read secrets directly.
  • Version shared code with tags (and a moving major tag), or pin to a full SHA when security matters most.
  • Organization workflow templates give new repositories a starting point; have them call a reusable workflow to avoid copies.

Next, you will control who and what may deploy: Environments, Approvals and Deployments.