Skip to content
Snippets Groups Projects
Commit a347d159 authored by Marcel Amirault's avatar Marcel Amirault Committed by Achilleas Pipinellis
Browse files

Update api docs to finish aligning EE and CE docs 

Squashing a few commits and continuing work
on merging the 12 api docs that have not
been ported to CE yet.
parent e555db6f
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 1166 additions and 135 deletions
doc/api/group_boards.md
+ 255
− 0
View file @ a347d159
@@ -61,6 +61,59 @@ Example response:
]
```
 
Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see
different parameters, due to the ability to have multiple group boards. Refer to the table
above to see what enpoint(s) belong to each tier.
Example response:
```json
[
{
"id": 1,
"name:": "group issue board",
"group": {
"id": 5,
"name": "Documentcloud",
"web_url": "http://example.com/groups/documentcloud"
},
"milestone": {
"id": 12
"title": "10.0"
},
"lists" : [
{
"id" : 1,
"label" : {
"name" : "Testing",
"color" : "#F0AD4E",
"description" : null
},
"position" : 1
},
{
"id" : 2,
"label" : {
"name" : "Ready",
"color" : "#FF0000",
"description" : null
},
"position" : 2
},
{
"id" : 3,
"label" : {
"name" : "Production",
"color" : "#FF5F00",
"description" : null
},
"position" : 3
}
]
}
]
```
## Single board
 
Gets a single board.
@@ -116,6 +169,206 @@ Example response:
}
```
 
Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see
different parameters, due to the ability to have multiple group boards:
Example response:
```json
{
"id": 1,
"name:": "group issue board",
"group": {
"id": 5,
"name": "Documentcloud",
"web_url": "http://example.com/groups/documentcloud"
},
"milestone": {
"id": 12
"title": "10.0"
},
"lists" : [
{
"id" : 1,
"label" : {
"name" : "Testing",
"color" : "#F0AD4E",
"description" : null
},
"position" : 1
},
{
"id" : 2,
"label" : {
"name" : "Ready",
"color" : "#FF0000",
"description" : null
},
"position" : 2
},
{
"id" : 3,
"label" : {
"name" : "Production",
"color" : "#FF5F00",
"description" : null
},
"position" : 3
}
]
}
```
## Create a Group Issue Board **[PREMIUM]**
Creates a Group Issue Board.
```
POST /groups/:id/boards
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the new board |
```bash
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards?name=newboard
```
Example response:
```json
{
"id": 1,
"name": "newboard",
"group": {
"id": 5,
"name": "Documentcloud",
"web_url": "http://example.com/groups/documentcloud"
},
"milestone": {
"id": 12
"title": "10.0"
},
"lists" : [
{
"id" : 1,
"label" : {
"name" : "Testing",
"color" : "#F0AD4E",
"description" : null
},
"position" : 1
},
{
"id" : 2,
"label" : {
"name" : "Ready",
"color" : "#FF0000",
"description" : null
},
"position" : 2
},
{
"id" : 3,
"label" : {
"name" : "Production",
"color" : "#FF5F00",
"description" : null
},
"position" : 3
}
]
}
```
## Update a Group Issue Board **[PREMIUM]**
> [Introduced][ee-5954] in GitLab 11.1.
Updates a Group Issue Board.
```
PUT /groups/:id/boards/:board_id
```
| Attribute | Type | Required | Description |
| ------------------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |
| `name` | string | no | The new name of the board |
| `assignee_id` | integer | no | The assignee the board should be scoped to |
| `milestone_id` | integer | no | The milestone the board should be scoped to |
| `labels` | string | no | Comma-separated list of label names which the board should be scoped to |
| `weight` | integer | no | The weight range from 0 to 9, to which the board should be scoped to |
```bash
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1?name=new_name&milestone_id=44&assignee_id=1&labels=GroupLabel&weight=4
```
Example response:
```json
{
"id": 1,
"project": null,
"lists": [],
"name": "new_name",
"group": {
"id": 5,
"name": "Documentcloud",
"web_url": "http://example.com/groups/documentcloud"
},
"milestone": {
"id": 44,
"iid": 1,
"group_id": 5,
"title": "Group Milestone",
"description": "Group Milestone Desc",
"state": "active",
"created_at": "2018-07-03T07:15:19.271Z",
"updated_at": "2018-07-03T07:15:19.271Z",
"due_date": null,
"start_date": null,
"web_url": "http://example.com/groups/documentcloud/-/milestones/1"
},
"assignee": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://example.com/root"
},
"labels": [{
"id": 11,
"name": "GroupLabel",
"color": "#428BCA",
"description": ""
}],
"weight": 4
}
```
## Delete a Group Issue Board **[PREMIUM]**
Deletes a Group Issue Board.
```
DELETE /groups/:id/boards/:board_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `board_id` | integer | yes | The ID of a board |
```bash
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1
```
## List board lists
 
