What are GitHub Actions reusable workflows, and how do they differ from composite actions?
A reusable workflow is a complete workflow file that declares on: workflow_call. A caller invokes it as an entire job with jobs.<id>.uses, pointing at a file path and a git ref. It can define several jobs, each with its own runs-on, service containers and dependencies. A composite action is an action.yml with runs.using: composite that bundles steps. You invoke it with steps[].uses inside a job you already own, and it runs on that job's runner.
Choose by where the shared logic lives. If you want to standardize jobs and runners (which machine runs the build, how test and lint jobs fan out, what permissions they get), use a reusable workflow. If you want to standardize a sequence of steps that teams drop into their own jobs, such as setting up a toolchain with caching, use a composite action. Many platforms use both: reusable workflows that call composite actions.
| Aspect | Reusable workflow | Composite action |
|---|---|---|
| Invoked at | Job level: jobs.<id>.uses |
Step level: steps[].uses |
| Runner control | Callee sets runs-on per job |
Inherits the caller's runner |
| Secrets | Passed explicitly or with secrets: inherit |
No secrets context; pass values as inputs |
| Context | Gets inputs; github context reflects the caller |
Shares the caller job's workspace and environment |
| Logs | Each called job appears separately | Appears as one step in the caller's log |
| Can contain | Multiple jobs, matrices, services | Steps only |
Copying YAML between repositories and using starter workflow templates are simpler alternatives. Both copy the file once, so later fixes never reach existing repos and the copies drift apart.
Why and when should you use shared CI pipelines, and who benefits?
Copied YAML drifts. One repo pins an old runtime, another skips the cache step, a third still runs a lint job everyone else dropped. Each copy started identical, but every local edit makes it a little more unique, until nobody can say what "our CI" actually does.
A workflow_call workflow fixes this by moving the pipeline into one place with a defined interface: typed inputs, declared secrets, and outputs. Treat it as a versioned internal API. Callers pin a tag or commit, maintainers publish changes deliberately, and breaking changes get a new major version instead of a silent edit.
Platform teams benefit most, along with any organization running many similar backend services: same language, same container build, same deploy target. The pattern pays off once you have more repos than you can comfortably patch by hand, and once their pipelines are similar enough to share without piles of conditional inputs.
The time savings come from two places. A fix, such as a security-hardened checkout step or a corrected cache key, lands once and reaches every caller on its next version bump. A new service gets working CI from a short caller file instead of a copied pipeline someone has to understand first.
Illustrative estimate: assume 40 repos and 30 minutes per repo to apply and verify one CI fix by hand. That is about 20 engineer-hours per fix. A shared workflow cuts it to one change plus routine version bumps.
The cost is ownership. Someone has to maintain the workflow, enforce review rules on it, keep a changelog, and publish a deprecation policy so callers know how long old versions stay supported.
How does a reusable workflow work at runtime?
A called workflow does not run as a separate pipeline. When a caller job says uses: org/ci-templates/.github/workflows/build.yml@v2, the runner fetches that file at the given ref and runs its jobs inside the caller's workflow run. The jobs appear in the caller's run, and the github context belongs to the caller.
Context belongs to the caller. github.repository, github.ref, github.sha and github.event_name describe the service repo and the event that triggered it, not the template repo. This is what makes one template work for many repos. A bare actions/checkout step in the callee checks out the caller's code at the caller's ref. It also means the callee cannot rely on files from its own repo unless it checks that repo out explicitly.
Environment does not cross the boundary. Variables in the caller's top-level env block are not visible to the callee. Anything the template needs must be declared as an input and passed with with:. This keeps the template's interface explicit and reviewable.
Secrets are opt-in. The callee sees only the secrets the caller passes by name under secrets:. secrets: inherit forwards everything instead, but only within the same organization or enterprise. Passing secrets by name keeps the exposure smaller and easier to audit.
Token permissions only narrow. The caller sets GITHUB_TOKEN scopes with permissions on the calling job, or falls back to its workflow or repository defaults. The callee can keep those scopes or reduce them, but it cannot grant itself more. A template that needs to write packages fails until each caller grants that scope.
Limits exist. GitHub limits how deeply workflows can nest and how many reusable workflows a single run can call. These values have changed over time, so check the current GitHub documentation before designing deep chains.
caller repo: org/service-a template repo: org/ci-templates
+--------------------------------------+ +------------------------------+
| caller workflow run | | .github/workflows/build.yml |
| | | ref: v2 (tag) |
| env: FOO=bar (stays in caller) | +--------------+---------------+
| | |
| job: build |<-- fetched @v2 --+
| permissions: packages: write |
| uses: org/ci-templates/...@v2 |
| with: -> inputs only |
| secrets: -> named, or inherit |
+-------------------+------------------+
|
| callee jobs join the caller's run
v
+--------------------------------------+
| callee jobs (from build.yml@v2) |
| github.repository = org/service-a |
| github.ref, sha, event = caller's |
| actions/checkout -> caller's code |
| GITHUB_TOKEN <= caller's scopes |
| caller env: not visible |
| secrets: only what was passed |
+--------------------------------------+
The template is fetched at its ref but its jobs run inside the caller's workflow run, so the github context, checkout target and token scopes come from the caller, and only declared inputs and passed secrets reach the callee.
How do you build a reusable build-and-test workflow and a composite action?
Create a dedicated repository, for example platform-ci, and put the reusable workflow at .github/workflows/build-test.yml. GitHub only resolves called workflows from that directory, so it cannot go in a subfolder. The trigger is on: workflow_call. Under it, declare inputs with explicit types:
- a
stringfor the runtime version, with a default - a
booleansuch asrun-integration-tests, defaulting tofalse - a
numberfor a test timeout
Mark an input required: true only when no sensible default exists. Callers then fail fast on a missing value instead of silently building the wrong thing.
Declare each secret under secrets (for example, a registry token) rather than relying on callers to use secrets: inherit. An explicit list documents the workflow's contract and limits what it can see.
To expose results, a step writes to $GITHUB_OUTPUT. The job maps that step output into its outputs. The workflow-level outputs block then references jobs.<job_id>.outputs.<name>. Callers can read only the values that pass through all three levels.
Put toolchain setup and dependency caching in a composite action, at a path such as .github/actions/setup-toolchain/action.yml with runs.using: composite. Every run step in a composite action must declare a shell. Reference the action by its full owner/repo/path@ref form. A ./ path resolves against the caller's checkout, not the central repo.
If platform-ci is private or internal, open its Actions settings and allow access from other repositories in the organization or enterprise. Without that setting, callers fail with a "not found" error.
Finally, set a top-level permissions block that grants only contents: read, and add more permissions per job only where a job needs them. A called workflow can reduce the caller's token permissions but cannot raise them.
# platform-ci/.github/workflows/build-test.yml
on:
workflow_call:
inputs:
service-name:
type: string
required: true # no sensible default, so callers must set it
runtime-version:
type: string
default: "20"
run-integration-tests:
type: boolean
default: false
test-timeout-minutes:
type: number
default: 15
secrets:
registry-token: # declared explicitly instead of relying on secrets: inherit
required: true
outputs:
artifact-version: # workflow level, which reads the job output
value: ${{ jobs.build.outputs.artifact-version }}
permissions:
contents: read # least privilege; widen per job only where needed
jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: ${{ inputs.test-timeout-minutes }}
outputs: # job level, which reads the step output
artifact-version: ${{ steps.version.outputs.version }}
steps:
- uses: actions/checkout@v4
# Full owner/repo/path@ref, because ./ would resolve in the caller's repo
- uses: my-org/platform-ci/.github/actions/setup-toolchain@v1
with: { runtime-version: "${{ inputs.runtime-version }}" }
- run: make test SERVICE="$SERVICE"
env: { SERVICE: "${{ inputs.service-name }}" }
- if: ${{ inputs.run-integration-tests }}
run: make integration-test
env: { REGISTRY_TOKEN: "${{ secrets.registry-token }}" }
- id: version # step level, which writes to $GITHUB_OUTPUT
run: echo "version=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
A reusable build-and-test workflow with typed inputs, defaults and a required flag, an explicitly declared secret, a step-to-job-to-workflow output chain, a call to a central composite action, and a top-level permissions block limited to contents: read.
How do you call a reusable workflow from a service repo?
In the service repo, the caller is a job whose uses: key points at the shared file instead of a runner. The reference takes the form owner/repo/.github/workflows/build-test.yml@ref, where ref is a tag, branch or commit SHA. The job has no runs-on or steps. You pass the service name and test command under with:, and they must match inputs the called workflow declares. You also map the registry credential under secrets:, for example registry_token: ${{ secrets.REGISTRY_TOKEN }}.
Explicit secrets vs. secrets: inherit
Explicit mapping makes the contract visible. A reviewer can read the caller and see that only one credential crosses the boundary. If the shared workflow later adds a step that would need something else, it fails rather than silently receiving it. secrets: inherit forwards every secret the caller can access, which saves boilerplate when many secrets are involved. The cost is that you are trusting every current and future version of the called workflow with all of them. Inheritance also only works within the same organization or enterprise. For shared pipelines owned by another team, explicit mapping is the safer default.
Matrix callers and outputs
You can add strategy.matrix to the calling job to fan out over services or runtime versions, then reference ${{ matrix.service }} inside with:. Each matrix leg is an independent run of the called workflow.
Outputs do not aggregate across those runs. A downstream job that reads the caller's output gets a single value, set by whichever matrix run that writes it finishes last. If you need a value per service, publish it under a distinct artifact name for each leg, or give each leg its own non-matrix caller job.
# .github/workflows/ci.yml in a service repo
name: ci
on:
pull_request:
push:
branches: [main]
jobs:
# Single caller: no runs-on or steps, just uses: + with: + secrets:
build-api:
uses: example-org/ci-workflows/.github/workflows/build-test.yml@v2
with:
service: api
test_command: npm test
secrets:
# Only this one credential crosses the boundary (vs. secrets: inherit)
registry_token: ${{ secrets.REGISTRY_TOKEN }}
# Matrix caller: each leg is an independent run of the called workflow
build-matrix:
strategy:
fail-fast: false
matrix:
service: [billing, auth]
node: ['20', '22']
uses: example-org/ci-workflows/.github/workflows/build-test.yml@v2
with:
service: ${{ matrix.service }}
test_command: npm test
node_version: ${{ matrix.node }}
secrets:
registry_token: ${{ secrets.REGISTRY_TOKEN }}
report:
needs: [build-api, build-matrix]
runs-on: ubuntu-latest
steps:
# build-api output is unambiguous; build-matrix output is whichever leg wrote last
- run: echo "api image: ${{ needs.build-api.outputs.image_tag }}"
- run: echo "matrix (last writer only): ${{ needs.build-matrix.outputs.image_tag }}"
A service repo calls a pinned reusable workflow with explicit inputs and one mapped secret, then fans out over services and Node versions, where the matrix job's output holds only one leg's value.
How should you version, test and roll out changes to shared workflows?
A service repo chooses its ref on the uses: line, and that choice decides who absorbs your changes. Pointing at main means every merge reaches every caller immediately, so one bad commit can break CI across the organization at once. Pin callers to a tag or a full commit SHA, and keep a major-version tag such as v2 that you move only on purpose.
| Ref strategy | Stability | Update effort for callers | Risk |
|---|---|---|---|
Branch (main) |
Low: changes on every merge | None | One bad merge breaks every caller |
Major tag (v2) |
Medium: moves only when maintainers promote | None within a major version | A bad promotion reaches all callers of that major |
Exact tag (v2.3.1) |
High, but tags can be force-moved | Edit the ref for each release | Callers miss fixes unless they bump |
| Commit SHA | Highest: immutable | Edit the ref for each release | Callers fall furthest behind on fixes |
A breaking change is anything that can make an unmodified caller fail or behave differently. That includes removing or renaming an input, making an optional input required, changing a default, renaming or removing an output, changing an output's format, or requiring a new secret or permission. Breaking changes get a new major tag. Other changes can move the existing one.
To roll out a change, push it to a branch and point a dedicated test caller repo at that branch ref. Make sure the test caller covers the matrix and the failure paths. When those runs pass, create an exact tag, move the major tag to the same commit, and add a changelog entry that states whether callers need to do anything.
The trade-off is blast radius versus drift. Major tags deliver fixes quickly, but a bad promotion affects everyone on that major. SHA pins contain the damage but leave teams on old code. Automated dependency update tooling reduces drift by opening pull requests when a new release appears, so pinned repos still see and review updates.
#!/usr/bin/env bash
# Promote a validated commit of the shared workflow repo to a release.
# Run only after the test caller repo has passed against the branch ref.
set -euo pipefail
RELEASE="v2.3.1" # exact, immutable release tag
MAJOR="v2" # moving major tag; callers on @v2 receive this release
BRANCH="release-candidate"
git fetch origin --tags
# Resolve the exact commit the test caller validated.
SHA=$(git rev-parse "origin/${BRANCH}")
echo "Promoting ${SHA} as ${RELEASE} and ${MAJOR}"
# Refuse to reuse an exact tag; exact tags should never move.
if git rev-parse -q --verify "refs/tags/${RELEASE}" >/dev/null; then
echo "Tag ${RELEASE} already exists; pick a new version" >&2
exit 1
fi
# Create the exact tag and publish it.
git tag -a "${RELEASE}" -m "Release ${RELEASE}" "${SHA}"
git push origin "refs/tags/${RELEASE}"
# Deliberately move the major tag to the same commit.
# Skip this for breaking changes: those get a new major (v3) instead.
git tag -f -a "${MAJOR}" -m "Move ${MAJOR} to ${RELEASE}" "${SHA}"
git push --force origin "refs/tags/${MAJOR}"
# Callers then choose their ref in .github/workflows/*.yml, e.g.:
# uses: my-org/shared-workflows/.github/workflows/ci.yml@v2 # follows promotions
# uses: my-org/shared-workflows/.github/workflows/ci.yml@v2.3.1 # exact release
# uses: my-org/shared-workflows/.github/workflows/ci.yml@${SHA} # immutable pin
echo "Done. Add a CHANGELOG entry for ${RELEASE} stating any caller action needed."
A promotion script that tags a validated commit with an immutable exact version, deliberately moves the major tag to it, and shows the three caller ref choices.
When should you avoid reusable workflows, and how do you debug them?
When the pattern is the wrong fit
A shared workflow works when most callers need the same thing. When one service needs a GPU runner, a nonstandard toolchain or an unusual release step, the usual fix is another boolean input. After a few of those, the interface becomes a set of if branches that nobody can test fully. The other option is forking the workflow for that service, which brings back the drift you were trying to remove. Access rules can also rule out the design. A reusable workflow in a private repository is only available to callers that its access settings allow, and secrets do not pass automatically across organization boundaries. Platform limits on nesting depth and on the number of called workflows can also block a layered design. Indirection has a cost too. A new engineer reading a ten-line caller cannot see what actually runs.
The alternatives are composite actions only, with each repo owning its job structure, copied templates that teams adapt freely, or plain per-repo YAML for outliers.
Debugging
In the caller's run, a called workflow's jobs appear nested under the calling job's name. Expand them there to see step logs. Most failures come from one of three causes:
- Workflow not found or inaccessible: check the
usespath, the ref and the source repo's Actions access setting. - Empty secret: pass the secret explicitly or use
secrets: inherit. - Permission denied: a called workflow cannot raise
GITHUB_TOKENpermissions above what the caller grants.
Check GitHub's current documentation for limits instead of relying on numbers you remember.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to github actions reusable workflows, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.