diff options
Diffstat (limited to 'doc/api/merge_request_approvals.md')
| -rw-r--r-- | doc/api/merge_request_approvals.md | 132 |
1 files changed, 123 insertions, 9 deletions
diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 5b8bad1d685..ea049c46e73 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -388,7 +388,7 @@ You can update project approval rules using the following endpoint: PUT /projects/:id/approval_rules/:approval_rule_id ``` -**Important:** Approvers and groups not in the `users`/`groups` parameters will be **removed** +**Important:** Approvers and groups not in the `users`/`groups` parameters are **removed** **Parameters:** @@ -516,7 +516,7 @@ the following endpoint: PUT /projects/:id/approvers ``` -**Important:** Approvers and groups not in the request will be **removed** +**Important:** Approvers and groups not in the request are **removed** **Parameters:** @@ -567,6 +567,120 @@ PUT /projects/:id/approvers } ``` +## External Project-level MR approvals **(ULTIMATE)** + +Configuration for approvals on a specific Merge Request which makes a call to an external HTTP resource. + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 13.10. +> - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** + +### Get project external approval rules **(ULTIMATE)** + +You can request information about a project's external approval rules using the following endpoint: + +```plaintext +GET /projects/:id/external_approval_rules +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | + +```json +[ + { + "id": 1, + "name": "Compliance Check", + "project_id": 6, + "external_url": "https://gitlab.com/example/test.json", + "protected_branches": [ + { + "id": 14, + "project_id": 6, + "name": "master", + "created_at": "2020-10-12T14:04:50.787Z", + "updated_at": "2020-10-12T14:04:50.787Z", + "code_owner_approval_required": false + } + ] + } +] +``` + +### Create external approval rule **(ULTIMATE)** + +You can create a new external approval rule for a project using the following endpoint: + +```plaintext +POST /projects/:id/external_approval_rules +``` + +| Attribute | Type | Required | Description | +|------------------------|----------------|----------|----------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `name` | string | yes | Display name of approval rule | +| `external_url` | string | yes | URL of external approval resource | +| `protected_branch_ids` | `array<Integer>` | no | The ids of protected branches to scope the rule by | + +### Delete external approval rule **(ULTIMATE)** + +You can delete an external approval rule for a project using the following endpoint: + +```plaintext +DELETE /projects/:id/external_approval_rules/:rule_id +``` + +| Attribute | Type | Required | Description | +|------------------------|----------------|----------|----------------------------------------------------| +| `rule_id` | integer | yes | The ID of an approval rule | +| `id` | integer | yes | The ID of a project | + +### Update external approval rule **(ULTIMATE)** + +You can update an existing external approval rule for a project using the following endpoint: + +```plaintext +PATCH /projects/:id/external_approval_rules/:rule_id +``` + +| Attribute | Type | Required | Description | +|------------------------|----------------|----------|----------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `rule_id` | integer | yes | The ID of an external approval rule | +| `name` | string | no | Display name of approval rule | +| `external_url` | string | no | URL of external approval resource | +| `protected_branch_ids` | `array<Integer>` | no | The ids of protected branches to scope the rule by | + +### Enable or disable External Project-level MR approvals **(ULTIMATE SELF)** + +Enable or disable External Project-level MR approvals is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../user/feature_flags.md) +can enable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:ff_compliance_approval_gates) +# For a single project +Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:ff_compliance_approval_gates) +# For a single project +Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>)) +``` + ## Merge Request-level MR approvals Configuration for approvals on a specific Merge Request. Must be authenticated for all endpoints. @@ -670,7 +784,7 @@ the following endpoint: PUT /projects/:id/merge_requests/:merge_request_iid/approvers ``` -**Important:** Approvers and groups not in the request will be **removed** +**Important:** Approvers and groups not in the request are **removed** **Parameters:** @@ -741,8 +855,8 @@ You can request information about a merge request's approval state by using the GET /projects/:id/merge_requests/:merge_request_iid/approval_state ``` -The `approval_rules_overwritten` will be `true` if the merge request level rules -are created for the merge request. If there's none, it'll be `false`. +The `approval_rules_overwritten` are `true` if the merge request level rules +are created for the merge request. If there are none, it is `false`. This includes additional information about the users who have already approved (`approved_by`) and whether a rule is already approved (`approved`). @@ -905,8 +1019,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules | `group_ids` | Array | no | The ids of groups as approvers | **Important:** When `approval_project_rule_id` is set, the `name`, `users` and -`groups` of project-level rule will be copied. The `approvals_required` specified -will be used. +`groups` of project-level rule are copied. The `approvals_required` specified +is used. ```json { @@ -977,7 +1091,7 @@ You can update merge request approval rules using the following endpoint: PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id ``` -**Important:** Approvers and groups not in the `users`/`groups` parameters will be **removed** +**Important:** Approvers and groups not in the `users`/`groups` parameters are **removed** **Important:** Updating a `report_approver` or `code_owner` rule is not allowed. These are system generated rules. @@ -1098,7 +1212,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve 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 match the current HEAD of the merge request for the approval to be added. If it -does not match, the response code will be `409`. +does not match, the response code is `409`. ```json { |