Setting up approval rules

With Managed Service for GitLab, you can flexibly set up mandatory approval rules before merging code into the target branch of the project. For more information on how approval rules work, see Approval rules.

Before getting started, create a service account with administrator privileges and add it to your GitLab project. Assign the Maintainer or Owner role to the account, as other roles do not enough permissions to set up approval rules. Next, log in to your GitLab instance and set up approval rules using the service account.

To use approval rules:

1. Create a GitLab token.
2. Enable approval rules.
3. Configure approval rules.
4. Set up Code Ownership (available in Standard and Advanced configurations).

Enable debugging mode and check out the exception handling rules.

Create a GitLab tokenCreate a GitLab token

You need a GitLab token to enable approval rules and access the repository, since the token is used for GitLab API authentication.

To create a token:

1. Open your GitLab instance.

2. Click the profile icon and select Edit profile.

3. Go to Access Tokens in the left-hand menu.

4. Click Add new token.

5. In the window that opens, enter a name in the Token name field to easily locate the token in your GitLab project.

6. In the Expiration date field, specify the date when the token expires.

   The default value is one month from the token creation date, and the maximum is one year. The token expires at 00:00 UTC on the specified date.

7. Under Select scopes, select api.

8. Click Create personal access token.

   This will generate a new token.

9. Copy and save it, as you will not be able to copy it later in GitLab.

Enable approval rulesEnable approval rules

1. Activate the GitLab setting that prevents merging into the target branch until every thread in the merge request is resolved:
   1. Open your project in GitLab.
   2. In the left-hand menu, select Settings → Merge requests.
   3. Under Merge checks, enable All threads must be resolved.
   4. Click Save changes.
2. Add a system hook:
   1. Open your GitLab instance.
   2. In the left-hand menu, select Search or go to → Admin Area.
   3. In the left-hand menu, select System Hooks.
   4. Click Add new webhook.
   5. Configure the hook as follows:
      • URL: http://localhost:24080/default.
      • In the Trigger section, disable all options except Merge request events, Push events, and Repository update events.
   6. Click Add webhook.
3. Enable the GitLab setting which allows sending messages to the local network:
   1. Open your GitLab instance.
   2. In the left-hand menu, select Search or go to → Admin Area.
   3. In the left-hand menu, select Settings → Network.
   4. Under Outbound requests, enable Allow requests to the local network from system hooks.
   5. In the list of IP addresses and domain names, specify http://localhost:24080.
   6. Click Save changes.
4. Enable approval rules in your Managed Service for GitLab instance:

   1. In the Yandex Cloud management console, select the folder containing your GitLab instance.

   2. Go to Managed Service for GitLab.

   3. Select the instance and click Edit at the top of the page.

   4. In the Approval rules field, select the approval rule configuration.

      Note

      The configuration you select affects the cost of using the instance computing resources.

   5. In the Gitlab token field, specify the token you created earlier.

   6. Click Save.

Configure approval rulesConfigure approval rules

The approval rules for the repository are stored in the APPROVALRULES file in the root directory. The configuration is read from the default branch when running the instance and is automatically reloaded when you modify the file.

The file consists of two sections:

• ApprovalRules: Describes the rules.
• BranchGroups: Describes which branches the rules apply to.

The structure of the APPROVALRULES file is as follows:

ApprovalRules:
  - <rule_name>:
      approvers:
        - <username>
        ...
      groups:
        - <group_name>
        ...
      count: <required_number_of_approvals>
BranchGroups:
  - <branch_group_name>:
      branches:
        - <branch_name>
        ...
      rules:
        - <rule_name>
        ...

Where:

• approvers: Names of GitLab users who can approve the merge request. The users must be added to the project either directly or via a group. When counting approvals, the merge request author is not counted in. A user on this list who has committed to the merge request and is not the author can also be an approver.
• groups: List of names of GitLab groups whose members can approve the merge request (except for members of the group for which this group is a subgroup).
• count: Integer from 0 to 100. If it is 0, the rule is optional.
• branches: List of names of branches where changes must be approved.
• rules: List of rules that apply to the specified branches.

You may use the * wildcard instead of usernames and in branch names.

For example, to apply the four-eyes principle to the repository main branch, add the following to the APPROVALRULES file:

ApprovalRules:
  - FourEyesRule:
      approvers:
        - "*"
      count: 1
BranchGroups:
  - Master:
      branches:
        - master
      rules:
        - FourEyesRule

Set up code ownershipSet up code ownership

This feature is available in Standard and Advanced configurations.

The code ownership settings for the repository are stored in the CODEOWNERS file in the root directory. The configuration is read from the default branch when running the instance and is automatically reloaded when you modify the file.

The file structure follows GitLab syntax, except that user subgroups and email addresses cannot be used as user IDs.

To use the code ownership settings when handling merge requests on specific branches, add the following entry to the APPROVALRULES file:

BranchGroups:
  - <branch_group_name>:
      branches:
        - <branch_name>
        ...
      rules:
        - CODE_OWNERS

DebuggingDebugging

Add the detailed_AR keyword to a merge request description to show detailed information on each rule in a thread:

• Users who have approved the merge request.
• Number of approvals still needed.
• Users who can still approve the merge request.

Handling exceptionsHandling exceptions

Incorrect configuration of approval rulesIncorrect configuration of approval rules

Issues related to the APPROVALRULES file are handled as follows:

• If the file is missing from the repository, no approval rules apply to the repository's merge requests.
• If the file is available but is configured incorrectly:
  • Users with the Maintainer role receive an email notification about the error.
  • All merge requests for this repository are blocked.

Bypassing the rulesBypassing the rules

If you need to commit merge request changes, but the responsible team members are not available, a user with the Maintainer role or higher can commit the changes by bypassing the existing approval rules:

1. Add force_merge as a comment in the merge request.
2. Update the merge request description so that Managed Service for GitLab is notified of the changes in the merge request.

This will resolve the thread and unblock the merge request. Users with the Maintainer role or higher will receive an email notification about the violated approval workflow.