Merge Checks (up to version 4)

Owned by Markus Sutter
Last updated: Dec 14, 2022 by Michael Rüegg
4 min read

Code Owners app consists of two parts:

1. Who is responsible for what part of you code? 

   => Owner rules

The members of group JavaDevs are responsible for all Java source code is defined by a Code Owner rule like:

**/*.java @@JavaDevs

Owner rules define which groups and users are active code owners in a pull request.

These active code owners are added as reviewers to the pull request.

2. How many of these Code Owners need to approve before a pull request can be merged?

   => Merge checks

Merge Checks in CODEOWNERS files are supported since version 4.0, older versions support basic Merge checks in repository settings only.

Changes in Java source code must be reviewed and approved by at least 2 members of the JavaDevs group is defined as a merge check in the CODEOWNERS file like:

Check(@@JavaDevs >= 2)

Merge checks are active and checked for a pull request if the referenced Owner group is active in this pull request.

How to combine multiple Merge checks?

If you add multiple merge checks each on its own line to the CODEOWNERS file,
all active Merge checks (aka. AND) get checked and must be fulfilled, before a pull request can be merged.

If either one Merge check or another needs to be fulfilled for a pull request to be merged,
combine the merge checks on one line with the OR syntax like:

(Check(@@JavaDevs >= 2) | Check(@@TeamLeads >= 1))

Read this as "two Java devs or one team lead need to approve" before a pull request can be merged.

All groups must be active in a OR Merge check for the check to be active in a pull request.

How to require all members of a group to approve in a Merge check?

Use * instead of a positive integer in the Merge check:

How to require approvals by Code Owners independent of groups?

Use the overall check type like:

Important: This check type must not be combined with other Merge Checks in the same CODEOWNERS file.

Use * instead of positive integer to require all Code Owners to approve.

Corresponds to the first option of Merge Check settings in previous versions:

How to require approvals for each active group and all mentioned individually in an Owner rule?

Use the all groups check type like:

Important: This check type must not be combined with other Merge Checks in the same CODEOWNERS file.

Corresponds to the first option of Merge Check settings in previous versions:



If you need help converting your requirements into Merge Check rules, or if you have an uncovered use case, please let us know.

Examples





 

Invalid Examples





Syntax

Group merge check for group:

  • with:

    • GROUP_IDENTIFIER: two @s followed by group name

    • QUOTA: positive integer or * for all group members

Combine multiple group checks:

  1. OR: Multiple group checks in parenthesis separated by |

Rules

  1. Group based checks:

    2. Only one check per line, except OR case.

    3. For checks on different lines, all must be fulfilled (AND)

    4. Check is active, if all groups referenced in line are explicitly referenced in an active CODEOWNERS rule in pull request:

       

  2. OverallCheck and AllGroupsCheck:

    1. Only allowed as single check in CODEOWNERS file.

  3. Multiple CODEOWNERS file active:

    1. Merge checks are checked for each file independently

  4. PR author does not count towards check quota, except if the PR author is the only active Code Owner.