Reusable Workflows and Composite Actions
As a GitHub organization's number of repositories grows, the same handful of pipeline patterns — build, test, lint, publish, scan — tend to get copy-pasted into dozens of workflow files with tiny variations. GitHub Actions provides two complementary mechanisms to eliminate that duplication: reusable workflows and composite actions. They solve the same underlying problem, DRY (don't repeat yourself) pipelines, but they operate at different levels of granularity and are invoked differently, and choosing the right one for a given case is a genuine design decision, not a matter of taste.
Cricket analogy: As a cricket academy opens more regional centers, the same handful of drills — throwdowns, fielding circuits, fitness tests — get re-taught slightly differently at each center; the national academy solves this with both a standardized drill card any coach can slot into their own session (like a composite action) and a complete standardized trial-day program other academies can adopt wholesale (like a reusable workflow), and picking which to standardize is a real coaching decision.
Composite actions: reusing a sequence of steps
A composite action packages a sequence of run and uses steps into a single callable action, defined in its own action.yml with runs.using: composite. It is invoked with a single uses: step inside an existing job, exactly like any third-party action from the Marketplace. Composite actions are the right tool when you want to reuse a chunk of steps — say, 'set up Node, restore the cache, install dependencies' — inside jobs that otherwise differ, because the calling job still defines its own runs-on, its own other steps, and its own job-level settings; the composite action only replaces a slice of the step list.
Cricket analogy: A fielding coach packages a specific three-drill warm-up sequence into one callable session module that any team's head coach can insert as a single item into their own practice plan — the head coach still decides the ground, the rest of the day's drills, and the overall schedule, only that one warm-up slice gets swapped in.
Reusable workflows: reusing an entire job graph
A reusable workflow is a complete workflow file that declares on: workflow_call and can define one or more jobs, each potentially running on different runners with different needs relationships between them. It is invoked with a uses: key at the job level in a calling workflow (jobs.<id>.uses: org/repo/.github/workflows/build.yml@main), and the calling job can pass typed inputs and secrets into it and read back its outputs. Reusable workflows are the right tool when the thing you want to share is not just a few steps but an entire multi-job pipeline shape — for example a standard 'build, then test in parallel across three OSes, then publish' pipeline that many repositories should follow identically.
Cricket analogy: A cricket board's complete international tour protocol — arrival quarantine, acclimatization nets, warm-up match, then the Test series itself, each phase potentially at a different venue — is a whole standardized program other touring boards can invoke wholesale, passing in typed specifics like the destination country and player roster, and reading back the tour's final fitness report.
# .github/workflows/reusable-build.yml
on:
workflow_call:
inputs:
node-version:
type: string
default: '20'
secrets:
NPM_TOKEN:
required: true
outputs:
artifact-name:
value: ${{ jobs.build.outputs.artifact-name }}
jobs:
build:
runs-on: ubuntu-latest
outputs:
artifact-name: ${{ steps.pack.outputs.name }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
- run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- id: pack
run: echo "name=dist-${{ github.sha }}" >> "$GITHUB_OUTPUT"
# .github/workflows/ci.yml (caller)
jobs:
build:
uses: my-org/shared-workflows/.github/workflows/reusable-build.yml@v1
with:
node-version: '18'
secrets:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}A useful mental model: a composite action is like an extracted function you call inside a larger method, while a reusable workflow is like calling an entirely separate program and getting its exit status and outputs back. Composite actions nest inside a job's steps: list; reusable workflows replace an entire job's steps: list with a single uses: pointing at another workflow file.
Both mechanisms support versioning by referencing a tag, branch, or commit SHA after the @, and pinning to a full commit SHA is the strongest supply-chain-security practice since tags and branches can be moved. Reusable workflows can call other reusable workflows, but GitHub caps the nesting depth (four levels as of recent platform limits) and the total number of reusable workflows referenced transitively in a single run, so extremely deep chains of indirection should be avoided in favor of flatter, more explicit composition.
Cricket analogy: You can reference a coach's training method by their general reputation ('current national coach,' which can change) or by pinning to the exact named individual who ran a specific 2019 camp — pinning the exact name is safer since 'current coach' can be reassigned; and while one specialist can bring in another specialist who brings in another, boards typically cap that chain at a few referral layers to avoid an untraceable mess of sub-consultants.
Composite actions do not have their own secrets: inheritance mechanism — every secret a composite action needs must be passed explicitly as a string input from the calling job. Forgetting this and referencing secrets.SOME_TOKEN directly inside a composite action's steps will silently resolve to an empty string rather than erroring, which can cause confusing authentication failures downstream. As a practical rule of thumb: deduplicate a handful of steps embedded inside otherwise-different jobs with a composite action, and deduplicate an entire pipeline shape — multiple jobs, needs: relationships, matrix strategies — across many repositories with a reusable workflow. Many mature organizations use both together.
- Composite actions bundle multiple steps into one callable
uses:step inside an existing job. - Reusable workflows (
on: workflow_call) bundle one or more entire jobs, invoked with a job-leveluses:in the caller. - Reusable workflows pass typed
inputs,secrets, and can returnoutputs; composite actions only takeinputsand cannot usesecretscontext directly. - Pin both by commit SHA rather than a mutable tag/branch for supply-chain security.
- Reusable workflow nesting depth and count are capped by GitHub, encouraging flatter composition.
- Composite actions suit step-level reuse inside varied jobs; reusable workflows suit whole-pipeline reuse across repos.
Practice what you learned
1. What top-level trigger must a reusable workflow declare to be callable from another workflow?
2. How does a composite action receive a secret it needs, such as an API token?
3. At what level in a calling workflow is a reusable workflow invoked?
4. Why is pinning a `uses:` reference to a full commit SHA considered more secure than pinning to a tag?
5. Which scenario is best suited to a composite action rather than a reusable workflow?
Was this page helpful?
You May Also Like
GitHub Actions Workflow Basics
GitHub Actions workflows are YAML files in .github/workflows that define when a pipeline runs, what jobs it contains, and what steps each job executes.
Jobs, Steps, and Runners
Jobs are independent units of work that run on isolated runners, steps are the ordered commands within a job, and runners are the actual machines that execute them.
GitHub Actions Triggers and Events
Learn how GitHub Actions workflows start: the `on:` key, common webhook events, scheduled runs, manual dispatch, and how to filter events by branch, path, or type.
Designing Multi-Stage Pipelines
Learn how to structure a CI/CD pipeline into logical stages — build, test, package, deploy — so failures surface early and each stage has a clear contract with the next.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics