Skip to content

G
gitlab-ce
Commit 819a7cbb authored by Evan Read's avatar Evan Read
Browse files
Options

Merge branch 'docs-mr-approvals' into 'master' 

MR Approvals documentation Revamp

See merge request gitlab-org/gitlab!23861
parents 7497dafc 759b88b2
Hide whitespace changes
Inline Side-by-side
Showing with 165 additions and 231 deletions
doc/api/merge_request_approvals.md
View file @ 819a7cbb
......@@ -956,7 +956,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve
| `id` | integer | yes | The ID of a project |
| `merge_request_iid` | integer | yes | The IID of MR |
| `sha` | string | no | The HEAD of the MR |
| `approval_password` **(STARTER)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request-starter) is enabled in the project settings. |
| `approval_password` **(STARTER)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request) is enabled in the project settings. |
The `sha` parameter works in the same way as
when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must
......
doc/user/application_security/index.md
View file @ 819a7cbb
......@@ -148,12 +148,15 @@ Clicking on this button will create a merge request to apply the solution onto t
![Create merge request from vulnerability](img/create_issue_with_list_hover.png)
## Security approvals in merge requests **(ULTIMATE)**
## Security approvals in merge requests
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2.
Merge Request Approvals can be configured to require approval from a member
of your security team when a vulnerability, or a software license compliance violation would be introduced by a merge request.
Merge Request Approvals can be configured to require approval from a member of your
security team when a merge request would introduce one of the following security issues:
- a security vulnerability
- a software license compliance violation
This threshold is defined as `high`, `critical`, or `unknown`
severity. When any vulnerabilities are present within a merge request, an
......
doc/user/project/code_owners.md
View file @ 819a7cbb
......@@ -33,7 +33,7 @@ the given file.
Once you've set Code Owners to a project, you can configure it to
receive approvals:
- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers-starter). **(STARTER)**
- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers).
- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
Once set, Code Owners are displayed in merge requests widgets:
......
doc/user/project/merge_requests/merge_request_approvals.md
View file @ 819a7cbb
......@@ -7,101 +7,37 @@ type: reference, concepts
> Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/blog/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only).
Merge request approvals enable enforced code review by requiring specified people
to approve a merge request before it can be unblocked for merging.
to approve a merge request before it can be merged.
## Use cases
Merge request approvals enable multiple use cases:
1. Enforcing review of all code that gets merged into a repository.
1. Specifying code maintainers for an entire repository.
1. Specifying reviewers for a given proposed code change.
1. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes.
- Enforcing review of all code that gets merged into a repository.
- Specifying reviewers for a given proposed code change, as well as a minimum number
of reviewers, through [Approval rules](#approval-rules)
- Specifying categories of reviewers, such as backend, frontend, quality assurance,
database, etc., for all proposed code changes.
- Automatically designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers),
determined by the files changed in a merge request.
- [Requiring approval from a security team](#security-approvals-in-merge-requests-ultimate)
before merging code that could introduce a vulnerability.**(ULTIMATE)**
## Enabling the new approvals interface
NOTE: **Note:**
Prior to 12.0, 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.
## 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:
## Approval rules
- 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)
Approval rules define how many approvals a merge request must receive before it can
be merged, and optionally which users should do the approving. This can be defined:
## Editing approvals **(PREMIUM)**
- [As project defaults](#adding--editing-a-default-approval-rule)
- [Per merge request](#editing--overriding-approval-rules-per-merge-request)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
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 approvals required.
1. Give the approval rule a name that describes the set of approvers selected.
1. Click **Add approval rule** to submit the new rule.
![Approvals premium project edit](img/approvals_premium_project_edit_v12_5.png)
## Multiple approval rules **(PREMIUM)**
If no approval rules are defined, any user can approve a merge request, though the default
minimum number of required approvers can still be set in the [project settings for merge request approvals](#merge-request-approvals-project-settings).
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
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
### Eligible approvers
The following can approve merge requests:
- Users being added as approvers at project or merge request level.
- [Code owners](#code-owners-as-eligible-approvers-starter) to the files changed by the merge request.
- [Code owners](#code-owners-as-eligible-approvers) to the files changed by the merge request.
An individual user can be added as an approver for a project if they are a member of:
......@@ -109,8 +45,8 @@ An individual user can be added as an approver for a project if they are a membe
- 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/issues/2048),
group approvers will be restricted.
A group of users can also be added as approvers. In the future, group approvers may be
[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/issues/2048).
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
......@@ -119,19 +55,25 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei
and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default)
are enabled on the project settings.
### Code Owners as eligible approvers **(STARTER)**
#### Implicit approvers
If the number of required approvals is greater than the number of assigned approvers,
approvals from other users will count towards meeting the requirement. These would be
users with developer [permissions](../../permissions.md) or higher in the project who
were not explicitly listed in the approval rules.
#### Code Owners as eligible approvers
> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5.
Once you've added [Code Owners](../code_owners.md) to your
repository, the owners to the corresponding files will become
eligible approvers, together with members with Developer or
higher permissions.
If you add [Code Owners](../code_owners.md) to your repository, the owners to the
corresponding files will become eligible approvers, together with members with Developer
or higher permissions.
To enable this merge request approval rule:
1. Navigate to your project's **Settings > General** and expand
**Merge request approvals**.
**Merge request approvals**.
1. Locate **All members with Developer role or higher and code owners (if any)** and click **Edit** to choose the number of approvals required.
![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v12_4.png)
......@@ -144,205 +86,185 @@ indistinguishably.
Alternatively, you can **require**
[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
### Implicit approvers
### Adding / editing a default approval rule
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.
To add or edit the default merge request approval rule:
## Adding or removing an approval
1. Navigate to your project's **Settings > General** and expand **Merge request approvals**.
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:
1. Click **Add approval rule**, or **Edit**.
- Add or change the **Rule name**.
- Set the number of required approvals in **No. approvals required**. The minimum value is `0`.
- (Optional) 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. Before typing
in the search field, approvers will be suggested based on the previous authors of
the files being changed by the merge request.
- (Optional) Click the **"trashcan"** button next to a group or user to delete it from
the rule.
1. Click **Add approval rule** or **Update approval rule**.
- **They are not an eligible approver**: They cannot do anything with respect
to approving this merge request.
Any merge requests that were created before changing the rules will not be changed.
They will keep the original approval rules, unless manually [overridden](#editing--overriding-approval-rules-per-merge-request).
- **They have not approved this merge request**:
NOTE: **Note:**
If a merge request targets a different project, such as from a fork to the upstream project,
the default approval rules will be taken from the target (upstream) project, not the
source (fork).
- If the required number of approvals has _not_ been yet met, they can approve
it by clicking the displayed **Approve** button.
#### Editing / overriding approval rules per merge request
![Approve](img/approve.png)
> Introduced in GitLab Enterprise Edition 9.4.
- If the required number of approvals has already been met, they can still
approve it by clicking the displayed **Approve additionally** button.
By default, the merge request approval rule listed in each merge request (MR) can be
edited by the MR author or a user with sufficient [permissions](../../permissions.md).
This ability can be disabled in the [merge request approvals settings](#prevent-overriding-default-approvals).
![Add approval](img/approve_additionally.png)
One possible scenario would be to add more approvers than were defined in the default
settings.
- **They have already approved this merge request**: They can remove their approval.
When creating or editing a merge request, find the **Approval rules** section, then follow
the same steps as [Adding / editing a default approval rule](#adding--editing-a-default-approval-rule).
![Remove approval](img/remove_approval.png)
### Multiple approval rules **(PREMIUM)**
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-threads-are-resolved)
or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md).
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
## Overriding the merge request approvals default settings
In GitLab Premium, it is possible to have multiple approval rules per merge request,
as well as multiple default approval rules per project.
> Introduced in GitLab Enterprise Edition 9.4.
Adding or editing multiple default rules is identical to
[adding or editing a single default approval rule](#adding--editing-a-default-approval-rule),
except the **Add approval rule** button will be available to add more rules, even after
a rule is already defined.
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).
Similarly, editing or overriding multiple approval rules per merge request is identical
to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request),
except the **Add approval rule** button will be available to add more rules, even after
a rule is already defined.
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.
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.
![Approvals premium merge request widget](img/approvals_premium_mr_widget.png)
One possible scenario would be to assign a group of approvers at the project
level and change them later when creating or editing the merge request.
## Adding or removing an approval
First, you have to enable this option in the project's settings:
When an [eligible approver](#eligible-approvers) visits an open merge request,
one of the following is possible:
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
- If the required number of approvals has _not_ been yet met, they can approve
it by clicking the displayed **Approve** button.
![Approvals can override](img/approvals_can_override.png)
![Approve](img/approve.png)
1. Click **Save changes**
- If the required number of approvals has already been met, they can still
approve it by clicking the displayed **Approve additionally** button.
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**.
![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:**
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).
The merge request author is not allowed to approve their own merge request if
[**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests)
is enabled in the project settings.
## Overriding merge request approvals default settings **(PREMIUM)**
Once the approval rules have been met, the merge request can be merged if there is nothing
else blocking it. Note that the merge request could still be blocked by other conditions,
such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved),
or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md).
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,
approval rules can be added to an MR with no restriction.
## Merge request approvals project settings
## Resetting approvals on push
The project settings for Merge request approvals are found by going to
**Settings > General** and expanding **Merge request approvals**.
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:
### Prevent overriding default approvals
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
By default, users are able to edit the approval rules in merge requests. If disabled,
the approval rules for all new merge requests will be determined by the
[default approval rules](#adding--editing-a-default-approval-rule). To disable this feature:
![Approvals remove on push](img/approvals_remove_on_push.png)
1. Uncheck the **Can override approvers and approvals required per merge request** checkbox.
1. Click **Save changes**
### Resetting approvals on push
You can force all approvals on a merge request to be removed when new commits are
pushed to the source branch of the merge request. If disabled, approvals will persist
even if there are changes added to the merge request. To enable this feature:
1. Check the **Remove all approvals in a merge request when new commits are pushed to its source branch**
checkbox.
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.
from the UI. However, approvals will be reset if the target branch is changed.
## Allowing merge request authors to approve their own merge requests
### Allowing merge request authors to approve their own merge requests
> [Introduced](https://gitlab.com/gitlab-org/gitlab/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
You can allow merge request authors to self-approve merge requests. Authors
also need to be included in the approvers list in order to be able to
approve their merge request.
approve their merge request. To enable this feature:
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. 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
### Prevent approval of merge requests by their committers
> [Introduced](https://gitlab.com/gitlab-org/gitlab/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).
You can prevent users that have committed to a merge request from approving it. To
enable this feature:
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. Check the **Prevent approval of merge requests by their committers** checkbox.
1. Click **Save changes**.
## Require authentication when approving a merge request **(STARTER)**
### Require authentication when approving a merge request
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0.
You can force the approver to enter a password in order to authenticate who is approving the merge request by
enabling **Require user password to approve**. This enables an Electronic Signature
for approvals such as the one defined by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)):
You can force the approver to enter a password in order to authenticate before adding
the approval. This enables an Electronic Signature for approvals such as the one defined
by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)).
To enable this feature:
1. Navigate to your project's **Settings > General** and expand **Merge request approvals**.
1. Tick the checkbox **Require user password to approve**.
1. Check the **Require user password to approve** checkbox.
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/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)
## Security approvals in merge requests **(ULTIMATE)**
> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2.
Merge Request Approvals can be configured to require approval from a member
of your security team when a vulnerability would be introduced by a merge request.
For more information, see
[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests-ultimate).
[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests).
## Enabling the new approvals interface
## License compliance approvals in merge requests **(ULTIMATE)**
Since [GitLab v12.0](https://gitlab.com/gitlab-org/gitlab/issues/10685), an updated approvals
interface is available by default. In versions older than 12.0, the updated interface is not
available unless the `approval_rules` feature flag is enabled, which can be done from
the Rails console by instance administrators.
> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3.
Use these commands to start the Rails console:
Merge Request Approvals can be configured to require approval from a member
of your security team when a blacklisted software license would be introduced by a merge request.
```shell
# Omnibus GitLab
gitlab-rails console
For more information, see
[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests-ultimate).
# 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 updated interface.
<!-- ## Troubleshooting
......
doc/user/search/index.md
View file @ 819a7cbb
......@@ -73,6 +73,15 @@ You can filter issues and merge requests by specific terms included in titles or
![filter issues by specific terms](img/issue_search_by_term.png)
### Filtering merge requests by approvers **(STARTER)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/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)
## Search history
You can view recent searches by clicking on the little arrow-clock icon, which is to the left of the search input. Click the search entry to run that search again. This feature is available for issues and merge requests. Searches are stored locally in your browser.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7