With GitHub offering both Composite Actions and Reusable Workflows, I’ve seen a lot of people having doubts about what they should use, and in fact I often have someone asking me: what is the difference between Reusable Workflows and Composite Actions?

In the past the difference was very clear, because Composite Actions allowed to only use bash scripts in them. But now that we have the possibility to use other actions as steps in the Composite Actions, as I explain in this video, the difference is more subtle.

Video

As usual, if you are a visual learner, or simply prefer to watch and listen instead of reading, here you have the video with the whole explanation and demo, which to be fair is much more complete than this post.

Link to the video: https://youtu.be/xa9gYSCf8q0

If you rather prefer reading, well... let's just continue :)

General

First of all, let me say that if you want to have a deep dive in either one of these features I’d highly recommend to check the specific videos I made about them, you can find them here (Composite Actions) and here (Reusable Workflows). To summarize, I would say that Composite Actions are intended to be more isolated and generic, while Reusable Workflows are more feature rich and appeal to slightly more specific scenarios.

In general, I would say 80% of the time you can probably use either one. But 20% of the time, you’ll need to use one or the other.

I’ve identified 6 main differences between those 2 flavors of GitHub Actions, and we will go through each one of those right now.

Difference 1: Nesting

The first one is about nesting. Composite Actions can be nested up to 10 layers. This means you can create a Composite Action that has another Composite Action as one of its steps, and so on so forth until the 10th level.

Reusable Workflows, on the other hand, cannot call another reusable workflow, you can’t chain them. Using another terminology which may be more familiar to users of other CI systems, you cannot have a template which refers to another template.

Difference 2: Secrets

The second big difference is about Secrets. Composite Actions cannot use secrets, not from the workflow nor as parameter. And this, as you can imagine, could be a fairly big limit.

Reusable Workflows instead can consume secrets, although you have to pass them to the workflow via parameter, as you can see in the image above.

This, together with the next difference, makes the Reusable Workflows way more flexible.

Difference 3: Conditionals

Third difference is that Reusable Workflows can use the if conditionals.

This means that the execution of parts of the template can be controlled by some conditions, like you would do in a normal workflow.

This behavior unfortunately is not present in the Composite Actions, where you can only have a flat list of steps and no control over their execution.

Difference 4: Storage

The fourth main difference I’ve identified is about storing them.

Reusable Workflows can be stored in your repo as normal YAML actions files, in the .github/workflows folder. Or you can create a centralized repository to store multiple Reusable Workflows.

Each Composite Actions definition, on the other hand, requires its own repository, which must be public, and a metadata file. And if you want to execute script from a file, then you’ll also need the script file in the same repo.

Difference 5: Jobs

The fifth difference is about multiple jobs. As we have said before, Composite Actions allow you to only have a flat list of steps. Therefore, you cannot have multiple jobs in a single Composite Action

In fact, a Composite Action doesn’t specify a job keyword, but uses runs instead, and can only be consumed from within a job in the caller repository.

Because of this, you can see a Composite Action basically like any other action you have on the marketplace.

The story is different, however, for Reusable Workflows.

They do define jobs inside them, and because of that you can have as many jobs as you want in a single Reusable Workflow.

And since they do use jobs, and you have to specify where the job will run, we can take this a little further: if your job needs to run on a specific runner or machine, you need to use Reusable Workflows.

Difference 6: Logging

The sixth and last difference between Reusable Workflows and Composite Actions is something I think is pretty important but often overlooked. I’m talking about logging.

With Reusable workflows you have a very rich log of what is happening, and every single job and step is logged independently in real time.

Using Composite Actions, instead, all you have is a single log of a single step... even if it contains multiple steps.

Conclusions

Because of all we have seen, Reusable Workflows make it simpler to spin up new repositories and projects and immediately start using automation and CI/CD workflows with GitHub Actions that you know will work. Composite Actions, on the other hand, allow you to pack multiple tasks and operations in a single step, to be reused inside a job.

Hope this clarifies once and for all the differences between those 2 powerful features of GitHub Actions. But let me know in the comments below if you have other questions about them that this article/video wasn’t able to answer.

Also, check out this video, in which I show how to build and use Reusable Workflows.

Like, share and follow me 🚀 for more content:

📽 YouTube
☕ Buy me a coffee
💖 Patreon
📧 Newsletter
🌐 CoderDave.io Website
👕 Merch
👦🏻 Facebook page
🐱‍💻 GitHub
👲🏻 Twitter
👴🏻 LinkedIn
🔉 Podcast