From ff400671d66dfd876b3a10c875a624051a7e5087 Mon Sep 17 00:00:00 2001 From: JulianMaurin Date: Tue, 23 Jun 2026 16:10:19 +0200 Subject: [PATCH 1/5] docs(workflow): rebuild the overview into a product landing hub Replace the stub overview with a hub page matching the other products: a benefit-led intro, an annotated pull_request_rules example, the edge-triggering note, and DocsetGrid cards for the building blocks and the most-used actions. Render the title in the section accent via hubAccent. Co-Authored-By: Claude Opus 4.8 (1M context) Change-Id: I21f19283a7dc5eccb499e1d264b151d2366812c5 --- src/content/docs/workflow.mdx | 82 +++++++++++++++++++++++++++++------ 1 file changed, 68 insertions(+), 14 deletions(-) diff --git a/src/content/docs/workflow.mdx b/src/content/docs/workflow.mdx index 094aac76b4..9e5b6de9e5 100644 --- a/src/content/docs/workflow.mdx +++ b/src/content/docs/workflow.mdx @@ -1,30 +1,84 @@ --- title: Workflow Automation -description: An overview of Mergify Workflow Automation and its capabilities to automate your pull request process. +description: Automate the routine work on your pull requests with rules that react to a pull request's state to label, comment, assign, rebase, merge, and more. +hubAccent: true --- -Mergify Workflow Automation is a rule-based system that automates pull request -tasks using `pull_request_rules` in your Mergify configuration file. +import Docset from '~/components/DocsetGrid/Docset.astro'; +import DocsetGrid from '~/components/DocsetGrid/DocsetGrid.astro'; -## How It Works +Workflow Automation handles the routine work on your pull requests. You write +rules in your Mergify configuration file, and Mergify carries them out: labeling, +commenting, assigning, rebasing, merging, and more. Your team spends less time on +pull request housekeeping. -Mergify evaluates the state of a pull request rather than individual events. -This means it checks the current status of a pull request and acts based on -defined conditions. This behavior is known as "edge triggering." +## Anatomy of a Rule -An action will only be re-triggered for a pull request if the state flips back -from being unmatched to matched. +Every rule lives under `pull_request_rules` and pairs a set of **conditions** +with the **actions** to run when a pull request matches them: + +```yaml +pull_request_rules: + - name: add "WIP" label when the title contains "WIP" + conditions: + - title ~= WIP + actions: + label: + toggle: + - WIP +``` + +Here, any pull request whose title contains `WIP` gets the `WIP` label. Once the +title no longer matches, Mergify removes it. + +## How Rules Are Evaluated + +Mergify evaluates the *state* of a pull request rather than individual events. It +checks the current status of a pull request and acts based on the conditions you +defined. This behavior is known as "edge triggering": an action only re-runs for +a pull request when its state flips back from unmatched to matched. :::note Mergify never evaluates rules for pull request drafts it creates while processing the [merge queue](/merge-queue). ::: -## Reference +## Building Blocks -- [Rule Syntax](/workflow/rule-syntax) for the `pull_request_rules` format + + + The `pull_request_rules` format and how to structure a rule. + + + Match pull requests on title, labels, CI status, files, authorship, and more. + + + The full catalog of tasks Mergify can run when a rule matches. + + + Where rules live and how the overall config file is structured. + + -- [Actions](/workflow/actions) for the full list of available actions +## Popular Actions -- [Configuration File](/configuration/file-format) for the overall config - structure + + + Automate the merging of your pull requests. + + + Add the pull request to the merge queue. + + + Add, remove, or toggle labels on a pull request. + + + Post a comment on a pull request. + + + Copy a pull request to another branch once it is merged. + + + Rebase the pull request on top of its base branch. + + From b6fb0490f162b286bc8d24e03b896679059c5c31 Mon Sep 17 00:00:00 2001 From: JulianMaurin Date: Tue, 23 Jun 2026 16:10:19 +0200 Subject: [PATCH 2/5] docs(workflow): rewrite the Rule Syntax page as a real reference Replace the placeholder stub with a field-by-field reference: the pull_request_rules fields table, how conditions and actions compose, rule evaluation, disabling a rule, and local validation. The conceptual intro is left to the overview to avoid duplication. Co-Authored-By: Claude Opus 4.8 (1M context) Change-Id: I4fa35918e0f13360b29905f901ccb0a6ada88ecf --- src/content/docs/workflow/rule-syntax.mdx | 106 ++++++++++++++++++++-- 1 file changed, 98 insertions(+), 8 deletions(-) diff --git a/src/content/docs/workflow/rule-syntax.mdx b/src/content/docs/workflow/rule-syntax.mdx index 8246998af1..b2f107f6cb 100644 --- a/src/content/docs/workflow/rule-syntax.mdx +++ b/src/content/docs/workflow/rule-syntax.mdx @@ -1,13 +1,103 @@ --- title: Rule Syntax -description: Overview of the syntax used in Mergify rules for Workflow Automation and Merge Queue. +description: How to write a Mergify workflow rule, from the structure of pull_request_rules to its conditions and actions. --- -This page is a placeholder stub to consolidate references to configuration file -format, conditions, data types, and sharing configuration. +import OptionsTable from '~/components/Tables/OptionsTable'; -Use the existing reference pages for full details: -- [Configuration File Format](/configuration/file-format) -- [Conditions](/configuration/conditions) -- [Data Types](/configuration/data-types) -- [Sharing Configuration](/configuration/sharing) +Workflow Automation rules live under the `pull_request_rules` key in your +[configuration file](/configuration/file-format), where each rule pairs a set of +conditions with the actions Mergify runs when a pull request matches them. For a +gentle introduction, see the [Workflow Automation overview](/workflow). This +page is the field-by-field reference. + +## Fields + +`pull_request_rules` is a list, and each entry is a single rule: a YAML +dictionary where `name`, `conditions`, and `actions` are required, while +`description` and `disabled` are optional. + + + +## Conditions + +`conditions` is a list of expressions describing which pull requests the rule +applies to. A pull request must satisfy **every** condition in the list for the +rule to match: + +```yaml +conditions: + - base = main + - label = ready-to-merge +``` + +Each condition is built from an attribute (such as `base`, `label`, or +`#approved-reviews-by`), an operator (such as `=`, `>=`, or `~=`), and usually a +value. See the [attributes list](/configuration/conditions#attributes-list) and +[operators list](/configuration/conditions#operators-list) for the full set. + +To express "any of" or "none of" instead of "all of", group conditions with the +[`and`, `or`, and `not` operators](/configuration/conditions#combining-conditions-using-logical-operators). +The same condition syntax also powers [Merge Queue](/merge-queue) and +[Merge Protections](/merge-protections), so what you learn here carries over. + +## Actions + +`actions` is a dictionary that maps an action name to its parameters. A single +rule can run several actions, and Mergify runs them all when the conditions +match: + +```yaml +pull_request_rules: + - name: warn and label pull requests in conflict + conditions: + - conflict + actions: + comment: + message: "@{{author}} this pull request is now in conflict 😩" + label: + toggle: + - conflict +``` + +The `{{author}}` placeholder is a [template](/configuration/data-types#template) +that Mergify fills in with the pull request's data. Browse every available +action and its parameters in the [Actions catalog](/workflow/actions). + +## Combining Rules + +Rules are evaluated independently: Mergify checks each one against the pull +request, and every rule whose conditions match runs its actions. Order the rules +however reads best, since matching does not stop at the first hit. For when an +action re-runs versus stays put, see +[how rules are evaluated](/workflow#how-rules-are-evaluated). + +## Disabling a Rule + +Set `disabled` with a `reason` to keep a rule in the file but stop it from +running. The reason is shown in the configuration check so others know why: + +```yaml +pull_request_rules: + - name: automatic merge + disabled: + reason: paused during the release freeze + conditions: + - "#approved-reviews-by >= 1" + actions: + merge: # merge with default options +``` + +## Validating Your Rules + +Mergify validates your configuration on every push and reports problems in the +"Checks" tab of your pull request. To catch mistakes earlier, validate and +simulate rules locally with the [Mergify CLI](/cli/config): + +```bash +mergify config validate +mergify config simulate https://github.com/owner/repo/pull/142 +``` + +See [Validation and Troubleshooting](/configuration/file-format#validation-and-troubleshooting) +for the full workflow. From 3bf1ba108fefed3b0a7d719cff048ed5e182a43f Mon Sep 17 00:00:00 2001 From: JulianMaurin Date: Tue, 23 Jun 2026 16:10:19 +0200 Subject: [PATCH 3/5] docs(workflow): refresh the section navigation entries Rename the overview child from "Workflow Automation" to "Overview" to match the other products, and fix two stale action icons: Comment (list -> message-square) and Edit (type -> git-pull-request-draft, since the action only toggles draft state). Co-Authored-By: Claude Opus 4.8 (1M context) Change-Id: I34dd8408ab47eedd35fa2915f77ea82259e56f70 --- src/content/navItems.tsx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/content/navItems.tsx b/src/content/navItems.tsx index a6373101d2..9c613809ce 100644 --- a/src/content/navItems.tsx +++ b/src/content/navItems.tsx @@ -233,7 +233,7 @@ const navItems: NavItem[] = [ icon: 'lucide:zap', path: '/workflow', children: [ - { title: 'Workflow Automation', path: '/workflow/', icon: 'lucide:zap' }, + { title: 'Overview', path: '/workflow', icon: 'lucide:lightbulb' }, { title: 'Rule Syntax', path: '/workflow/rule-syntax', icon: 'lucide:badge-question-mark' }, { title: 'Actions', @@ -244,7 +244,7 @@ const navItems: NavItem[] = [ { title: 'Backport', path: '/workflow/actions/backport', icon: 'lucide:git-branch' }, { title: 'Close', path: '/workflow/actions/close', icon: 'lucide:circle-x' }, { title: 'Copy', path: '/workflow/actions/copy', icon: 'lucide:share-2' }, - { title: 'Comment', path: '/workflow/actions/comment', icon: 'lucide:list' }, + { title: 'Comment', path: '/workflow/actions/comment', icon: 'lucide:message-square' }, { title: 'Delete Head Branch (Deprecated)', path: '/workflow/actions/delete_head_branch', @@ -255,7 +255,11 @@ const navItems: NavItem[] = [ path: '/workflow/actions/dismiss_reviews', icon: 'lucide:message-square-x', }, - { title: 'Edit', path: '/workflow/actions/edit', icon: 'lucide:type' }, + { + title: 'Edit', + path: '/workflow/actions/edit', + icon: 'octicon:git-pull-request-draft-16', + }, { title: 'GitHub Actions', path: '/workflow/actions/github_actions', From 0a523fad0ad986f8abe203669a03118675cf6902 Mon Sep 17 00:00:00 2001 From: JulianMaurin Date: Tue, 23 Jun 2026 16:10:20 +0200 Subject: [PATCH 4/5] docs(workflow): align action descriptions and correct the edit action Make each action read identically across the actions index and its page frontmatter (copy, comment, label, queue) to match the overview cards. Correct the edit action: its config schema only exposes the draft state, so its card, description, and intro no longer claim it edits the body or title. Co-Authored-By: Claude Opus 4.8 (1M context) Change-Id: I935508fd79dc15c9e17350c8583bfbe534f18638 --- src/content/docs/workflow/actions.mdx | 10 +++++----- src/content/docs/workflow/actions/comment.mdx | 4 ++-- src/content/docs/workflow/actions/edit.mdx | 8 ++++---- src/content/docs/workflow/actions/label.mdx | 2 +- src/content/docs/workflow/actions/queue.mdx | 2 +- 5 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/content/docs/workflow/actions.mdx b/src/content/docs/workflow/actions.mdx index 3e4862ac42..a3028e00c1 100644 --- a/src/content/docs/workflow/actions.mdx +++ b/src/content/docs/workflow/actions.mdx @@ -28,10 +28,10 @@ management. Close a pull request. - Copy a pull request. + Copy a pull request to another branch. - Comment a pull request. + Post a comment on a pull request. Deprecated — use GitHub's built-in "Automatically delete head branches" setting instead. @@ -39,14 +39,14 @@ management. Dismiss previous reviews on a pull request. - - Edit pull request body, title or draft state. + + Convert a pull request to or from a draft. Dispatch an existing GitHub workflow in the repository. - Add, remove or toggle label on a pull request. + Add, remove, or toggle labels on a pull request. Automate the merging of your pull requests. diff --git a/src/content/docs/workflow/actions/comment.mdx b/src/content/docs/workflow/actions/comment.mdx index 9465ff8a12..23e1079f36 100644 --- a/src/content/docs/workflow/actions/comment.mdx +++ b/src/content/docs/workflow/actions/comment.mdx @@ -1,6 +1,6 @@ --- title: Comment -description: Comment a pull request. +description: Post a comment on a pull request. --- import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable'; @@ -15,7 +15,7 @@ your contributors. ## Parameters - + ## Examples diff --git a/src/content/docs/workflow/actions/edit.mdx b/src/content/docs/workflow/actions/edit.mdx index 22dfbdf337..6d4aeab6ce 100644 --- a/src/content/docs/workflow/actions/edit.mdx +++ b/src/content/docs/workflow/actions/edit.mdx @@ -1,13 +1,13 @@ --- title: Edit -description: Edit pull request attributes. +description: Convert a pull request to or from a draft. --- import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable'; -The `edit` action allows Mergify to edit the body of a pull request. This can -be helpful in situations where you want to automatically edit attributes -of the pull request. +The `edit` action lets Mergify change a pull request's draft state. This is +helpful when you want to automatically convert a pull request to or from a draft +based on its conditions. ## Parameters diff --git a/src/content/docs/workflow/actions/label.mdx b/src/content/docs/workflow/actions/label.mdx index 1dc4c1c484..cce9b6dd8e 100644 --- a/src/content/docs/workflow/actions/label.mdx +++ b/src/content/docs/workflow/actions/label.mdx @@ -1,6 +1,6 @@ --- title: Label -description: Add, remove and toggle labels on a pull request. +description: Add, remove, or toggle labels on a pull request. --- import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable'; diff --git a/src/content/docs/workflow/actions/queue.mdx b/src/content/docs/workflow/actions/queue.mdx index 51c4d7b429..e15f34c8b1 100644 --- a/src/content/docs/workflow/actions/queue.mdx +++ b/src/content/docs/workflow/actions/queue.mdx @@ -1,6 +1,6 @@ --- title: Queue -description: Put your pull request into the merge queue. +description: Add the pull request to the merge queue. --- import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable'; From b76c43bdbda8af1420775f5ff0ec5898055a8f1b Mon Sep 17 00:00:00 2001 From: JulianMaurin Date: Tue, 23 Jun 2026 16:10:20 +0200 Subject: [PATCH 5/5] docs(workflow): add examples to actions that lacked them Add an Examples section to dismiss_reviews, rebase, and request_reviews, each with a schema-checked pull_request_rules snippet, matching the pattern of the other action pages. Also normalize rebase's ActionOptionsTable quoting and fix a note typo. Co-Authored-By: Claude Opus 4.8 (1M context) Change-Id: I2e29d8269e3e8e9b1754f18b3d47332852275ee3 --- .../docs/workflow/actions/dismiss_reviews.mdx | 18 ++++++++++++++++ src/content/docs/workflow/actions/rebase.mdx | 21 +++++++++++++++++-- .../docs/workflow/actions/request_reviews.mdx | 18 ++++++++++++++++ 3 files changed, 55 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workflow/actions/dismiss_reviews.mdx b/src/content/docs/workflow/actions/dismiss_reviews.mdx index 927d4ff3f9..e945b0c2d8 100644 --- a/src/content/docs/workflow/actions/dismiss_reviews.mdx +++ b/src/content/docs/workflow/actions/dismiss_reviews.mdx @@ -13,3 +13,21 @@ reviews in your pull request workflow. ## Parameters + +## Examples + +### Dismiss Approvals When New Commits Are Pushed + +Keep approvals fresh by removing them whenever new commits are pushed, while +leaving change requests in place. + +```yaml +pull_request_rules: + - name: dismiss stale approvals + conditions: + - base = main + actions: + dismiss_reviews: + approved: true + changes_requested: false +``` diff --git a/src/content/docs/workflow/actions/rebase.mdx b/src/content/docs/workflow/actions/rebase.mdx index 6dec315824..12cf146bdd 100644 --- a/src/content/docs/workflow/actions/rebase.mdx +++ b/src/content/docs/workflow/actions/rebase.mdx @@ -11,7 +11,7 @@ up-to-date with the latest changes from the base branch. :::note You do not need to use this action if you use the [merge - queue](/merge-queue). The merge queue automatically update the pull requests + queue](/merge-queue). The merge queue automatically updates the pull requests it processes as necessary, making sure they are tested with up-to-date code before being merged. ::: @@ -25,4 +25,21 @@ up-to-date with the latest changes from the base branch. ## Parameters - + + +## Examples + +### Autosquash Fixup Commits + +Rebase a pull request and fold in any `fixup!`, `squash!`, or `amend!` commits +once it is ready to merge. + +```yaml +pull_request_rules: + - name: autosquash fixup commits + conditions: + - label = ready-to-merge + actions: + rebase: + autosquash: true +``` diff --git a/src/content/docs/workflow/actions/request_reviews.mdx b/src/content/docs/workflow/actions/request_reviews.mdx index 50d22e7919..de33ccc36f 100644 --- a/src/content/docs/workflow/actions/request_reviews.mdx +++ b/src/content/docs/workflow/actions/request_reviews.mdx @@ -16,3 +16,21 @@ certain pull requests. ## Parameters + +## Examples + +### Request a Review for Sensitive Files + +Ask the security team to review whenever a pull request changes files under +`security/`. + +```yaml +pull_request_rules: + - name: request a security review + conditions: + - files ~= ^security/ + actions: + request_reviews: + teams: + - security +```