Skip to content

G
gitlab-ce
Commit 070689cb authored by Douwe Maan's avatar Douwe Maan
Browse files
Options

Merge branch '11877-public-approval-api-ee-docs' into 'master' 

Doc: add project approval rule endpoints

See merge request gitlab-org/gitlab-ce!31455
parents 2fa900ab 104fada7
Show whitespace changes
Inline Side-by-side
Showing with 238 additions and 56 deletions
doc/api/merge_request_approvals.md
View file @ 070689cb
...@@ -23,20 +23,98 @@ GET /projects/:id/approvals ...@@ -23,20 +23,98 @@ GET /projects/:id/approvals
```json ```json
{ {
"approvers": [ "approvals_before_merge": 2,
"reset_approvals_on_push": true,
"disable_overriding_approvers_per_merge_request": false
}
```
### Change configuration
>**Note:** This API endpoint is only available on 10.6 Starter and above.
If you are allowed to, you can change approval configuration using the following
endpoint:
```
POST /projects/:id/approvals
```
**Parameters:**
| Attribute | Type | Required | Description |
| ------------------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| `id` | integer | yes | The ID of a project |
| `approvals_before_merge` | integer | no | How many approvals are required before an MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. |
| `reset_approvals_on_push` | boolean | no | Reset approvals on a new push |
| `disable_overriding_approvers_per_merge_request` | boolean | no | Allow/Disallow overriding approvers per MR |
| `merge_requests_author_approval` | boolean | no | Allow/Disallow authors from self approving merge requests; `true` means authors cannot self approve |
| `merge_requests_disable_committers_approval` | boolean | no | Allow/Disallow committers from self approving merge requests |
```json
{
"approvals_before_merge": 2,
"reset_approvals_on_push": true,
"disable_overriding_approvers_per_merge_request": false,
"merge_requests_author_approval": false,
"merge_requests_disable_committers_approval": false
}
```
### Get project-level rules
>**Note:** This API endpoint is only available on 12.3 Starter and above.
You can request information about a project's approval rules using the following endpoint:
```
GET /projects/:id/approval_rules
```
**Parameters:**
| Attribute | Type | Required | Description |
|----------------------|---------|----------|-----------------------------------------------------------|
| `id` | integer | yes | The ID of a project |
```json
[
{
"id": 1,
"name": "security",
"rule_type": "regular",
"eligible_approvers": [
{ {
"user": {
"id": 5, "id": 5,
"name": "John Doe6", "name": "John Doe",
"username": "user5", "username": "jdoe",
"state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5" "state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/jdoe"
},
{
"id": 50,
"name": "Group Member 1",
"username": "group_member_1",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/group_member_1"
} }
],
"approvals_required": 3,
"users": [
{
"id": 5,
"name": "John Doe",
"username": "jdoe",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/jdoe"
} }
], ],
"approver_groups": [ "groups": [
{ {
"group": { "id": 5,
"id": 1,
"name": "group1", "name": "group1",
"path": "group1", "path": "group1",
"description": "", "description": "",
...@@ -51,52 +129,148 @@ GET /projects/:id/approvals ...@@ -51,52 +129,148 @@ GET /projects/:id/approvals
"ldap_cn": null, "ldap_cn": null,
"ldap_access": null "ldap_access": null
} }
],
"contains_hidden_groups": false
}
]
```
### Create project-level rule
>**Note:** This API endpoint is only available on 12.3 Starter and above.
You can create project approval rules using the following endpoint:
```
POST /projects/:id/approval_rules
```
**Parameters:**
| Attribute | Type | Required | Description |
|----------------------|---------|----------|-----------------------------------------------------------|
| `id` | integer | yes | The ID of a project |
| `name` | string | yes | The name of the approval rule |
| `approvals_required` | integer | yes | The number of required approvals for this rule |
| `users` | integer | no | The ids of users as approvers |
| `groups` | integer | no | The ids of groups as approvers |
```json
{
"id": 1,
"name": "security",
"rule_type": "regular",
"eligible_approvers": [
{
"id": 2,
"name": "John Doe",
"username": "jdoe",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/jdoe"
},
{
"id": 50,
"name": "Group Member 1",
"username": "group_member_1",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/group_member_1"
}
],
"approvals_required": 1,
"users": [
{
"id": 2,
"name": "John Doe",
"username": "jdoe",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/jdoe"
} }
], ],
"approvals_before_merge": 2, "groups": [
"reset_approvals_on_push": true, {
"disable_overriding_approvers_per_merge_request": false "id": 5,
"name": "group1",
"path": "group1",
"description": "",
"visibility": "public",
"lfs_enabled": false,
"avatar_url": null,
"web_url": "http://localhost/groups/group1",
"request_access_enabled": false,
"full_name": "group1",
"full_path": "group1",
"parent_id": null,
"ldap_cn": null,
"ldap_access": null
}
],
"contains_hidden_groups": false
} }
``` ```
### Change configuration ### Update project-level rule
>**Note:** This API endpoint is only available on 10.6 Starter and above. >**Note:** This API endpoint is only available on 12.3 Starter and above.
If you are allowed to, you can change approval configuration using the following You can update project approval rules using the following endpoint:
endpoint:
``` ```
POST /projects/:id/approvals PUT /projects/:id/approval_rules/:approval_rule_id
``` ```
**Important:** Approvers and groups not in the `users`/`groups` param will be **removed**
**Parameters:** **Parameters:**
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| ------------------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- | |----------------------|---------|----------|-----------------------------------------------------------|
| `id` | integer | yes | The ID of a project | | `id` | integer | yes | The ID of a project |
| `approvals_before_merge` | integer | no | How many approvals are required before an MR can be merged | | `approval_rule_id` | integer | yes | The ID of a approval rule |
| `reset_approvals_on_push` | boolean | no | Reset approvals on a new push | | `name` | string | yes | The name of the approval rule |
| `disable_overriding_approvers_per_merge_request` | boolean | no | Allow/Disallow overriding approvers per MR | | `approvals_required` | integer | yes | The number of required approvals for this rule |
| `merge_requests_author_approval` | boolean | no | Allow/Disallow authors from self approving merge requests; `true` means authors cannot self approve | | `users` | integer | no | The ids of users as approvers |
| `merge_requests_disable_committers_approval` | boolean | no | Allow/Disallow committers from self approving merge requests | | `groups` | integer | no | The ids of groups as approvers |
```json ```json
{ {
"approvers": [ "id": 1,
"name": "security",
"rule_type": "regular",
"eligible_approvers": [
{ {
"user": { "id": 2,
"id": 5, "name": "John Doe",
"name": "John Doe6", "username": "jdoe",
"username": "user5", "state": "active",
"state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5" "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/jdoe"
},
{
"id": 50,
"name": "Group Member 1",
"username": "group_member_1",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/group_member_1"
} }
],
"approvals_required": 1,
"users": [
{
"id": 2,
"name": "John Doe",
"username": "jdoe",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/jdoe"
} }
], ],
"approver_groups": [ "groups": [
{ {
"group": { "id": 5,
"id": 1,
"name": "group1", "name": "group1",
"path": "group1", "path": "group1",
"description": "", "description": "",
...@@ -111,18 +285,31 @@ POST /projects/:id/approvals ...@@ -111,18 +285,31 @@ POST /projects/:id/approvals
"ldap_cn": null, "ldap_cn": null,
"ldap_access": null "ldap_access": null
} }
}
], ],
"approvals_before_merge": 2, "contains_hidden_groups": false
"reset_approvals_on_push": true,
"disable_overriding_approvers_per_merge_request": false,
"merge_requests_author_approval": false,
"merge_requests_disable_committers_approval": false
} }
``` ```
### Delete project-level rule
>**Note:** This API endpoint is only available on 12.3 Starter and above.
You can delete project approval rules using the following endpoint:
```
DELETE /projects/:id/approval_rules/:approval_rule_id
```
**Parameters:**
| Attribute | Type | Required | Description |
|----------------------|---------|----------|-----------------------------------------------------------|
| `id` | integer | yes | The ID of a project |
| `approval_rule_id` | integer | yes | The ID of a approval rule
### Change allowed approvers ### Change allowed approvers
>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead.
>**Note:** This API endpoint is only available on 10.6 Starter and above. >**Note:** This API endpoint is only available on 10.6 Starter and above.
If you are allowed to, you can change approvers and approver groups using If you are allowed to, you can change approvers and approver groups using
...@@ -227,8 +414,6 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals ...@@ -227,8 +414,6 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals
} }
} }
], ],
"approvers": [],
"approver_groups": []
} }
``` ```
...@@ -249,7 +434,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals ...@@ -249,7 +434,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals
|----------------------|---------|----------|--------------------------------------------| |----------------------|---------|----------|--------------------------------------------|
| `id` | integer | yes | The ID of a project | | `id` | integer | yes | The ID of a project |
| `merge_request_iid` | integer | yes | The IID of MR | | `merge_request_iid` | integer | yes | The IID of MR |
| `approvals_required` | integer | yes | Approvals required before MR can be merged | | `approvals_required` | integer | yes | Approvals required before MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. |
```json ```json
{ {
...@@ -264,14 +449,13 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals ...@@ -264,14 +449,13 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals
"merge_status": "cannot_be_merged", "merge_status": "cannot_be_merged",
"approvals_required": 2, "approvals_required": 2,
"approvals_left": 2, "approvals_left": 2,
"approved_by": [], "approved_by": []
"approvers": [],
"approver_groups": []
} }
``` ```
### Change allowed approvers for Merge Request ### Change allowed approvers for Merge Request
>**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead.
>**Note:** This API endpoint is only available on 10.6 Starter and above. >**Note:** This API endpoint is only available on 10.6 Starter and above.
If you are allowed to, you can change approvers and approver groups using If you are allowed to, you can change approvers and approver groups using
...@@ -401,8 +585,6 @@ does not match, the response code will be `409`. ...@@ -401,8 +585,6 @@ does not match, the response code will be `409`.
} }
} }
], ],
"approvers": [],
"approver_groups": []
} }
``` ```
......
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