Recommendations for using approval rules in Yandex Managed Service for GitLab

With Managed Service for GitLab, you can flexibly set up mandatory approval rules before merging code into the target branch of the project. This feature is an alternative to the GitLab Enterprise Edition’s Approval Rules tool and is available regardless of the GitLab version.

In Managed Service for GitLab, approval rules are configured only as code (configuration as code) in the files named APPROVALRULES and, optionally, CODEOWNERS.

For more information, see Approval rules in Yandex Managed Service for GitLab.

This section gives examples of APPROVALRULES and, optionally, CODEOWNERS for the following common scenarios:

• Rule setup example for role-based review
• Rule setup example for two-stage review
• Rule setup example for review of changes in CI/CD

In addition to approval rules, you can also set up branch protection in your repository. These two mechanisms work in parallel; therefore, approval rules alone may not be enough for a merge request to merge into the target branch. For clarity, the examples assume that the referenced branches are not the repository's main branches (e.g., main) and are protected against direct pushes only.

The approval rules will take effect after changes made to APPROVALRULES and, optionally, CODEOWNERS are merged into the repository's main branch. There is no need to propagate these changes to other branches.

Merge request reviewers must have at least the Reporter role in the GitLab project; in most cases, the more privileged Developer role is used.

Getting startedGetting started

1. If you have no GitLab instance yet, create and activate one.

2. If no approval rules have been configured in your GitLab instance and project so far, configure them.

   Note

   The minimum configuration you need for approval rules to function is specified in each example.

3. Create users and groups as described in the examples below.

4. Create the files named APPROVALRULES and, optionally, CODEOWNERS in the repository's main branch according to the examples below.

Rule setup example for role-based reviewRule setup example for role-based review

This example presents a scenario for mandatory reviews of merge requests by information security officers. For a merge into the release branch, the merge request has to be approved by a user with this username: security-expert1 or security-expert2.

This scenario also suits other simple cases where you want to protect a single branch and assign specific approvers.

APPROVALRULES file contents:

# Approval rules
ApprovalRules:
  # Rule name (any)
  - SecurityReview:
      # List of users (usernames) authorized to approve the merge request
      approvers:
        - "security-expert1"
        - "security-expert2"
      # Required number of approvals
      count: 1
# Branch groups subject to the rules
BranchGroups:
  # Branch group name (any)
  - Release:
      # List of branches subject to the rules
      branches:
        - release
      # Rules to apply
      rules:
        - SecurityReview

As a result, when a merge request for the release branch is created, one of the specified users gets auto-assigned in the Reviewer field, and the merge request gets blocked until approved.

ApprovalRules:
  - SecurityReview:
      groups:
        - "soc"
        - "secops"
      count: 1
...

Rule setup example for two-stage reviewRule setup example for two-stage review

This example presents a scenario for mandatory two-stage reviews of merge requests:

1. For a merge into the stage branch, you need one approval by a developer from the devs group, who reviews the code for correctness, style, tests, and architecture.
2. For a merge into the release branch, you need two approvals: one by a developer from the devs group and one by a tech lead from the tech-leads group, the latter reviewing alignment with business goals and team standards.

This implies that changes first go from the main development branch (e.g., dev) into staging (stage branch) for tests, and only then to release (release branch).

You can also adapt this scenario for cases where different approval rules are required for merge requests to be merged into different branches.

APPROVALRULES file contents:

# Approval rules
ApprovalRules:
  # Rule name (any)
  - TechnicalReview:
      # List of groups whose members can approve a merge request
      groups:
        - devs
      # Required number of approvals
      count: 1
  - LeadApproval:
      groups:
        - tech-leads
      count: 1
# Branch groups subject to the rules
BranchGroups:
  # Branch group name (any)
  - Stage:
      # List of branches subject to the rules
      branches:
        - stage
      # Rules to apply
      rules:
        - TechnicalReview
  - Release:
      branches:
        - release
      rules:
        - TechnicalReview
        - LeadApproval

As a result, when a merge request for the stage branch is created, one of the devs group members gets auto-assigned in the Reviewer field, and the merge request gets blocked until approved. After the merge, the changes are tested on staging.

Next, the developer creates a merge request from stage to release. Reviewers from the devs and tech-leads groups get auto-assigned in the Reviewer field, one from each group, and the merge request gets blocked until approved by both of these.

ApprovalRules:
  - TechnicalReview:
      approvers:
        - "dev1"
        - "dev2"
      count: 1
...

Rule setup example for review of changes in CI/CDRule setup example for review of changes in CI/CD

This example presents a scenario for mandatory reviews of merge requests by DevOps engineers, only if the CI/CD configuration was modified. If a merge request changes the .gitlab-ci.yml file or .yml files in the ci/ directory, you need approval by one of the devops-team group member for a merge into the release branch.

This scenario also suits other cases where you want different teams or users have different scopes of review across the repository directories or files.

Path-based filtering is not supported by APPROVALRULES; therefore, you should combine approval rules with the code ownership mechanism.

CODEOWNERS file contents:

# <filepaths_or_filtering_patterns> @<group_in_charge>
.gitlab-ci.yml @devops-team
ci/*.yml @devops-team

APPROVALRULES file contents:

# Branch groups subject to the rules
BranchGroups:
  # Branch group name (any)
  - Release:
      # List of branches subject to the rules
      branches:
        - release
      # Rules to apply
      rules:
        - CODE_OWNERS

As a result, when a merge request for the release branch is created affecting .gitlab-ci.yml or ci/*.yml, one of the devops-team group members gets auto-assigned in the Reviewer field, and the merge request gets blocked until approved.

BranchGroups:
  - All:
      branches:
        - "*"
      rules:
        - CODE_OWNERS

See alsoSee also

• Approval rules in Yandex Managed Service for GitLab
• Setting up approval rules in Yandex Managed Service for GitLab
• Creating and activating a Managed Service for GitLab instance

GitLab guidesGitLab guides

• Merge request approval rules
• Syntax of CODEOWNERS file
• Protected branches
• Default branch
• Roles and permissions
• Groups