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
Hide whitespace changes
Inline Side-by-side
Showing with 238 additions and 56 deletions
doc/api/merge_request_approvals.md
View file @ 070689cb
...@@ -23,36 +23,6 @@ GET /projects/:id/approvals ...@@ -23,36 +23,6 @@ GET /projects/:id/approvals
```json ```json
{ {
"approvers": [
{
"user": {
"id": 5,
"name": "John Doe6",
"username": "user5",
"state":"active","avatar_url":"https://www.gravatar.com/avatar/4aea8cf834ed91844a2da4ff7ae6b491?s=80\u0026d=identicon","web_url":"http://localhost/user5"
}
}
],
"approver_groups": [
{
"group": {
"id": 1,
"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
}
}
],
"approvals_before_merge": 2, "approvals_before_merge": 2,
"reset_approvals_on_push": true, "reset_approvals_on_push": true,
"disable_overriding_approvers_per_merge_request": false "disable_overriding_approvers_per_merge_request": false
...@@ -75,7 +45,7 @@ POST /projects/:id/approvals ...@@ -75,7 +45,7 @@ POST /projects/:id/approvals
| 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 | | `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 | | `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 | | `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_author_approval` | boolean | no | Allow/Disallow authors from self approving merge requests; `true` means authors cannot self approve |
...@@ -83,20 +53,68 @@ POST /projects/:id/approvals ...@@ -83,20 +53,68 @@ POST /projects/:id/approvals
```json ```json
{ {
"approvers": [ "approvals_before_merge": 2,
{ "reset_approvals_on_push": true,
"user": { "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": [
{
"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,
"approver_groups": [ "users": [
{ {
"group": { "id": 5,
"id": 1, "name": "John Doe",
"username": "jdoe",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/jdoe"
}
],
"groups": [
{
"id": 5,
"name": "group1", "name": "group1",
"path": "group1", "path": "group1",
"description": "", "description": "",
...@@ -111,18 +129,187 @@ POST /projects/:id/approvals ...@@ -111,18 +129,187 @@ POST /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_before_merge": 2, "approvals_required": 1,
"reset_approvals_on_push": true, "users": [
"disable_overriding_approvers_per_merge_request": false, {
"merge_requests_author_approval": false, "id": 2,
"merge_requests_disable_committers_approval": false "name": "John Doe",
"username": "jdoe",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon",
"web_url": "http://localhost/jdoe"
}
],
"groups": [
{
"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
}
```
### Update project-level rule
>**Note:** This API endpoint is only available on 12.3 Starter and above.
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` param will be **removed**
**Parameters:**
| Attribute | Type | Required | Description |
|----------------------|---------|----------|-----------------------------------------------------------|
| `id` | integer | yes | The ID of a project |
| `approval_rule_id` | integer | yes | The ID of a approval rule |
| `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"
}
],
"groups": [
{
"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
} }
``` ```
### 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