docs: document branch filters for merge_group workflows (#43500)

Co-authored-by: hiromieguchi802-lab <270042125+hiromieguchi802-lab@users.noreply.github.com>
Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>

Author: hiromieguchi802-lab

content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md

@@ -384,14 +384,17 @@ on:
 
 Runs your workflow when a pull request is added to a merge queue, which adds the pull request to a merge group. For more information see [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request-with-a-merge-queue).
 
-For example, you can run a workflow when the `checks_requested` activity has occurred.
+You can use the `branches` or `branches-ignore` filter to configure your workflow to run only for merge groups that target specific branches. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onmerge_groupbranchesbranches-ignore).
+
+For example, the following workflow runs when the `checks_requested` activity occurs for a merge group that targets `main`.
 
 ```yaml
 on:
   pull_request:
-    branches: [ "main" ]
+    branches: [main]
   merge_group:
     types: [checks_requested]
+    branches: [main]
 ```
 
 ## `milestone`

content/actions/reference/workflows-and-actions/workflow-syntax.md

@@ -78,6 +78,68 @@ run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}
 
 {% data reusables.actions.workflows.triggering-workflow-branches4 %}
 
+## `on.merge_group.<branches|branches-ignore>`
+
+When using the `merge_group` event, you can configure a workflow to run only for merge groups that target specific branches.
+
+Use the `branches` filter when you want to include branch name patterns or when you want to both include and exclude branch name patterns. Use `branches-ignore` when you only want to exclude branch name patterns. You cannot use both `branches` and `branches-ignore` for the same event in a workflow.
+
+The `branches` and `branches-ignore` filters accept glob patterns that use characters like `*`, `**`, `+`, `?`, `!` and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with `\`. For more information about glob patterns, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet).
+
+### Example: Including branches
+
+The patterns defined in `branches` are evaluated against the target branch's name. For example, the following workflow will run whenever there is a `merge_group` event for a merge group that targets:
+
+* A branch named `main`
+* A branch whose name starts with `releases/`
+
+```yaml
+on:
+  merge_group:
+    types: [checks_requested]
+    branches:
+      - main
+      - 'releases/**'
+```
+
+### Example: Excluding branches
+
+When a pattern matches the `branches-ignore` pattern, the workflow will not run. The patterns defined in `branches-ignore` are evaluated against the target branch's name. For example, the following workflow will run whenever there is a `merge_group` event unless the merge group targets:
+
+* A branch named `canary`
+* A branch whose name matches `releases/**-alpha`, like `releases/beta/3-alpha` <!-- markdownlint-disable-line outdated-release-phase-terminology -->
+
+```yaml
+on:
+  merge_group:
+    types: [checks_requested]
+    branches-ignore:
+      - canary
+      - 'releases/**-alpha'
+```
+
+### Example: Including and excluding branches
+
+You cannot use `branches` and `branches-ignore` to filter the same event in a single workflow. If you want to both include and exclude branch patterns for a single event, use the `branches` filter along with the `!` character to indicate which branches should be excluded.
+
+If you define a branch with the `!` character, you must also define at least one branch without the `!` character. If you only want to exclude branches, use `branches-ignore` instead.
+
+The order that you define patterns matters.
+
+* A matching negative pattern (prefixed with `!`) after a positive match will exclude the branch.
+* A matching positive pattern after a negative match will include the branch again.
+
+The following workflow will run on `merge_group` events for merge groups that target `releases/10` or `releases/beta/mona`, but not for merge groups that target `releases/10-alpha` or `releases/beta/3-alpha` because the negative pattern `!releases/**-alpha` follows the positive pattern. <!-- markdownlint-disable-line outdated-release-phase-terminology -->
+
+```yaml
+on:
+  merge_group:
+    types: [checks_requested]
+    branches:
+      - 'releases/**'
+      - '!releases/**-alpha'
+```
+
 ## `on.push.<branches|tags|branches-ignore|tags-ignore>`
 
 {% data reusables.actions.workflows.run-on-specific-branches-or-tags1 %}