Use a reusable workflow when you want security checks to stay under central control and update everywhere, and a workflow template when you want a starting point that teams then own. For a golden path, many teams use a short template that calls a reusable workflow.
What each one is
GitHub documents both features, and they solve different problems.
A workflow template is a pre-written workflow file stored in a special place so people in your organization can pick it when they add a workflow. According to GitHub's docs, you create a repository named .github in your organization, add a directory named workflow-templates, put the workflow file in it, and add a metadata file with the same name ending in .properties.json. The metadata gives the template a name and description and can limit where it is offered by file patterns. A team that picks the template gets its own copy of the file.
A reusable workflow is an ordinary workflow file that other workflows call. For a workflow to be reusable, its triggers must include workflow_call. A caller references it from a job with the uses keyword, and can pass inputs and secrets.
Side by side
| Question | Workflow template | Reusable workflow |
|---|---|---|
| How does a team get it? | Picks it when adding a workflow, and receives a copy | Calls it from a job |
| Who owns the logic after that? | The team that copied it | The team that maintains the reusable file |
| How does a fix reach every repo? | Each team must update its copy | Change the reusable file, or move its version tag |
| Can teams customise freely? | Yes, it is their file | Through the inputs you expose, no further |
| Suited to | Giving a good starting point | Keeping security steps consistent |
A pattern that uses both
Put the real checks in a reusable workflow in a central repository, then offer a workflow template that is just a few lines long and calls it. New services get the call automatically, and you keep control of what runs.
name: security
on:
pull_request:
jobs:
checks:
uses: my-org/platform-workflows/.github/workflows/security-scan.yml@v1
secrets: inherit
The reference follows the pattern owner, repository, path and a ref. Using a version tag for the ref lets you release changes deliberately, and teams can move to a new major version when ready. Think about whether passing all secrets with the inherit keyword suits your setup, since it hands the called workflow access to the caller's secrets. Passing just the ones it needs is a tighter default.
Trade offs to weigh
- Central change risk. A bad release of a reusable workflow can break many repositories at once. Test it on a pilot repo first and publish new versions under new tags.
- Flexibility. Too few inputs and teams feel boxed in, which pushes them off the road. Too many and you lose consistency.
- Visibility. Make sure developers can read the central workflow, so failures are not a mystery.
Try it yourself
Click through it at your own pace, or open it full screen. See how a pull request check reports back, which is what your shared workflow will produce in every repository.
Where Safeguard fits
Safeguard's CLI can run in a pipeline step, and its policies and gates decide what blocks a pull request, so the same rules can apply wherever the shared workflow runs. You can try a free scan at gold.safeguard.sh/scan.
Quick check
Can a workflow template force teams to keep the security steps?
No. A team gets a copy and can edit it. To require checks, combine a template or reusable workflow with a repository rule that makes the check required.
Where do reusable workflows live?
In the workflows directory of a repository, not in subdirectories of it. Callers reference them by path and ref.
Sources
- GitHub Docs: Reusing workflow configurations
- GitHub Docs: Creating workflow templates for your organization
Last reviewed: 19 October 2026.
