diff options
Diffstat (limited to 'doc/api')
53 files changed, 1131 insertions, 283 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 23c69deef23..b2bb55f2fcf 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -37,16 +37,16 @@ The following API resources are available in the project context: | [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | | [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | | [Issue boards](boards.md) | `/projects/:id/boards` | -| [Issue links](issue_links.md) **[STARTER]** | `/projects/:id/issues/.../links` | +| [Issue links](issue_links.md) **(STARTER)** | `/projects/:id/issues/.../links` | | [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | | [Labels](labels.md) | `/projects/:id/labels` | -| [Managed licenses](managed_licenses.md) **[ULTIMATE]** | `/projects/:id/managed_licenses` | +| [Managed licenses](managed_licenses.md) **(ULTIMATE)** | `/projects/:id/managed_licenses` | | [Members](members.md) | `/projects/:id/members` (also available for groups) | -| [Merge request approvals](merge_request_approvals.md) **[STARTER]** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | +| [Merge request approvals](merge_request_approvals.md) **(STARTER)** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | | [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | | [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups) | | [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | -| [Packages](packages.md) **[PREMIUM]** | `/projects/:id/packages` | +| [Packages](packages.md) **(PREMIUM)** | `/projects/:id/packages` | | [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) | | [Pipelines](pipelines.md) | `/projects/:id/pipelines` | | [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | @@ -71,7 +71,7 @@ The following API resources are available in the project context: | [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | | [Services](services.md) | `/projects/:id/services` | | [Tags](tags.md) | `/projects/:id/repository/tags` | -| [Vulnerabilities](vulnerabilities.md) **[ULTIMATE]** | `/projects/:id/vulnerabilities` (also available for groups) | +| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/vulnerabilities` (also available for groups) | | [Wikis](wikis.md) | `/projects/:id/wikis` | ### Group resources @@ -82,10 +82,10 @@ The following API resources are available in the group context: |:-----------------------------------------------------------------|:---------------------------------------------------------------------------------| | [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) | | [Custom attributes](custom_attributes.md) | `/groups/:id/custom_attributes` (also available for projects and users) | -| [Discussions](discussions.md) (threaded comments) **[ULTIMATE]** | `/groups/:id/epics/.../discussions` (also available for projects) | -| [Epic issues](epic_issues.md) **[ULTIMATE]** | `/groups/:id/epics/.../issues` | -| [Epic links](epic_links.md) **[ULTIMATE]** | `/groups/:id/epics/.../epics` | -| [Epics](epics.md) **[ULTIMATE]** | `/groups/:id/epics` | +| [Discussions](discussions.md) (threaded comments) **(ULTIMATE)** | `/groups/:id/epics/.../discussions` (also available for projects) | +| [Epic issues](epic_issues.md) **(ULTIMATE)** | `/groups/:id/epics/.../issues` | +| [Epic links](epic_links.md) **(ULTIMATE)** | `/groups/:id/epics/.../epics` | +| [Epics](epics.md) **(ULTIMATE)** | `/groups/:id/epics` | | [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | | [Group badges](group_badges.md) | `/groups/:id/badges` | | [Group issue boards](group_boards.md) | `/groups/:id/boards` | @@ -115,12 +115,12 @@ The following API resources are available outside of project and group contexts | [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | | [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | | [Feature flags](features.md) | `/features` | -| [Geo Nodes](geo_nodes.md) **[PREMIUM ONLY]** | `/geo_nodes` | +| [Geo Nodes](geo_nodes.md) **(PREMIUM ONLY)** | `/geo_nodes` | | [Import repository from GitHub](import.md) | `/import/github` | | [Issues](issues.md) | `/issues` (also available for groups and projects) | | [Issues Statistics](issues_statistics.md) | `/issues_statistics` (also available for groups and projects) | | [Keys](keys.md) | `/keys` | -| [License](license.md) **[CORE ONLY]** | `/license` | +| [License](license.md) **(CORE ONLY)** | `/license` | | [Markdown](markdown.md) | `/markdown` | | [Merge requests](merge_requests.md) | `/merge_requests` (also available for groups and projects) | | [Namespaces](namespaces.md) | `/namespaces` | @@ -147,16 +147,17 @@ Endpoints are available for: - [GitLab CI YAML templates](templates/gitlab_ci_ymls.md). - [Open source license templates](templates/licenses.md). -## SCIM **[SILVER ONLY]** +## SCIM **(SILVER ONLY)** [GitLab.com Silver and above](https://about.gitlab.com/pricing/) provides an [SCIM API](scim.md) that implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`. ## Road to GraphQL -Going forward, we will start on moving to -[GraphQL](graphql/index.md) and deprecate the use of -controller-specific endpoints. GraphQL has a number of benefits: +[GraphQL](graphql/index.md) is available in GitLab, which will +allow deprecation of controller-specific endpoints. + +GraphQL has a number of benefits: 1. We avoid having to maintain two different APIs. 1. Callers of the API can request only what they need. @@ -311,9 +312,9 @@ By default, impersonation is enabled. To disable impersonation: 1. Edit `/etc/gitlab/gitlab.rb`: - ```ruby - gitlab_rails['impersonation_enabled'] = false - ``` + ```ruby + gitlab_rails['impersonation_enabled'] = false + ``` 1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. @@ -326,10 +327,10 @@ To re-enable impersonation, remove this configuration and reconfigure GitLab. 1. Edit `config/gitlab.yml`: - ```yaml - gitlab: - impersonation_enabled: false - ``` + ```yaml + gitlab: + impersonation_enabled: false + ``` 1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. diff --git a/doc/api/boards.md b/doc/api/boards.md index a96206f5df3..08ec1d832df 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -141,7 +141,7 @@ Example response: } ``` -## Create a board **[STARTER]** +## Create a board **(STARTER)** Creates a board. @@ -209,7 +209,7 @@ Example response: } ``` -## Update a board **[STARTER]** +## Update a board **(STARTER)** > [Introduced][ee-5954] in [GitLab Starter](https://about.gitlab.com/pricing/) 11.1. @@ -229,7 +229,6 @@ PUT /projects/:id/boards/:board_id | `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/projects/5/boards/1?name=new_name&milestone_id=43&assignee_id=1&labels=Doing&weight=4 ``` @@ -291,7 +290,7 @@ Example response: } ``` -## Delete a board **[STARTER]** +## Delete a board **(STARTER)** Deletes a board. @@ -405,8 +404,8 @@ POST /projects/:id/boards/:board_id/lists | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `label_id` | integer | no | The ID of a label | -| `assignee_id` **[PREMIUM]** | integer | no | The ID of a user | -| `milestone_id` **[PREMIUM]** | integer | no | The ID of a milestone | +| `assignee_id` **(PREMIUM)** | integer | no | The ID of a user | +| `milestone_id` **(PREMIUM)** | integer | no | The ID of a milestone | NOTE: **Note**: Label, assignee and milestone arguments are mutually exclusive, diff --git a/doc/api/commits.md b/doc/api/commits.md index 25015fad9e3..6eb4c47415f 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -716,6 +716,7 @@ Example response if commit is signed: ``` Example response if commit is unsigned: + ```json { "message": "404 GPG Signature Not Found" diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 1d7523fcc3d..41f6ab436e8 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -19,13 +19,13 @@ Example response: { "id": 1, "title": "Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", "created_at": "2013-10-02T10:12:29Z" }, { "id": 3, "title": "Another Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", "created_at": "2013-10-02T11:12:29Z" } ] diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 9defef4fd53..208b8dca2e2 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -4,7 +4,7 @@ Discussions are a set of related notes on: - Snippets - Issues -- Epics **[ULTIMATE]** +- Epics **(ULTIMATE)** - Merge requests - Commits @@ -430,7 +430,7 @@ Parameters: curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636 ``` -## Epics **[ULTIMATE]** +## Epics **(ULTIMATE)** ### List group epic discussions diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index ec59ea7068e..02317cc6c09 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -1,4 +1,4 @@ -# Epic Issues API **[ULTIMATE]** +# Epic Issues API **(ULTIMATE)** Every API call to epic_issues must be authenticated. diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index 9ad90a6d0f1..6089198e46a 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -1,4 +1,4 @@ -# Epic Links API **[ULTIMATE]** +# Epic Links API **(ULTIMATE)** >**Note:** > This endpoint was [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9188) in GitLab 11.8. diff --git a/doc/api/epics.md b/doc/api/epics.md index 0541cfaa715..d05eb0a8804 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -1,4 +1,4 @@ -# Epics API **[ULTIMATE]** +# Epics API **(ULTIMATE)** Every API call to epic must be authenticated. @@ -302,7 +302,7 @@ POST /groups/:id/epics/:epic_iid/todo | 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 | -| `epic_iid ` | integer | yes | The internal ID of a group's epic | +| `epic_iid` | integer | yes | The internal ID of a group's epic | ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/5/todo diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index ea31abdd87e..ac64cbedf7d 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -1,4 +1,4 @@ -# Geo Nodes API **[PREMIUM ONLY]** +# Geo Nodes API **(PREMIUM ONLY)** In order to interact with Geo node endpoints, you need to authenticate yourself as an admin. diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 6c1cce620ca..bdc7c1959d2 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -1,6 +1,8 @@ -# GraphQL API (Alpha) +# GraphQL API -> [Introduced][ce-19008] in GitLab 11.0. +> - [Introduced][ce-19008] in GitLab 11.0 (enabled by feature flag `graphql`). +> - [Always enabled](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30444) + in GitLab 12.1. [GraphQL](https://graphql.org/) is a query language for APIs that allows clients to request exactly the data they need, making it @@ -23,30 +25,18 @@ programmatically with GitLab. To achieve this, it needs full coverage - anything possible in the REST API should also be possible in the GraphQL API. To help us meet this vision, the frontend should use GraphQL in preference to -the REST API for new features, although the alpha status of GraphQL may prevent -this from being a possibility at times. +the REST API for new features. There are no plans to deprecate the REST API. To reduce the technical burden of supporting two APIs in parallel, they should share implementations as much as possible. -## Enabling the GraphQL feature - -The GraphQL API itself is currently in Alpha, and therefore hidden behind a -feature flag. You can enable the feature using the [features api][features-api] on a self-hosted instance. - -For example: - -```shell -curl --data "value=100" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/features/graphql -``` - ## Available queries A first iteration of a GraphQL API includes the following queries 1. `project` : Within a project it is also possible to fetch a `mergeRequest` by IID. -1. `group` : Basic group information and epics **[ULTIMATE]** are currently supported. +1. `group` : Basic group information and epics **(ULTIMATE)** are currently supported. 1. `namespace` : Within a namespace it is also possible to fetch `projects`. ### Multiplex queries @@ -57,6 +47,12 @@ info about multiplexed queries is also available for [graphql-ruby](https://graphql-ruby.org/queries/multiplex.html) the library GitLab uses on the backend. +## Reference + +GitLab's GraphQL reference [is available](reference/index.md). + +It is automatically generated from GitLab's GraphQL schema and embedded in a Markdown file. + ## GraphiQL The API can be explored by using the GraphiQL IDE, it is available on your diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md new file mode 100644 index 00000000000..2d3bec4ff67 --- /dev/null +++ b/doc/api/graphql/reference/index.md @@ -0,0 +1,507 @@ +<!--- + This documentation is auto generated by a script. + + Please do not edit this file directly, check compile_docs task on lib/tasks/gitlab/graphql.rake. +---> + +# GraphQL API Resources + +This documentation is self-generated based on GitLab current GraphQL schema. + +The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql). + +## Objects + +### AddAwardEmojiPayload + +| Name | Type | Description | +| --- | ---- | ---------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Reasons why the mutation failed. | +| `awardEmoji` | AwardEmoji | The award emoji after mutation | + +### AwardEmoji + +| Name | Type | Description | +| --- | ---- | ---------- | +| `name` | String! | The emoji name | +| `description` | String! | The emoji description | +| `unicode` | String! | The emoji in unicode | +| `emoji` | String! | The emoji as an icon | +| `unicodeVersion` | String! | The unicode version for this emoji | +| `user` | User! | The user who awarded the emoji | + +### Blob + +| Name | Type | Description | +| --- | ---- | ---------- | +| `id` | ID! | | +| `name` | String! | | +| `type` | EntryType! | | +| `path` | String! | | +| `flatPath` | String! | | +| `webUrl` | String | | +| `lfsOid` | String | | + +### Commit + +| Name | Type | Description | +| --- | ---- | ---------- | +| `id` | ID! | | +| `sha` | String! | | +| `title` | String | | +| `description` | String | | +| `message` | String | | +| `authoredDate` | Time | | +| `webUrl` | String! | | +| `author` | User | | +| `latestPipeline` | Pipeline | Latest pipeline for this commit | + +### DetailedStatus + +| Name | Type | Description | +| --- | ---- | ---------- | +| `group` | String! | | +| `icon` | String! | | +| `favicon` | String! | | +| `detailsPath` | String! | | +| `hasDetails` | Boolean! | | +| `label` | String! | | +| `text` | String! | | +| `tooltip` | String! | | + +### DiffPosition + +| Name | Type | Description | +| --- | ---- | ---------- | +| `headSha` | String! | The sha of the head at the time the comment was made | +| `baseSha` | String | The merge base of the branch the comment was made on | +| `startSha` | String! | The sha of the branch being compared against | +| `filePath` | String! | The path of the file that was changed | +| `oldPath` | String | The path of the file on the start sha. | +| `newPath` | String | The path of the file on the head sha. | +| `positionType` | DiffPositionType! | | +| `oldLine` | Int | The line on start sha that was changed | +| `newLine` | Int | The line on head sha that was changed | +| `x` | Int | The X postion on which the comment was made | +| `y` | Int | The Y position on which the comment was made | +| `width` | Int | The total width of the image | +| `height` | Int | The total height of the image | + +### Discussion + +| Name | Type | Description | +| --- | ---- | ---------- | +| `id` | ID! | | +| `createdAt` | Time! | | + +### Group + +| Name | Type | Description | +| --- | ---- | ---------- | +| `id` | ID! | | +| `name` | String! | | +| `path` | String! | | +| `fullName` | String! | | +| `fullPath` | ID! | | +| `description` | String | | +| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | +| `visibility` | String | | +| `lfsEnabled` | Boolean | | +| `requestAccessEnabled` | Boolean | | +| `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | +| `webUrl` | String! | | +| `avatarUrl` | String | | +| `parent` | Group | | + +### GroupPermissions + +| Name | Type | Description | +| --- | ---- | ---------- | +| `readGroup` | Boolean! | Whether or not a user can perform `read_group` on this resource | + +### Issue + +| Name | Type | Description | +| --- | ---- | ---------- | +| `userPermissions` | IssuePermissions! | Permissions for the current user on the resource | +| `iid` | ID! | | +| `title` | String! | | +| `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | +| `description` | String | | +| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | +| `state` | IssueState! | | +| `reference` | String! | | +| `author` | User! | | +| `milestone` | Milestone | | +| `dueDate` | Time | | +| `confidential` | Boolean! | | +| `discussionLocked` | Boolean! | | +| `upvotes` | Int! | | +| `downvotes` | Int! | | +| `userNotesCount` | Int! | | +| `webPath` | String! | | +| `webUrl` | String! | | +| `relativePosition` | Int | | +| `closedAt` | Time | | +| `createdAt` | Time! | | +| `updatedAt` | Time! | | +| `taskCompletionStatus` | TaskCompletionStatus! | | + +### IssuePermissions + +| Name | Type | Description | +| --- | ---- | ---------- | +| `readIssue` | Boolean! | Whether or not a user can perform `read_issue` on this resource | +| `adminIssue` | Boolean! | Whether or not a user can perform `admin_issue` on this resource | +| `updateIssue` | Boolean! | Whether or not a user can perform `update_issue` on this resource | +| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource | +| `reopenIssue` | Boolean! | Whether or not a user can perform `reopen_issue` on this resource | + +### Label + +| Name | Type | Description | +| --- | ---- | ---------- | +| `description` | String | | +| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | +| `title` | String! | | +| `color` | String! | | +| `textColor` | String! | | + +### MergeRequest + +| Name | Type | Description | +| --- | ---- | ---------- | +| `userPermissions` | MergeRequestPermissions! | Permissions for the current user on the resource | +| `id` | ID! | | +| `iid` | String! | | +| `title` | String! | | +| `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | +| `description` | String | | +| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | +| `state` | MergeRequestState! | | +| `createdAt` | Time! | | +| `updatedAt` | Time! | | +| `sourceProject` | Project | | +| `targetProject` | Project! | | +| `project` | Project! | | +| `projectId` | Int! | | +| `sourceProjectId` | Int | | +| `targetProjectId` | Int! | | +| `sourceBranch` | String! | | +| `targetBranch` | String! | | +| `workInProgress` | Boolean! | | +| `mergeWhenPipelineSucceeds` | Boolean | | +| `diffHeadSha` | String | | +| `mergeCommitSha` | String | | +| `userNotesCount` | Int | | +| `shouldRemoveSourceBranch` | Boolean | | +| `forceRemoveSourceBranch` | Boolean | | +| `mergeStatus` | String | | +| `inProgressMergeCommitSha` | String | | +| `mergeError` | String | | +| `allowCollaboration` | Boolean | | +| `shouldBeRebased` | Boolean! | | +| `rebaseCommitSha` | String | | +| `rebaseInProgress` | Boolean! | | +| `mergeCommitMessage` | String | | +| `defaultMergeCommitMessage` | String | | +| `mergeOngoing` | Boolean! | | +| `sourceBranchExists` | Boolean! | | +| `mergeableDiscussionsState` | Boolean | | +| `webUrl` | String | | +| `upvotes` | Int! | | +| `downvotes` | Int! | | +| `subscribed` | Boolean! | | +| `headPipeline` | Pipeline | | +| `taskCompletionStatus` | TaskCompletionStatus! | | + +### MergeRequestPermissions + +| Name | Type | Description | +| --- | ---- | ---------- | +| `readMergeRequest` | Boolean! | Whether or not a user can perform `read_merge_request` on this resource | +| `adminMergeRequest` | Boolean! | Whether or not a user can perform `admin_merge_request` on this resource | +| `updateMergeRequest` | Boolean! | Whether or not a user can perform `update_merge_request` on this resource | +| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource | +| `pushToSourceBranch` | Boolean! | Whether or not a user can perform `push_to_source_branch` on this resource | +| `removeSourceBranch` | Boolean! | Whether or not a user can perform `remove_source_branch` on this resource | +| `cherryPickOnCurrentMergeRequest` | Boolean! | Whether or not a user can perform `cherry_pick_on_current_merge_request` on this resource | +| `revertOnCurrentMergeRequest` | Boolean! | Whether or not a user can perform `revert_on_current_merge_request` on this resource | + +### MergeRequestSetWipPayload + +| Name | Type | Description | +| --- | ---- | ---------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Reasons why the mutation failed. | +| `mergeRequest` | MergeRequest | The merge request after mutation | + +### Metadata + +| Name | Type | Description | +| --- | ---- | ---------- | +| `version` | String! | | +| `revision` | String! | | + +### Milestone + +| Name | Type | Description | +| --- | ---- | ---------- | +| `description` | String | | +| `title` | String! | | +| `state` | String! | | +| `dueDate` | Time | | +| `startDate` | Time | | +| `createdAt` | Time! | | +| `updatedAt` | Time! | | + +### Namespace + +| Name | Type | Description | +| --- | ---- | ---------- | +| `id` | ID! | | +| `name` | String! | | +| `path` | String! | | +| `fullName` | String! | | +| `fullPath` | ID! | | +| `description` | String | | +| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | +| `visibility` | String | | +| `lfsEnabled` | Boolean | | +| `requestAccessEnabled` | Boolean | | + +### Note + +| Name | Type | Description | +| --- | ---- | ---------- | +| `userPermissions` | NotePermissions! | Permissions for the current user on the resource | +| `id` | ID! | | +| `project` | Project | The project this note is associated to | +| `author` | User! | The user who wrote this note | +| `resolvedBy` | User | The user that resolved the discussion | +| `system` | Boolean! | Whether or not this note was created by the system or by a user | +| `body` | String! | The content note itself | +| `bodyHtml` | String | The GitLab Flavored Markdown rendering of `note` | +| `createdAt` | Time! | | +| `updatedAt` | Time! | | +| `discussion` | Discussion | The discussion this note is a part of | +| `resolvable` | Boolean! | | +| `resolvedAt` | Time | The time the discussion was resolved | +| `position` | DiffPosition | The position of this note on a diff | + +### NotePermissions + +| Name | Type | Description | +| --- | ---- | ---------- | +| `readNote` | Boolean! | Whether or not a user can perform `read_note` on this resource | +| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource | +| `adminNote` | Boolean! | Whether or not a user can perform `admin_note` on this resource | +| `resolveNote` | Boolean! | Whether or not a user can perform `resolve_note` on this resource | +| `awardEmoji` | Boolean! | Whether or not a user can perform `award_emoji` on this resource | + +### PageInfo + +| Name | Type | Description | +| --- | ---- | ---------- | +| `hasNextPage` | Boolean! | When paginating forwards, are there more items? | +| `hasPreviousPage` | Boolean! | When paginating backwards, are there more items? | +| `startCursor` | String | When paginating backwards, the cursor to continue. | +| `endCursor` | String | When paginating forwards, the cursor to continue. | + +### Pipeline + +| Name | Type | Description | +| --- | ---- | ---------- | +| `userPermissions` | PipelinePermissions! | Permissions for the current user on the resource | +| `id` | ID! | | +| `iid` | String! | | +| `sha` | String! | | +| `beforeSha` | String | | +| `status` | PipelineStatusEnum! | | +| `detailedStatus` | DetailedStatus! | | +| `duration` | Int | Duration of the pipeline in seconds | +| `coverage` | Float | Coverage percentage | +| `createdAt` | Time! | | +| `updatedAt` | Time! | | +| `startedAt` | Time | | +| `finishedAt` | Time | | +| `committedAt` | Time | | + +### PipelinePermissions + +| Name | Type | Description | +| --- | ---- | ---------- | +| `updatePipeline` | Boolean! | Whether or not a user can perform `update_pipeline` on this resource | +| `adminPipeline` | Boolean! | Whether or not a user can perform `admin_pipeline` on this resource | +| `destroyPipeline` | Boolean! | Whether or not a user can perform `destroy_pipeline` on this resource | + +### Project + +| Name | Type | Description | +| --- | ---- | ---------- | +| `userPermissions` | ProjectPermissions! | Permissions for the current user on the resource | +| `id` | ID! | | +| `fullPath` | ID! | | +| `path` | String! | | +| `nameWithNamespace` | String! | | +| `name` | String! | | +| `description` | String | | +| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | +| `tagList` | String | | +| `sshUrlToRepo` | String | | +| `httpUrlToRepo` | String | | +| `webUrl` | String | | +| `starCount` | Int! | | +| `forksCount` | Int! | | +| `createdAt` | Time | | +| `lastActivityAt` | Time | | +| `archived` | Boolean | | +| `visibility` | String | | +| `containerRegistryEnabled` | Boolean | | +| `sharedRunnersEnabled` | Boolean | | +| `lfsEnabled` | Boolean | | +| `mergeRequestsFfOnlyEnabled` | Boolean | | +| `avatarUrl` | String | | +| `issuesEnabled` | Boolean | | +| `mergeRequestsEnabled` | Boolean | | +| `wikiEnabled` | Boolean | | +| `snippetsEnabled` | Boolean | | +| `jobsEnabled` | Boolean | | +| `publicJobs` | Boolean | | +| `openIssuesCount` | Int | | +| `importStatus` | String | | +| `onlyAllowMergeIfPipelineSucceeds` | Boolean | | +| `requestAccessEnabled` | Boolean | | +| `onlyAllowMergeIfAllDiscussionsAreResolved` | Boolean | | +| `printingMergeRequestLinkEnabled` | Boolean | | +| `namespace` | Namespace | | +| `group` | Group | | +| `statistics` | ProjectStatistics | | +| `repository` | Repository | | +| `mergeRequest` | MergeRequest | | +| `issue` | Issue | | + +### ProjectPermissions + +| Name | Type | Description | +| --- | ---- | ---------- | +| `changeNamespace` | Boolean! | Whether or not a user can perform `change_namespace` on this resource | +| `changeVisibilityLevel` | Boolean! | Whether or not a user can perform `change_visibility_level` on this resource | +| `renameProject` | Boolean! | Whether or not a user can perform `rename_project` on this resource | +| `removeProject` | Boolean! | Whether or not a user can perform `remove_project` on this resource | +| `archiveProject` | Boolean! | Whether or not a user can perform `archive_project` on this resource | +| `removeForkProject` | Boolean! | Whether or not a user can perform `remove_fork_project` on this resource | +| `removePages` | Boolean! | Whether or not a user can perform `remove_pages` on this resource | +| `readProject` | Boolean! | Whether or not a user can perform `read_project` on this resource | +| `createMergeRequestIn` | Boolean! | Whether or not a user can perform `create_merge_request_in` on this resource | +| `readWiki` | Boolean! | Whether or not a user can perform `read_wiki` on this resource | +| `readProjectMember` | Boolean! | Whether or not a user can perform `read_project_member` on this resource | +| `createIssue` | Boolean! | Whether or not a user can perform `create_issue` on this resource | +| `uploadFile` | Boolean! | Whether or not a user can perform `upload_file` on this resource | +| `readCycleAnalytics` | Boolean! | Whether or not a user can perform `read_cycle_analytics` on this resource | +| `downloadCode` | Boolean! | Whether or not a user can perform `download_code` on this resource | +| `downloadWikiCode` | Boolean! | Whether or not a user can perform `download_wiki_code` on this resource | +| `forkProject` | Boolean! | Whether or not a user can perform `fork_project` on this resource | +| `createProjectSnippet` | Boolean! | Whether or not a user can perform `create_project_snippet` on this resource | +| `readCommitStatus` | Boolean! | Whether or not a user can perform `read_commit_status` on this resource | +| `requestAccess` | Boolean! | Whether or not a user can perform `request_access` on this resource | +| `createPipeline` | Boolean! | Whether or not a user can perform `create_pipeline` on this resource | +| `createPipelineSchedule` | Boolean! | Whether or not a user can perform `create_pipeline_schedule` on this resource | +| `createMergeRequestFrom` | Boolean! | Whether or not a user can perform `create_merge_request_from` on this resource | +| `createWiki` | Boolean! | Whether or not a user can perform `create_wiki` on this resource | +| `pushCode` | Boolean! | Whether or not a user can perform `push_code` on this resource | +| `createDeployment` | Boolean! | Whether or not a user can perform `create_deployment` on this resource | +| `pushToDeleteProtectedBranch` | Boolean! | Whether or not a user can perform `push_to_delete_protected_branch` on this resource | +| `adminWiki` | Boolean! | Whether or not a user can perform `admin_wiki` on this resource | +| `adminProject` | Boolean! | Whether or not a user can perform `admin_project` on this resource | +| `updatePages` | Boolean! | Whether or not a user can perform `update_pages` on this resource | +| `adminRemoteMirror` | Boolean! | Whether or not a user can perform `admin_remote_mirror` on this resource | +| `createLabel` | Boolean! | Whether or not a user can perform `create_label` on this resource | +| `updateWiki` | Boolean! | Whether or not a user can perform `update_wiki` on this resource | +| `destroyWiki` | Boolean! | Whether or not a user can perform `destroy_wiki` on this resource | +| `createPages` | Boolean! | Whether or not a user can perform `create_pages` on this resource | +| `destroyPages` | Boolean! | Whether or not a user can perform `destroy_pages` on this resource | +| `readPagesContent` | Boolean! | Whether or not a user can perform `read_pages_content` on this resource | + +### ProjectStatistics + +| Name | Type | Description | +| --- | ---- | ---------- | +| `commitCount` | Int! | | +| `storageSize` | Int! | | +| `repositorySize` | Int! | | +| `lfsObjectsSize` | Int! | | +| `buildArtifactsSize` | Int! | | +| `packagesSize` | Int! | | +| `wikiSize` | Int | | + +### RemoveAwardEmojiPayload + +| Name | Type | Description | +| --- | ---- | ---------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Reasons why the mutation failed. | +| `awardEmoji` | AwardEmoji | The award emoji after mutation | + +### Repository + +| Name | Type | Description | +| --- | ---- | ---------- | +| `rootRef` | String | | +| `empty` | Boolean! | | +| `exists` | Boolean! | | +| `tree` | Tree | | + +### Submodule + +| Name | Type | Description | +| --- | ---- | ---------- | +| `id` | ID! | | +| `name` | String! | | +| `type` | EntryType! | | +| `path` | String! | | +| `flatPath` | String! | | + +### TaskCompletionStatus + +| Name | Type | Description | +| --- | ---- | ---------- | +| `count` | Int! | | +| `completedCount` | Int! | | + +### ToggleAwardEmojiPayload + +| Name | Type | Description | +| --- | ---- | ---------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Reasons why the mutation failed. | +| `awardEmoji` | AwardEmoji | The award emoji after mutation | +| `toggledOn` | Boolean! | True when the emoji was awarded, false when it was removed | + +### Tree + +| Name | Type | Description | +| --- | ---- | ---------- | +| `lastCommit` | Commit | | + +### TreeEntry + +| Name | Type | Description | +| --- | ---- | ---------- | +| `id` | ID! | | +| `name` | String! | | +| `type` | EntryType! | | +| `path` | String! | | +| `flatPath` | String! | | +| `webUrl` | String | | + +### User + +| Name | Type | Description | +| --- | ---- | ---------- | +| `name` | String! | | +| `username` | String! | | +| `avatarUrl` | String! | | +| `webUrl` | String! | | + diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 4157b25477f..4d10f83720b 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -236,7 +236,7 @@ Example response: } ``` -## Create a group issue board **[PREMIUM]** +## Create a group issue board **(PREMIUM)** Creates a Group Issue Board. @@ -300,7 +300,7 @@ Example response: } ``` -## Update a group issue board **[PREMIUM]** +## Update a group issue board **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5954) in GitLab 11.1. @@ -368,7 +368,7 @@ Example response: } ``` -## Delete a group issue board **[PREMIUM]** +## Delete a group issue board **(PREMIUM)** Deletes a Group Issue Board. diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md new file mode 100644 index 00000000000..71a05b4d338 --- /dev/null +++ b/doc/api/group_clusters.md @@ -0,0 +1,280 @@ +# Group clusters API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30213) +in GitLab 12.1. + +NOTE: **Note:** +User will need at least maintainer access for the group to use these endpoints. + +## List group clusters + +Returns a list of group clusters. + +``` +GET /groups/:id/clusters +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters +``` + +Example response: + +```json +[ + { + "id":18, + "name":"cluster-1", + "domain":"example.com", + "created_at":"2019-01-02T20:18:12.563Z", + "provider_type":"user", + "platform_type":"kubernetes", + "environment_scope":"*", + "cluster_type":"group_type", + "user": + { + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..", + "web_url":"https://gitlab.example.com/root" + }, + "platform_kubernetes": + { + "api_url":"https://104.197.68.152", + "authorization_type":"rbac", + "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----" + } + }, + { + "id":19, + "name":"cluster-2", + ... + } +] +``` + +## Get a single group cluster + +Gets a single group cluster. + +``` +GET /groups/:id/clusters/:cluster_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/18 +``` + +Example response: + +```json +{ + "id":18, + "name":"cluster-1", + "domain":"example.com", + "created_at":"2019-01-02T20:18:12.563Z", + "provider_type":"user", + "platform_type":"kubernetes", + "environment_scope":"*", + "cluster_type":"group_type", + "user": + { + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..", + "web_url":"https://gitlab.example.com/root" + }, + "platform_kubernetes": + { + "api_url":"https://104.197.68.152", + "authorization_type":"rbac", + "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----" + }, + "group": + { + "id":26, + "name":"group-with-clusters-api", + "web_url":"https://gitlab.example.com/group-with-clusters-api" + } +} +``` + +## Add existing cluster to group + +Adds an existing Kubernetes cluster to the group. + +``` +POST /groups/:id/clusters/user +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `name` | String | yes | The name of the cluster | +| `domain` | String | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | +| `enabled` | Boolean | no | Determines if cluster is active or not, defaults to true | +| `managed` | Boolean | no | Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true | +| `platform_kubernetes_attributes[api_url]` | String | yes | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | String | yes | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | +| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **[PREMIUM]** | + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/user \ +-H "Accept: application/json" \ +-H "Content-Type:application/json" \ +--request POST --data '{"name":"cluster-5", "platform_kubernetes_attributes":{"api_url":"https://35.111.51.20","token":"12345","ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"}}' +``` + +Example response: + +```json +{ + "id":24, + "name":"cluster-5", + "created_at":"2019-01-03T21:53:40.610Z", + "provider_type":"user", + "platform_type":"kubernetes", + "environment_scope":"*", + "cluster_type":"group_type", + "user": + { + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..", + "web_url":"https://gitlab.example.com/root" + }, + "platform_kubernetes": + { + "api_url":"https://35.111.51.20", + "authorization_type":"rbac", + "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----" + }, + "group": + { + "id":26, + "name":"group-with-clusters-api", + "web_url":"https://gitlab.example.com/root/group-with-clusters-api" + } +} +``` + +## Edit group cluster + +Updates an existing group cluster. + +``` +PUT /groups/:id/clusters/:cluster_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | String | no | The name of the cluster | +| `domain` | String | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | +| `platform_kubernetes_attributes[api_url]` | String | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | +| `environment_scope` | String | no | The associated environment to the cluster **[PREMIUM]** | + +NOTE: **Note:** +`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added +through the ["Add an existing Kubernetes Cluster"](../user/project/clusters/index.md#adding-an-existing-kubernetes-cluster) option or +through the ["Add existing cluster to group"](#add-existing-cluster-to-group) endpoint. + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/24 \ +-H "Content-Type:application/json" \ +--request PUT --data '{"name":"new-cluster-name","domain":"new-domain.com","api_url":"https://new-api-url.com"}' +``` + +Example response: + +```json +{ + "id":24, + "name":"new-cluster-name", + "domain":"new-domain.com", + "created_at":"2019-01-03T21:53:40.610Z", + "provider_type":"user", + "platform_type":"kubernetes", + "environment_scope":"*", + "cluster_type":"group_type", + "user": + { + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..", + "web_url":"https://gitlab.example.com/root" + }, + "platform_kubernetes": + { + "api_url":"https://new-api-url.com", + "authorization_type":"rbac", + "ca_cert":null + }, + "group": + { + "id":26, + "name":"group-with-clusters-api", + "web_url":"https://gitlab.example.com/group-with-clusters-api" + } +} + +``` + +## Delete group cluster + +Deletes an existing group cluster. + +``` +DELETE /groups/:id/clusters/:cluster_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | +| `cluster_id` | integer | yes | The ID of the cluster | + +Example request: + +```bash +curl --request DELETE --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/groups/26/clusters/23' +``` diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 98e81217875..a819e06bcd9 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -137,7 +137,7 @@ Parameters: [ce-12819]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12819 -## Get all burndown chart events for a single milestone **[STARTER]** +## Get all burndown chart events for a single milestone **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1 diff --git a/doc/api/groups.md b/doc/api/groups.md index e1bf296bc41..0d500f783aa 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -434,8 +434,8 @@ Parameters: | `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. | +| `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 @@ -466,14 +466,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 | **[STARTER]** 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 | **[STARTER ONLY]** Pipeline minutes quota for this group. | -| `extra_shared_runners_minutes_limit` | integer | no | **[STARTER 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" @@ -573,7 +573,7 @@ GET /groups?search=foobar ] ``` -## Sync group with LDAP **[CORE ONLY]** +## Sync group with LDAP **(CORE ONLY)** Syncs the group with its linked LDAP group. Only available to group owners and administrators. @@ -589,7 +589,7 @@ Parameters: Please consult the [Group Members](members.md) documentation. -### Add LDAP group link **[CORE ONLY]** +### Add LDAP group link **(CORE ONLY)** Adds an LDAP group link. @@ -604,7 +604,7 @@ 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 **[CORE ONLY]** +### Delete LDAP group link **(CORE ONLY)** Deletes an LDAP group link. @@ -634,11 +634,13 @@ Parameters: By default, groups only get 20 namespaces at a time because the API results are paginated. To get more (up to 100), pass the following as an argument to the API call: + ``` /groups?per_page=100 ``` And to switch pages add: + ``` /groups?per_page=100&page=2 ``` diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 1c7db6a8e4c..280431fa87c 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -1,4 +1,4 @@ -# Issue links API **[STARTER]** +# Issue links API **(STARTER)** ## List issue relations @@ -67,7 +67,6 @@ POST /projects/:id/issues/:issue_iid/links | `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) of a target project | | `target_issue_iid` | integer/string | yes | The internal ID of a target project's issue | - ```json { "source_issue" : { @@ -141,14 +140,12 @@ Deletes an issue link, thus removes the two-way relationship. DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id ``` - | 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 | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `issue_link_id` | integer/string | yes | The ID of an issue relationship | - ```json { "source_issue" : { diff --git a/doc/api/issues.md b/doc/api/issues.md index 544da1e262c..23126a05b66 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -47,7 +47,7 @@ GET /issues?confidential=true | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues 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)_ | -| `weight` **[STARTER]** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -57,7 +57,7 @@ GET /issues?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential ` | Boolean | no | Filter confidential or public issues. | +| `confidential` | Boolean | no | Filter confidential or public issues. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/issues @@ -198,7 +198,7 @@ GET /groups/:id/issues?confidential=true | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues 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)_ | -| `weight` **[STARTER]** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | @@ -206,7 +206,7 @@ GET /groups/:id/issues?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential ` | Boolean | no | Filter confidential or public issues. | +| `confidential` | Boolean | no | Filter confidential or public issues. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4/issues @@ -347,7 +347,7 @@ GET /projects/:id/issues?confidential=true | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues 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)_ | -| `weight` **[STARTER]** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `weight` **(STARTER)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | @@ -355,7 +355,7 @@ GET /projects/:id/issues?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential ` | Boolean | no | Filter confidential or public issues. | +| `confidential` | Boolean | no | Filter confidential or public issues. | ```bash @@ -603,7 +603,7 @@ POST /projects/:id/issues | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | | `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.| | `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | -| `weight` **[STARTER]** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | +| `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug @@ -703,7 +703,7 @@ PUT /projects/:id/issues/:issue_iid | `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | | `updated_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | -| `weight` **[STARTER]** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | +| `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | | `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | ```bash diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 58a32e879d7..d7edb296be2 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -43,7 +43,7 @@ GET /issues_statistics?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential ` | Boolean | no | Filter confidential or public issues. | +| `confidential` | Boolean | no | Filter confidential or public issues. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/issues_statistics @@ -99,7 +99,7 @@ GET /groups/:id/issues_statistics?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential ` | Boolean | no | Filter confidential or public issues. | +| `confidential` | Boolean | no | Filter confidential or public issues. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4/issues_statistics @@ -155,8 +155,7 @@ GET /projects/:id/issues_statistics?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | -| `confidential ` | Boolean | no | Filter confidential or public issues. | - +| `confidential` | Boolean | no | Filter confidential or public issues. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues_statistics diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 223bfed91a9..1add5f432ac 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -359,7 +359,7 @@ GET /projects/:id/jobs/:job_id/artifacts |-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | -| `job_token` **[PREMIUM]** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -368,7 +368,7 @@ curl --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https ``` To use this in a [`script` definition](../ci/yaml/README.md#script) inside -`.gitlab-ci.yml` **[PREMIUM]**, you can use either: +`.gitlab-ci.yml` **(PREMIUM)**, you can use either: - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. For example, the following job will download the artifacts of the job with ID @@ -425,7 +425,7 @@ Parameters | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | | `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | | `job` | string | yes | The name of the job. | -| `job_token` **[PREMIUM]** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -434,7 +434,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ``` To use this in a [`script` definition](../ci/yaml/README.md#script) inside -`.gitlab-ci.yml` **[PREMIUM]**, you can use either: +`.gitlab-ci.yml` **(PREMIUM)**, you can use either: - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. For example, the following job will download the artifacts of the `test` job @@ -485,7 +485,7 @@ Parameters | Attribute | Type | Required | Description | |-----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id ` | integer | yes | The unique job identifier. | +| `job_id` | integer | yes | The unique job identifier. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | Example request: @@ -782,7 +782,6 @@ DELETE /projects/:id/jobs/:job_id/artifacts | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `job_id` | integer | yes | ID of a job. | - Example request: ```sh diff --git a/doc/api/license.md b/doc/api/license.md index 2a8de64bdbf..12f1d03d576 100644 --- a/doc/api/license.md +++ b/doc/api/license.md @@ -1,4 +1,4 @@ -# License **[CORE ONLY]** +# License **(CORE ONLY)** In order to interact with license endpoints, you need to authenticate yourself as an admin. @@ -131,7 +131,6 @@ Returns: - `201 Created` if the license is successfully added. - `400 Bad Request` if the license couldn't be added, with an error message explaining the reason. - ## Delete a license ``` diff --git a/doc/api/lint.md b/doc/api/lint.md index 71c09d35b8c..b9b49f3df27 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -22,30 +22,30 @@ Example responses: - Valid content: - ```json - { - "status": "valid", - "errors": [] - } - ``` + ```json + { + "status": "valid", + "errors": [] + } + ``` - Invalid content: - ```json - { - "status": "invalid", - "errors": [ - "variables config should be a hash of key value pairs" - ] - } - ``` + ```json + { + "status": "invalid", + "errors": [ + "variables config should be a hash of key value pairs" + ] + } + ``` - Without the content attribute: - ```json - { - "error": "content is missing" - } - ``` + ```json + { + "error": "content is missing" + } + ``` [ce-5953]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5953 diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index 47b193111b6..1af7567626f 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -1,4 +1,4 @@ -# Managed Licenses API **[ULTIMATE]** +# Managed Licenses API **(ULTIMATE)** ## List managed licenses @@ -105,7 +105,7 @@ DELETE /projects/:id/managed_licenses/:managed_license_id curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses/4" ``` -When successful, it replies with an HTTP 204 response. +When successful, it replies with an HTTP 204 response. ## Edit an existing managed license diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 49aaac06b46..c211916464a 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -1,4 +1,4 @@ -# Merge request approvals API **[STARTER]** +# Merge request approvals API **(STARTER)** Configuration for approvals on all Merge Requests (MR) in the project. Must be authenticated for all endpoints. @@ -178,7 +178,6 @@ PUT /projects/:id/approvers } ``` - ## Merge Request-level MR approvals Configuration for approvals on a specific Merge Request. Must be authenticated for all endpoints. @@ -250,7 +249,6 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals | `merge_request_iid` | integer | yes | The IID of MR | | `approvals_required` | integer | yes | Approvals required before MR can be merged | - ```json { "id": 5, @@ -359,7 +357,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve | `id` | integer | yes | The ID of a project | | `merge_request_iid` | integer | yes | The IID of MR | | `sha` | string | no | The HEAD of the MR | -| `approval_password` **[STARTER]** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request-starter) is enabled in the project settings. | +| `approval_password` **(STARTER)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/merge_request_approvals.md#require-authentication-when-approving-a-merge-request-starter) is enabled in the project settings. | The `sha` parameter works in the same way as when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 850e3be42d5..662a4b3e424 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -44,7 +44,7 @@ Parameters: | `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. | +| `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 | @@ -206,7 +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. | +| `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 | @@ -358,7 +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. | +| `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 | @@ -846,7 +846,7 @@ 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 +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: @@ -1331,9 +1331,11 @@ If you don't have permissions to accept this merge request - you'll get a `401` If the merge request is already merged or closed - you get `405` and error message 'Method Not Allowed' In case the merge request is not set to be merged when the pipeline succeeds, you'll also get a `406` error. + ``` PUT /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds ``` + Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user @@ -2261,6 +2263,6 @@ Example response: [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]** +## Approvals **(STARTER)** For approvals, please see [Merge Request Approvals](merge_request_approvals.md) diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 8f69378dac3..a6ded7d3bd2 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -148,7 +148,7 @@ 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]** +## Get all burndown chart events for a single milestone **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1 diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 5db7035fd90..2b6eddf78a1 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -68,7 +68,7 @@ the `plan` parameter associated with a namespace: ] ``` -NOTE: **Note:** Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **[BRONZE ONLY]**. +NOTE: **Note:** Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **(BRONZE ONLY)**. ## Search for namespace diff --git a/doc/api/notes.md b/doc/api/notes.md index c09129c22d4..acbf0334563 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -5,7 +5,7 @@ Notes are comments on: - Snippets - Issues - Merge requests -- Epics **[ULTIMATE]** +- Epics **(ULTIMATE)** This includes system notes, which are notes about changes to the object (for example, when a milestone changes, there will be a corresponding system note). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). @@ -396,7 +396,7 @@ Parameters: curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602 ``` -## Epics **[ULTIMATE]** +## Epics **(ULTIMATE)** ### List all epic notes diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index ccc1cccf7a4..c6667784617 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -31,7 +31,7 @@ If the `custom` level is used, specific email events can be controlled. Availabl - `merge_merge_request` - `failed_pipeline` - `success_pipeline` -- `new_epic` **[ULTIMATE]** +- `new_epic` **(ULTIMATE)** ## Global notification settings @@ -84,7 +84,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]** | +| `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,7 +153,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]** | +| `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: diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index dfe62554852..76e3a0fa1a4 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -192,7 +192,7 @@ access_token = client.password.get_token('user@example.com', 'secret') puts access_token.token ``` -## Access GitLab API with `access token` +## Access GitLab API with `access token` The `access token` allows you to make requests to the API on behalf of a user. You can pass the token either as GET parameter: diff --git a/doc/api/packages.md b/doc/api/packages.md index 618e5c3056a..ca90771b085 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -1,4 +1,4 @@ -# Packages API **[PREMIUM]** +# Packages API **(PREMIUM)** This is the API docs of [GitLab Packages](../administration/packages.md). @@ -76,7 +76,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9305) in GitLab 11.8. -Get a list of package files of a single package. +Get a list of package files of a single package. ``` GET /projects/:id/packages/:package_id/package_files diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 70fbe24099f..9678203eb40 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -1,6 +1,6 @@ # Pages domains API -Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/features/pages/). +Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/product/pages/). The GitLab Pages feature must be enabled to use these endpoints. Find out more about [administering](../administration/pages/index.md) and [using](../user/project/pages/index.md) the feature. diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index 76343b4cd82..271632b61c3 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -1,4 +1,4 @@ -# Project Aliases API **[PREMIUM ONLY]** +# Project Aliases API **(PREMIUM ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index 3a7b3d8975e..1c382232837 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -91,7 +91,7 @@ POST /projects/:id/badges | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link | | `image_url` | string | yes | URL of the badge image | diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 327781f6c93..614ea41d572 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -167,7 +167,7 @@ Parameters: | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | | `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | -| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **[PREMIUM]** | +| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **(PREMIUM)** | Example request: @@ -257,7 +257,7 @@ Parameters: | `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes | | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | -| `environment_scope` | String | no | The associated environment to the cluster **[PREMIUM]** | +| `environment_scope` | String | no | The associated environment to the cluster **(PREMIUM)** | NOTE: **Note:** `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 66a749e4811..eab905bbc5f 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -74,7 +74,7 @@ POST /projects/:id/variables | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `environment_scope` | string | no | The `environment_scope` of the variable **[PREMIUM]** | +| `environment_scope` | string | no | The `environment_scope` of the variable **(PREMIUM)** | ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" @@ -108,7 +108,7 @@ PUT /projects/:id/variables/:key | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `environment_scope` | string | no | The `environment_scope` of the variable **[PREMIUM]** | +| `environment_scope` | string | no | The `environment_scope` of the variable **(PREMIUM)** | ``` curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value" diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 2b2e40fb276..c1588f2292a 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -1,6 +1,6 @@ # Project snippets -### Snippet visibility level +## Snippet visibility level Snippets in GitLab can be either private, internal or public. You can set it with the `visibility` field in the snippet. @@ -14,7 +14,7 @@ Constants for snippet visibility levels are: | `public` | The snippet can be accessed without any authentication | NOTE: **Note:** -From July 2019, the `Internal` visibility setting is disabled for new projects, groups, +From July 2019, the `Internal` visibility setting is disabled for new projects, groups, and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` visibility setting keep this setting. You can read more about the change in the [relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388). diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index 34d73abfcbf..2732fa47fa0 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -14,7 +14,7 @@ GET /projects/:id/statistics | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id ` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | Example response: diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index 0a94a8d47ae..cc932e3ef58 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -16,7 +16,7 @@ Support will be added for [Issue and Merge Request templates](../user/project/de in a future release. Support for [Group-level file templates](../user/group/index.md#group-file-templates-premium) -**[PREMIUM]** was [added](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987) +**(PREMIUM)** was [added](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987) in GitLab 11.5 ## Get all templates of a particular type @@ -27,7 +27,7 @@ GET /projects/:id/templates/:type | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id ` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `type` | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses)` of the template | Example response (licenses): @@ -93,7 +93,7 @@ GET /projects/:id/templates/:type/:key | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id ` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `id` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `type` | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses)` of the template | | `key` | string | yes | The key of the template, as obtained from the collection endpoint | | `project` | string | no | The project name to use when expanding placeholders in the template. Only affects licenses | diff --git a/doc/api/projects.md b/doc/api/projects.md index e07d6ce9a42..781192fb92e 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -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 | **[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) | +| `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: @@ -708,11 +708,17 @@ POST /projects | `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 | -| `jobs_enabled` | boolean | no | Enable jobs for this project | -| `wiki_enabled` | boolean | no | Enable wiki for this project | -| `snippets_enabled` | boolean | no | Enable snippets for this project | +| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead | +| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead | +| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead | +| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead | +| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead | +| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` | | `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | @@ -721,17 +727,23 @@ POST /projects | `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | -| `merge_method` | string | no | Set the merge method used | +| `merge_method` | string | no | Set the [merge method](#project-merge-method) used | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | | `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 | | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | +| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` | +| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | +| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | +| `build_coverage_regex` | string | no | Test coverage parsing | | `ci_config_path` | string | no | The path to CI config file | +| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | +| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | | `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 | +| `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: **Note:** If your HTTP repository is not publicly accessible, @@ -753,11 +765,17 @@ POST /projects/user/:user_id | `path` | string | no | Custom repository name for new project. By default generated based on name | | `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 | -| `merge_requests_enabled` | boolean | no | Enable merge requests for this project | -| `jobs_enabled` | boolean | no | Enable jobs for this project | -| `wiki_enabled` | boolean | no | Enable wiki for this project | -| `snippets_enabled` | boolean | no | Enable snippets for this project | +| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead | +| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead | +| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead | +| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead | +| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead | +| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` | | `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | @@ -766,18 +784,24 @@ POST /projects/user/:user_id | `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | -| `merge_method` | string | no | Set the merge method used | +| `merge_method` | string | no | Set the [merge method](#project-merge-method) used | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | | `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 | | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | +| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` | +| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | +| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | +| `build_coverage_regex` | string | no | Test coverage parsing | | `ci_config_path` | string | no | The path to CI config file | +| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | +| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | | `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 | +| `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: **Note:** If your HTTP repository is not publicly accessible, add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git` @@ -798,11 +822,17 @@ PUT /projects/:id | `path` | string | no | Custom repository name for the project. By default generated based on name | | `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 | -| `jobs_enabled` | boolean | no | Enable jobs for this project | -| `wiki_enabled` | boolean | no | Enable wiki for this project | -| `snippets_enabled` | boolean | no | Enable snippets for this project | +| `issues_enabled` | boolean | no | (deprecated) Enable issues for this project. Use `issues_access_level` instead | +| `merge_requests_enabled` | boolean | no | (deprecated) Enable merge requests for this project. Use `merge_requests_access_level` instead | +| `jobs_enabled` | boolean | no | (deprecated) Enable jobs for this project. Use `builds_access_level` instead | +| `wiki_enabled` | boolean | no | (deprecated) Enable wiki for this project. Use `wiki_access_level` instead | +| `snippets_enabled` | boolean | no | (deprecated) Enable snippets for this project. Use `snippets_access_level` instead | +| `issues_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `repository_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `merge_requests_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `builds_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `wiki_access_level` | string | no | One of `disabled`, `private` or `enabled` | +| `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` | | `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | @@ -811,22 +841,28 @@ PUT /projects/:id | `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | -| `merge_method` | string | no | Set the merge method used | +| `merge_method` | string | no | Set the [merge method](#project-merge-method) used | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | | `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 | +| `build_git_strategy` | string | no | The Git strategy. Defaults to `fetch` | +| `build_timeout` | integer | no | The maximum amount of time in minutes that a job is able run (in seconds) | +| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled | +| `build_coverage_regex` | string | no | Test coverage parsing | | `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) | +| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | +| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | | `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 | +| `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: **Note:** If your HTTP repository is not publicly accessible, add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git` @@ -1612,7 +1648,7 @@ POST /projects/:id/housekeeping | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | -## Push Rules **[STARTER]** +## Push Rules **(STARTER)** ### Get project push rules @@ -1631,6 +1667,7 @@ GET /projects/:id/push_rule "id": 1, "project_id": 3, "commit_message_regex": "Fixes \d+\..*", + "commit_message_negative_regex": "ssh\:\/\/", "branch_name_regex": "", "deny_delete_tag": false, "created_at": "2012-10-12T17:04:47Z", @@ -1663,18 +1700,19 @@ 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. | +| 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+\..*` | +| `commit_message_negative_regex` **(STARTER)** | string | no | No commit message is allowed to match this, e.g. `ssh\:\/\/` | +| `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 @@ -1684,18 +1722,19 @@ 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. | +| 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+\..*` | +| `commit_message_negative_regex` **(STARTER)** | string | no | No commit message is allowed to match this, e.g. `ssh\:\/\/` | +| `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 @@ -1736,7 +1775,7 @@ 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]** +## Start the pull mirroring process for a Project **(STARTER)** > Introduced in [GitLab Starter](https://about.gitlab.com/pricing) 10.3. diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 6e41584afef..9309306ba05 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -166,9 +166,9 @@ 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 | **[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 | +| `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: @@ -229,7 +229,7 @@ Example response: } ``` -### Example with user / group level access **[STARTER]** +### 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. diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index 3adca61a108..fb6fa040244 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -5,6 +5,7 @@ **Valid access levels** Currently, these levels are recognized: + ``` 0 => No access 30 => Developer access diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 681dc72c934..4aff79c9c62 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -121,9 +121,9 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `sha` (optional) - The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. For example: - ```sh - curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha> - ``` +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha> +``` ## Compare branches, tags or commits @@ -235,17 +235,17 @@ Example response: ```json { - "id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863", - "short_id": "1a0b36b3", - "title": "Initial commit", - "created_at": "2014-02-27T08:03:18.000Z", - "parent_ids": [], - "message": "Initial commit\n", - "author_name": "Dmitriy Zaporozhets", - "author_email": "dmitriy.zaporozhets@gmail.com", - "authored_date": "2014-02-27T08:03:18.000Z", - "committer_name": "Dmitriy Zaporozhets", - "committer_email": "dmitriy.zaporozhets@gmail.com", - "committed_date": "2014-02-27T08:03:18.000Z" + "id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863", + "short_id": "1a0b36b3", + "title": "Initial commit", + "created_at": "2014-02-27T08:03:18.000Z", + "parent_ids": [], + "message": "Initial commit\n", + "author_name": "Dmitriy Zaporozhets", + "author_email": "dmitriy.zaporozhets@gmail.com", + "authored_date": "2014-02-27T08:03:18.000Z", + "committer_name": "Dmitriy Zaporozhets", + "committer_email": "dmitriy.zaporozhets@gmail.com", + "committed_date": "2014-02-27T08:03:18.000Z" } ``` diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 2c44c4abc93..5a722a75cb9 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -43,7 +43,7 @@ Example response: "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba" ], "committed_date": "2018-09-20T09:26:24.000-07:00", - "authored_date": "2018-09-20T09:26:24.000-07:00", + "authored_date": "2018-09-20T09:26:24.000-07:00", "status": null } ``` diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index f0a7ac4e41d..7ad4d78014c 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -88,7 +88,7 @@ Parameters: curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events/1 ``` -## Epics **[ULTIMATE]** +## Epics **(ULTIMATE)** ### List group epic label events diff --git a/doc/api/runners.md b/doc/api/runners.md index 1318b9ca828..e6962d17a98 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -20,10 +20,10 @@ Here's an example of how the two tokens are used in Runner registration: 1. You use that authentication token and add it to the [Runner's configuration file](https://docs.gitlab.com/runner/commands/#configuration-file): - ```toml - [[runners]] - token = "<authentication_token>" - ``` + ```toml + [[runners]] + token = "<authentication_token>" + ``` GitLab and Runner are then connected. diff --git a/doc/api/scim.md b/doc/api/scim.md index 3870ea788e7..ece7f56e394 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -1,4 +1,4 @@ -# SCIM API **[SILVER ONLY]** +# SCIM API **(SILVER ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab Silver](https://about.gitlab.com/pricing/) 11.10. @@ -6,7 +6,7 @@ The SCIM API implements the [the RFC7644 protocol](https://tools.ietf.org/html/r NOTE: **Note:** [Group SSO](../user/group/saml_sso/index.md) and the feature -flag `:group_scim` must be enabled for the group. For more information, see [SCIM setup documentation](../user/group/saml_sso/scim_setup.md#requirements). +flag `:group_scim` must be enabled for the group. For more information, see [SCIM setup documentation](../user/group/saml_sso/scim_setup.md#requirements). ## Get a list of SAML users diff --git a/doc/api/search.md b/doc/api/search.md index abb77ae05dc..60acf600ac7 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -19,7 +19,7 @@ GET /search Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, snippet_blobs, users. -If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]** +If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)** The response depends on the requested scope. @@ -283,7 +283,7 @@ Example response: ] ``` -### Scope: wiki_blobs **[STARTER]** +### Scope: wiki_blobs **(STARTER)** This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -308,7 +308,7 @@ Example response: ] ``` -### Scope: commits **[STARTER]** +### Scope: commits **(STARTER)** This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -341,7 +341,7 @@ Example response: ] ``` -### Scope: blobs **[STARTER]** +### Scope: blobs **(STARTER)** This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -415,7 +415,7 @@ GET /groups/:id/search Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users. -If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]** +If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)** The response depends on the requested scope. @@ -617,7 +617,7 @@ Example response: ] ``` -### Scope: wiki_blobs **[STARTER]** +### Scope: wiki_blobs **(STARTER)** This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -642,7 +642,7 @@ Example response: ] ``` -### Scope: commits **[STARTER]** +### Scope: commits **(STARTER)** This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. @@ -675,7 +675,7 @@ Example response: ] ``` -### Scope: blobs **[STARTER]** +### Scope: blobs **(STARTER)** This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. diff --git a/doc/api/services.md b/doc/api/services.md index 4f35c17e927..df15e6892b0 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -1146,7 +1146,7 @@ Get JetBrains TeamCity CI service settings for a project. GET /projects/:id/services/teamcity ``` -## Jenkins CI **[STARTER]** +## Jenkins CI **(STARTER)** A continuous integration and build server diff --git a/doc/api/settings.md b/doc/api/settings.md index 0f46662a8ae..ff48cac1f47 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -150,7 +150,7 @@ these parameters: - `file_template_project_id` - `geo_node_allowed_ips` -Example responses: **[PREMIUM ONLY]** +Example responses: **(PREMIUM ONLY)** ```json "external_authorization_service_enabled": true, @@ -174,12 +174,12 @@ are listed in the descriptions of the relevant settings. | `after_sign_up_text` | string | no | Text shown to the user after signing up | | `akismet_api_key` | string | required by: `akismet_enabled` | API key for akismet spam protection. | | `akismet_enabled` | boolean | no | (**If enabled, requires:** `akismet_api_key`) Enable or disable akismet spam protection. | -| `allow_group_owners_to_manage_ldap` | boolean | no | **[PREMIUM]** Set to `true` to allow group owners to manage LDAP | +| `allow_group_owners_to_manage_ldap` | boolean | no | **(PREMIUM)** Set to `true` to allow group owners to manage LDAP | | `allow_local_requests_from_hooks_and_services` | boolean | no | Allow requests to the local network from hooks and services. | | `authorized_keys_enabled` | boolean | no | By default, we write to the `authorized_keys` file to support Git over SSH without additional configuration. GitLab can be optimized to authenticate SSH keys via the database file. Only disable this if you have configured your OpenSSH server to use the AuthorizedKeysCommand. | | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It will automatically build, test, and deploy applications based on a predefined CI/CD configuration. | -| `check_namespace_plan` | boolean | no | **[PREMIUM]** Enabling this will make only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | +| `check_namespace_plan` | boolean | no | **(PREMIUM)** Enabling this will make only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `clientside_sentry_dsn` | string | required by: `clientside_sentry_enabled` | Clientside Sentry Data Source Name. | | `clientside_sentry_enabled` | boolean | no | (**If enabled, requires:** `clientside_sentry_dsn`) Enable Sentry error reporting for the client side. | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | @@ -196,31 +196,31 @@ are listed in the descriptions of the relevant settings. | `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. | | `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. | | `ed25519_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. | -| `elasticsearch_aws` | boolean | no | **[PREMIUM]** Enable the use of AWS hosted Elasticsearch | -| `elasticsearch_aws_access_key` | string | no | **[PREMIUM]** AWS IAM access key | -| `elasticsearch_aws_region` | string | no | **[PREMIUM]** The AWS region the elasticsearch domain is configured | -| `elasticsearch_aws_secret_access_key` | string | no | **[PREMIUM]** AWS IAM secret access key | -| `elasticsearch_experimental_indexer` | boolean | no | **[PREMIUM]** Use the experimental elasticsearch indexer. More info: <https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer> | -| `elasticsearch_indexing` | boolean | no | **[PREMIUM]** Enable Elasticsearch indexing | -| `elasticsearch_search` | boolean | no | **[PREMIUM]** Enable Elasticsearch search | -| `elasticsearch_url` | string | no | **[PREMIUM]** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (e.g., `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | -| `elasticsearch_limit_indexing` | boolean | no | **[PREMIUM]** Limit Elasticsearch to index certain namespaces and projects | -| `elasticsearch_project_ids` | array of integers | no | **[PREMIUM]** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | -| `elasticsearch_namespace_ids` | array of integers | no | **[PREMIUM]** The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | -| `email_additional_text` | string | no | **[PREMIUM]** Additional text added to the bottom of every email for legal/auditing/compliance reasons | +| `elasticsearch_aws` | boolean | no | **(PREMIUM)** Enable the use of AWS hosted Elasticsearch | +| `elasticsearch_aws_access_key` | string | no | **(PREMIUM)** AWS IAM access key | +| `elasticsearch_aws_region` | string | no | **(PREMIUM)** The AWS region the elasticsearch domain is configured | +| `elasticsearch_aws_secret_access_key` | string | no | **(PREMIUM)** AWS IAM secret access key | +| `elasticsearch_experimental_indexer` | boolean | no | **(PREMIUM)** Use the experimental elasticsearch indexer. More info: <https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer> | +| `elasticsearch_indexing` | boolean | no | **(PREMIUM)** Enable Elasticsearch indexing | +| `elasticsearch_search` | boolean | no | **(PREMIUM)** Enable Elasticsearch search | +| `elasticsearch_url` | string | no | **(PREMIUM)** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (e.g., `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | +| `elasticsearch_limit_indexing` | boolean | no | **(PREMIUM)** Limit Elasticsearch to index certain namespaces and projects | +| `elasticsearch_project_ids` | array of integers | no | **(PREMIUM)** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `elasticsearch_namespace_ids` | array of integers | no | **(PREMIUM)** The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `email_additional_text` | string | no | **(PREMIUM)** Additional text added to the bottom of every email for legal/auditing/compliance reasons | | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | | `enforce_terms` | boolean | no | (**If enabled, requires:** `terms`) Enforce application ToS to all users. | -| `external_auth_client_cert` | string | no | **[PREMIUM]** (**If enabled, requires:** `external_auth_client_key`) The certificate to use to authenticate with the external authorization service | -| `external_auth_client_key` | string | required by: `external_auth_client_cert` | **[PREMIUM]** Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored | -| `external_auth_client_key_pass` | string | no | **[PREMIUM]** Passphrase to use for the private key when authenticating with the external service this is encrypted when stored | -| `external_authorization_service_enabled` | boolean | no | **[PREMIUM]** (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url` ) Enable using an external authorization service for accessing projects | -| `external_authorization_service_default_label` | string | required by: `external_authorization_service_enabled` | **[PREMIUM]** The default classification label to use when requesting authorization and no classification label has been specified on the project | -| `external_authorization_service_timeout` | float | required by: `external_authorization_service_enabled` | **[PREMIUM]** The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001) | -| `external_authorization_service_url` | string | required by: `external_authorization_service_enabled` | **[PREMIUM]** URL to which authorization requests will be directed | -| `file_template_project_id` | integer | no | **[PREMIUM]** The ID of a project to load custom file templates from | +| `external_auth_client_cert` | string | no | **(PREMIUM)** (**If enabled, requires:** `external_auth_client_key`) The certificate to use to authenticate with the external authorization service | +| `external_auth_client_key` | string | required by: `external_auth_client_cert` | **(PREMIUM)** Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored | +| `external_auth_client_key_pass` | string | no | **(PREMIUM)** Passphrase to use for the private key when authenticating with the external service this is encrypted when stored | +| `external_authorization_service_enabled` | boolean | no | **(PREMIUM)** (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url` ) Enable using an external authorization service for accessing projects | +| `external_authorization_service_default_label` | string | required by: `external_authorization_service_enabled` | **(PREMIUM)** The default classification label to use when requesting authorization and no classification label has been specified on the project | +| `external_authorization_service_timeout` | float | required by: `external_authorization_service_enabled` | **(PREMIUM)** The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001) | +| `external_authorization_service_url` | string | required by: `external_authorization_service_enabled` | **(PREMIUM)** URL to which authorization requests will be directed | +| `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from | | `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | -| `geo_status_timeout` | integer | no | **[PREMIUM]** The amount of seconds after which a request to get a secondary node status will time out. | +| `geo_status_timeout` | integer | no | **(PREMIUM)** The amount of seconds after which a request to get a secondary node status will time out. | | `gitaly_timeout_default` | integer | no | Default Gitaly timeout, in seconds. This timeout is not enforced for git fetch/push operations or Sidekiq jobs. Set to `0` to disable timeouts. | | `gitaly_timeout_fast` | integer | no | Gitaly fast operation timeout, in seconds. Some Gitaly operations are expected to be fast. If they exceed this threshold, there may be a problem with a storage shard and 'failing fast' can help maintain the stability of the GitLab instance. Set to `0` to disable timeouts. | | `gitaly_timeout_medium` | integer | no | Medium Gitaly timeout, in seconds. This should be a value between the Fast and the Default timeout. Set to `0` to disable timeouts. | @@ -229,7 +229,7 @@ are listed in the descriptions of the relevant settings. | `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help. | | `help_page_support_url` | string | no | Alternate support URL for help page. | | `help_page_text` | string | no | Custom text displayed on the help page. | -| `help_text` | string | no | **[PREMIUM]** GitLab server administrator information | +| `help_text` | string | no | **(PREMIUM)** GitLab server administrator information | | `hide_third_party_offers` | boolean | no | Do not display offers from third parties within GitLab. | | `home_page_url` | string | no | Redirect to this URL when not logged in. | | `housekeeping_bitmaps_enabled` | boolean | required by: `housekeeping_enabled` | Enable Git pack file bitmap creation. | @@ -252,9 +252,9 @@ are listed in the descriptions of the relevant settings. | `metrics_sample_interval` | integer | required by: `metrics_enabled` | The sampling interval in seconds. | | `metrics_timeout` | integer | required by: `metrics_enabled` | The amount of seconds after which InfluxDB will time out. | | `mirror_available` | boolean | no | Allow mirrors to be set up for projects. If disabled, only admins will be able to set up mirrors in projects. | -| `mirror_capacity_threshold` | integer | no | **[PREMIUM]** Minimum capacity to be available before scheduling more mirrors preemptively | -| `mirror_max_capacity` | integer | no | **[PREMIUM]** Maximum number of mirrors that can be synchronizing at the same time. | -| `mirror_max_delay` | integer | no | **[PREMIUM]** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | +| `mirror_capacity_threshold` | integer | no | **(PREMIUM)** Minimum capacity to be available before scheduling more mirrors preemptively | +| `mirror_max_capacity` | integer | no | **(PREMIUM)** Maximum number of mirrors that can be synchronizing at the same time. | +| `mirror_max_delay` | integer | no | **(PREMIUM)** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | | `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | | `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | | `password_authentication_enabled_for_web` | boolean | no | Enable authentication for the web interface via a GitLab account password. Default is `true`. | @@ -266,12 +266,12 @@ are listed in the descriptions of the relevant settings. | `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to `0` to disable polling. | | `project_export_enabled` | boolean | no | Enable project export. | | `prometheus_metrics_enabled` | boolean | no | Enable prometheus metrics. | -| `pseudonymizer_enabled` | boolean | no | **[PREMIUM]** When enabled, GitLab will run a background job that will produce pseudonymized CSVs of the GitLab database that will be uploaded to your configured object storage directory. +| `pseudonymizer_enabled` | boolean | no | **(PREMIUM)** When enabled, GitLab will run a background job that will produce pseudonymized CSVs of the GitLab database that will be uploaded to your configured object storage directory. | `recaptcha_enabled` | boolean | no | (**If enabled, requires:** `recaptcha_private_key` and `recaptcha_site_key`) Enable recaptcha. | | `recaptcha_private_key` | string | required by: `recaptcha_enabled` | Private key for recaptcha. | | `recaptcha_site_key` | string | required by: `recaptcha_enabled` | Site key for recaptcha. | | `repository_checks_enabled` | boolean | no | GitLab will periodically run `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | -| `repository_size_limit` | integer | no | **[PREMIUM]** Size limit per repository (MB) | +| `repository_size_limit` | integer | no | **(PREMIUM)** Size limit per repository (MB) | | `repository_storages` | array of strings | no | A list of names of enabled storage paths, taken from `gitlab.yml`. New projects will be created in one of these stores, chosen at random. | | `require_two_factor_authentication` | boolean | no | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. | | `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for groups, projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is `null` which means there is no restriction. | @@ -279,15 +279,15 @@ are listed in the descriptions of the relevant settings. | `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. | | `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | -| `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **[PREMIUM]** Set the maximum number of pipeline minutes that a group can use on shared Runners per month. | +| `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared Runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | | `sign_in_text` | string | no | Text on the login page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | | `signup_enabled` | boolean | no | Enable registration. Default is `true`. | -| `slack_app_enabled` | boolean | no | **[PREMIUM]** (**If enabled, requires:** `slack_app_id`, `slack_app_secret` and `slack_app_secret`) Enable Slack app. | -| `slack_app_id` | string | required by: `slack_app_enabled` | **[PREMIUM]** The app id of the Slack-app. | -| `slack_app_secret` | string | required by: `slack_app_enabled` | **[PREMIUM]** The app secret of the Slack-app. | -| `slack_app_verification_token` | string | required by: `slack_app_enabled` | **[PREMIUM]** The verification token of the Slack-app. | +| `slack_app_enabled` | boolean | no | **(PREMIUM)** (**If enabled, requires:** `slack_app_id`, `slack_app_secret` and `slack_app_secret`) Enable Slack app. | +| `slack_app_id` | string | required by: `slack_app_enabled` | **(PREMIUM)** The app id of the Slack-app. | +| `slack_app_secret` | string | required by: `slack_app_enabled` | **(PREMIUM)** The app secret of the Slack-app. | +| `slack_app_verification_token` | string | required by: `slack_app_enabled` | **(PREMIUM)** The verification token of the Slack-app. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. | | `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. | | `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). | @@ -310,4 +310,4 @@ are listed in the descriptions of the relevant settings. | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the "You won't be able to pull or push project code via SSH" warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | | `local_markdown_version` | integer | no | Increase this value when any cached markdown should be invalidated. | -| `geo_node_allowed_ips` | string | yes | **[PREMIUM]** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | +| `geo_node_allowed_ips` | string | yes | **(PREMIUM)** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | diff --git a/doc/api/tags.md b/doc/api/tags.md index 3177fec618f..af86ba961f4 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -141,6 +141,7 @@ Parameters: "message": null } ``` + The message will be `null` when creating a lightweight tag otherwise it will contain the annotation. diff --git a/doc/api/users.md b/doc/api/users.md index e1fccc14df3..b43b4de823b 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -164,6 +164,7 @@ the `group_saml` provider option: ... } ] +``` You can lookup users by external UID and provider: @@ -359,8 +360,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 **[STARTER]** -- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]** +- `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 @@ -396,8 +397,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]** +- `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, @@ -592,6 +593,30 @@ Example responses } ``` +## User counts + +Get the counts (same as in top right menu) of the currently signed in user. + +| Attribute | Type | Description | +| --------- | ---- | ----------- | +| `merge_requests` | number | Merge requests that are active and assigned to current user. | + +``` +GET /user_counts +``` + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user_counts" +``` + +Example response: + +```json +{ + "merge_requests": 4 +} +``` + ## List user projects Please refer to the [List of user projects](projects.md#list-user-projects). diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 5752fb7c078..5f875528a6c 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -9,7 +9,7 @@ The V3 API documentation is still Below are the changes made between V3 and V4. -### 8.17 +## 8.17 - Removed `GET /projects/:search` (use: `GET /projects?search=x`) [!8877](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8877) - `iid` filter has been removed from `GET /projects/:id/issues` [!8967](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8967) @@ -18,7 +18,7 @@ Below are the changes made between V3 and V4. - Project snippets do not return deprecated field `expires_at` [!8723](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8723) - Endpoints under `GET /projects/:id/keys` have been removed (use `GET /projects/:id/deploy_keys`) [!8716](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8716) -### 9.0 +## 9.0 - Status 409 returned for `POST /projects/:id/members` when a member already exists [!9093](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9093) - Moved `DELETE /projects/:id/star` to `POST /projects/:id/unstar` [!9328](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9328) diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index f1b11c7bceb..eaa4c13de55 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -1,4 +1,4 @@ -# Vulnerabilities API **[ULTIMATE]** +# Vulnerabilities API **(ULTIMATE)** Every API call to vulnerabilities must be authenticated. @@ -30,6 +30,7 @@ GET /projects/:id/vulnerabilities?scope=all GET /projects/:id/vulnerabilities?scope=dismissed GET /projects/:id/vulnerabilities?severity=high GET /projects/:id/vulnerabilities?confidence=unknown,experimental +GET /projects/:id/vulnerabilities?pipeline_id=42 ``` | Attribute | Type | Required | Description | @@ -39,6 +40,7 @@ GET /projects/:id/vulnerabilities?confidence=unknown,experimental | `scope` | string | no | Returns vulnerabilities for the given scope: `all` or `dismissed`. Defaults to `dismissed` | | `severity` | string array | no | Returns vulnerabilities belonging to specified severity level: `undefined`, `info`, `unknown`, `low`, `medium`, `high`, or `critical`. Defaults to all' | | `confidence` | string array | no | Returns vulnerabilities belonging to specified confidence level: `undefined`, `ignore`, `unknown`, `experimental`, `low`, `medium`, `high`, or `confirmed`. Defaults to all | +| `pipeline_id` | integer/string | no | Returns vulnerabilities belonging to specified pipeline. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/vulnerabilities |