Get a list of the board's lists.
@@ -282,3 +535,5 @@ DELETE /groups/:id/boards/:board_id/lists/:list_id
```bash
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1/lists/1
```
[ee-5954]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5954
doc/api/group_milestones.md
+ 15
− 0
View file @ a347d159
@@ -136,3 +136,18 @@ Parameters:
- `milestone_id` (required) - The ID of a group milestone
 
[ce-12819]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12819
## Get all burndown chart events for a single milestone **[STARTER]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1
Get all burndown chart events for a single milestone.
```
GET /groups/:id/milestones/:milestone_id/burndown_events
```
Parameters:
- `id` (required) - The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of a group milestone
doc/api/groups.md
+ 86
− 18
View file @ a347d159
@@ -70,8 +70,8 @@ GET /groups?statistics=true
"repository_size" : 33,
"wiki_size" : 100,
"lfs_objects_size" : 123,
"job_artifacts_size" : 57
"job_artifacts_size" : 57,
"packages_size": 0
}
}
]
@@ -375,6 +375,16 @@ Example response:
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters:
Additional response parameters: **[STARTER]**
```json
"shared_runners_minutes_limit": 133,
"extra_shared_runners_minutes_limit": 133,
```
When adding the parameter `with_projects=false`, projects will not be returned.
 
```bash
@@ -412,13 +422,15 @@ Parameters:
 
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `name` | string | yes | The name of the group |
| `path` | string | yes | The path of the group |
| `description` | string | no | The group's description |
| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. |
| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
| `request_access_enabled` | boolean | no | Allow users to request member access. |
| `parent_id` | integer | no | The parent group id for creating nested group. |
| `name` | string | yes | The name of the group |
| `path` | string | yes | The path of the group |
| `description` | string | no | The group's description |
| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. |
| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
| `request_access_enabled` | boolean | no | Allow users to request member access. |
| `parent_id` | integer | no | The parent group ID for creating nested group. |
| `shared_runners_minutes_limit` | integer | no | **[STARTER ONLY]** Pipeline minutes quota for this group. |
| `extra_shared_runners_minutes_limit` | integer | no | **[STARTER ONLY]** Extra pipeline minutes quota for this group. |
 
## Transfer project to group
 
@@ -445,14 +457,18 @@ PUT /groups/:id
 
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of the group |
| `name` | string | no | The name of the group |
| `path` | string | no | The path of the group |
| `description` | string | no | The description of the group |
| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. |
| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
| `request_access_enabled` | boolean | no | Allow users to request member access. |
| `file_template_project_id` | integer | no | **(Premium)** The ID of a project to load custom file templates from |
| `id` | integer | yes | The ID of the group |
| `name` | string | no | The name of the group |
| `path` | string | no | The path of the group |
| `description` | string | no | The description of the group |
| `membership_lock` | boolean | no | **[STARTER]** Prevent adding new members to project membership within this group |
| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group |
| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. |
| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group |
| `request_access_enabled` | boolean | no | Allow users to request member access. |
| `file_template_project_id` | integer | no | **[PREMIUM]** The ID of a project to load custom file templates from |
| `shared_runners_minutes_limit` | integer | no | **[STARTER ONLY]** Pipeline minutes quota for this group |
| `extra_shared_runners_minutes_limit` | integer | no | **[STARTER ONLY]** Extra pipeline minutes quota for this group |
 
```bash
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental"
@@ -520,7 +536,7 @@ Example response:
 
## Remove group
 
Removes group with all projects inside.
Removes group with all projects inside. Only available to group owners and administrators.
 
```
DELETE /groups/:id
@@ -552,10 +568,62 @@ GET /groups?search=foobar
]
```
 
## Sync group with LDAP **[CORE ONLY]**
Syncs the group with its linked LDAP group. Only available to group owners and administrators.
```
POST /groups/:id/ldap_sync
```
Parameters:
- `id` (required) - The ID or path of a user group
## Group members
 
Please consult the [Group Members](members.md) documentation.
 
