Mention that workflow needs to exist on default branch to use workflow_dispatch

[jsoref]

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/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatch

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

Add more text explaining requirements relating to presence on default branch

Additional information

https://github.com/orgs/community/discussions/25746#discussioncomment-8067852

Content design plan:

Add a sentence to the on.worklfow_dispatch section of Workflow Syntax for GitHub Actions that says something like:

This trigger only receives events when the workflow file is on the default branch.

[jsoref]

Some prose should probably also be added near https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onevent_nametypes explaining which events are handled by the workflow in the default branch and which are handled by other versions of the workflow (which I believe is basically push, pull_request*, and workflow_dispatch if someone with write(?) permissions asks a workflow present on the default branch to run from a non-default branch).

[nguyenalex836]

@jsoref Thanks for opening this issue, and providing the discussion this stemmed from 💛 I'll get this triaged for review ✨

[nguyenalex836]

@jsoref Thanks again for raising this flag on this! ✨ We've discussed with the team, and would appreciate if you could send over some snippets for what you hand in mind regarding -

Add more text explaining requirements relating to presence on default branch

Some prose should probably also be added near https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onevent_nametypes

CC @SiaraMist @jc-clark

[jsoref]

Here's a sample workflow with some runs: https://github.com/jsoref/on.event-name.types/actions/workflows/issue-labeled.yml

I'm not sure how many types this applies to, but at least for on.issue.types, only workflows on the default branch at the time the event is dispatched are consulted.

-Some events have activity types that give you more control over when your workflow should run.
+Some events have activity types that give you more control over when your workflow should run.
+Generally these events are only dispatched to workflows on the default branch.

The reason for this text is that there is a workflow jsoref/on.event-name.types@3bbb2e6 which is on the main branch, and it did not run when the invalid label was added to jsoref/on.event-name.types#3 -- because at the time of that event, the default branch was test not main.

[nguyenalex836]

@jsoref Thanks for sending that over! Going to loop in @SiaraMist and @jc-clark to give this a quick review 💛

[jsoref]

For the title item, https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatch

-When using the workflow_dispatch event, you can optionally specify inputs that are passed to the workflow.
+When using the workflow_dispatch event, you can optionally specify inputs that are passed to the workflow.
+
+This event is only received by workflows on the default branch.

It's documented, but not here, where a reader is likely to look for it.

Instead, you have to be in:
https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch

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

I'm not wed to my text. It's just to point out roughly where I'd expect content and roughly what I think is needed.

[SiaraMist]

Thanks for opening this @jsoref! I agree that we should add this information to the Workflow Syntax article as well.

I'd suggest adding a sentence to this section you linked that says something like:

This trigger only receives events when the workflow file is on the default branch.

You or anyone else is welcome to open a PR to add this information.

[huyz]

Is it true that the workflow needs to exist on the default branch?

It seems it's possible to trigger the registration of workflow_dispatch without touching the default branch. See https://stackoverflow.com/a/71057825/161972 and other answers.

Plus, when I click on the Run workflow button, I get to choose the workflow version by ref:

Maybe I'm misunderstanding and the distinction is between the existence of the workflow file vs. the workflow_dispatch trigger?

[nguyenalex836]

@huyz Hello! 👋 Your specific question would best be handled by our wonderful support team ✨ Please feel free to reach out to them for assistance!

If there's anything in the documents that you have suggestions for updating, please feel free to open an issue 💛