Workflows on and for multiple branches?

[ringods]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Workflow Configuration

Discussion Details

For Github Actions to perform its magic, I have to commit my Github Actions workflow files to my Git repository. After these are committed, the system can scan these and start them when the matching events happen.

Now, what is the best setup when you have multiple release branches? Take for example main already at major v3, and having separate release branches named release/v1 and release/v2.

Each of these branches can have workflow files, which an even diverge in its contents. I'm a bit puzzled which one is picked up when. How should I configure my workflow files for releases to be done from these 3 branches?

Scenario 1

On main, my workflow file could contain:

on:
  push:
    branches:
      - main
      - 'release/**'

The rest of the workflow file then checks out the correct branch when it is triggered. Unknown though which actions it will execute: the definition in the workflow file of main, or the one from the triggered release branch?

Scenario 2

On main, my workflow contains:

on:
  push:
    branches:
      - main

And on a release branch, for instance for v1, my workflow contains:

on:
  push:
    branches:
      - 'release/v1'

So in general, can someone explain a bit deeper which workflow files are scanned in my git repository for the correct workflows to be executed in the end?

[frazrajpoot01]

Hey! I ran into this exact confusion a while back. The short answer to your question is that for push events, GitHub Actions looks at the workflow file on the branch where the event actually happens. It doesn't read from main unless the push was actually to main.

Here is how that plays out for your two scenarios:

If you go with Scenario 1 (the catch-all on main), and someone pushes to release/v1, GitHub completely ignores the workflow file on main. It checks out the release/v1 branch and looks for the .github/workflows folder there.

If the file doesn't exist on release/v1, nothing runs.

If it does exist, it runs whatever is defined in the release/v1 version of that file.

Because of how that works under the hood, Scenario 2 is the way to go. It reflects the reality of how Git version control applies to workflow files.

Since release branches usually diverge over time anyway (for example, your release/v1 branch might need older build tools or dependencies than main at v3), you actually want the workflow file on release/v1 to be explicitly tailored to build v1.

A quick tip for keeping it clean:
If your release steps are exactly the same across all branches and you just hate copy-pasting code, look into reusable workflows (workflow_call). You can keep your main deployment logic centralized on main, and just put tiny trigger files on your release branches that call the main workflow.

Hope this helps clear it up!

[ddryzhov]

Hey! This is a classic point of confusion with GitHub Actions.

The rule of thumb is: GitHub always looks at the workflow file in the specific branch you are pushing to.

So, for your Scenario 1: if you push to release/v1, GitHub checks the .github/workflows folder inside release/v1. It doesn't care what's in main at that moment. If the workflow file in release/v1 doesn't have the release/** trigger, nothing will happen.

Scenario 2 is definitely the way to go. It’s much cleaner to have the workflow in release/v1 only care about v1, and the one in main only care about main. That way, as your versions diverge (different Node versions, different build steps, etc.), your CI/CD stays synced with the code it’s actually building.

One tip: If you find yourself copy-pasting the same 100 lines of YAML across all branches, look into Reusable Workflows. You can keep the main logic in one file and just "call" it from the small workflow files in your release branches.

Hope this helps clear the fog!

[ringods]

@frazrajpoot01 & @ddryzhov thanks both for the swift responses.