How to start using reusable workflows with GitHub Actions

Why reusable workflows matter

GitHub Actions has long been the go-to for automating builds, tests, and deployments. But for a long time, if you wanted to use the same workflow in multiple repositories, you had to copy and paste the YAML file everywhere it was needed. That approach quickly becomes a maintenance headache when you need to update a step or fix a bug across dozens of repos.

Reusable workflows, generally available since late 2021, solve this by letting you define a workflow once and invoke it from anywhere in your organization. The main benefits:

• No more copy-paste. You can DRY up your Actions configuration. If three Node apps build the same way, one reusable workflow handles all of them.
• Consistent enforcement. Combined with OpenID Connect, reusable workflows let you require specific tests to pass before a deployment can proceed. For instance, you can put a policy in front of a cloud-hosted database that only accepts migrations triggered by a designated reusable workflow.

Making a workflow reusable

A reusable workflow is just a standard GitHub Actions workflow with one extra trigger added: workflow_call. To convert an existing workflow, add this to the YAML file:

on:
workflow_call:

Once that's in place, you can invoke the workflow from any other workflow using the standard uses syntax with the repository path and a branch or tag reference:

Uses:
USER_OR_ORG_NAME/REPO_NAME/.github/workflows/REUSABLE_WORKFLOW_FILE.yml@TAG_OR_BRANCH

Reusable workflows accept two kinds of parameters. Use inputs for non-sensitive data like job names or configuration values, and secrets for credentials and other sensitive information.

Enabling organizational access

After adding the workflow_call trigger, you need to make sure repositories outside the workflow's own repo can see it. Navigate to the repository's Settings, select Actions, and enable access for other repositories in your organization:

Known limitations

Before you adopt reusable workflows, keep a few constraints in mind:

• Private repos are isolated. You cannot reference a reusable workflow from a private repository in another repository's workflow. Only workflows inside that same private repository can use it.
• Nesting is allowed, but capped. You can call a reusable workflow from within another reusable workflow, up to four levels of nesting.

Reusable workflows vs. composite actions

Composite actions are another way to reduce duplication in GitHub Actions. They let you bundle multiple actions into a single action that you can drop into any workflow, which can significantly shrink long YAML files. Instead of updating credentials in a dozen places, you update one composite action.

There is significant overlap between the two approaches. In many cases you could use either one — some estimates say up to 80% of scenarios are covered by both. But the remaining cases usually demand one or the other. A key differentiator: if your job must run on a particular runner or machine type, you need a reusable workflow. Composite actions don't define a runner; they are more generic and isolated by design.

The real advantage of reusable workflows is that they can orchestrate multiple jobs. This gives you granular control over how different jobs interact and what conditions must be met. Composite actions, by contrast, are more about bundling steps together and cannot dictate job-level settings.

Reusable workflows also have a simpler file layout. Composite actions require a separate folder per action, which adds a layer of nesting when you have many of them. Reusable workflows can live anywhere in the repository, so you avoid that extra directory sprawl.

The takeaway

Following the DRY principle pays off when it comes to automation. Reusable workflows let you stand up new repositories with proven CI/CD configurations immediately, with no copy-paste or drift between projects. That leaves less time spent duplicating YAML and more time writing the code that matters.