Behavior of `branches` filter on existing branches

[vwheeler63]

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/reference/workflows-and-actions/workflow-syntax

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

These to parts that describe using a branches filter:

• on.<pull_request|pull_request_target>.<branches|branches-ignore>
• on.push.<branches|tags|branches-ignore|tags-ignore>

Additional information

I just lost about 5 hours trying a large variety of variations and reviewing the docs related to branches filters on GitHub Actions. Here is what I discovered, and I believe this important fact is nowhere in the docs and should be:

    When a workflow is put in place that has a `branches` filter, or modified
    to add additional branches to an existing `branches` filter, any matching
    branches that already existed PRIOR to this modification are NOT eligible
    to trigger the workflow.

    Only new branches added AFTER the workflow is in place, with matching
    branch names, can trigger the workflow.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[vwheeler63]

Additional Details:

It is evident that the master branch is an exception to this. Details:

I had an existing branch named docs/doc-build-test with a workflow starting with this:

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

Then I added this additional item to the branches filter: - 'docs/*' to make it:

on:
  push:
    branches:
      - master
      - 'release/*'
      - 'docs/*'

and NOTHING I did on the existing docs/doc-build-test branch triggered the workflow. On a hunch I tried changes on a branch docs/doc_build_test_2 (using underscores) and that worked exactly as predicted, and finally, I deleted the original docs/doc-build-test branch and created a new one from the current master branch with the exact same name AFTER the workflow update was in place, and THEN AND ONLY THEN did changes on that branch trigger the workflow.

My conclusion was that the branch is flagged as eligible upon branch creation based on existing workflows, not as a result of adding or modifying the workflow. Whether this is a correct conclusion or not, I don't know. But now you have the details.

If my conclusion was correct, then I can only guess that the master (or default) branch is somehow excluded from this.

Kind regards,
Vic