|
| 1 | +--- |
| 2 | +title: Merge Protections |
| 3 | +description: Go beyond GitHub's native branch protections and craft custom, advanced rules using Mergify. |
| 4 | +--- |
| 5 | + |
| 6 | +import { Image } from "astro:assets" |
| 7 | +import mainScreen from "../../images/merge-protections/main-screen.png" |
| 8 | +import bpScreen from "../../images/merge-protections/branch-protections.png" |
| 9 | +import requiredChecksScreen from "../../images/merge-protections/required-check.png" |
| 10 | +import mergeAfterBody from "../../images/merge-protections/merge-after.png" |
| 11 | +import dependsOnBody from "../../images/merge-protections/depends-on.png" |
| 12 | +import scheduleFreezeScreen from "../../images/merge-protections/schedule-freeze.png" |
| 13 | +import commentScreen from "../../images/merge-protections/schedule-freeze.png" |
| 14 | + |
| 15 | +[GitHub's branch |
| 16 | +protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) |
| 17 | +and |
| 18 | +[rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) |
| 19 | +are foundational, but their customizations are somewhat limited. |
| 20 | + |
| 21 | +For more advanced or specific scenarios, Mergify's Merge Protections can step |
| 22 | +in, enabling you to define nuanced conditions that cater to your project's |
| 23 | +unique needs. This flexibility means you can design branch protection rules |
| 24 | +that the native system simply can't handle. |
| 25 | + |
| 26 | +## Why Mergify Over Native GitHub Branch Protection and Rulesets? |
| 27 | + |
| 28 | +1. **Advanced Conditions**: Mergify supports a vast array of conditions, which |
| 29 | + means you can create extremely specific rules based on any of the pull |
| 30 | + request metadata. |
| 31 | + |
| 32 | +2. **Dependencies**: Leverage dependencies between pull requests. |
| 33 | + |
| 34 | +3. **Scheduled Merges**: Make sure merges are done on the right time. |
| 35 | + |
| 36 | +4. **Freeze**: Schedule one-time or recurring total or partial freeze for your |
| 37 | + repository. |
| 38 | + |
| 39 | +## Enabling Merge Protections |
| 40 | + |
| 41 | +Merge protections can be configured directly from your |
| 42 | +[dashboard](https://dashboard.mergify.com) by clicking on the `Merge |
| 43 | +Protections` link in the sidebar. |
| 44 | + |
| 45 | +<Image src={mainScreen} alt="Mergify Merge Protections" /> |
| 46 | + |
| 47 | +Once enabled on your repository, Mergify will post a check entitled `Mergify |
| 48 | +Merge Protections` on your pull requests. You need to ensure this checks is |
| 49 | +required in your branch protection settings or in your rulesets. |
| 50 | + |
| 51 | +<Image src={bpScreen} alt="GitHub Branch Protection" /> |
| 52 | + |
| 53 | +Once `Mergify Merge Protections` is required in your repository rules, it will |
| 54 | +be marked as enforced in your GitHub checks and will prevent any pull request |
| 55 | +to be merged if does not match your conditions. |
| 56 | + |
| 57 | +<Image src={requiredChecksScreen} alt="GitHub required cheks" /> |
| 58 | + |
| 59 | +Mergify will also post an update as a comment on pull requests, including |
| 60 | +details of the matching protections. |
| 61 | + |
| 62 | +<Image src={commentScreen} alt="Merge Protections comment" /> |
| 63 | + |
| 64 | +## Built-in Protections |
| 65 | + |
| 66 | +Mergify provides multiple built-in protections that are available |
| 67 | +out-of-the-box. |
| 68 | + |
| 69 | +### Depends-On |
| 70 | + |
| 71 | +The Depends-On protection prevents pull request to be merged if the dependent |
| 72 | +pull requests are not yet merged. |
| 73 | + |
| 74 | +To use this feature, you simply need to list pull request dependencies in the |
| 75 | +pull request body using one of the following format: |
| 76 | + |
| 77 | +```yaml |
| 78 | +Depends-On: #123 |
| 79 | +Depends-On: https://github.com/myorg/myrepo/pull/123 |
| 80 | +Depends-On: myorg/myrepo#123 |
| 81 | +``` |
| 82 | +
|
| 83 | +<Image src={dependsOnBody} alt="Using Depends-On in the pull request body on GitHub"/> |
| 84 | +
|
| 85 | +A pull request can depends on any other pull request if both those conditions |
| 86 | +are matched: |
| 87 | +- Mergify is enabled on the target repository; |
| 88 | +- The repository is part of the same organization. |
| 89 | +
|
| 90 | +### Merge-After |
| 91 | +
|
| 92 | +You can use the `Merge-After` pull request header to merge a pull request after |
| 93 | +a certain date using our [timestamp format](/configuration/data-types#timestamp). |
| 94 | + |
| 95 | +<Image src={mergeAfterBody} alt="Using Merge-After in the pull request body on GitHub"/> |
| 96 | + |
| 97 | +## Adding New Rules |
| 98 | + |
| 99 | +You can add any new rule by clicking on the `New Rule` button and using a |
| 100 | +template or writing from scratch. |
| 101 | + |
| 102 | +The format of the rules is as follow: |
| 103 | + |
| 104 | +```yaml |
| 105 | +name: <name of your rule> |
| 106 | +description: <description of your rule> |
| 107 | +if: <list of conditions that the pull request needs to match to see the rule applied> |
| 108 | +success_conditions: <list of conditions that needs to match for the check to be a success> |
| 109 | +``` |
| 110 | + |
| 111 | +You can refer to [the format of the conditions](/configuration/conditions/) for |
| 112 | +more details. |
| 113 | + |
| 114 | +For example, to check that your pull request targeting the `main` branch |
| 115 | +follows the conventional commit convention you can write: |
| 116 | + |
| 117 | +```yaml |
| 118 | +name: Enforce conventional commit |
| 119 | +description: Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/ |
| 120 | +if: |
| 121 | + - base = main |
| 122 | +success_conditions: |
| 123 | + - "title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:(.+))?:" |
| 124 | +``` |
| 125 | + |
| 126 | +## Scheduling Freezes |
| 127 | + |
| 128 | +If you want to prevent pull request to be merged during certain periods, you |
| 129 | +can create scheduled freezes on your repository. |
| 130 | + |
| 131 | +<Image src={scheduleFreezeScreen} alt="Scheduled Freezes" /> |
| 132 | + |
| 133 | +You can also freeze your repository instantly by clicking on "Freeze Merges |
| 134 | +Now". |
0 commit comments