From ff400671d66dfd876b3a10c875a624051a7e5087 Mon Sep 17 00:00:00 2001 From: JulianMaurin Date: Tue, 23 Jun 2026 16:10:19 +0200 Subject: [PATCH 1/3] 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/3] 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/3] 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',