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

• Have a new workflow run from a PR (none main branch) before committing into main branch possible? community/community#25746 (reply in thread)

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.