diff options
author | Marcel Amirault <ravlen@gmail.com> | 2019-05-05 14:52:24 +0000 |
---|---|---|
committer | Achilleas Pipinellis <axil@gitlab.com> | 2019-05-05 14:52:24 +0000 |
commit | 12e1969759d637a8a7dbda4124e89bae677361ce (patch) | |
tree | 06fd52f9d65bc8470134c60054e6bb8dd092a9ef /doc/user/project/merge_requests/merge_request_approvals.md | |
parent | 205df512790d6372d4672c523fad4075a8a39d3b (diff) | |
download | gitlab-ce-12e1969759d637a8a7dbda4124e89bae677361ce.tar.gz |
Docs: Merge EE doc/user/project/merge_requests to CE
Diffstat (limited to 'doc/user/project/merge_requests/merge_request_approvals.md')
-rw-r--r-- | doc/user/project/merge_requests/merge_request_approvals.md | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md new file mode 100644 index 00000000000..265871a7b4b --- /dev/null +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -0,0 +1,319 @@ +# Merge request approvals **[STARTER]** + +> Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only). + +NOTE: **Note:** +If you are running a self-managed instance, the new interface shown on +this page will not be available unless the feature flag +`approval_rules` is enabled, which can be done from the Rails console by +instance administrators. + +Use these commands to start the Rails console: + +```sh +# Omnibus GitLab +gitlab-rails console + +# Installation from source +cd /home/git/gitlab +sudo -u git -H bin/rails console RAILS_ENV=production +``` + +Then run `Feature.enable(:approval_rules)` to enable the feature flag. + +The documentation for the older interface can be accessed +[here](/11.7/ee/user/project/merge_requests/merge_request_approvals.html). + +## Overview + +Merge request approvals enable enforced code review by requiring specified people to approve a merge request before it can be unblocked for merging. + +## Use cases + +1. Enforcing review of all code that gets merged into a repository. +2. Specifying code maintainers for an entire repository. +3. Specifying reviewers for a given proposed code change. +4. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes. + +## Editing approvals + +To edit the merge request approvals: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals**. + + ![Approvals starter project empty](img/approvals_starter_project_empty.png) + +1. Click **Edit**. +1. Search for users or groups that will be [eligible to approve](#eligible-approvers) + merge requests and click the **Add** button to add them as approvers. Note: selecting + approvers is optional. +1. Set the minimum number of required approvals under the **No. approvals required** + box. Note: the minimum can be 0. +1. Click **Update approvers**. + + ![Approvals starter project edit](img/approvals_starter_project_edit.png) + +The steps above are the minimum required to get approvals working in your +merge requests, but there are a couple more options available that might be +suitable to your workflow: + +- Choose whether the default settings can be + [overridden per merge request](#overriding-the-merge-request-approvals-default-settings) +- Choose whether [approvals will be reset with new pushed commits](#resetting-approvals-on-push) + +## Editing approvals **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. + +CAUTION: **Caution:** +There was a [regression affecting this feature in 11.8](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9648). We recommend upgrading _at least_ to version 11.8.2. to avoid any issues. + +NOTE: **Note:** +In 11.8 this feature does not work in [private groups](https://gitlab.com/gitlab-org/gitlab-ee/issues/10356). + +For GitLab Premium, [multiple approver rules](#multiple-approval-rules-premium) can be configured. To configure the merge +request approval rules: + +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Click **Add approvers** to create a new approval rule. +1. Just like in [GitLab Starter](#editing-approvals), select the approval members and aprovals required. +1. Give the approval rule a name that describes the set of approvers selected. +1. Click **Add approvers** to submit the new rule. + + ![Approvals premium project edit](img/approvals_premium_project_edit.png) + +## Multiple approval rules **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. + +For GitLab Premium, a merge request's overall approval status is determined by a set of rules. Each rule contains: + +- A set of [eligible approvers](#eligible-approvers). +- A minimum number of approvals required. + +When an [eligible approver](#eligible-approvers) approves a merge request, it will reduce the number of approvals left for +all rules that the approver belongs to. + +![Approvals premium merge request widget](img/approvals_premium_mr_widget.png) + +If no approval rules are set, then the overall minimum number of approvals required can be configured. With no approval rules, +any [eligible approver](#eligible-approvers) may approve. + +## Eligible approvers + +The following can approve merge requests: + +- Users being added as approvers at project or merge request level. +- [Code owners](https://docs.gitlab.com/ee/user/project/code_owners.html) related to the merge request ([introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5). + +An individual user can be added as an approver for a project if they are a member of: + +- The project. +- The project's immediate parent group. +- A group that has access to the project via a [share](../members/share_project_with_groups.md). + +A group can also be added as an approver. [In the future](https://gitlab.com/gitlab-org/gitlab-ee/issues/2048), +group approvers will be restricted. + +If a user is added as an individual approver and is also part of a group approver, +then that user is just counted once. The merge request author, as well as users who have committed +to the merge request, do not count as eligible approvers, +if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) +and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) +are enabled on the project settings. + +### Implicit approvers + +If the number of required approvals is greater than the number of approvers, +other users will become implicit approvers to fill the gap. +Those implicit approvers include members of the given project with Developer role or higher. + +## Adding or removing an approval + +If approvals are activated for the given project, when a user visits an open +merge request, depending on their [eligibility](#eligible-approvers), one of +the following is possible: + +- **They are not an eligible approver**: They cannot do anything with respect + to approving this merge request. + +- **They have not approved this merge request**: + + - If the required number of approvals has _not_ been yet met, they can approve + it by clicking the displayed **Approve** button. + ![Approve](img/approve.png) + - If the required number of approvals has already been met, they can still + approve it by clicking the displayed **Approve additionally** button. + ![Add approval](img/approve_additionally.png) + +- **They have already approved this merge request**: They can remove their approval. + + ![Remove approval](img/remove_approval.png) + +NOTE: **Note:** +The merge request author is only allowed to approve their own merge request +if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is disabled on the project settings. + +For a given merge request, if the approval restrictions have been satisfied, +the merge request is unblocked and can be merged. +Note, that meeting the required number of approvals is a necessary, but not +sufficient condition for unblocking a merge request from being merged. There +are other conditions that may block it, such as merge conflicts, +[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved) +or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). + +## Code Owners approvals **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. + +It is possible to require at least one approval for each entry in the +[`CODEOWNERS` file](https://docs.gitlab.com/ee/user/project/code_owners.html) that matches a file changed in +the merge request. To enable this feature: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals**. +1. Tick the **Require approval from code owners** checkbox + checkbox. +1. Click **Save changes**. + +When this feature is enabled, all merge requests will need approval +from one code owner per matched rule before it can be merged. + +## Overriding the merge request approvals default settings + +> Introduced in GitLab Enterprise Edition 9.4. + +NOTE: **Note:** +If you are using GitLab Premium, things are a little different with [multiple approval rules](#multiple-approval-rules-premium). +Read the differences [in GitLab Premium when overriding merge request approvals](#overriding-merge-request-approvals-default-settings-premium). + +If approvals are [set at the project level](#editing-approvals), the +default configuration (number of required approvals and approvers) can be +overridden for each merge request in that project. + +One possible scenario would be to to assign a group of approvers at the project +level and change them later when creating or editing the merge request. + +First, you have to enable this option in the project's settings: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals** +1. Tick the "Can override approvers and approvals required per merge request" + checkbox + + ![Approvals can override](img/approvals_can_override.png) + +1. Click **Save changes** + +NOTE: **Note:** +If approver overriding is enabled +and the project level approvers are changed after a merge request is created, +the merge request retains the previous approvers. +However, the approvers can be changed by [editing the merge request](#overriding-the-merge-request-approvals-default-settings). + +--- + +The default approval settings can now be overridden when creating a +[merge request](index.md) or by editing it after it's been created: + +1. Click **Edit** under the **Approvers** section. +1. Search for users or groups that will be [eligible to approve](#eligible-approvers) + merge requests and click the **Add** button to add them as approvers or + remove existing approvers that were set in the project's settings. +1. If you want to change the number of required approvals, set a new number + in the **No. approvals required** box. +1. Click **Update approvers**. + +There are however some restrictions: + +- The amount of required approvals, if changed, must be greater than the default + set at the project level. This ensures that you're not forced to adjust settings + when someone is unavailable for approval, yet the process is still enforced. + +NOTE: **Note:** +If you are contributing to a forked project, things are a little different. +Read what happens when the +[source and target branches are not the same](#merge-requests-with-different-source-branch-and-target-branch-projects). + +## Overriding merge request approvals default settings **[PREMIUM]** + +In GitLab Premium, when the approval rules are [set at the project level](#editing-approvals-premium), and +**Can override approvers and approvals required per merge request** is checked, there are a few more +restrictions (compared to [GitLab Starter](#overriding-the-merge-request-approvals-default-settings)): + +- Approval rules can be added to an MR with no restriction. +- For project sourced approval rules, editing and removing approvers is not allowed. +- The approvals required of all approval rules is configurable, but if a rule is backed by a project rule, then it is restricted +to the minimum approvals required set in the project's corresponding rule. + +## Resetting approvals on push + +If approvals are [set at the project level](#editing-approvals), +you can choose whether all approvals on a merge request are removed when +new commits are pushed to the source branch of the merge request: + +1. Navigate to your project's **Settings > General** and expand + **Merge request approvals** +1. Tick the "Remove all approvals in a merge request when new commits are pushed to its source branch" + checkbox + + ![Approvals remove on push](img/approvals_remove_on_push.png) + +1. Click **Save changes** + +NOTE: **Note:** +Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) +from the UI. +However, approvals will be reset if the target branch is changed. + +If you want approvals to persist, independent of changes to the merge request, +turn this setting to off by unchecking the box and saving the changes. + +## Allowing merge request authors to approve their own merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. + +You can allow merge request authors to self-approve merge requests by +enabling it [at the project level](#editing-approvals). Authors +also need to be included in the approvers list in order to be able to +approve their merge request. + +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox, which is enabled by default. +1. Click **Save changes**. + +## Prevent approval of merge requests by their committers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. + +You can prevent users that have committed to a merge request from approving it by +enabling [**Prevent approval of merge requests by their committers**](#prevent-approval-of-merge-requests-by-their-committers). + +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Tick the checkbox **Prevent approval of merge requests by their committers**. +1. Click **Save changes**. + +## Merge requests with different source branch and target branch projects + +If the merge request source branch and target branch belong to different +projects (which happens in merge requests in forked projects), everything is +with respect to the target branch's project (typically the original project). +In particular, since the merge request in this case is part of the target +branch's project, the relevant settings are the target project's. The source +branch's project settings are not applicable. Even if you start the merge +request from the source branch's project UI, pay attention to the created merge +request itself. It belongs to the target branch's project. + +## Approver suggestions + +Approvers are suggested for merge requests based on the previous authors of the files affected by the merge request. + +## Filtering merge requests by approvers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9468) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.9. + +To filter merge requests by an individual approver, you can type (or select from +the dropdown) `approver` and select the user. + +![Filter MRs by an approver](img/filter_approver_merge_requests.png) |