One CI workflow for many repositories: reusable workflows
Short answer: If you have ten repositories with nearly identical CI files, each one slowly drifts: one has the new Node version, another the old deploy step. GitHub Actions' reusable workflows fix that. Put the shared pipeline in one repository with on: workflow_call, define the inputs and secrets it needs, and have each project call it with a single uses: line pinned to a tag or commit. Update the shared workflow once, then roll the new version out to projects deliberately.
The copy-paste problem
Agencies and small product teams often start every new project by copying the last project's .github/workflows folder. A year later:
- some projects still use an old runtime version
- a security fix was applied in three repositories out of twelve
- each deploy step has small, undocumented differences
- nobody is sure which version is "right"
Reusable workflows let you keep one source of truth for the common parts.
Creating a reusable workflow
GitHub's documentation explains that reusable workflows are YAML files in the .github/workflows directory (subdirectories aren't supported) and that a workflow is reusable when its on triggers include workflow_call.
A shared build-and-deploy workflow in a repository called ci-shared might start like this:
on:
workflow_call:
inputs:
node-version:
type: string
default: "22"
deploy-target:
type: string
required: true
secrets:
deploy-token:
required: true
Inside, jobs use ${{ inputs.node-version }} and ${{ secrets.deploy-token }} like any other workflow.
Calling it from a project
GitHub's docs explain that you call a reusable workflow at job level with uses, not as a step:
jobs:
ci:
uses: your-org/ci-shared/.github/workflows/build-deploy.yml@v1
with:
deploy-target: production
secrets:
deploy-token: ${{ secrets.DEPLOY_TOKEN }}
That's the whole CI file for the project, apart from its triggers.
Passing secrets
You can pass secrets one by one, as above, or use secrets: inherit, which the docs say makes the caller's secrets available to the called workflow even if they aren't listed in its definition. Explicit passing is clearer about what the shared workflow can see. For environment secrets, the docs note that the job in the reusable workflow must set environment.
Getting results back
Reusable workflows can define outputs, such as a version number or a preview URL, that the caller can use in later jobs. GitHub's docs warn that with a matrix, the output comes from the last successful run that set a value, so design outputs carefully.
Versioning: pin a ref
The reference after @ can be a commit SHA, a release tag or a branch. GitHub's docs say the commit SHA is the safest option for stability and security, and that if a tag and a branch share a name, the tag wins.
A practical approach:
- tag releases of the shared workflow (
v1.4.0) and keep a moving major tag (v1) if you want projects to receive non-breaking updates - pin critical or regulated projects to a SHA
- never point production projects at
@main, where any merge changes their pipeline instantly
Within the same repository, the docs explain that local references use the caller's own commit, so changes are tested together.
Sharing from a private repository
If your shared workflows are in a private repository, you must allow access. GitHub's docs describe the setting under the repository's Actions settings, in the Access section. They also include a warning worth reading: outside collaborators on the calling repositories can indirectly access the private repository's workflows and view logs of runs that use them. Runners receive a read-only token for the repository that expires after an hour. Keep secrets and sensitive details out of the shared repository's code and logs.
Limits to know
GitHub's docs say you can nest reusable workflows up to ten levels deep, counting the top-level caller, and loops aren't allowed. In practice, one or two levels keep things understandable.
Reusable workflows or composite actions?
Composite actions bundle steps inside a job; reusable workflows provide whole jobs, with their own runners, environments and secrets. Use composite actions for small shared step sequences, such as "set up project and install dependencies", and reusable workflows for complete pipelines, such as "build, test and deploy".
What to keep out of the shared workflow
Keep project-specific details in the caller: domain names, environment names, feature flags and anything only one client needs. If the shared workflow starts filling with if conditions for individual projects, it's doing too much; split it into two workflows, or move the special steps into the project's own job that runs after the shared one. A shared pipeline should describe what every project has in common, not every exception.
Rolling out changes safely
- Change the shared workflow on a branch and test it by pointing one non-critical project at that branch.
- Tag a release with release notes describing changes and required inputs.
- Move projects to the new tag gradually, starting with internal or low-risk ones.
- Keep the previous tag available so a project can roll back by changing one line.
A worked example
An illustrative Melbourne web agency maintained fifteen client sites, each with its own copied workflow. A change to their hosting's deploy method meant editing fifteen files, and two were missed. They created a ci-shared repository with a reusable build-and-deploy workflow taking the site name and target as inputs, tagged it v1, and replaced each project's workflow with a short caller. The next hosting change was one pull request to ci-shared, a new tag, and a staged rollout.
FAQ
Can a reusable workflow use the caller's code?
Yes. It checks out the calling repository by default when it uses the checkout action.
Do callers need the same triggers?
No. Each project defines its own triggers and calls the shared workflow.
Does this cost extra?
Jobs in reusable workflows use runner minutes like any other job.
Can I see which projects use an old version?
Search your organisation's repositories for the workflow path and tag.
If your CI files have drifted apart across projects, tell us how many repositories you maintain and we'll help you consolidate them.