Build what's next on GitHub, the place for anyone from anywhere to build anything.
Join us October 28-29 in San Francisco or online for GitHub Universe, our flagship developer event uniting people, agents, and the world's code.
Reusable workflows offer a simple and powerful way to avoid copying and pasting workflows across your repositories.
From automating repetitive tasks to building continuous integration and continuous deployment pipelines, you can do a lot with GitHub Actions.
But until recently, you had to copy and paste YAML files from one repository to another if you wanted to use them in more than one place.
Enter reusable workflows, which officially launched in 2021 and offer a simple and powerful way to avoid copying and pasting workflows across your repositories.
Below, I’ll go over some of the benefits of reusable workflows and how to use them. I’ll also talk through how reusable workflows are different from composite actions and some current limitations.
New to GitHub Actions?
If you haven’t used Actions before, don’t start your learning journey with reusable workflows. It will drive you crazy. Try learning more about GitHub Actions first in our guide (and then maybe try doing even more things with them).
Case in point: if you have three different Node applications and you’re building them all the same way, you can use one reusable workflow instead of copying and pasting your workflows again and again.
Let’s say, for example, that you have a cloud-hosted database and your applications are going to run database migrations when they’re deployed. You can put a policy in front of that database requiring that a specific reusable workflow is used before any deployment.
A reusable workflow is just like any GitHub Actions workflow with one key difference: it includes a workflow_call trigger.
That means all you need to do is add in the following syntax to any action’s YAML workflow file:
You can then reference this workflow in another workflow by adding in this syntax:
You can also pass data such as job information or passwords to a reusable workflow by using inputs and secret triggers. Inputs are used to pass non-sensitive information while secrets are used to pass along sensitive information such as passwords and credentials. You can learn more about that in our docs.
After you add a workflow_call trigger, you need to make sure that your repositories in your organization have access to it. To do this, go to your repository settings, select Actions, and enable access to repositories in your organization.
Enabling access for GitHub Actions at the organization level
A real-world example with reusable workflows
While building a new repository to develop hot.opensauced.pizza, I needed to centralize my GitHub Actions compliance workflows (and avoid copying and pasting because who wants to do that when they can avoid it?).
To do this, I added a workflow_call trigger to my original YAML workflow file in my open-sauced repository. You can see that here in my YAML file—or in the code snippet below.
Next, I built a new YAML workflow in my hot.opensauced.pizza repository and had it call back to my reusable compliance workflow. It looked like this (and you can check out the YAML file here):
Why this matters: Reusable workflows helped provide consistency across my projects and made my life easier. By copying and pasting a few key YAML files from one project to another, I was immediately good to go on day one.
There are some limitations with reusable workflows. I want to call out a few to keep in mind:
When we launched reusable workflows, one of the first questions we got was around how they’re different from composite actions.
For the uninitiated, composite actions enable you to combine multiple actions into a single action that you can then insert into any workflow. This means you can refactor long YAML workflow files into much smaller files—and you can also save yourself a fair amount of copying and pasting. Plus, if something like your credentials change, you won’t have to update an entire YAML file.
In practice, there are kinds of problems you can solve with either reusable workflows or a composite workflow. Both approaches have individual strengths and weaknesses. 80% of the time you can probably use either one. But 20% of the time, you’ll need to use one or the other.
For example, if your job needs to run on a specific runner or machine, you need to use reusable workflows. Composite actions don’t specify this type of thing. Composite actions are intended to be more isolated and generic.
| Reusable workflows | Composite actions |
| Can connect a maximum of four levels of workflows | Can be nested to have up to 10 composite actions in one workflow |
| Can use secrets | Cannot use secrets |
| Can use if: conditionals | Cannot use if: conditionals |
| Can be stored as normal YAML files in your project | Requires individual folders for each composite action |
| Can use multiple jobs | Cannot use multiple jobs |
| Each step is logged in real-time | Logged as one step even if it contains multiple steps |
With reusable workflows, you can have multiple jobs and that gives you a lot of more granular control—and power. They allow you to specify any number of things and customize them more to your liking.
Reusable workflows also don’t require individual folders for each workflow like composite actions do. This can make using reusable workflows simpler since you can avoid nesting a bunch of different folders like you’d need to do with composite actions.
The more things you can do to follow the DRY principle, the better. Reusable workflows make it simple to spin up new repositories and projects and immediately start using automation and CI/CD workflows with GitHub Actions that you know will work. That saves you time, and it lets you focus more on what’s important: writing great code.