### Add LDAP group link **[CORE ONLY]**
Adds an LDAP group link.
```
POST /groups/:id/ldap_group_links
```
Parameters:
- `id` (required) - The ID of a group
- `cn` (required) - The CN of a LDAP group
- `group_access` (required) - Minimum access level for members of the LDAP group
- `provider` (required) - LDAP provider for the LDAP group
### Delete LDAP group link **[CORE ONLY]**
Deletes an LDAP group link.
```
DELETE /groups/:id/ldap_group_links/:cn
```
Parameters:
- `id` (required) - The ID of a group
- `cn` (required) - The CN of a LDAP group
Deletes a LDAP group link for a specific LDAP provider
```
DELETE /groups/:id/ldap_group_links/:provider/:cn
```
Parameters:
- `id` (required) - The ID of a group
- `cn` (required) - The CN of a LDAP group
- `provider` (required) - Name of a LDAP provider
## Namespaces in groups
 
By default, groups only get 20 namespaces at a time because the API results are paginated.
doc/api/issues.md
+ 123
− 16
View file @ a347d159
This diff is collapsed.
doc/api/merge_requests.md
+ 166
− 22
View file @ a347d159
@@ -29,27 +29,28 @@ GET /merge_requests?search=foo&in=title
 
Parameters:
 
| Attribute | Type | Required | Description |
| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` |
| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request |
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `created_after` | datetime | no | Return merge requests created on or after the given time |
| `created_before` | datetime | no | Return merge requests created on or before the given time |
| `updated_after` | datetime | no | Return merge requests updated on or after the given time |
| `updated_before` | datetime | no | Return merge requests updated on or before the given time |
| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. |
| `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me` |
| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
| `source_branch` | string | no | Return merge requests with the given source branch |
| `target_branch` | string | no | Return merge requests with the given target branch |
| `search` | string | no | Search merge requests against their `title` and `description` |
| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` |
| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests |
| Attribute | Type | Required | Description |
| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` |
| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` |
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request |
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `created_after` | datetime | no | Return merge requests created on or after the given time |
| `created_before` | datetime | no | Return merge requests created on or before the given time |
| `updated_after` | datetime | no | Return merge requests updated on or after the given time |
| `updated_before` | datetime | no | Return merge requests updated on or before the given time |
| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. |
| `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me` |
| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
| `source_branch` | string | no | Return merge requests with the given source branch |
| `target_branch` | string | no | Return merge requests with the given target branch |
| `search` | string | no | Search merge requests against their `title` and `description` |
| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` |
| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests |
 
```json
[
@@ -147,6 +148,20 @@ Parameters:
]
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
[
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
]
```
## List project merge requests
 
Get all merge requests for this project.
@@ -191,6 +206,7 @@ Parameters:
| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13060] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ |
| `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ |
| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ |
| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
| `source_branch` | string | no | Return merge requests with the given source branch |
| `target_branch` | string | no | Return merge requests with the given target branch |
@@ -293,6 +309,20 @@ Parameters:
]
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
[
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
]
```
## List group merge requests
 
Get all merge requests for this group and its subgroups.
@@ -328,6 +358,7 @@ Parameters:
| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> |
| `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ |
| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ |
| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
| `source_branch` | string | no | Return merge requests with the given source branch |
| `target_branch` | string | no | Return merge requests with the given target branch |
@@ -427,6 +458,20 @@ Parameters:
]
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
[
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
]
```
## Get single MR
 
Shows information about a single merge request.
@@ -565,6 +610,18 @@ Parameters:
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
## Get single MR participants
 
Get a list of merge request participants.
@@ -767,6 +824,7 @@ Parameters:
## Create MR
 
Creates a new merge request.
```
POST /projects/:id/merge_requests
```
@@ -788,6 +846,15 @@ POST /projects/:id/merge_requests
| `allow_maintainer_to_push` | boolean | no | Deprecated, see allow_collaboration |
| `squash` | boolean | no | Squash commits into a single commit when merging |
 
If `approvals_before_merge` **[STARTER]** is not provided, it inherits the value from the
target project. If it is provided, then the following conditions must hold in
order for it to take effect:
1. The target project's `approvals_before_merge` must be greater than zero. (A
value of zero disables approvals for that project.)
2. The provided value of `approvals_before_merge` must be greater than the
target project's `approvals_before_merge`.
```json
{
"id": 1,
@@ -893,6 +960,18 @@ POST /projects/:id/merge_requests
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
## Update MR
 
Updates an existing merge request. You can change the target branch, title, or even close the MR.
@@ -1034,6 +1113,18 @@ Must include at least one non-required attribute from above.
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
## Delete a merge request
 
Only for admins and project owners. Soft deletes the merge request in question.
@@ -1191,7 +1282,19 @@ Parameters:
}
```
 
## Returns the up to date merge-ref HEAD commit
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
## Merge to default merge ref path
 
Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge`
ref, of the target project repository, if possible. This ref will have the state the target branch would have if
@@ -1349,6 +1452,18 @@ Parameters:
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
## Rebase a merge request
 
