diff --git a/package-lock.json b/package-lock.json index 7db453884e..88e4f023e7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2822,6 +2822,18 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/@nodable/entities": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-1.1.0.tgz", + "integrity": "sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/nodable" + } + ], + "license": "MIT" + }, "node_modules/@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -6200,9 +6212,9 @@ } }, "node_modules/cheerio/node_modules/undici": { - "version": "7.24.5", - "resolved": "https://registry.npmjs.org/undici/-/undici-7.24.5.tgz", - "integrity": "sha512-3IWdCpjgxp15CbJnsi/Y9TCDE7HWVN19j1hmzVhoAkY/+CJx449tVxT5wZc1Gwg8J+P0LWvzlBzxYRnHJ+1i7Q==", + "version": "7.25.0", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.25.0.tgz", + "integrity": "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ==", "license": "MIT", "engines": { "node": ">=20.18.1" @@ -6769,9 +6781,9 @@ } }, "node_modules/defu": { - "version": "6.1.6", - "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.6.tgz", - "integrity": "sha512-f8mefEW4WIVg4LckePx3mALjQSPQgFlg9U8yaPdlsbdYcHQyj9n2zL2LJEA52smeYxOvmd/nB7TpMtHGMTHcug==", + "version": "6.1.7", + "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.7.tgz", + "integrity": "sha512-7z22QmUWiQ/2d0KkdYmANbRUVABpZ9SNYyH5vx6PZ+nE5bcC0l7uFvEfHlyld/HcGBFTL536ClDt3DEcSlEJAQ==", "license": "MIT" }, "node_modules/dequal": { @@ -8078,9 +8090,9 @@ } }, "node_modules/fast-xml-parser": { - "version": "5.5.12", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.5.12.tgz", - "integrity": "sha512-nUR0q8PPfoA/svPM43Gup7vLOZWppaNrYgGmrVqrAVJa7cOH4hMG6FX9M4mQ8dZA1/ObGZHzES7Ed88hxEBSJg==", + "version": "5.6.0", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.6.0.tgz", + "integrity": "sha512-5G+uaEBbOm9M4dgMOV3K/rBzfUNGqGqoUTaYJM3hBwM8t71w07gxLQZoTsjkY8FtfjabqgQHEkeIySBDYeBmJw==", "funding": [ { "type": "github", @@ -8089,6 +8101,7 @@ ], "license": "MIT", "dependencies": { + "@nodable/entities": "^1.1.0", "fast-xml-builder": "^1.1.4", "path-expression-matcher": "^1.5.0", "strnum": "^2.2.3" @@ -9984,9 +9997,9 @@ } }, "node_modules/linkinator/node_modules/undici": { - "version": "7.24.5", - "resolved": "https://registry.npmjs.org/undici/-/undici-7.24.5.tgz", - "integrity": "sha512-3IWdCpjgxp15CbJnsi/Y9TCDE7HWVN19j1hmzVhoAkY/+CJx449tVxT5wZc1Gwg8J+P0LWvzlBzxYRnHJ+1i7Q==", + "version": "7.25.0", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.25.0.tgz", + "integrity": "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ==", "dev": true, "license": "MIT", "engines": { @@ -15636,9 +15649,9 @@ "license": "MIT" }, "node_modules/undici": { - "version": "6.24.1", - "resolved": "https://registry.npmjs.org/undici/-/undici-6.24.1.tgz", - "integrity": "sha512-sC+b0tB1whOCzbtlx20fx3WgCXwkW627p4EA9uM+/tNNPkSS+eSEld6pAs9nDv7WbY1UUljBMYPtu9BCOrCWKA==", + "version": "6.25.0", + "resolved": "https://registry.npmjs.org/undici/-/undici-6.25.0.tgz", + "integrity": "sha512-ZgpWDC5gmNiuY9CnLVXEH8rl50xhRCuLNA97fAUnKi8RRuV4E6KG31pDTsLVUKnohJE0I3XDrTeEydAXRw47xg==", "dev": true, "license": "MIT", "engines": { diff --git a/src/content/docs/integrations/dependabot.mdx b/src/content/docs/integrations/dependabot.mdx index d87868ea5f..49d3d52ae0 100644 --- a/src/content/docs/integrations/dependabot.mdx +++ b/src/content/docs/integrations/dependabot.mdx @@ -19,19 +19,17 @@ intervention. There are two primary ways to automate the merging of Dependabot PRs with Mergify: -### 1. Direct Merge or Merge Queue +### 1. Using the Merge Queue -You can set up a pull request rule to automatically merge Dependabot PRs or -place them in the merge queue. +You can set up a queue rule to automatically enqueue Dependabot PRs into the +merge queue using [`autoqueue`](/merge-queue/rules#autoqueueing-pull-requests). ```yaml -pull_request_rules: - - name: Automatically merge Dependabot PRs - conditions: +queue_rules: + - name: default + autoqueue: true + queue_conditions: - author = dependabot[bot] - actions: - merge: - # Or use queue: to use the merge queue ``` ### 2. PR Approval @@ -53,19 +51,18 @@ pull_request_rules: Dependabot provides specific labels for the type of dependency update, such as `dependabot-dependency-name`, `dependabot-dependency-type`, and -`dependabot-update-type`. You can use these labels in your Mergify rules to +`dependabot-update-type`. You can use these in your queue rule conditions to filter which Dependabot PRs to auto-merge. For instance, you might only want to auto-merge minor version bumps: ```yaml -pull_request_rules: - - name: Auto merge minor version bumps - conditions: +queue_rules: + - name: default + autoqueue: true + merge_method: merge + queue_conditions: - author = dependabot[bot] - dependabot-update-type = version-update:semver-minor - actions: - queue: - method: merge ``` ## Batching Dependency Updates @@ -81,18 +78,12 @@ For example, you could set up a merge queue to batch those PRs 10 by 10: queue_rules: # If you have other queue rules defined, add this at the end so it is processed last - name: dep-update + autoqueue: true batch_size: 10 # Wait for up to 30 minutes for the batch to fill up batch_max_wait_time: 30 min queue_conditions: - author = dependabot[bot] - -pull_request_rules: - - name: Automatically queue Dependabot PRs - conditions: - - author = dependabot[bot] - actions: - queue: ``` ## Disable Dependabot's Automatic Rebase diff --git a/src/content/docs/integrations/renovate.mdx b/src/content/docs/integrations/renovate.mdx index f772c84c0d..1e895929f9 100644 --- a/src/content/docs/integrations/renovate.mdx +++ b/src/content/docs/integrations/renovate.mdx @@ -17,19 +17,17 @@ submits automated pull requests. There are two primary ways to automate the merging of Renovate PRs with Mergify: -### 1. Direct Merge or Merge Queue +### 1. Using the Merge Queue -You can set up a pull request rule to automatically merge Renovate PRs or -place them in the merge queue. +You can set up a queue rule to automatically enqueue Renovate PRs into the +merge queue using [`autoqueue`](/merge-queue/rules#autoqueueing-pull-requests). ```yaml -pull_request_rules: - - name: Automatically merge Renovate PRs - conditions: +queue_rules: + - name: default + autoqueue: true + queue_conditions: - author = renovate[bot] - actions: - merge: - # Or use queue: to use the merge queue ``` ### 2. PR Approval @@ -60,18 +58,12 @@ For example, you could set up a merge queue to batch those PRs 10 by 10: queue_rules: # If you have other queues defined, add this at the end so it is processed last - name: dep-update + autoqueue: true batch_size: 10 # Wait for up to 30 minutes for the batch to fill up batch_max_wait_time: 30 min queue_conditions: - author = renovate[bot] - -pull_request_rules: - - name: Automatically queue Renovate PRs - conditions: - - author = renovate[bot] - actions: - queue: ``` With Mergify and Renovate working together, you can ensure your project's diff --git a/src/content/docs/integrations/snyk.mdx b/src/content/docs/integrations/snyk.mdx index e87cfffed7..6fe218199a 100644 --- a/src/content/docs/integrations/snyk.mdx +++ b/src/content/docs/integrations/snyk.mdx @@ -59,18 +59,18 @@ allowing for a thorough review. file](/configuration/file-format) file in the repository root. ```yaml - pull_request_rules: - - name: Automatic merge Snyk PRs on Status Checks passing - conditions: + queue_rules: + - name: default + autoqueue: true + merge_method: merge + queue_conditions: - author = snyk-bot - base = main - actions: - merge: - method: merge ``` - This configuration ensures that Snyk PRs are automatically merged when - they meet the defined conditions. + This configuration uses [`autoqueue`](/merge-queue/rules#autoqueueing-pull-requests) + to automatically enqueue and merge Snyk PRs when they meet the defined + conditions. ## Batching Dependency Updates @@ -86,18 +86,12 @@ For example, you could set up a merge queue to batch those PRs 10 by 10: queue_rules: # If you have other queue rules defined, add this at the end so it is processed last - name: dep-update + autoqueue: true batch_size: 10 # Wait for up to 30 minutes for the batch to fill up batch_max_wait_time: 30 min queue_conditions: - author = snyk-bot - -pull_request_rules: - - name: Automatically queue Snyk PRs - conditions: - - author = snyk-bot - actions: - queue: ``` ## Tips for Efficient Dependency Upgrades diff --git a/src/content/docs/migrate/bulldozer.mdx b/src/content/docs/migrate/bulldozer.mdx index bd5daabbe6..9555ae9017 100644 --- a/src/content/docs/migrate/bulldozer.mdx +++ b/src/content/docs/migrate/bulldozer.mdx @@ -1,30 +1,31 @@ --- title: Migrate from Bulldozer to Mergify -description: Map Bulldozer configuration and behaviors to Mergify rules and merge queue. +description: Move from Bulldozer automerge to Mergify's Merge Queue for safer, faster merges. --- [Bulldozer](https://github.com/palantir/bulldozer) focuses on automerging pull -requests based on labels, reviews, and status checks. Mergify covers that and -more, with a powerful rule engine and a production‑grade merge queue. +requests based on labels, reviews, and status checks. Mergify's [Merge +Queue](/merge-queue) covers that and more, with automatic PR updates, +prioritization, batching, and parallel checks. -This page shows a practical, minimal‑diff path to move from Bulldozer to -Mergify. +This page shows a practical path to move from Bulldozer to Mergify's Merge +Queue. :::tip[Need help?] -We’ve migrated many teams from Bulldozer. [Reach -out](mailto:support@mergify.com) and we’ll review your Bulldozer configuration +We've migrated many teams from Bulldozer. [Reach +out](mailto:support@mergify.com) and we'll review your Bulldozer configuration and propose an equivalent Mergify setup. ::: ## Typical Migration Plan -1. Keep your labels and branch protections as‑is -2. Translate Bulldozer settings to one or two Mergify rules -3. Start with a dry‑run or low‑impact setup and expand gradually +1. Keep your labels and branch protections as-is +2. Set up a Mergify merge queue with conditions matching your Bulldozer config +3. Start with a low-impact setup and expand gradually -## Common Bulldozer config → Mergify +## Common Bulldozer config → Mergify Merge Queue Example Bulldozer snippet: @@ -38,59 +39,49 @@ merge: - "ci/circleci: ete-tests" ``` -Equivalent Mergify: +Equivalent Mergify merge queue: ```yaml title=.mergify.yml -pull_request_rules: - - name: Automerge when ready - conditions: +queue_rules: + - name: default + merge_method: squash + autoqueue: true + queue_conditions: + - base = main - label = merge when ready - head ~= ^feature/ - "check-success = ci/circleci: ete-tests" - actions: - merge: - method: squash ``` Notes: - Checks map to `check-success = ` (or `check-skipped`, `check-neutral`) - Required labels map to `label = ` conditions - Approvals map to review count or specific reviewers +- The merge queue keeps PRs updated automatically — no manual rebases needed -## Enabling the Merge Queue (optional but recommended) - -If you rely on Bulldozer plus manual rebases to keep PRs up‑to‑date, [Mergify’s -Merge Queue](/merge-queue) removes that toil — with even more optimizations. +## Going Further with Merge Queue -Add a queue rule and switch to queueing instead of immediate merge: +Once you have basic automerge working, you can take advantage of features +Bulldozer doesn't offer: -```yaml title=.mergify.yml -queue_rules: - - name: default - autoqueue: true - queue_conditions: - - base = main - - check-success = ci -``` +- [Priorities](/merge-queue/priority) — urgent PRs jump ahead in the queue -- The queue keeps PRs updated and merges them only after passing on the latest - version of the base branch +- [Batches](/merge-queue/batches) — merge multiple PRs at once to reduce CI + load -- You can set [priorities](/merge-queue/priority), - [batches](/merge-queue/batches), and [parallel - checks](/merge-queue/parallel-checks) later +- [Parallel checks](/merge-queue/parallel-checks) — test multiple queue + entries simultaneously ## Feature parity quick table -- Merge methods: squash/merge/rebase → supported +- Merge methods: squash/merge/rebase → supported via `merge_method` -- Delete branch after merge → [`delete_head_branch` - action](/workflow/actions/delete_head_branch) +- Delete branch after merge → use GitHub's "Automatically delete head branches" + repository setting -- Rebase/update before merge → - [`rebase`](/workflow/actions/rebase)/[`update`](/workflow/actions/update) - actions or merge queue `update_method` +- Rebase/update before merge → automatic in merge queue -- Require labels → conditions `label = ` +- Require labels → `label =` in `queue_conditions` -- Restrict by authors/paths → conditions `author =`, `files ~=`, etc. +- Restrict by authors/paths → `author =`, `files ~=`, etc. in + `queue_conditions` diff --git a/src/content/docs/workflow.mdx b/src/content/docs/workflow.mdx index 38dd523570..094aac76b4 100644 --- a/src/content/docs/workflow.mdx +++ b/src/content/docs/workflow.mdx @@ -1,90 +1,30 @@ --- -title: Introducing Mergify Workflow Automation -description: An overview of Mergify Workflow Automation and its capabilities to supercharge your pull request process. +title: Workflow Automation +description: An overview of Mergify Workflow Automation and its capabilities to automate your pull request process. --- -Mergify Workflow Automation is a sophisticated system designed to revolutionize -your pull request process. It empowers development teams to automate tasks and -processes using a rule-based approach. This ensures efficiency, consistency, -and adherence to project standards. +Mergify Workflow Automation is a rule-based system that automates pull request +tasks using `pull_request_rules` in your Mergify configuration file. -## Why Use Mergify Workflow Automation? - -1. **Automate Repetitive Tasks**: Frequent tasks such as labeling, assigning, - or merging pull requests can be automated, freeing up developers to focus on - code and innovative solutions. - -2. **Consistent Standards**: Ensure that each pull request adheres to your - project's guidelines, with automated checks and balances in place. - -3. **Flexible and Powerful**: The system is based on rules that you define, - offering flexibility to cater to your project's unique needs. - -4. **Real-time Feedback**: Instantly inform contributors about the status of - their pull requests, ensuring clarity and quick response times. - -5. **Easier On-boarding**: Make it easy for any developer to understand your - repository rules by crafting your rules in an easy-to-read YAML format. - -## State-Based, Edge-Triggered System +## How It Works 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." -An action will only by re-triggered for a pull request if the state flips back +An action will only be re-triggered for a pull request if the state flips back from being unmatched to matched. -For instance, consider a rule that specifies a pull request should be merged if -it has at least two approved reviews and all CI checks pass. Even if the second -approval and CI success come at different times, Mergify will act once the -entire state of the pull request matches the rule. - -```yaml -pull_request_rules: - - name: merge automatically when CI passes and PR is approved - conditions: - - "#approved-reviews-by >= 2" - - check-success = my-favorite-ci - actions: - merge: -``` - -On the other hand, a rule that posts a comment when a pull request is in -conflict with its base branch will only be triggered when the pull request -becomes in conflict, or when it becomes in conflict again — not every push to -its base branch. - -```yaml -pull_request_rules: - - name: merge automatically when CI passes and PR is approved - conditions: - - conflict - actions: - comment: - message: Your PR is in conflict, {{author}}. You should fix it. -``` - -This makes sure the system does not *spam* the pull request. - :::note -Mergify never evaluates rules for pull request drafts it creates to + Mergify never evaluates rules for pull request drafts it creates while processing the [merge queue](/merge-queue). ::: -## Getting Started +## Reference -To begin with Mergify, you'll need to [setup Mergify on your GitHub -repository](/integrations/github). You can then [set up rules for your -repository](writing-your-first-rule). +- [Rule Syntax](/workflow/rule-syntax) for the `pull_request_rules` format -Each rule will contain conditions (e.g., pull request state, number of reviews) -and actions (e.g., merge, label). When a pull request meets the conditions of a -rule, the specified actions are automatically executed. +- [Actions](/workflow/actions) for the full list of available actions -Mergify Workflow Automation is more than just a tool – it's a game changer for -developers and teams who seek efficiency, consistency, and automation in their -pull request process. By introducing state-based, edge-triggered rules, Mergify -provides unparalleled control over your project's workflows. Dive in, set up -your first rule, and experience the transformation firsthand. +- [Configuration File](/configuration/file-format) for the overall config + structure diff --git a/src/content/docs/workflow/actions/dismiss_reviews.mdx b/src/content/docs/workflow/actions/dismiss_reviews.mdx index dc167238cd..927d4ff3f9 100644 --- a/src/content/docs/workflow/actions/dismiss_reviews.mdx +++ b/src/content/docs/workflow/actions/dismiss_reviews.mdx @@ -3,7 +3,6 @@ title: Dismiss Reviews description: Dismiss previous reviews on a pull request. --- -import Button from '../../../../components/Button.astro'; import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable'; The `dismiss_reviews` action allows Mergify to automatically dismiss approved @@ -14,9 +13,3 @@ reviews in your pull request workflow. ## Parameters - -## Examples - - diff --git a/src/content/docs/workflow/actions/rebase.mdx b/src/content/docs/workflow/actions/rebase.mdx index bbd408a76d..6dec315824 100644 --- a/src/content/docs/workflow/actions/rebase.mdx +++ b/src/content/docs/workflow/actions/rebase.mdx @@ -4,7 +4,6 @@ description: Rebase the pull request on top of its base branch. --- import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable' -import Button from '../../../../components/Button.astro'; The `rebase` action makes Mergify rebase the pull request on top of its base branch. This is useful when you want to ensure that your pull request is always @@ -27,9 +26,3 @@ up-to-date with the latest changes from the base branch. ## Parameters - -## Examples - - diff --git a/src/content/docs/workflow/actions/request_reviews.mdx b/src/content/docs/workflow/actions/request_reviews.mdx index a3bce33c80..50d22e7919 100644 --- a/src/content/docs/workflow/actions/request_reviews.mdx +++ b/src/content/docs/workflow/actions/request_reviews.mdx @@ -4,7 +4,6 @@ description: Request reviews from specific users or teams. --- import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable' -import Button from '../../../../components/Button.astro'; The `request_reviews` action lets Mergify request reviews from specified users or teams. This is useful when you want to ensure specific team members review @@ -17,12 +16,3 @@ certain pull requests. ## Parameters - -## Use Cases - -There are plenty of possibilities for the request reviews action. Read below to -discover them. - - diff --git a/src/content/docs/workflow/automerge.mdx b/src/content/docs/workflow/automerge.mdx deleted file mode 100644 index 683984490e..0000000000 --- a/src/content/docs/workflow/automerge.mdx +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: Setting Up Automatic Merges -description: Learn how to automate your pull request merges with Mergify. ---- - -Mergify's automatic merging is a powerful feature designed to help maintainers -save time and keep their repositories up-to-date efficiently. It automates the -process of merging pull requests (PRs) once they meet your specified -conditions, thereby reducing the need for manual intervention. - -This capability is particularly beneficial in scenarios where numerous PRs are -regularly opened, such as in open-source projects or in teams practicing -continuous integration. By utilizing automatic merging, you can ensure that PRs -get merged promptly once they're ready, helping to maintain a smooth and -fast-paced development workflow. - -## Pre-requisites - -Before setting up automatic merges, ensure you meet the following requirements: - -1. **Mergify Integration**: Your repository must be [configured with - Mergify](/integrations/github). - -2. **Mergify Configuration File**: Automatic merging is configured using a - [configuration file](/configuration/file-format) in your repository. This - file contains the rules and actions Mergify will follow, including the - conditions for automatic merging. - -3. **Branch Protection Rules**: Review any [branch protection - rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) - that might prevent automatic merging. For example, make sure that required - status checks are configured correctly and that they pass before Mergify - tries to merge your PRs. - -## Setting Up Automatic Merging - -To enable automatic merging in a Mergify-powered repository, follow these -steps: - -1. **Create or Edit the Mergify Configuration File**: Navigate to your - repository and create or open the [Mergify configuration - file](/configuration/file-format). This file is where you define all your - Mergify rules. - -2. **Define a Pull Request Rule for Merging**: In the configuration file, you - will need to create a rule that tells Mergify when to automatically merge a - pull request. Here's an example of a basic rule: - - ```yaml - pull_request_rules: - - name: Automatic merge when CI passes and reviews approve - conditions: - - "#approved-reviews-by >= 1" - - check-success = CI # replace "CI" with the name of your CI status check - actions: - merge: - method: merge - ``` - - In this example, a pull request is automatically merged when it has at - least one approved review and the CI status check passes. - - :::note - Any merge conditions defined in your branch protection settings do not need - to be repeated here. Mergify automatically injects branch protection - settings in the conditions. - ::: - -3. **Customize Your Merge Action**: The `merge` action in the rule can be - customized further. You can specify the `method` to use for merging - (`merge`, `rebase`, or `squash`), or specify commit message options. Check - the [merge action](/workflow/actions/merge/) documentation for more - information on these options. - -4. **Save and Commit Your Changes**: Once you've added and customized your - merge rule, commit the changes to your configuration file and push it to - your repository. We recommend merging it via a pull request so Mergify can - validate the configuration file. - -With these settings, Mergify will automatically merge eligible pull requests -based on the conditions you've specified. - -## Validating All Status Checks - -A common condition is to require that "every status check (CI) passes" — -especially before executing the [merge](/workflow/actions/merge) or adding a -pull request to a [queue](/merge-queue/lifecycle). - -:::danger -There is no such thing as "every status check" in GitHub. -::: - -Here's why: - -1. Each pull request can have its own custom list of status checks. This means - the list of "status check" **does not exist** and is not common to all pull - requests. - -2. On creation, or when a new commit is pushed, a pull request has **no** - status check. - -3. A status check might not be reported by a service (CI) (e.g., because it's - broken) and therefore be absent. - -Those three facts make it **mandatory** to write explicitly the checks that are -expected for your condition to be valid. Therefore you must list explicitly -every status check that is expected, e.g.: - -```yaml -conditions: - - check-success = build: Windows - - check-success = build: Linux -``` - -**Do not** use conditions such as: - -- `#check-failure = 0`, because this will be true as soon as the pull request - is created and before any service report its status (see point 2. above). - -- `check-success ~= build` while expecting this to wait for "all" status checks - that have `build` in their name (see point 1. and 2.above). - -Such conditions won't do what you want them to do. - -## Restricting Automatic Merges - -In some cases, you might want to restrict automatic merges based on certain -conditions. This can be useful to enforce code quality standards, ensure all -necessary checks have passed, or prevent merging of pull requests that do not -meet certain criteria. Here's how you can set this up: - -1. **Specify the Restrictive Conditions**: In your pull request rule, you can - specify conditions that a pull request must meet before it can be merged. - This can include anything from passing status checks to having a certain - number of approved reviews. - - Here's an example that restricts automatic merging to pull requests that - have at least two approved reviews and all status checks passing: - - ```yaml - pull_request_rules: - - name: Automatic merge when CI passes and reviews approve - conditions: - - "#approved-reviews-by >= 2" - - check-success = CI # replace "CI" with the name of your CI status check - actions: - merge: - method: merge - ``` - -2. **Use Negative Conditions**: You can also use negative conditions to prevent - automatic merging. For instance, you might want to prevent merging if - certain labels are present. Here's an example: - - ```yaml - pull_request_rules: - - name: Automatic merge when CI passes and reviews approve, unless 'do-not-merge' label is present - conditions: - - "#approved-reviews-by >= 2" - - check-success = CI # replace "CI" with the name of your CI status check - - label != do-not-merge - actions: - merge: - method: merge - ``` - - In this case, the `label!=do-not-merge` condition prevents automatic - merging if the `do-not-merge` label is attached to the pull request. - -Remember, conditions are highly flexible and can be adapted to suit your -project's specific needs. For a full list of available conditions, refer to the -[conditions documentation](/configuration/conditions). - -## Automatic Merge and Queues - -When automatic merging is enabled, pull requests are merged as soon as all the -conditions specified in your rule are met. In the context of [Mergify's Merge -Queue](/merge-queue), automatic merge works in tandem with the prioritization -and organization that queues offer. You can leverage the [queue -action](/workflow/actions/queue) to put pull requests in the merge queue rather -than merging directly. - -Here's an example of how this might look in your Mergify configuration file: - -```yaml -pull_request_rules: - - name: Automatic merge when CI passes and reviews approve - conditions: - - "#approved-reviews-by >= 2" - - check-success = CI # replace "CI" with the name of your CI status check - actions: - queue: - merge_method: merge -``` - -In this case, when a pull request meets the conditions -(`#approved-reviews-by >= 2` and `check-success = CI`), it is added to the merge -queue. Once it's at the front of the queue, Mergify will automatically merge it -into the target branch and then move on to the next pull request in the queue. - -This combination of queues and automatic merging allows for a more efficient -and organized way of managing your pull requests, ensuring that pull requests -are merged in a timely and prioritized manner. diff --git a/src/content/docs/workflow/dismiss-reviews.mdx b/src/content/docs/workflow/dismiss-reviews.mdx deleted file mode 100644 index ea60943fb9..0000000000 --- a/src/content/docs/workflow/dismiss-reviews.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Dismiss Reviews -description: Optimize your pull request workflow, tailoring review dismissal to specific scenarios and users. ---- - -Keeping your reviews up to date is essential to maintain a coherent and -reliable development workflow. Mergify offers a granular approach with the -[`dismiss_reviews`](/workflow/actions/dismiss_reviews) action. - -1. **Conditional Triggers**: Only dismiss reviews when specific conditions on - the pull request are met. - -2. **Selective Removal**: Choose to remove only approvals, only reviews from - particular users, or only changes requested. - -3. **Targeted Dismissal**: Dismiss reviews only from users that are in the - requested reviewers list. - -4. **Event-driven**: Opt to have the action run when a PR is pushed again or - keep it active continuously. - -There are multiple scenarios where you can use this action to automatically -remove change requests or approvals. - -## Re-Review on Push - -Automatically dismiss reviews when new commits are pushed to a PR targeting the -main branch with a "re-review" label: - -```yaml -pull_request_rules: - - name: dismiss reviews when new commits are pushed, if the label "re-review" is present - conditions: - - base = main - - label = re-review - actions: - dismiss_reviews: -``` - -## Team-based Review Dismissal - -Retain the approvals if the author is from a trusted team, even if they update -their code: - -```yaml -pull_request_rules: - - name: remove outdated reviews for non trusted authors - conditions: - - base = main - - author != @mytrustedteam - actions: - dismiss_reviews: -``` - -## Specific User-based Review Dismissal - -Dismiss reviews from specific users, which can be useful if you have a bot user -or a particular reviewer whose comments might not be relevant upon code -changes: - -```yaml -pull_request_rules: - - name: remove reviews from the bot when the PR is updated - conditions: - - base = main - actions: - dismiss_reviews: - approved: - - mybotusername - changes_requested: - - mybotusername -``` - -## Dismiss Reviews When Request Review - -When a user request a new review from a reviewer, asking for a review does not -dismiss the current review from the reviewer. You can do that using this -snippet: - -```yaml -pull_request_rules: - - name: dismiss reviews when review is requested - conditions: - - base = main - actions: - dismiss_reviews: - approved: from_requested_reviewers - changes_requested: from_requested_reviewers - when: always - message: "Review dismissed due to new review request." -``` diff --git a/src/content/docs/workflow/rebase.mdx b/src/content/docs/workflow/rebase.mdx deleted file mode 100644 index 65a3bf6c0d..0000000000 --- a/src/content/docs/workflow/rebase.mdx +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Rebasing Pull Requests -description: Bring your pull requests up-to-date with their base branch automatically. ---- - -import { Image } from "astro:assets"; -import rebaseScreenshot from "../../images/commands/rebase/example.png" - -Rebasing is a method to integrate changes from one branch into another. It's -essentially like "replaying" changes from your branch onto another branch. This -is helpful when you want to ensure your changes are built upon the most recent -commits of the branch you're targeting. - -Rebasing a pull request in GitHub allows you to update the entire commit -history of a branch onto its base branch, while the base branch received new -commits. - -Mergify allows to rebase pull requests in two different ways: - -- Either by using the [`rebase` command](/commands/rebase) which rebases the - pull request immediately; - -- Either by using an automation rule that automatically triggers a rebase - when a pull request meets conditions. - -## Rebasing a PR from GitHub - -To instantly rebase a pull request without leaving GitHub, use the Mergify -rebase command by typing: - -```text -@mergifyio rebase -``` - -Sending command @mergifyio rebase in the pull request conversation on GitHub. - -This command triggers a `git rebase` operation and force-push the rebased -branch. - -import RebaseAdvantage from '../commands/_rebase_advantages.mdx'; - - - -## Automatically Rebasing PRs - -You might be tempted to rebase pull requests automatically when they are behind -their base branch, such as `main` or `master`. The [`rebase` -action](/workflow/actions/rebase) is a great candidate to help in such a case. - -You can write an automation rule that does exactly this for you: - -```yaml -pull_request_rules: - - name: continuously rebase pull requests when it's labeled with `rebase` - conditions: - - label = rebase - actions: - rebase: -``` - -Note that this rebases the pull request as long as it has the label. - -If you wanted to rebase only once, you would also need to remove the label once -the rebase is done: - -```yaml -pull_request_rules: - - name: rebase pull requests once when it's labeled with `rebase` - conditions: - - label = rebase - actions: - rebase: {} - label: - remove: - - rebase -``` - -### Rebasing Outdated Pull Requests - -As rebasing a PR is likely to re-trigger your CI, rebasing your PR continuously -could be time consuming for your CI system. Rather than doing it on every merge -done in the base branch, you can rebase only when the PR is behind a number of -commits. For example: - -```yaml -pull_request_rules: - - name: rebase pull request when it's more than 10 commits behind main - conditions: - - base = main - - "#commits-behind >= 10" - actions: - rebase: -``` - -With this rule, as soon as the pull request is more than 10 commits behind the -`main` branch, Mergify automatically rebases the pull request which therefore -retriggers the CI. This is useful to make sure that you don't merge pull -request that are too much out-of-date. - -:::caution - If your goal is to only merge pull requests that are rebased and retested - before being merged, you are actually looking for a [merge - queue](/merge-queue). A merge queue makes sure each pull request is up to - date and retested before being merged, while avoiding to update all pull - requests at once. -::: - -### Rebasing Pull Requests Once a Week - -As stated above, rebasing too often your pull requests might not be great for -your CI resource usage. Therefore, you could also use a strategy where rebase -would only be done during a certain time frame, once a day. - -```yaml -pull_request_rules: - - name: rebase pull requests in the morning - conditions: - - base = main - - "schedule = Mon-Fri 08:00-09:00[US/Pacific]" - actions: - rebase: -``` - -With this rule, any pull request that is out-of-date between 8am and 9am PST -during the week will be rebased. diff --git a/src/content/docs/workflow/request-reviews.mdx b/src/content/docs/workflow/request-reviews.mdx deleted file mode 100644 index c80526b30c..0000000000 --- a/src/content/docs/workflow/request-reviews.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Request Reviews -description: Enhance your review workflow with customized, efficient, and dynamic review assignments tailored to your needs. ---- -Mergify's [`request_reviews`](/workflow/actions/request_reviews) action -provides an enhanced mechanism to automate and personalize your review process, -taking it several notches above GitHub's conventional review assignment. By -harnessing the versatility of pull request rules and conditions, you can define -intricate workflows tailored to your team's needs. Let's explore how to utilize -the action for various scenarios. - -Below is a list of examples of what you could achieve with pull request rules -and the `request_reviews` action. - -## Basic Assignment - -Automatically request specific users or teams to review a pull request when -it's labeled with `review`. The rule checks for a pull request labeled `review` -and then requests reviews from `user1`, `user2`, and `team1`. - -```yaml -pull_request_rules: - - name: request review from users and team when pull request is labeled with `review` - conditions: - - label = review - actions: - request_reviews: - users: - - user1 - - user2 - teams: - - team1 -``` - -## Flexible Reviewers Assignment - -Dynamic reviewer assignments based on the content and context of pull requests. - -### File Type Based Review - -Assign a Python expert to review changes in Python files. - -```yaml -pull_request_rules: - - name: ask jd to review changes on python files - conditions: - - files ~= \.py$ - actions: - request_reviews: - users: - - jd -``` - -### Label Based Review - -For security-focused pull requests, you might want specialized teams to review. - -```yaml -pull_request_rules: - - name: ask the security teams to review security labeled PR - conditions: - - label = security - actions: - request_reviews: - teams: - - "@myorg/security-dev" - - "@myorg/security-ops" -``` - -## Random Review Assignment - -Evenly distribute the review workload among team members. - -This rule assigns two random users from a list of four to review pull requests -labeled as `review`. - -```yaml -pull_request_rules: - - name: randomly ask two members for review - conditions: - - label = review - actions: - request_reviews: - users: - - jd - - sileht - - CamClrt - - GuillaumeOj - random_count: 2 -``` - -## Hierarchical Review System - -Define a hierarchy in the review process, with junior team members reviewing -first. If changes affect critical components, senior members step in. - -```yaml -pull_request_rules: - - name: junior review for all PRs - conditions: - - base = main - actions: - request_reviews: - users: - - junior1 - - junior2 - - - name: senior review for critical components - conditions: - - base = main - - files ~= ^critical/ - actions: - request_reviews: - users: - - seniorDev -``` - -## Expertise-based Review Assignment - -Ensure domain experts review relevant changes. If a PR modifies -database-related files, request a review from the database expert. - -```yaml -pull_request_rules: - - name: database expert review for database-related changes - conditions: - - files ~= ^database/ - actions: - request_reviews: - users: - - dbExpert -``` - -## Load Balancing Review Assignments - -Distribute reviews more fairly, ensuring certain team members aren't -overwhelmed. - -```yaml -pull_request_rules: - - name: balanced review assignment - conditions: - - label = review - actions: - request_reviews: - users: - jd: 2 - sileht: 3 - CamClrt: 1 - GuillaumeOj: 1 - random_count: 2 -``` - -## Cross-Team Review - -Facilitate cross-team collaboration and knowledge sharing. When core components -are changed, it's beneficial to get insights from another team. - -```yaml -pull_request_rules: - - name: cross-team review for core changes - conditions: - - files ~= ^core/ - actions: - request_reviews: - teams: - - "@anotherTeam" -``` - -{/* This is a great idea but we don't have pushed-at exposed yet - -## Escalation of Review - -Ensure stagnant PRs get the attention they need by escalating them to senior -team members. - -```yaml -pull_request_rules: - - name: escalate review after 48 hours of inactivity - conditions: - - pushed-at > 2 days - - "#review-requested = 0" - actions: - request_reviews: - users: - - seniorReviewer -``` - -*/} - -## On-Demand Review Request - -Allow authors to trigger specific domain reviews by adding labels. - -```yaml -pull_request_rules: - - name: on-demand database expert review - conditions: - - label = request-db-review - actions: - request_reviews: - teams: - - dbExperts -``` - -## Mentorship Review Process - -Pull requests from new developers are first reviewed by mentors to ensure -guidance. - -```yaml -pull_request_rules: - - name: mentor review for new dev - conditions: - - author = newdev - actions: - request_reviews: - users: - - mentorUser -``` - -## Collaborative Review Process - -When critical files are modified, request multiple teams to collaboratively -review the changes. - -```yaml -pull_request_rules: - - name: multi-team review for critical changes - conditions: - - files ~= ^critical/ - actions: - request_reviews: - teams: - - "@teamA" - - "@teamB" -``` - -## Time-Sensitive Review - -PRs marked as urgent get reviewed by a dedicated quick response team. - -```yaml -pull_request_rules: - - name: urgent review request - conditions: - - label = urgent - actions: - request_reviews: - teams: - - "@quickResponseTeam" -``` - -With these comprehensive use cases, you're well-equipped to optimize and -customize your review workflows using Mergify's `request_reviews` action. Adapt -and mix these scenarios to perfectly fit your team's unique requirements. diff --git a/src/content/docs/workflow/writing-your-first-rule.mdx b/src/content/docs/workflow/writing-your-first-rule.mdx deleted file mode 100644 index d3027bf844..0000000000 --- a/src/content/docs/workflow/writing-your-first-rule.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Writing Your First Rule -description: Automate your first workflow with Mergify Workflow Automation ---- - -import { Image } from "astro:assets" -import configEditorScreenshot from "../../images/workflow/writing-your-first-rule/config-editor.png" -import summaryScreenshot from "../../images/workflow/writing-your-first-rule/summary.png" - -## Understanding The Configuration File - -The Mergify configuration file consists of two primary components: rules and -actions. Rules define the conditions under which specific actions should be -triggered, while actions specify the automated tasks to be performed on the -pull requests. By combining rules and actions, you can create a powerful and -flexible automation process tailored to your specific requirements. - -In the following sections, we will explore how to define rules using conditions -and how to set up actions for various use cases, such as merging, labeling, and -assigning pull requests. - -Mergify streamlines your pull request process by applying rules you define. To -utilize Mergify, you must create a configuration file within each repository -where you want to enable its functionality. - -Place the configuration file in the root directory of the repository, and name -it one of the following: `.mergify.yml`, `.mergify/config.yml`, or -`.github/mergify.yml`. - -The [configuration file](/configuration/file-format) relies on -[YAML](https://yaml.org/), a simple and human-readable data file format. For -comprehensive details on the configuration file format, please refer to the -[configuration file format](/configuration/file-format) section. - -## The Rules - -To create a rule in the Mergify configuration file, you must specify the -following three essential components: - -- **Rule name**: A unique identifier for each rule, allowing you to easily - manage and organize your automation workflow. - -- **Conditions**: A list of criteria that the pull request must fulfill for the - rule to apply, such as the status of checks, labels, or approvals. - -- **Actions**: A list of automated tasks executed when the conditions are met, - such as merging, labeling, or assigning the pull request. - -By carefully crafting your rules, you can build a powerful and customized pull -request automation process that aligns with your project's needs. - -### Writing Your First Rule - -To get started with creating your first rule in the Mergify configuration file, -follow these steps: - -1. **Choose a unique name for your rule**: This will help you identify and - manage the rule within your configuration file. - -2. **Define the conditions**: List the criteria that a pull request must meet - for the rule to apply. Conditions are written in YAML syntax and may include - factors like the pull request's status, labels, or number of approvals. - -3. **Specify the actions**: Determine the tasks that should be executed - automatically when the conditions are met, such as merging the pull request, - adding labels, or assigning reviewers. - -Here's a sample rule that demonstrates the process: - -```yaml -pull_request_rules: - - name: Automatic merge when CI passes and approved - conditions: - - "#approved-reviews-by >= 2" - - check-success = your-ci-name - - base = main - actions: - merge: -``` - -In this example, the rule named "Automatic merge when CI passes and approved" -will be triggered when the following conditions are met: - -- The pull request has at least 2 approved reviews. -- The *your-ci-name* check passes. -- The base branch for the pull request is *main*. - -When these conditions are satisfied, Mergify will perform the following action: - -- Automatically merge the pull request. - -### Using the Configuration Editor - -The [Mergify dashboard](https://dashboard.mergify.com) provides a built-in -configuration editor to help you create, edit, and test your configuration file -easily. The editor allows you to write and validate your Mergify configuration -without leaving the dashboard, ensuring that your rules are correctly formatted -and functional. - -To use the configuration editor, follow these steps: - -1. **Navigate to the [Mergify dashboard](https://dashboard.mergify.com)**: Log - in to your Mergify account and access your dashboard. - -2. **Open the configuration editor**: Locate and click on the *Configuration - Editor* link or button within the dashboard. - -3. **Edit your configuration**: Use the textarea provided to write or modify - your Mergify configuration file. The editor supports YAML syntax and - provides a convenient way to define your rules, conditions, and actions. - -4. **Specify a pull request number**: To validate your configuration, enter a - pull request number in the designated field. This allows the editor to test - your configuration against a real pull request to ensure it works as - expected. - -5. **Validate your configuration**: As you edit your configuration, the editor - automatically checks for syntax and formatting errors. Ensure that your - configuration is valid before proceeding. - -6. **Create a pull request to save your configuration**: Once you have finished - editing and validating your configuration, click the "Create Pull Request" - button. This will generate a new pull request with your updated - configuration file, allowing you to review the changes before merging them - into your repository. - -By using the configuration editor, you can easily manage your Mergify rules and -ensure a smooth automation process for your pull requests. - -Mergify configuration editor - -## Understanding Mergify Rule Conclusions - -Mergify continuously evaluates your rules whenever a pull request is updated or -modified. When a rule's conditions are met, Mergify triggers the corresponding -actions. To help users understand what is happening with their rules and why -certain actions are or are not triggered, Mergify provides a -summary of its rules -evaluation within a Check, similar to other CI systems. - -### Mergify Summary - -The Mergify Summary is a concise report of the rules evaluation for each pull -request. It is displayed as a Check within the GitHub UI, making it easy for you -to review the results and understand the state of your rules and actions. - -To view the Mergify Summary, follow these steps: - -1. **Open the pull request**: Navigate to the pull request you want to review - within the GitHub UI. - -2. **Access the Checks tab**: Click on the "Checks" tab located near the top of - the pull request page. - -3. **Locate the Mergify Summary**: Scroll through the list of Checks to find - the one named "Mergify". Click on the "Details" link to view the full - summary. - -The Mergify Summary provides information on: - -- The rules that were evaluated. -- The conditions that were met or not met. -- The actions that were triggered or not triggered. - -By reviewing the Mergify Summary, you can gain insight into the behavior of your -Mergify configuration and make any necessary adjustments to your rules and -actions. - -Mergify rules summary diff --git a/src/content/navItems.tsx b/src/content/navItems.tsx index 79d377545e..a3c6fe3268 100644 --- a/src/content/navItems.tsx +++ b/src/content/navItems.tsx @@ -227,31 +227,8 @@ const navItems: NavItem[] = [ icon: 'bi:gear', path: '/workflow', children: [ - { title: 'Introducing Workflow Automation', path: '/workflow/', icon: 'bi:robot' }, - { - title: 'Writing Your First Rule', - path: '/workflow/writing-your-first-rule', - icon: 'bi:rulers', - }, + { title: 'Workflow Automation', path: '/workflow/', icon: 'bi:robot' }, { title: 'Rule Syntax', path: '/workflow/rule-syntax', icon: 'bi:patch-question' }, - { - title: 'Use Cases', - icon: 'bi:lightbulb', - children: [ - { title: 'Automatic Merge', path: '/workflow/automerge', icon: 'octicon:git-merge-16' }, - { - title: 'Request Reviews', - path: '/workflow/request-reviews', - icon: 'octicon:code-review-16', - }, - { - title: 'Dismiss Reviews', - path: '/workflow/dismiss-reviews', - icon: 'tabler:message-x', - }, - { title: 'Rebasing PRs', path: '/workflow/rebase', icon: 'tabler:git-branch' }, - ], - }, { title: 'Actions', icon: 'bi:rocket',