Ambiguous on:workflow_dispatch statement about "default branch"

[neongreen]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch

What part(s) of the article would you like to see updated?

The docs say that workflow_dispatch will only trigger a workflow run "if the workflow file is on the default branch".

However, below it's shown that the user can choose which branch to use:

I'm struggling to interpret the phrasing from the docs. Let's say we have .github/workflows/deploy.yml with a trigger on: workflow_dispatch. The default branch is main. Which interpretation is true?

• a) Only deploy.yml@main can ever run. The versions in other branches can never run. The branch selector does nothing.

• b) If deploy.yml exists in main, then the user can trigger a version located in any branch. If deploy.yml does not exist in main, the versions in other branches cannot be triggered.

• c) The user can trigger a version of deploy.yml located in any branch. However, if ANOTHER WORKFLOW tries to trigger deploy.yml via gh, API, or by any other means, then this ANOTHER WORKFLOW must be located in main.

• d) ...something else?

Additional information

No response

[nguyenalex836]

@neongreen Thank you for raising this issue! I'll get this triaged for review ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[subatoi]

Hi @neongreen 👋 thanks for raising an issue. The best answer I can provide here is that it's true that it's only officially supported by the default branch, and that the reason other branches are visible on the dropdown is to support the case where you may be testing a new workflow, triggered by workflow_dispatch, that hasn't yet been committed to the default branch.

The conversation in this issue might also be relevant: #34884. The method noted there isn't officially supported.

I hope this helps—may I ask if your GitHub plan includes Support? They are best positioned to help with this kind of query in general.

[neongreen]

@subatoi for context — I’m not looking to use this feature. I’m evaluating the security of a CI setup.

What I need to know is “can someone potentially run this workflow from a non-default branch, and under what conditions?”. This someone can be an external contributor, for example.

When I read “this event will only trigger a workflow run …”, I interpret it as a guarantee: a workflow with this trigger will NEVER run from a non-default branch.

The same of course applies to everything else in the documentation. If I read “a nested workflow cannot access secrets”, now I have to wonder if it actually can’t access secrets — or whether it can, just not officially.

[neongreen]

So, just to clarify — in #34884, the author seeks to run a workflow from a non-default branch. GitHub does not want to officially commit to this feature. This is perfectly understandable.

In this issue, I didn’t want to run a workflow — I wanted to know if somebody else could.

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[subatoi]

Thanks for the additional context—we'll ask an SME to review this internally, but since our requests are made in the context of the accuracy of the docs, I'm afraid we're unable to guarantee a timeframe for their response. If it's available to you, in this case the faster way to get an answer would be via GitHub Support.

[nguyenalex836]

@neongreen Thank you for your patience while our SME team reviewed! 💛 They confirmed that b) is correct:

If deploy.yml exists in main, then the user can trigger a version located in any branch. If deploy.yml does not exist in main, the versions in other branches cannot be triggered.

They are proposing the following wording to add more clarity:

This event will only trigger a workflow run if the workflow file exists on the default branch.

I've added the help wanted label so that you, or anyone else, may make this update ✨