Automatically rebase the `source_branch` of the merge request against its
@@ -1616,6 +1731,18 @@ Example response:
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
## Unsubscribe from a merge request
 
Unsubscribes the authenticated user from a merge request to not receive
@@ -1749,6 +1876,18 @@ Example response:
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
## Create a todo
 
Manually creates a todo for the current user on a merge request.
@@ -1970,6 +2109,7 @@ Example response:
}]
}
```
## Set a time estimate for a merge request
 
Sets an estimated time of work for this merge request.
@@ -2114,3 +2254,7 @@ Example response:
[ce-14016]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14016
[ce-15454]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15454
[ce-18935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18935
## Approvals **[STARTER]**
For approvals, please see [Merge Request Approvals](merge_request_approvals.md)
doc/api/milestones.md
+ 15
− 0
View file @ a347d159
@@ -147,3 +147,18 @@ Parameters:
 
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of a project milestone
## Get all burndown chart events for a single milestone **[STARTER]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1
Gets all burndown chart events for a single milestone.
```
GET /projects/:id/milestones/:milestone_id/burndown_events
```
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of a project milestone
doc/api/namespaces.md
+ 15
− 1
View file @ a347d159
@@ -54,7 +54,21 @@ Example response:
]
```
 
**Note**: `members_count_with_descendants` are presented only for group maintainers/owners.
Users on GitLab.com [Bronze or higher](https://about.gitlab.com/pricing/#gitlab-com) may also see
the `plan` parameter associated with a namespace:
```json
[
{
"id": 1,
"name": "user1",
"plan": "bronze",
...
}
]
```
**Note**: Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **[BRONZE ONLY]**.
 
## Search for namespace
 
doc/api/notification_settings.md
+ 33
− 18
View file @ a347d159
# Notification settings API
 
>**Note:** This feature was [introduced][ce-5632] in GitLab 8.12.
>**Note:** This feature was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632) in GitLab 8.12.
 
**Valid notification levels**
 
@@ -17,22 +17,22 @@ custom
 
If the `custom` level is used, specific email events can be controlled. Available events are returned by `NotificationSetting.email_events`. Currently, these events are recognized:
 
```
new_note
new_issue
reopen_issue
close_issue
reassign_issue
issue_due
new_merge_request
push_to_merge_request
reopen_merge_request
close_merge_request
reassign_merge_request
merge_merge_request
failed_pipeline
success_pipeline
```
- `new_note`
- `new_issue`
- `reopen_issue`
- `close_issue`
- `reassign_issue`
- `issue_due`
- `new_merge_request`
- `push_to_merge_request`
- `reopen_merge_request`
- `close_merge_request`
- `reassign_merge_request`
- `merge_merge_request`
- `failed_pipeline`
- `success_pipeline`
- `new_epic` **[ULTIMATE]**
 
## Global notification settings
 
@@ -85,6 +85,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.
| `merge_merge_request` | boolean | no | Enable/disable this notification |
| `failed_pipeline` | boolean | no | Enable/disable this notification |
| `success_pipeline` | boolean | no | Enable/disable this notification |
| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **[ULTIMATE]** |
 
Example response:
 
@@ -153,6 +154,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.
| `merge_merge_request` | boolean | no | Enable/disable this notification |
| `failed_pipeline` | boolean | no | Enable/disable this notification |
| `success_pipeline` | boolean | no | Enable/disable this notification |
| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **[ULTIMATE]** |
 
Example responses:
 
