Single workflow vs multiple workflows

Is there any advantage or convention to using multiple workflows vs a single workflow where there are many jobs?

For example, what might be some of the benefits to running a Unit Test workflow, Lint workflow, etc. separately from each other vs having a single workflow that runs unit tests and lints as jobs?

I imagine there are probably tradeoffs, so there might not be a single best way to do things, but what are you all doing? Are there any folks that really split everything out into multiple workflows and love it?


It’s hard to say which one is best between single workflow and multiple workflows.
Different users or projects have many different use cases. It depends on what you need the workflows to do with your project, and sometimes it even depends on your personal preference.

If you want the workflows to execute a series of coherent jobs based on a Git ref, setting up all the jobs in a single workflow may be a good choice.

If you want the workflows to execute different jobs at different stages or on different events, using multiple workflows may be the good choice.

Thanks @brightran - as I suspected, this question doesn’t have one right answer. It seems like there’s a great opportunity to provide more guidance to developers through the use of blog posts and documentation.

I imagine that anyone who’s been using GitHub Actions for more than a few months with a sizeable codebase has had to grapple with this decision. I’m very interested to hear what key differences others have found that might influence the decision to go with a single workflow vs. multiple workflows.

I have been migrating our CI to GH workflow in past month or so. My impression is that you will quickly realize when jobs have to run in the same workflow. When you try to split jobs in different workflows, you will either hit a wall where you just can’t achieve what you want due to some limitation on GH or you will start to copy/paste substantial amount of yaml between workflows.

Anything that requires synchronization between jobs will have to be in the same workflow. If you just want to run Job B after Job A succeed, you can do it in either one workflow or two (by dispatching events). But if you want Job C to run after Job A and B succeeded, you will only be able to do it with jobs in the same workflow.

Sometimes you will be forced to run separate workflows. For example, if people open PRs from forks, your workflows running on the PRs will not have access to any of your secrets. In this case, you will have to split the jobs that require credentials from the ones that require to run on the code from your PR.

This is only few examples but you shouldn’t worry too much about the separation of your workflows in my opinion. The system, to me, is not so flexible that you can get very far in the wrong direction. You will hit limitations quickly enough and it will be obvious that it isn’t the way to go.


Brilliant response @benjamin-bergia

It sounds like the best way to approach this is to choose an option (single or multiple) and try to accomplish what you want. Eventually, and because of the constraints of the system, one option will become the “obvious” path forward.