on.<push|pull-request>.<branches|branches-ignore>

1 minute read
On this page

Use the branches filter to configure a workflow to run on specific branches.

  • To include any branch names or name patterns, specify them in branches.

  • To exclude any branch names or name patterns, specify them in branches-ignore.

branches and branches-ignore filtering specifications:

  • Match more than one branch with name patterns:

    • branches and branches-ignore accept special characters such as , *, +, ?, and !.

    • If you want a literal match, and your branch name contains a special character, you must escape it with \ for the match to work.

  • You cannot use branches and branches-ignore for the same event in a workflow.

    • Instead, use a negative pattern (the special character ! before the branch name or pattern) to indicate excluded branches.

    • In the case of a matching positive and negative pattern for the same event, the last evaluated pattern takes precedence.

Example usage

In the following example, repository Git refs are evaluated according to the filter. Because branches and branches-ignore filtering cannot be used for the same event in a workflow, the special character ! is used to exclude branches.

  • The workflow is triggered whenever there is a push event to:

    • A branch named main (refs/heads/main).

    • A branch named example/branch-1 (refs/heads/example/branch-1).

    • A branch whose name matches example/**/test, such as example/dev/test.

  • The workflow is not triggered whenever there is a push event to:

    • A branch named example/branch-3 (refs/heads/example/branch-3) due to the matching negative pattern '!example/**-3'.

    • A branch named example/branch-2 (refs/heads/example/branch-2), because the matching negative pattern '!example/**-2' is evaluated after the positive match.

on:
  push:
    branches:
      - main
      - 'example/branch-1'
      - 'example/**-2'
      - 'example/**/test'
      - '!example/branch-3'
      - '!example/**-2'