Setting up approval rules

With Managed Service for GitLab, you can flexibly set up mandatory approval rules before any code can be added to 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 provide enough permissions to configure approval rules. Next, log in to the GitLab instance and set up the approval rules via 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).

If required, enable debugging mode and check out the rules for handling exceptions.

Create a GitLab tokenCreate a GitLab token

You need the GitLab token to enable approval rules and access the repository, because 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, in the Token name field, enter a name to easily locate the token in your GitLab project.

6. In the Expiration date field, specify the token's expiration date.

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

7. Under Select scopes, select api.

8. Click Create personal access token.

   A new token will be generated.

9. Copy and save it. Later you will not be able to copy it in GitLab.

Enable approval rulesEnable approval rules

1. Activate the GitLab setting that prevents merging changes to the target branch until all threads in a merge request are resolved:
   1. Open your project in GitLab.
   2. In the left-hand menu, select Settings → Merge requests.
   3. Under Merge checks, select 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. Specify the hook parameters:
      • 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 system hook.
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. In the Outbound requests section, enable the Allow requests to the local network from system hooks option.
   5. In the list of IP addresses and domain names, specify the http://localhost:24080 URL.
   6. Click Save changes.
4. Enable approval rules in the Managed Service for GitLab instance:

   1. In the Yandex Cloud management console, select the folder where the GitLab instance is located.

   2. Select 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's computing resources.

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

   6. Click Save.

Set up the approval rulesSet up the 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 loaded 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: Name of the GitLab user who can approve the merge request.
• groups: Name of the GitLab group whose users can approve the merge request.
• branches: Branch with updates that require approval.
• rules: Rule applied to the specified branches.

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

For example, to apply the four-eyes principle to the repository master 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

The 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 loaded when you modify the file.

The file structure supports the GitLab syntax, except for the use of user subgroups and email addresses as user IDs.

To use the code ownership settings when handling merge requests to specific branches, add the following record 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 have detailed information on each rule output in a thread:

• Names of users who approved the merge request.
• How many approvals are left to be received.
• Names of remaining users who can 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 get an email notification about the error.
  • All merge requests of the repository are blocked.

Overriding the rulesOverriding 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 overriding the existing approval rules:

1. Add a comment with the force_merge keyword to the merge request.
2. Update the merge request description so that Managed Service for GitLab gets notified of the changes in the merge request.

This will close the thread and unblock the merge request. During the integration, users with the Maintainer role or higher will receive an email notification about the violated code approval workflow.