Skip to content

Behavior of branches filter on existing branches #42813

Open
Open
Behavior of branches filter on existing branches#42813
Labels
builder personacontentThis issue or pull request belongs to the Docs Content teamgithub_actionsPull requests that update GitHub Actions contentnever-staleDo not close as stale

Description

@vwheeler63
vwheeler63
opened on Feb 6, 2026

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:

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.

Activity

  1. vwheeler63
    added
    contentThis issue or pull request belongs to the Docs Content team
    on Feb 6, 2026

  2. welcome commented on Feb 6, 2026

    @welcome
    welcomebot
    on Feb 6, 2026 – with 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.

  3. github-actions
    added
    triageDo not begin working on this issue until triaged by the team
    on Feb 6, 2026

  4. vwheeler63 commented on Feb 6, 2026

    @vwheeler63
    vwheeler63
    on Feb 6, 2026
    Author

    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

  5. Sharra-writes commented on Feb 13, 2026

    @Sharra-writes
    Sharra-writes
    on Feb 13, 2026
    Contributor

    @vwheeler63 Thanks for letting us know! I'm going to have to check with our engineers and make sure this isn't a bug, but if it's working as intended, it does look like a caveat we would want to include.

  6. Sharra-writes
    added
    github_actionsPull requests that update GitHub Actions content
    and removed
    triageDo not begin working on this issue until triaged by the team
    on Feb 13, 2026

  7. vwheeler63 commented on Feb 14, 2026

    @vwheeler63
    vwheeler63
    on Feb 14, 2026
    Author

    @vwheeler63 Thanks for letting us know! I'm going to have to check with our engineers and make sure this isn't a bug, but if it's working as intended, it does look like a caveat we would want to include.

    Agreed! Looking forward to what the engineers have to say.

  8. github-actions commented on Mar 16, 2026

    @github-actions
    github-actionsbot
    on Mar 16, 2026 – with GitHub Actions
    Contributor

    A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.

  9. github-actions
    added
    InactiveWill be closed automatically by a stall check if no activity is detected.
    on Mar 16, 2026

  10. vwheeler63 commented on Mar 16, 2026

    @vwheeler63
    vwheeler63
    on Mar 16, 2026
    Author

    Not stale.

  11. Sharra-writes
    removed
    InactiveWill be closed automatically by a stall check if no activity is detected.
    on Mar 17, 2026

  12. github-actions commented on Apr 27, 2026

    @github-actions
    github-actionsbot
    on Apr 27, 2026 – with GitHub Actions
    Contributor

    A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.

  13. github-actions
    added
    InactiveWill be closed automatically by a stall check if no activity is detected.
    on Apr 27, 2026

  14. vwheeler63 commented on Apr 28, 2026

    @vwheeler63
    vwheeler63
    on Apr 28, 2026
    Author

    not stale

  15. Sharra-writes
    removed
    InactiveWill be closed automatically by a stall check if no activity is detected.
    on Apr 29, 2026

  16. github-actions commented on Sep 7, 2026

    @github-actions
    github-actionsbot
    on Sep 7, 2026 – with GitHub Actions
    Contributor

    A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.

  17. github-actions
    added
    InactiveWill be closed automatically by a stall check if no activity is detected.
    on Sep 7, 2026
  18. subatoi
    added
    never-staleDo not close as stale
    and removed
    InactiveWill be closed automatically by a stall check if no activity is detected.
    on Sep 8, 2026
  19. janiceilene
    added
    builder persona
    on Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    builder personacontentThis issue or pull request belongs to the Docs Content teamgithub_actionsPull requests that update GitHub Actions contentnever-staleDo not close as stale

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions