diff --git a/doc/api/merge_request_approval_settings.md b/doc/api/merge_request_approval_settings.md index e0d16e12c960c8369fd613922616a47ea772e306..3a03d98cc9c0cdedb5daa2a886298dcb413bf3b9 100644 --- a/doc/api/merge_request_approval_settings.md +++ b/doc/api/merge_request_approval_settings.md @@ -17,6 +17,9 @@ Configuration for [approval settings on all merge requests](../user/project/merge_requests/approvals/settings.md) in a group or project. All endpoints require authentication. +NOTE: +Approval settings control security-critical behaviors such as whether authors can approve their own merge requests and whether approval rules can be overridden. Access to modify these settings is restricted to users with appropriate administrative roles to maintain security integrity. + ## Group MR approval settings Prerequisites: @@ -90,6 +93,10 @@ Example response: Update the merge request approval settings of a group. +Prerequisites: + +- You must have the Owner role in the group. + ```plaintext PUT /groups/:id/merge_request_approval_setting ``` @@ -228,6 +235,10 @@ Example response: Update the merge request approval settings of a project. +Prerequisites: + +- You must have the Maintainer role in the project. + ```plaintext PUT /projects/:id/merge_request_approval_setting ``` diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 17d4474fb164b7b6cefb80cd43449df3fc2ae2dd..1ba57645b9e8865ad0242cfd8b53c7a21bfda294 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -25,7 +25,12 @@ This API manages the configuration for approvals on merge requests in your proje - Reset all approvals, not just your own, on a merge request. - View and manage approval rules for a project. -All endpoints require authentication. +All endpoints require authentication. Different endpoints have different authorization requirements: + +- **Viewing approval information**: Requires at least the Reporter role for the project. +- **Approving/unapproving merge requests**: Requires being an [eligible approver](../user/project/merge_requests/approvals/rules.md#eligible-approvers). +- **Managing project-level approval rules**: Requires at least the Maintainer role for the project. +- **Managing merge request-level approval rules**: Requires at least the Developer role for the project or being the merge request author (when permitted by project settings). ## Approve merge request @@ -146,6 +151,9 @@ curl --request PUT \ These endpoints apply to projects and their approval rules. All endpoints require authentication. +NOTE: +For security reasons, creating, updating, and deleting project-level approval rules requires at least the Maintainer role for the project. This ensures that only authorized users can modify security-critical approval rule configurations. + ### Retrieve approval configuration for a project Retrieves the approval configuration for a project. @@ -177,8 +185,11 @@ Supported attributes: ### Update approval configuration for a project -Updates the approval configuration for a project. The currently authenticated user must be an -[eligible approver](../user/project/merge_requests/approvals/rules.md#eligible-approvers). +Updates the approval configuration for a project. + +Prerequisites: + +- You must have at least the Maintainer role for the project. ```plaintext POST /projects/:id/approvals @@ -495,6 +506,10 @@ Supported attributes: Creates an approval rule for a project. +Prerequisites: + +- You must have at least the Maintainer role for the project. + The `rule_type` field supports these rule types: - `any_approver`: A pre-configured default rule with `approvals_required` set to `0`. @@ -629,6 +644,10 @@ curl --request POST \ Updates a specified approval rule for a project. This endpoint removes any approvers and groups not defined in the `group_ids`, `user_ids`, or `usernames` attributes. +Prerequisites: + +- You must have at least the Maintainer role for the project. + Hidden groups (private groups the user doesn't have permission to view) that are not in the `users` or `groups` parameters are preserved by default. To remove them, set `remove_hidden_groups` to `true`. This ensures hidden groups are not removed unintentionally when a user updates an approval rule. @@ -738,6 +757,10 @@ Supported attributes: Deletes an approval rule for a specified project. +Prerequisites: + +- You must have at least the Maintainer role for the project. + ```plaintext DELETE /projects/:id/approval_rules/:approval_rule_id ``` @@ -1091,6 +1114,11 @@ is set with the ID of an existing approval rule from the project, this endpoint: - Copies the values for `name`, `users`, and `groups` from the project's rule. - Uses the `approvals_required` value you specify. +Prerequisites: + +- You must have at least the Developer role for the project, or be the author of the merge request. +- The project setting [Prevent editing approval rules in merge requests](../user/project/merge_requests/approvals/settings.md#prevent-editing-approval-rules-in-merge-requests) must be disabled (unless you have administrator access). + ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/approval_rules ``` @@ -1173,6 +1201,11 @@ not included in the `group_ids`, `user_ids`, or `usernames` attributes. The `report_approver` or `code_owner` rules are system-generated, and you cannot edit them. +Prerequisites: + +- You must have at least the Developer role for the project, or be the author of the merge request. +- The project setting [Prevent editing approval rules in merge requests](../user/project/merge_requests/approvals/settings.md#prevent-editing-approval-rules-in-merge-requests) must be disabled (unless you have administrator access). + ```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id ``` @@ -1253,12 +1286,17 @@ Supported attributes: Deletes an approval rule for a specified merge request. +The `report_approver` or `code_owner` rules are system-generated, and you cannot edit them. + +Prerequisites: + +- You must have at least the Developer role for the project, or be the author of the merge request. +- The project setting [Prevent editing approval rules in merge requests](../user/project/merge_requests/approvals/settings.md#prevent-editing-approval-rules-in-merge-requests) must be disabled (unless you have administrator access). + ```plaintext DELETE /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id ``` -The `report_approver` or `code_owner` rules are system-generated, and you cannot edit them. - Supported attributes: | Attribute | Type | Required | Description | diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 2f5010c14c336c76c8d0da8225e3991ee6cf232c..ad7da4c1173bb02bf792a49798a6cfb6cc648e80 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -45,6 +45,9 @@ Prerequisites: - To add a group as an approver in GitLab.com, you must be a member of the group or the group must be public. +NOTE: +For security reasons, only users with at least the Maintainer role can create, edit, or delete approval rules. This requirement was strengthened to prevent unauthorized modification of approval rules that could bypass security controls. + To add a merge request approval rule: 1. On the left sidebar, select **Search or go to** and find your project. @@ -80,6 +83,9 @@ Prerequisites: - To add a group as an approver in GitLab.com, you must be a member of the group or the group must be public. +NOTE: +For security reasons, only users with at least the Maintainer role can create, edit, or delete approval rules. This requirement was strengthened to prevent unauthorized modification of approval rules that could bypass security controls. + To edit a merge request approval rule: 1. On the left sidebar, select **Search or go to** and find your project. @@ -140,6 +146,9 @@ Prerequisites: - You must be the author of the merge request. - The project setting [Prevent editing approval rules](settings.md#prevent-editing-approval-rules-in-merge-requests) is disabled. +NOTE: +While merge request authors with the Developer role can override approval rules on individual merge requests (when permitted by project settings), only users with at least the Maintainer role can modify the default project-level approval rules. This distinction ensures that security-critical approval rule configurations remain under appropriate administrative control. + To override approvers of a merge request: 1. When [creating a new merge request](../creating_merge_requests.md), scroll to the **Approval Rules** section, @@ -369,6 +378,24 @@ in the following ways: the [**Prevent committers approval**](settings.md#prevent-approvals-by-users-who-add-commits) project setting. +## Security considerations + +Approval rules are a critical security control that help ensure code changes receive appropriate review before being merged. To maintain the integrity of these security controls: + +- **Role-based access control**: Only users with at least the Maintainer role can create, edit, or delete project-level approval rules. This prevents unauthorized users from bypassing security controls by modifying approval requirements. + +- **Separation of concerns**: While merge request authors with the Developer role can override approval rules on individual merge requests (when permitted by project settings), they cannot modify the underlying project-level approval rule configurations. + +- **Administrative oversight**: Project administrators should regularly review approval rule configurations to ensure they align with security and compliance requirements. + +- **Audit trail**: All changes to approval rules are logged in the audit events for compliance and security monitoring purposes. + +For additional security, consider: + +- Enabling the [**Prevent editing approval rules in merge requests**](settings.md#prevent-editing-approval-rules-in-merge-requests) setting to prevent any overrides at the merge request level. +- Using [merge request approval policies](../../../application_security/policies/merge_request_approval_policies.md) for organization-wide enforcement of approval requirements. +- Implementing [code owners](../../codeowners/_index.md) to ensure domain experts review relevant changes. + ## Troubleshooting ### Approval rule name can't be blank