@@ -182,4 +184,17 @@ Example responses:
}
```
 
[ce-5632]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632
Users on GitLab [Ultimate or Gold](https://about.gitlab.com/pricing/) will also see
the `new_epic` parameter:
```json
{
"level": "custom",
"events": {
"new_note": true,
"new_issue": false,
"new_epic": false,
...
}
}
```
doc/api/projects.md
+ 197
− 26
View file @ a347d159
@@ -14,7 +14,7 @@ Values for the project visibility level are:
The project can be cloned by any logged in user.
 
- `public`:
The project can be cloned without any authentication.
The project can be accessed without any authentication.
 
## Project merge method
 
@@ -41,23 +41,23 @@ GET /projects
 
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `archived` | boolean | no | Limit by archived status |
| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` |
| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
| `search` | string | no | Return list of projects matching the search criteria |
| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. |
| `owned` | boolean | no | Limit by projects explicitly owned by the current user |
| `membership` | boolean | no | Limit by projects that the current user is a member of |
| `starred` | boolean | no | Limit by projects starred by the current user |
| `statistics` | boolean | no | Include project statistics |
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
| `with_issues_enabled` | boolean | no | Limit by enabled issues feature |
| `archived` | boolean | no | Limit by archived status |
| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` |
| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` |
| `search` | string | no | Return list of projects matching the search criteria |
| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. |
| `owned` | boolean | no | Limit by projects explicitly owned by the current user |
| `membership` | boolean | no | Limit by projects that the current user is a member of |
| `starred` | boolean | no | Limit by projects starred by the current user |
| `statistics` | boolean | no | Include project statistics |
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) |
| `with_issues_enabled` | boolean | no | Limit by enabled issues feature |
| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature |
| `with_programming_language` | string | no | Limit by projects which use the given programming language |
| `wiki_checksum_failed` | boolean | no | Limit projects where the wiki checksum calculation has failed _([Introduced][ee-6137] in [GitLab Premium][eep] 11.2)_ |
| `repository_checksum_failed` | boolean | no | Limit projects where the repository checksum calculation has failed _([Introduced][ee-6137] in [GitLab Premium][eep] 11.2)_ |
| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) |
| `with_programming_language` | string | no | Limit by projects which use the given programming language |
| `wiki_checksum_failed` | boolean | no | **[PREMIUM]** Limit projects where the wiki checksum calculation has failed *([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2)* |
| `repository_checksum_failed` | boolean | no | **[PREMIUM]** Limit projects where the repository checksum calculation has failed *([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2)* |
| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) |
 
When `simple=true` or the user is unauthenticated this returns something like:
 
@@ -156,7 +156,8 @@ When the user is authenticated and `simple` is not set this returns something li
"repository_size": 1038090,
"wiki_size" : 0,
"lfs_objects_size": 0,
"job_artifacts_size": 0
"job_artifacts_size": 0,
"packages_size": 0
},
"_links": {
"self": "http://example.com/api/v4/projects",
@@ -239,7 +240,8 @@ When the user is authenticated and `simple` is not set this returns something li
"repository_size": 2066080,
"wiki_size" : 0,
"lfs_objects_size": 0,
"job_artifacts_size": 0
"job_artifacts_size": 0,
"packages_size": 0
},
"_links": {
"self": "http://example.com/api/v4/projects",
@@ -254,6 +256,20 @@ When the user is authenticated and `simple` is not set this returns something li
]
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
[
{
"id": 4,
"description": null,
"approvals_before_merge": 0,
...
}
]
```
You can filter by [custom attributes](custom_attributes.md) with:
 
```
@@ -349,7 +365,8 @@ GET /users/:user_id/projects
"repository_size": 1038090,
"wiki_size" : 0,
"lfs_objects_size": 0,
"job_artifacts_size": 0
"job_artifacts_size": 0,
"packages_size": 0
},
"_links": {
"self": "http://example.com/api/v4/projects",
@@ -432,7 +449,8 @@ GET /users/:user_id/projects
"repository_size": 2066080,
"wiki_size" : 0,
"lfs_objects_size": 0,
"job_artifacts_size": 0
"job_artifacts_size": 0,
"packages_size": 0
},
"_links": {
"self": "http://example.com/api/v4/projects",
@@ -548,6 +566,7 @@ GET /projects/:id
"group_access_level": 10
}
],
"repository_storage": "default",
"only_allow_merge_if_pipeline_succeeds": false,
"only_allow_merge_if_all_discussions_are_resolved": false,
"printing_merge_requests_link_enabled": true,
@@ -559,7 +578,8 @@ GET /projects/:id
"repository_size": 1038090,
"wiki_size" : 0,
"lfs_objects_size": 0,
"job_artifacts_size": 0
"job_artifacts_size": 0,
"packages_size": 0
},
"_links": {
"self": "http://example.com/api/v4/projects",
@@ -573,6 +593,18 @@ GET /projects/:id
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `approvals_before_merge` parameter:
```json
{
"id": 3,
"description": null,
"approvals_before_merge": 0,
...
}
```
**Note**: The `web_url` and `avatar_url` attributes on `namespace` were [introduced][ce-27427] in GitLab 11.11.
 
If the project is a fork, and you provide a valid token to authenticate, the
@@ -674,6 +706,7 @@ POST /projects
| `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. |
| `path` | string | yes if name is not provided | Repository name for new project. Generated based on name if not provided (generated lowercased with dashes). |
| `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) |
| `default_branch` | string | no | `master` by default |
| `description` | string | no | Short project description |
| `issues_enabled` | boolean | no | Enable issues for this project |
| `merge_requests_enabled` | boolean | no | Enable merge requests for this project |
@@ -695,8 +728,16 @@ POST /projects
| `avatar` | mixed | no | Image file for avatar of the project |
| `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
| `ci_config_path` | string | no | The path to CI config file |
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `approvals_before_merge` | integer | no | **[STARTER]** How many approvers should approve merge requests by default |
| `mirror` | boolean | no | **[STARTER]** Enables pull mirroring in a project |
| `mirror_trigger_builds` | boolean | no | **[STARTER]** Pull mirroring triggers builds |
| `initialize_with_readme` | boolean | no | `false` by default |
 
>**Note**: If your HTTP repository is not publicly accessible,
add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
where `password` is a public access key with the `api` scope enabled.
## Create project for user
 
Creates a new project owned by the specified user. Available only for admins.
@@ -710,7 +751,6 @@ POST /projects/user/:user_id
| `user_id` | integer | yes | The user ID of the project owner |
| `name` | string | yes | The name of the new project |
| `path` | string | no | Custom repository name for new project. By default generated based on name |
| `default_branch` | string | no | `master` by default |
| `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) |
| `description` | string | no | Short project description |
| `issues_enabled` | boolean | no | Enable issues for this project |
@@ -733,6 +773,15 @@ POST /projects/user/:user_id
| `avatar` | mixed | no | Image file for avatar of the project |
| `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
| `ci_config_path` | string | no | The path to CI config file |
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `approvals_before_merge` | integer | no | **[STARTER]** How many approvers should approve merge requests by default |
| `external_authorization_classification_label` | string | no | **[CORE ONLY]** The classification label for the project |
| `mirror` | boolean | no | **[STARTER]** Enables pull mirroring in a project |
| `mirror_trigger_builds` | boolean | no | **[STARTER]** Pull mirroring triggers builds |
>**Note**: If your HTTP repository is not publicly accessible,
add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
where `password` is a public access key with the `api` scope enabled.
 
## Edit project
 
@@ -769,6 +818,19 @@ PUT /projects/:id
| `avatar` | mixed | no | Image file for avatar of the project |
| `ci_config_path` | string | no | The path to CI config file |
| `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../user/project/pipelines/settings.md#git-shallow-clone) |
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `approvals_before_merge` | integer | no | **[STARTER]** How many approvers should approve merge request by default |
| `external_authorization_classification_label` | string | no | **[CORE ONLY]** The classification label for the project |
| `mirror` | boolean | no | **[STARTER]** Enables pull mirroring in a project |
| `mirror_user_id` | integer | no | **[STARTER]** User responsible for all the activity surrounding a pull mirror event |
| `mirror_trigger_builds` | boolean | no | **[STARTER]** Pull mirroring triggers builds |
| `only_mirror_protected_branches` | boolean | no | **[STARTER]** Only mirror protected branches |
| `mirror_overwrites_diverged_branches` | boolean | no | **[STARTER]** Pull mirror overwrites diverged branches |
| `packages_enabled` | boolean | no | **[PREMIUM ONLY]** Enable or disable packages repository feature |
>**Note**: If your HTTP repository is not publicly accessible,
add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`
where `password` is a public access key with the `api` scope enabled.
 
## Fork project
 
@@ -1546,11 +1608,106 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap
POST /projects/:id/housekeeping
```
 
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |
## Push Rules **[STARTER]**
### Get project push rules
Get the push rules of a project.
```
GET /projects/:id/push_rule
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |
```json
{
"id": 1,
"project_id": 3,
"commit_message_regex": "Fixes \d+\..*",
"branch_name_regex": "",
"deny_delete_tag": false,
"created_at": "2012-10-12T17:04:47Z",
"member_check": false,
"prevent_secrets": false,
"author_email_regex": "",
"file_name_regex": "",
"max_file_size": 5,
"commit_committer_check": false
}
```
The following attributes are restricted to certain plans, and will not appear if
you do not have access to those features:
* `commit_committer_check` only available on **[PREMIUM]**
### Add project push rule
Adds a push rule to a specified project.
```
POST /projects/:id/push_rule
```
| Attribute | Type | Required | Description |
| -------------------------------------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |
| `deny_delete_tag` **[STARTER]** | boolean | no | Deny deleting a tag |
| `member_check` **[STARTER]** | boolean | no | Restrict commits by author (email) to existing GitLab users |
| `prevent_secrets` **[STARTER]** | boolean | no | GitLab will reject any files that are likely to contain secrets |
| `commit_message_regex` **[STARTER]** | string | no | All commit messages must match this, e.g. `Fixed \d+\..*` |
| `branch_name_regex` **[STARTER]** | string | no | All branch names must match this, e.g. `(feature|hotfix)\/*` |
| `author_email_regex` **[STARTER]** | string | no | All commit author emails must match this, e.g. `@my-company.com$` |
| `file_name_regex` **[STARTER]** | string | no | All commited filenames must **not** match this, e.g. `(jar|exe)$` |
| `max_file_size` **[STARTER]** | integer | no | Maximum file size (MB) |
| `commit_committer_check` **[PREMIUM]** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. |
### Edit project push rule
Edits a push rule for a specified project.
```
PUT /projects/:id/push_rule
```
| Attribute | Type | Required | Description |
| -------------------------------------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |
| `deny_delete_tag` **[STARTER]** | boolean | no | Deny deleting a tag |
| `member_check` **[STARTER]** | boolean | no | Restrict commits by author (email) to existing GitLab users |
| `prevent_secrets` **[STARTER]** | boolean | no | GitLab will reject any files that are likely to contain secrets |
| `commit_message_regex` **[STARTER]** | string | no | All commit messages must match this, e.g. `Fixed \d+\..*` |
| `branch_name_regex` **[STARTER]** | string | no | All branch names must match this, e.g. `(feature|hotfix)\/*` |
| `author_email_regex` **[STARTER]** | string | no | All commit author emails must match this, e.g. `@my-company.com$` |
| `file_name_regex` **[STARTER]** | string | no | All commited filenames must **not** match this, e.g. `(jar|exe)$` |
| `max_file_size` **[STARTER]** | integer | no | Maximum file size (MB) |
| `commit_committer_check` **[PREMIUM]** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. |
### Delete project push rule
> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 9.0.
Removes a push rule from a project. This is an idempotent method and can be called multiple times.
Either the push rule is available or not.
```
DELETE /projects/:id/push_rule
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
 
### Transfer a project to a new namespace
## Transfer a project to a new namespace
> Introduced in GitLab 11.1.
 
```
PUT /projects/:id/transfer
@@ -1572,6 +1729,22 @@ Read more in the [Project import/export](project_import_export.md) documentation
 
Read more in the [Project members](members.md) documentation.
 
## Start the pull mirroring process for a Project **[STARTER]**
> Introduced in [GitLab Starter](https://about.gitlab.com/pricing) 10.3.
```
POST /projects/:id/mirror/pull
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
```bash
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/mirror/pull
```
## Project badges
 
Read more in the [Project Badges](project_badges.md) documentation.
@@ -1602,6 +1775,4 @@ GET /projects/:id/snapshot
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `wiki` | boolean | no | Whether to download the wiki, rather than project, repository |
 
[eep]: https://about.gitlab.com/pricing/ "Available only in GitLab Premium"
[ee-6137]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137
[ce-27427]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27427
doc/api/protected_branches.md
+ 149
− 5
View file @ a347d159
@@ -10,6 +10,7 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels`
0 => No access
30 => Developer access
40 => Maintainer access
60 => Admin access
```
 
## List protected branches
@@ -51,6 +52,36 @@ Example response:
]
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `user_id` and `group_id` parameters:
Example response:
```json
[
{
"name": "master",
"push_access_levels": [
{
"access_level": 40,
"user_id": null,
"group_id": null,
"access_level_description": "Maintainers"
}
],
"merge_access_levels": [
{
"access_level": null,
"user_id": null,
"group_id": 1234,
"access_level_description": "Example Merge Group"
}
]
},
...
]
```
## Get a single protected branch or wildcard protected branch
 
Gets a single protected branch or wildcard protected branch.
@@ -88,6 +119,33 @@ Example response:
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `user_id` and `group_id` parameters:
Example response:
```json
{
"name": "master",
"push_access_levels": [
{
"access_level": 40,
"user_id": null,
"group_id": null,
"access_level_description": "Maintainers"
}
],
"merge_access_levels": [
{
"access_level": null,
"user_id": null,
"group_id": 1234,
"access_level_description": "Example Merge Group"
}
]
}
```
## Protect repository branches
 
Protects a single repository branch or several project repository
@@ -98,15 +156,47 @@ POST /projects/:id/protected_branches
```
 
```bash
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30'
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40'
```
 
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the branch or wildcard |
| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) |
| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the branch or wildcard |
| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) |
| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) |
| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, maintainer access level) |
| `allowed_to_push` | array | no | **[STARTER]** Array of access levels allowed to push, with each described by a hash |
| `allowed_to_merge` | array | no | **[STARTER]** Array of access levels allowed to merge, with each described by a hash |
| `allowed_to_unprotect` | array | no | **[STARTER]**Array of access levels allowed to unprotect, with each described by a hash |
Example response:
```json
{
"name": "*-stable",
"push_access_levels": [
{
"access_level": 30,
"access_level_description": "Developers + Maintainers"
}
],
"merge_access_levels": [
{
"access_level": 30,
"access_level_description": "Developers + Maintainers"
],
"unprotect_access_levels": [
{
"access_level": 40,
"access_level_description": "Maintainers"
}
]
}
```
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `user_id` and `group_id` parameters:
 
Example response:
 
@@ -116,13 +206,65 @@ Example response:
"push_access_levels": [
{
"access_level": 30,
"user_id": null,
"group_id": null,
"access_level_description": "Developers + Maintainers"
}
],
"merge_access_levels": [
{
"access_level": 30,
"user_id": null,
"group_id": null,
"access_level_description": "Developers + Maintainers"
],
"unprotect_access_levels": [
{
"access_level": 40,
"user_id": null,
"group_id": null,
"access_level_description": "Maintainers"
}
]
}
```
### Example with user / group level access **[STARTER]**
Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the
form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API in ][ee-3516] in GitLab 10.3 EE.
```bash
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1'
```
Example response:
```json
{
"name":"*-stable",
"push_access_levels": [
{
"access_level":null,
"user_id":1,
"group_id":null,
"access_level_description":"Administrator"
}
],
"merge_access_levels": [
{
"access_level":40,
"user_id":null,
"group_id":null,
"access_level_description":"Maintainers"
}
],
"unprotect_access_levels": [
{
"access_level":40,
"user_id":null,
"group_id":null,
"access_level_description":"Maintainers"
}
]
}
@@ -144,3 +286,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://git
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the branch |
[ee-3516]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3516 "ProtectedBranches API handles per user/group granularity"
doc/api/settings.md
+ 71
− 3
View file @ a347d159
This diff is collapsed.
doc/api/users.md
+ 41
− 26
View file @ a347d159
@@ -223,6 +223,8 @@ Parameters:
 
- `id` (required) - The ID of a user
 
Example Responses:
```json
{
"id": 1,
@@ -264,6 +266,19 @@ Parameters:
}
```
 
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: **[STARTER]**
```json
{
"id": 1,
"username": "john_smith",
"shared_runners_minutes_limit": 133,
"extra_shared_runners_minutes_limit": 133
...
}
```
You can include the user's [custom attributes](custom_attributes.md) in the response with:
 
```
@@ -287,32 +302,30 @@ POST /users
 
Parameters:
 
- `email` (required) - Email
- `password` (optional) - Password
- `reset_password` (optional) - Send user password reset link - true or false (default)
- `force_random_password` (optional) - Set user password to a random value - true or false (default)
- `username` (required) - Username
- `name` (required) - Name
- `skype` (optional) - Skype ID
- `linkedin` (optional) - LinkedIn
- `twitter` (optional) - Twitter account
- `website_url` (optional) - Website URL
- `organization` (optional) - Organization name
- `projects_limit` (optional) - Number of projects user can create
- `extern_uid` (optional) - External UID
- `provider` (optional) - External provider name
- `group_id_for_saml` (optional) - ID of group where SAML has been configured
- `bio` (optional) - User's biography
- `location` (optional) - User's location
- `public_email` (optional) - The public email of the user
- `admin` (optional) - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
- `skip_confirmation` (optional) - Skip confirmation - true or false (default)
- `external` (optional) - Flags the user as external - true or false(default)
- `avatar` (optional) - Image file for user's avatar
- `private_profile` (optional) - User's profile is private - true or false
- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
- `email` (required) - Email
- `password` (optional) - Password
- `reset_password` (optional) - Send user password reset link - true or false(default)
- `username` (required) - Username
- `name` (required) - Name
- `skype` (optional) - Skype ID
- `linkedin` (optional) - LinkedIn
- `twitter` (optional) - Twitter account
- `website_url` (optional) - Website URL
- `organization` (optional) - Organization name
- `projects_limit` (optional) - Number of projects user can create
- `extern_uid` (optional) - External UID
- `provider` (optional) - External provider name
- `bio` (optional) - User's biography
- `location` (optional) - User's location
- `public_email` (optional) - The public email of the user
- `admin` (optional) - User is admin - true or false (default)
- `can_create_group` (optional) - User can create groups - true or false
- `skip_confirmation` (optional) - Skip confirmation - true or false (default)
- `external` (optional) - Flags the user as external - true or false(default)
- `avatar` (optional) - Image file for user's avatar
- `private_profile` (optional) - User's profile is private - true or false
- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user **[STARTER]**
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]**
 
## User modification
 
@@ -348,6 +361,8 @@ Parameters:
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
- `avatar` (optional) - Image file for user's avatar
- `private_profile` (optional) - User's profile is private - true or false
- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user **[STARTER]**
- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]**
 
On password update, user will be forced to change it upon next login.
Note, at the moment this method does only return a `404` error,
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