How to develop (iterate on, debug!) a workflow file in a non-default branch?

I want to develop a workflow file for my repository. I have read quite a bit of documentation by now and tried things for various hours.

Here is what’s frustrating: I still have so many questions about the relationship between the branch that I develop in and the actual workflow behavior. I don’t yet know how to get started, really.

I was hoping for well-specified behavior, such as “workflow files are only picked up from the default branch of your repository” or “workflow files are picked up from a configurable set of branches in your repository”, or something equally precise.

All I found in the docs was (let me know if I missed something in the docs):

> Commit your changes in the workflow file to the branch where you want your workflow to run.


This statement is ambiguous. But it helps, and it got my hopes up! It suggests that I can develop my workflow file in a non-default branch, i.e. in a regular pull request within my repo. Great.

Why do I care about that? In my repository the master branch is the default branch and I want to make sure that I merge only a valid, tested, working workflow file into the master branch.

Now, how can I iterate on the workflow file, develop it (and see its effects) while it’s not yet merged to master?

The quote above is promising, it suggests that a valid workflow file should “just work” even if not yet merged to the default branch. So I tried that.

But actual behavior is just super confusing and discouraging: in the PR in which I try to develop my workflow file I seem to get some feedback when there are syntax errors in the YAML document, but the workflow does not seem to trigger upon configured events. Or does it? And I just can’t see it in the Actions tab? Woof… this is fishy!

I’d love to understand: which method do you people out there resort to, in practice? Do you iterate on the workflow file(s) in your master branch until it works? Or did you find a way through a non-default branch? (if it’s through the master branch: that sucks, but at least I’d love to make sure that there really is no better way before I do that).

I also found this highly related discussion: – that adds to confusion:

> A new workflow only appears in the “Actions” tab when it lands in the master default branch.

Aha, ok. Precise!

> Alternatively, you can access the new workflow via commit or PR.

Sounds cool, but what … what, can you tell me more? I don’t understand this.

> we’re working on an update to the Actions tab so you’ll be able to see all of your workflows. Even ones that have not yet been merged into your default branch

Oh, so… the system is looking at workflow files not in the default branch, they just don’t appear in the Actions tab, yet? Mhm…

> Not being able to work on (or create) workflows in non-default branches themselves is a major issue for me, and sort of defeats the whole purpose of GitHub Actions and an evolving CI, in my opinion.

This. Exactly. I am actually pretty shocked that it’s so hard to jump into workflow development.

> It shows all workflow runs (including those from workflows not in default branches).

What? Well, no, not really, not in my case. (this quote is a week old).

> I’m facing a similar issue. My default branch (master) does not contain any workflow. Adding a fairly simple workflow via Pull Request doesn’t get picked up and the status box remains empty also the Action tab. I copied this workflow from another repository so it’s supposed to work

Yeah. This is what I face, too.


For the record, my strategy for now: I created a fresh repository, just for developing a workflow file in its master branch.

1 Like

There is a summary I get according to my testes, it may be helpful to you:

  1. Every workflow run has a branch or tag ref that triggered the workflow run ( github.ref ). The YAML file of the workflow should exist in the branch or tag, and the events defined in the YAML file also should occur on the branch or tag.

For example, there are two branches on my repository, master (default branch) and Dev. I added a CI workflow on Dev branch, named CI_Dev , the YMAL file of CI_Dev only exists on Dev. And added a CI workflow on master branch, named CI_master , the YMAL file of CI_master only exists on master.

If I push changes in Dev, CI_Dev is triggered, and CI_master is not triggered. If I open a PR to merge changes from Dev into master, CI_Dev is triggered, and CI_master is not triggered.

If I push changes in master, CI_master is triggered, and CI_Dev is not triggered. If I open a PR to merge changes from master into Dev, CI_master is triggered, and CI_Dev is not triggered.


  1. The ref of some events always is the default branch (master) by default, such as Issue comment event , Issues event , Label event , etc… So, if you want these events can trigger your workflow, you should define them in the YAML file of this workflow, and the YAML file should exist in the default branch.

  2. Only the workflows defined in the default branch are listed under All workflows at the left of the page on Actions tab. For the workflows defined in the non-default branches, all of their runs are listed in All workflows.

1 Like

Thanks, your comment adds credence to my plan.
This does seem like the only reasonable solution based on the current state of Github Actions.