diff --git a/src/content/docs/merge-protections.mdx b/src/content/docs/merge-protections.mdx index 8d1a90bb4d..90de45fc72 100644 --- a/src/content/docs/merge-protections.mdx +++ b/src/content/docs/merge-protections.mdx @@ -1,6 +1,4 @@ --- -# This is the new landing page for Merge Protections after split -# (frontmatter title intentionally left same for nav purposes) title: Merge Protections description: Go beyond GitHub's native branch protections and craft custom, advanced rules using Mergify. --- @@ -8,7 +6,7 @@ description: Go beyond GitHub's native branch protections and craft custom, adva import { Image } from "astro:assets" import commentScreen from "../images/merge-protections/comment.png" -> Mergify Merge Protections extend GitHub's native Branch Protections & Rulesets with fine‑grained, dynamic rules. +> Mergify Merge Protections extend GitHub's native Branch Protections & Rulesets with fine-grained, dynamic rules. Merge Protections let you: @@ -29,7 +27,7 @@ Merge Protections let you: | Capability | GitHub Native | Mergify Merge Protections | | ---------- | ------------- | ------------------------- | | Conditional logic (complex AND/OR on PR metadata) | No | Extensive | -| Depends‑On relationships | No | Yes | +| Depends-On relationships | No | Yes | | Time / schedule based merge windows | No | Yes | | Repository freeze (manual or scheduled) | No | Yes | | Single composite check gate | Partial | Yes | @@ -58,7 +56,7 @@ The feature is composed of several building blocks documented in dedicated pages - [Enabling & Configuration](/merge-protections/setup) - [Auto-Merge](/merge-protections/auto-merge) -- [Built‑in Protections](/merge-protections/builtin) +- [Built-in Protections](/merge-protections/builtin) - [Custom Rules](/merge-protections/custom-rules) - [Scheduling Freezes](/merge-protections/freeze) - [Examples & Patterns](/merge-protections/examples) diff --git a/src/content/docs/merge-protections/builtin.mdx b/src/content/docs/merge-protections/builtin.mdx index 150acf4b4c..fbb34c2cd6 100644 --- a/src/content/docs/merge-protections/builtin.mdx +++ b/src/content/docs/merge-protections/builtin.mdx @@ -1,5 +1,5 @@ --- -title: Built‑in Merge Protections +title: Built-in Merge Protections description: "Protections available out of the box: Depends-On, Merge-After, Configuration Changed." --- @@ -25,9 +25,12 @@ Depends-On: org/repo#123 Rules: -- All referenced PRs must be in repositories with Mergify enabled +- All referenced pull requests must be in repositories with Mergify enabled. A + reference Mergify cannot resolve (the repository has no Mergify, or the pull + request does not exist) fails the protection rather than waiting on it -- They must belong to the same organization +- They must belong to the same repository owner: the user or organization that + owns the repository declaring the dependency - A dependency that is still open blocks the protection until that pull request merges. A circular chain (or a pull request that lists itself) never @@ -49,9 +52,11 @@ gains a **Depends On** section linking to each queued pull request it waits for. The merge queue status [API](/api/usage) reports the same list as `depends_on_pull_requests`. -This display covers dependencies inside a [stack](/merge-queue/stacks) in the -same repository. A dependency on a pull request in another repository still -blocks the merge, but the queue does not show it. +The queue shows this only for the pull requests ahead of it in a +[stack](/merge-queue/stacks) in the same repository. Any other dependency still +blocks the merge without appearing there, whether it points at a pull request +in another repository or at one in the same repository that is not part of the +same stack. ## Merge-After diff --git a/src/content/docs/merge-protections/custom-rules.mdx b/src/content/docs/merge-protections/custom-rules.mdx index 8e81b46a73..82c0a8861d 100644 --- a/src/content/docs/merge-protections/custom-rules.mdx +++ b/src/content/docs/merge-protections/custom-rules.mdx @@ -18,6 +18,9 @@ merge_protections: - ``` +Write them by hand, or build them in the [dashboard](/merge-protections/setup), +which commits the same YAML to your configuration file through a pull request. + Evaluation: - If all `if` conditions are true, the rule becomes **active**. - If **active**, all `success_conditions` must be true for the rule to **succeed**. diff --git a/src/content/docs/merge-protections/freeze.mdx b/src/content/docs/merge-protections/freeze.mdx index 19090fa21e..05a40cd3cd 100644 --- a/src/content/docs/merge-protections/freeze.mdx +++ b/src/content/docs/merge-protections/freeze.mdx @@ -19,39 +19,65 @@ Use freezes to coordinate: Scheduled Freezes -In the dashboard under Merge Protections → Freezes: +In the dashboard under `Merge Protections` → `Scheduled Freezes`: 1. Click `Schedule a Freeze` -2. Define start / end, and the timezone they are expressed in +2. Fill in `Freeze Reason`, which is required and names the freeze wherever + Mergify reports it -3. Add matching conditions: by default the freeze applies to every pull +3. Under `Schedule`, set `From` and `To`, and the timezone they are expressed + in + +4. Add `Matching Conditions`: by default the freeze applies to every pull request, but you can limit its scope with this field -4. Add exclude conditions: a pull request that matches all of them is allowed +5. Add `Exclude Conditions`: a pull request that matches all of them is allowed through the freeze, so specific pull requests (like hotfixes) can still merge while everything else is blocked -5. Save; active freezes appear in the list +6. Save; active freezes appear in the list New Scheduled Freeze -While a freeze is active, the `Mergify Merge Protections` check stays pending -on every matching pull request, and its summary names the freeze holding it -back: waiting for that freeze to end, or, when the freeze has no end date, -waiting for someone to remove it. Pull requests matching the freeze's exclude -conditions are left alone (see [Allowing Exceptions](#allowing-exceptions) -below), as are pull requests that cannot be merged anyway: drafts, closed ones, -and conflicting ones. +Without the merge queue, an active freeze leaves the `Mergify Merge +Protections` check pending on every matching pull request, and its summary +names the freeze holding it back: waiting for that freeze to end, or, when the +freeze has no end date, waiting for someone to remove it. Pull requests +matching the freeze's exclude conditions are left alone (see [Allowing +Exceptions](#allowing-exceptions) below), as are pull requests that cannot be +merged anyway: drafts, closed ones, and conflicting ones. When the [merge queue](/merge-queue) is enabled, the freeze is reported in that -check but does not change its conclusion. The queue holds the merge back until -the freeze ends. +check but is not what decides its conclusion. The queue holds the merge back +until the freeze ends. ## Manual Instant Freeze Use the `Freeze Merges Now` action for immediate blocking. You can later unfreeze manually. +## Recurring Merge Windows + +A freeze covers a single window: it has one start and one end, and nothing +repeats it. To block merges on a recurring basis, such as outside working hours +or every weekend, write a [merge protection +rule](/merge-protections/custom-rules) with a `schedule` condition instead: + +```yaml +merge_protections: + - name: Merge during working hours + description: Only merge between 9am and 5pm, Monday to Friday + if: + - base = main + success_conditions: + - schedule = Mon-Fri 09:00-17:00[America/Chicago] +``` + +Outside the window the rule is pending, so the `Mergify Merge Protections` +check holds the pull request back the same way an active freeze does; the rule +passes again once the window reopens. See +[schedule](/configuration/data-types#schedule) for the accepted formats. + ## Allowing Exceptions To let specific pull requests through a freeze, use exclude conditions. They diff --git a/src/content/docs/merge-protections/setup.mdx b/src/content/docs/merge-protections/setup.mdx index f794d959a5..280336b5a6 100644 --- a/src/content/docs/merge-protections/setup.mdx +++ b/src/content/docs/merge-protections/setup.mdx @@ -14,10 +14,16 @@ import deployScreenshot from "../../images/merge-protections/deploy.png" 1. Go to the [Mergify dashboard](https://dashboard.mergify.com) 2. Click the `Merge Protections` section 3. Select your repository -4. Enable the feature and create rules +4. Activate the product, then create rules under `Rules` Merge Protections rules for a repository +The rules themselves live in your repository's [configuration +file](/configuration/file-format), under the `merge_protections` key. The +dashboard's rule builder is an editor for that file: it opens a pull request +adding your rules to it. You can write them by hand instead. See [Custom +Rules](/merge-protections/custom-rules) for the rule structure. + ## Reporting Method: check-runs vs deployments You can configure how Merge Protections report their status to GitHub using the