Skip to content

G
gitlab-ce
Commit 088e0cbb authored by Marcel Amirault's avatar Marcel Amirault Committed by Achilleas Pipinellis
Browse files
Options

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 36259857
Expand all Show whitespace changes
Inline Side-by-side
Showing with 701 additions and 174 deletions
doc/api/group_boards.md
View file @ 088e0cbb
......@@ -70,6 +70,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.
......@@ -134,9 +187,59 @@ Example response:
}
```
## Create a board
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 board.
Creates a Group Issue Board.
```
POST /groups/:id/boards
......@@ -198,11 +301,11 @@ Example response:
}
```
## Update a board
## Update a Group Issue Board **[PREMIUM]**
> [Introduced][ee-5954] in GitLab 11.1.
Updates a board.
Updates a Group Issue Board.
```
PUT /groups/:id/boards/:board_id
......@@ -267,9 +370,9 @@ Example response:
}
```
## Delete a board
## Delete a Group Issue Board **[PREMIUM]**
Deletes a board.
Deletes a Group Issue Board.
```
DELETE /groups/:id/boards/:board_id
......
doc/api/groups.md
View file @ 088e0cbb
......@@ -377,6 +377,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
......@@ -420,9 +430,9 @@ Parameters:
| `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 | (admin-only) Pipeline minutes quota for this group. |
| `extra_shared_runners_minutes_limit` | integer | no | (admin-only) Extra pipeline minutes quota for this group. |
| `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
......@@ -453,14 +463,14 @@ PUT /groups/:id
| `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 | Prevent adding new members to project membership within this 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 | (admin-only) Pipeline minutes quota for this group |
| `extra_shared_runners_minutes_limit` | integer | no | (admin-only) Extra pipeline minutes quota for this group |
| `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"
......@@ -560,7 +570,7 @@ GET /groups?search=foobar
]
```
## Sync group with LDAP
## Sync group with LDAP **[CORE ONLY]**
Syncs the group with its linked LDAP group. Only available to group owners and administrators.
......@@ -576,9 +586,9 @@ Parameters:
Please consult the [Group Members](members.md) documentation.
### Add LDAP group link
### Add LDAP group link **[CORE ONLY]**
Adds LDAP group link
Adds an LDAP group link.
```
POST /groups/:id/ldap_group_links
......@@ -591,9 +601,9 @@ Parameters:
- `group_access` (required) - Minimum access level for members of the LDAP group
- `provider` (required) - LDAP provider for the LDAP group
### Delete LDAP group link
### Delete LDAP group link **[CORE ONLY]**
Deletes a LDAP group link
Deletes an LDAP group link.
```
DELETE /groups/:id/ldap_group_links/:cn
......
doc/api/issues.md
View file @ 088e0cbb
This diff is collapsed.
doc/api/merge_requests.md
View file @ 088e0cbb
This diff is collapsed.
doc/api/namespaces.md
View file @ 088e0cbb
......@@ -55,7 +55,21 @@ Example response:
]
```
**Note**: `members_count_with_descendants` and `plan` 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
View file @ 088e0cbb
# 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,23 +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_epic
```
- `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
......@@ -86,7 +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][ee-6626] in 11.3) |
| `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:
......@@ -155,7 +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][ee-6626] in 11.3) |
| `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:
......@@ -186,5 +185,17 @@ Example responses:
}
```
[ce-5632]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632
[ee-6626]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626
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
View file @ 088e0cbb
......@@ -55,8 +55,8 @@ GET /projects
| `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)_ |
| `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:
......@@ -258,6 +258,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:
```
......@@ -582,6 +596,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
......@@ -706,9 +732,9 @@ POST /projects
| `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 | How many approvers should approve merge request by default |
| `mirror` | boolean | no | Enables pull mirroring in a project |
| `mirror_trigger_builds` | boolean | no | Pull mirroring triggers builds |
| `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,
......@@ -751,10 +777,10 @@ POST /projects/user/:user_id
| `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 | How many approvers should approve merge request by default |
| `external_authorization_classification_label` | string | no | The classification label for the project |
| `mirror` | boolean | no | Enables pull mirroring in a project |
| `mirror_trigger_builds` | boolean | no | Pull mirroring triggers builds |
| `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`
......@@ -794,15 +820,16 @@ PUT /projects/:id
| `tag_list` | array | no | The list of tags for a project; put array of tags, that should be finally assigned to a project |
| `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 | How many approvers should approve merge request by default |
| `external_authorization_classification_label` | string | no | The classification label for the project |
| `mirror` | boolean | no | Enables pull mirroring in a project |
| `mirror_user_id` | integer | no | User responsible for all the activity surrounding a pull mirror event |
| `mirror_trigger_builds` | boolean | no | Pull mirroring triggers builds |
| `only_mirror_protected_branches` | boolean | no | Only mirror protected branches |
| `mirror_overwrites_diverged_branches` | boolean | no | Pull mirror overwrites diverged branches |
| `packages_enabled` | boolean | no | Enable or disable packages repository feature |
| `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`
......@@ -1668,7 +1695,7 @@ PUT /projects/:id/push_rule
### Delete project push rule
> Introduced in GitLab 9.0.
> 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.
......@@ -1751,6 +1778,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
View file @ 088e0cbb
......@@ -56,6 +56,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.
......@@ -97,6 +127,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
......@@ -117,10 +174,41 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitla
| `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 | Array of access levels allowed to push, with each described by a hash |
| `allowed_to_merge` | array | no | Array of access levels allowed to merge, with each described by a hash |
| `allowed_to_unprotect` | array | no | Array of access levels allowed to unprotect, with each described by a hash |
| `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,
"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,
"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:
......@@ -153,7 +241,7 @@ Example response:
}
```
### Example with user / group level access
### 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.
......
doc/api/settings.md
View file @ 088e0cbb
This diff is collapsed.
doc/api/users.md
View file @ 088e0cbb
......@@ -224,6 +224,8 @@ Parameters:
- `id` (required) - The ID of a user
Example Responses:
```json
{
"id": 1,
......@@ -266,6 +268,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:
```
......@@ -291,8 +306,7 @@ 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)
- `reset_password` (optional) - Send user password reset link - true or false(default)
- `username` (required) - Username
- `name` (required) - Name
- `skype` (optional) - Skype ID
......@@ -303,7 +317,6 @@ Parameters:
- `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
......@@ -313,8 +326,8 @@ Parameters:
- `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
- `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
......@@ -350,6 +363,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,
......
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