diff options
Diffstat (limited to 'doc/user/project/merge_requests/approvals')
| -rw-r--r-- | doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png | bin | 0 -> 42034 bytes | |||
| -rw-r--r-- | doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png | bin | 0 -> 25594 bytes | |||
| -rw-r--r-- | doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png | bin | 0 -> 12376 bytes | |||
| -rw-r--r-- | doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png | bin | 0 -> 13847 bytes | |||
| -rw-r--r-- | doc/user/project/merge_requests/approvals/index.md | 145 | ||||
| -rw-r--r-- | doc/user/project/merge_requests/approvals/rules.md | 232 | ||||
| -rw-r--r-- | doc/user/project/merge_requests/approvals/settings.md | 125 |
7 files changed, 502 insertions, 0 deletions
diff --git a/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png Binary files differnew file mode 100644 index 00000000000..306bf57354d --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png diff --git a/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png b/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png Binary files differnew file mode 100644 index 00000000000..669148a41d8 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png diff --git a/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png Binary files differnew file mode 100644 index 00000000000..a6636f0bc7f --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png diff --git a/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png b/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png Binary files differnew file mode 100644 index 00000000000..c5596b965ff --- /dev/null +++ b/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md new file mode 100644 index 00000000000..ac48e44da52 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/index.md @@ -0,0 +1,145 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html' +--- + +# Merge request approvals **(FREE)** + +> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. + +You can configure your merge requests so that they must be approved before +they can be merged. You can do this by creating [rules](rules.md) or by specifying +a list of users who act as [code owners](../../code_owners.md) for specific files. + +You can configure merge request approvals for each project. In higher GitLab tiers, +Administrators of self-managed GitLab instances can configure approvals +[for the entire instance](../../../admin_area/merge_requests_approvals.md). + +## How approvals work + +With [merge request approval rules](rules.md), you can set the minimum number of +required approvals before work can merge into your project. You can also extend these +rules to define what types of users can approve work. Some examples of rules you can create include: + +- Users with specific permissions can always approve work. +- [Code owners](../../code_owners.md) can approve work for files they own. +- Users with specific permissions can approve work, + [even if they don't have merge rights](rules.md#merge-request-approval-segregation-of-duties) + to the repository. +- Users with specific permissions can be allowed or denied the ability + to [override approval rules on a specific merge request](rules.md#edit-or-override-merge-request-approval-rules). + +You can also configure additional [settings for merge request approvals](settings.md) +for more control of the level of oversight and security your project needs, including: + +- [Prevent users from overriding a merge request approval rule.](settings.md#prevent-overrides-of-default-approvals) +- [Reset approvals when new code is pushed.](settings.md#reset-approvals-on-push) +- Allow (or disallow) [authors and committers](settings.md) to approve their own merge requests. +- [Require password authentication when approving.](settings.md#require-authentication-for-approvals) +- [Require security team approval.](settings.md#security-approvals-in-merge-requests) + +You can configure your merge request approval rules and settings through the GitLab +user interface or [with the API](../../../../api/merge_request_approvals.md). + +## Approve a merge request + +When an [eligible approver](rules.md#eligible-approvers) visits an open merge request, +GitLab displays one of these buttons after the body of the merge request: + +- **Approve**: The merge request doesn't yet have the required number of approvals. +- **Approve additionally**: The merge request has the required number of approvals. +- **Revoke approval**: The user viewing the merge request has already approved + the merge request. + +Eligible approvers can also use the `/approve` +[quick action](../../../project/quick_actions.md) when adding a comment to +a merge request. + +After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge +unless it's blocked for another reason. Merge requests can be blocked by other problems, +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). + +To prevent merge request authors from approving their own merge requests, +enable [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) +in your project's settings. + +If you enable [approval rule overrides](settings.md#prevent-overrides-of-default-approvals), +merge requests created before a change to default approval rules are not affected. +The only exceptions are changes to the [target branch](rules.md#approvals-for-protected-branches) +of the rule. + +## Optional approvals + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. + +GitLab allows all users with Developer or greater [permissions](../../../permissions.md) +to approve merge requests. Approvals in GitLab Free are optional, and don't prevent +a merge request from merging without approval. + +## Required approvals **(PREMIUM)** + +> Moved to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.9. + +Required approvals enforce code reviews by the number and type of users you specify. +Without the approvals, the work cannot merge. Required approvals enable multiple use cases: + +- Enforce review of all code that gets merged into a repository. +- Specify reviewers for a given proposed code change, and a minimum number + of reviewers, through [Approval rules](rules.md). +- Specify categories of reviewers, such as backend, frontend, quality assurance, or + database, for all proposed code changes. +- Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), + to determine who should review the work. +- [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) + before merging code that could introduce a vulnerability. **(ULTIMATE)** + +## Notify external services **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. +> - [Deployed behind a feature flag](../../../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can create an external approval rule to integrate approvals with third-party tools. +When users create, change, or close merge requests, GitLab sends a notification. +The users of the third-party tools can then approve merge requests from outside of GitLab. + +With this integration, you can integrate with third-party workflow tools, like +[ServiceNow](https://www.servicenow.co.uk/), or the custom tool of your choice. +You can modify your external approval rules +[by using the REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals). + +The lack of an external approval doesn't block the merging of a merge request. + +When [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, +changes to default approval rules will **not** be applied to existing +merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches) +of the rule. + +To learn more about use cases, feature discovery, and development timelines, +see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +## Related links + +- [Merge request approvals API](../../../../api/merge_request_approvals.md) +- [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md new file mode 100644 index 00000000000..32f0160771f --- /dev/null +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -0,0 +1,232 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +--- + +# Merge request approval rules + +Approval rules define how many [approvals](index.md) a merge request must receive before it can +be merged, and which users should do the approving. You can define approval rules: + +- [As project defaults](#add-an-approval-rule). +- [Per merge request](#edit-or-override-merge-request-approval-rules). +- [At the instance level](../../../admin_area/merge_requests_approvals.md) + +If you don't define a [default approval rule](#add-an-approval-rule), +any user can approve a merge request. Even if you don't define a rule, you can still +enforce a [minimum number of required approvers](settings.md) in the project's settings. + +You can define a single rule to approve merge requests from among the available +rules, or you can select [multiple approval rules](#add-multiple-approval-rules). + +Merge requests that target a different project, such as from a fork to the upstream project, +use the default approval rules from the target (upstream) project, not the source (fork). + +## Add an approval rule + +To add a merge request approval rule: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**, and then select **Add approval rule**. +1. Add a human-readable **Rule name**. +1. Set the number of required approvals in **Approvals required**. A value of `0` makes + [the rule optional](#configure-optional-approval-rules), and any number greater than `0` + creates a required rule. +1. To add users or groups as approvers, search for users or groups that are + [eligible to approve](#eligible-approvers), and select **Add**. GitLab suggests approvers based on + previous authors of the files changed by the merge request. + + NOTE: + On GitLab.com, you can add a group as an approver if you're a member of that group or the + group is public. + +1. Select **Add approval rule**. + +Users of GitLab Premium and higher tiers can create [additional approval rules](#add-multiple-approval-rules). + +Your configuration for approval rule overrides determines if the new rule is applied +to existing merge requests: + +- If [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, + changes to these default rules are not applied to existing merge requests, except for + changes to the [target branch](#approvals-for-protected-branches) of the rule. +- If approval rule overrides are not allowed, all changes to default rules + are applied to existing merge requests. Any approval rules that were previously + manually [overridden](#edit-or-override-merge-request-approval-rules) during the + period when approval rule overrides where allowed, are not modified. + +## Edit an approval rule + +To edit a merge request approval rule: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**, and then select **Edit**. +1. (Optional) Change the **Rule name**. +1. Set the number of required approvals in **Approvals required**. The minimum value is `0`. +1. Add or remove eligible approvers, as needed: + - *To add users or groups as approvers,* search for users or groups that are + [eligible to approve](#eligible-approvers), and select **Add**. + + NOTE: + On GitLab.com, you can add a group as an approver if you're a member of that group or the + group is public. + + - *To remove users or groups,* identify the group or user to remove, and + select **{remove}** **Remove**. +1. Select **Update approval rule**. + +## Add multiple approval rules **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab Premium 11.10. + +In GitLab Premium and higher tiers, you can enforce multiple approval rules on a +merge request, and multiple default approval rules for a project. If your tier +supports multiple default rules: + +- When [adding](#add-an-approval-rule) or [editing](#edit-an-approval-rule) an approval rule + for a project, GitLab displays the **Add approval rule** button even after a rule is defined. +- When editing or overriding multiple approval rules + [on a merge request](#edit-or-override-merge-request-approval-rules), GitLab + displays the **Add approval rule** button even after a rule is defined. + +When an [eligible approver](#eligible-approvers) approves a merge request, it +reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to: + + + +## Eligible approvers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. + +To be eligible as an approver for a project, a user must be a member of one or +more of these: + +- The project. +- The project's immediate parent [group](#group-approvers). +- A group that has access to the project via a [share](../../members/share_project_with_groups.md). +- A [group added as approvers](#group-approvers). + +The following users can approve merge requests if they have Developer or +higher [permissions](../../../permissions.md): + +- Users added as approvers at the project or merge request level. +- Users who are [Code owners](#code-owners-as-eligible-approvers) of the files + changed in the merge request. + +To show who has participated in the merge request review, the Approvals widget in +a merge request displays a **Commented by** column. This column lists eligible approvers +who commented on the merge request. It helps authors and reviewers identify who to +contact with questions about the merge request's content. + +If the number of required approvals is greater than the number of assigned approvers, +approvals from other users with Developer [permissions](../../../permissions.md) or higher +in the project counts toward meeting the required number of approvals, even if the +users were not explicitly listed in the approval rules. + +### Group approvers + +You can add a group of users as approvers, but those users count as approvers only if +they have direct membership to the group. 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). + +A user's membership in an approvers group affects their individual ability to +approve in these ways: + +- A user already part of a group approver who is later added as an individual approver + counts as one approver, and not two. +- Merge request authors do not count as eligible approvers on their own merge requests by default. + To change this behavior, disable the + [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) + project setting. +- Committers to merge requests can approve a merge request. To change this behavior, enable the + [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) + project setting. + +### Code owners as eligible approvers + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. +> - Moved to GitLab Premium in 13.9. + +If you add [code owners](../../code_owners.md) to your repository, the owners of files +become eligible approvers in the project. To enable this merge request approval rule: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Locate **Any eligible user** and select the number of approvals required: + +  + +You can also +[require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) +for protected branches. **(PREMIUM)** + +## Merge request approval segregation of duties + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. +> - Moved to GitLab Premium in 13.9. + +You may need to grant users with [Reporter permissions](../../../permissions.md#project-members-permissions), +permission to approve merge requests before they can merge to a protected branch. +Some users (like managers) may not need permission to push or merge code, but still need +oversight on proposed work. To enable approval permissions for these users without +granting them push access: + +1. [Create a new group](../../../group/index.md#create-a-group). +1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), + and select the Reporter role for the user. +1. [Share the project with your group](../../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), + based on the Reporter role. +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select **Add approval rule** or **Update approval rule**. +1. [Add the group](../../../group/index.md#create-a-group) to the permission list. + +  + +### Edit or override merge request approval rules + +By default, the merge request author (or a user with sufficient [permissions](../../../permissions.md)) +can edit the approval rule listed in a merge request. When editing an approval rule +on a merge request, you can either add or remove approvers: + +1. In the merge request, find the **Approval rules section**. +1. When creating a new merge request, scroll to the **Approval Rules** section, + and add or remove your desired approval rules before selecting **Create merge request**. +1. When viewing an existing merge request: + 1. Select **Edit**. + 1. Scroll to the **Approval Rules** section. + 1. Add or remove your desired approval rules. + 1. Select **Save changes**. + +Administrators can change the [merge request approvals settings](settings.md#prevent-overrides-of-default-approvals) +to prevent users from overriding approval rules for merge requests. + +## Configure optional approval rules + +Merge request approvals can be optional for projects where approvals are +appreciated, but not required. To make an approval rule optional: + +- When you [create or edit a rule](#edit-an-approval-rule), set **Approvals required** to `0`. +- Use the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule) + to set the `approvals_required` attribute to `0`. + +## Approvals for protected branches **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab Premium 12.8. + +Approval rules are often relevant only to specific branches, like your +[default branch](../../repository/branches/default.md). To configure an +approval rule for certain branches: + +1. [Create an approval rule](#add-an-approval-rule). +1. Go to your project and select **Settings**. +1. Expand **Merge request (MR) approvals**. +1. Select a **Target branch**: + - To protect all branches, select **Any branch**. + - To select a specific branch, select it from the list: + +  +1. To enable this configuration, read + [Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md new file mode 100644 index 00000000000..8769f6a7470 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -0,0 +1,125 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +--- + +# Merge request approval settings + +You can configure the settings for [merge request approvals](index.md) to +ensure the approval rules meet your use case. You can also configure +[approval rules](rules.md), which define the number and type of users who must +approve work before it's merged. Merge request approval settings define how +those rules are applied as a merge request moves toward completion. + +## Edit merge request approval settings + +To view or edit merge request approval settings: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. + +In this section of general settings, you can configure the settings described +on this page. + +## Prevent overrides of default approvals + +By default, users can override the approval rules you [create for a project](rules.md) +on a per-merge request basis. If you don't want users to change approval rules +on merge requests, you can disable this setting: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Prevent users from modifying MR approval rules in merge requests** checkbox. +1. Select **Save changes**. + +TODO This change affects all open merge requests. + +## Reset approvals on push + +By default, an approval on a merge request remains in place, even if you add more changes +after the approval. If you want to remove all existing approvals on a merge request +when more changes are added to it: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Require new approvals when new commits are added to an MR** checkbox. +1. Select **Save changes**. + +Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) +However, approvals are reset if the target branch is changed. + +## Prevent authors from approving their own work **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. +> - Moved to GitLab Premium in 13.9. + +By default, the author of a merge request cannot approve it. To change this setting: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Clear the **Prevent MR approval by the author** checkbox. +1. Select **Save changes**. + +Authors can edit the approval rule in an individual merge request and override +this setting, unless you configure one of these options: + +- [Prevent overrides of default approvals](#prevent-overrides-of-default-approvals) at + the project level. +- *(Self-managed instances only)* Prevent overrides of default approvals + [at the instance level](../../../admin_area/merge_requests_approvals.md). When configured + at the instance level, you can't edit this setting at the project or individual + merge request levels. + +## Prevent committers from approving their own work **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. + +By default, users who commit to a merge request can still approve it. At both +the project level or [instance level](../../../admin_area/merge_requests_approvals.md) +you can prevent committers from approving merge requests that are partially +their own. To do this: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Prevent MR approvals from users who make commits to the MR** checkbox. + If this checkbox is cleared, an administrator has disabled it + [at the instance level](../../../admin_area/merge_requests_approvals.md), and + it can't be changed at the project level. +1. Select **Save changes**. + +Even with this configuration, [code owners](../../code_owners.md) who contribute +to a merge request can approve merge requests that affect files they own. + +To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), +read the official Git documentation for an explanation. + +## Require authentication for approvals + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. +> - Moved to GitLab Premium in 13.9. + +You can force potential approvers to first authenticate with a password. This +permission enables an electronic signature for approvals, such as the one defined by +[Code of Federal Regulations (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)): + +1. Enable password authentication for the web interface, as described in the + [sign-in restrictions documentation](../../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. +1. Select the **Require user password for approvals** checkbox. +1. Select **Save changes**. + +## Security approvals in merge requests **(ULTIMATE)** + +You can require that a member of your security team approves a merge request if a +merge request could introduce a vulnerability. To learn more, see +[Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). + +## Related links + +- [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) +- [Compliance Dashboard](../../../compliance/compliance_dashboard/index.md) +- [Merge request approvals API](../../../../api/merge_request_approvals.md) |
