diff options
Diffstat (limited to 'doc/api')
87 files changed, 2122 insertions, 1729 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index db0c593dc03..c23a383c70f 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use the GitLab [REST](http://spec.openapis.org/oas/v3.0.3) API to automate GitLab. -You can also use a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/api/openapi/openapi.yaml), +You can also use a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/openapi/openapi.yaml), to test the API directly from the GitLab user interface. Contributions are welcome. @@ -59,8 +59,8 @@ version number. New features and bug fixes are released in tandem with GitLab. Apart from incidental patch and security releases, GitLab is released on the 22nd of each -month. Backward-incompatible changes (for example, endpoint and parameter removal), -and removal of entire API versions are done in tandem with major GitLab releases. +month. Major API version changes, and removal of entire API versions, are done in tandem +with major GitLab releases. All deprecations and changes between versions are in the documentation. For the changes between v3 and v4, see the [v3 to v4 documentation](v3_to_v4.md). @@ -73,7 +73,7 @@ Only API version v4 is available. Version v3 was removed in ## How to use the API API requests must include both `api` and the API version. The API -version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/api/api.rb). +version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/api.rb). For example, the root of the v4 API is at `/api/v4`. ### Valid API request @@ -597,7 +597,8 @@ send the payload body: - Request payload (JSON): ```shell - curl --request POST --header "Content-Type: application/json" --data '{"name":"<example-name>", "description":"<example-description"}' "https://gitlab/api/v4/projects" + curl --request POST --header "Content-Type: application/json" \ + --data '{"name":"<example-name>", "description":"<example-description"}' "https://gitlab/api/v4/projects" ``` URL encoded query strings have a length limitation. Requests that are too large diff --git a/doc/api/applications.md b/doc/api/applications.md index b3a46b70c9e..7047dccea88 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -40,7 +40,9 @@ Parameters: Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=MyApplication&redirect_uri=http://redirect.uri&scopes=" "https://gitlab.example.com/api/v4/applications" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --data "name=MyApplication&redirect_uri=http://redirect.uri&scopes=" \ + "https://gitlab.example.com/api/v4/applications" ``` Example response: diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 93fefe50d9e..dec2b85c61d 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -11,6 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Instance Audit Events **(PREMIUM SELF)** The Audit Events API allows you to retrieve [instance audit events](../administration/audit_events.md#instance-events). +This API cannot retrieve group or project audit events. To retrieve audit events using the API, you must [authenticate yourself](README.md#authentication) as an Administrator. @@ -133,6 +134,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34078) in GitLab 12.5. The Group Audit Events API allows you to retrieve [group audit events](../administration/audit_events.md#group-events). +This API cannot retrieve project audit events. A user with a Owner role (or above) can retrieve group audit events of all users. A user with a Developer or Maintainer role is limited to group audit events based on their individual actions. diff --git a/doc/api/boards.md b/doc/api/boards.md index 3252036c840..3cdd9552d66 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -250,7 +250,8 @@ Example response: "path_with_namespace": "diaspora/diaspora-project-site", "created_at": "2018-07-03T05:48:49.982Z", "default_branch": null, - "tag_list": [], + "tag_list": [], //deprecated, use `topics` instead + "topics": [], "ssh_url_to_repo": "ssh://user@example.com/diaspora/diaspora-project-site.git", "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git", "web_url": "http://example.com/diaspora/diaspora-project-site", diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index de56405056a..b98373b5a58 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -4,9 +4,7 @@ group: Activation info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Broadcast Messages API - -> Introduced in GitLab 8.12. +# Broadcast Messages API **(FREE SELF)** Broadcast messages API operates on [broadcast messages](../user/admin_area/broadcast_messages.md). @@ -109,7 +107,9 @@ Parameters: Example request: ```shell -curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages" +curl --data "message=Deploy in progress&color=#cecece" \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/broadcast_messages" ``` Example response: @@ -154,7 +154,8 @@ Parameters: Example request: ```shell -curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1" +curl --request PUT --data "message=Update message&color=#000" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/broadcast_messages/1" ``` Example response: diff --git a/doc/api/commits.md b/doc/api/commits.md index 22d98b2b0a6..711b565bdbd 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -7,7 +7,7 @@ type: reference, api # Commits API **(FREE)** -This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository). Read more about [GitLab-specific information](../user/project/repository/index.md#commits) for commits. +This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository). Read more about [GitLab-specific information](../user/project/repository/index.md#commit-changes-to-a-repository) for commits. ## List repository commits @@ -28,6 +28,7 @@ GET /projects/:id/repository/commits | `with_stats` | boolean | no | Stats about each commit are added to the response | | `first_parent` | boolean | no | Follow only the first parent commit upon seeing a merge commit | | `order` | string | no | List commits in order. Possible values: `default`, [`topo`](https://git-scm.com/docs/git-log#Documentation/git-log.txt---topo-order). Defaults to `default`, the commits are shown in reverse chronological order. | +| `trailers` | boolean | no | Parse and include [Git trailers](https://git-scm.com/docs/git-interpret-trailers) for every commit | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits" @@ -141,7 +142,8 @@ PAYLOAD=$(cat << 'JSON' } JSON ) -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data "$PAYLOAD" "https://gitlab.example.com/api/v4/projects/1/repository/commits" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + --data "$PAYLOAD" "https://gitlab.example.com/api/v4/projects/1/repository/commits" ``` Example response: @@ -305,9 +307,11 @@ Parameters: | `sha` | string | yes | The commit hash | | `branch` | string | yes | The name of the branch | | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced in GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) | +| `message` | string | no | A custom commit message to use for the new commit. [Introduced in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62481) ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/cherry_pick" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/cherry_pick" ``` Example response: @@ -380,7 +384,8 @@ Parameters: | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced in GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=master" \ + "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert" ``` Example response: @@ -534,7 +539,9 @@ POST /projects/:id/repository/commits/:sha/comments | `line_type` | string | no | The line type. Takes `new` or `old` as arguments | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "note=Nice picture man\!" --form "path=dudeism.md" --form "line=11" --form "line_type=new" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "note=Nice picture man\!" --form "path=dudeism.md" --form "line=11" --form "line_type=new" \ + "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments" ``` Example response: @@ -791,6 +798,7 @@ Example response: "source_project_id":35, "target_project_id":35, "labels":[ ], + "draft":false, "work_in_progress":false, "milestone":null, "merge_when_pipeline_succeeds":false, diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 0b37c0ad91a..4de024da2de 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -90,7 +90,8 @@ GET /groups/:id/registry/repositories | `tags_count` | boolean | no | If the parameter is included as true, each repository includes `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/2/registry/repositories?tags=1&tags_count=true" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/2/registry/repositories?tags=1&tags_count=true" ``` Example response: @@ -161,7 +162,8 @@ GET /registry/repositories/:id | `tags_count` | boolean | no | If the parameter is included as `true`, the response includes `"tags_count"`. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/registry/repositories/2?tags=true&tags_count=true" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/registry/repositories/2?tags=true&tags_count=true" ``` Example response: @@ -202,7 +204,8 @@ DELETE /projects/:id/registry/repositories/:repository_id | `repository_id` | integer | yes | The ID of registry repository. | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2" ``` ## List registry repository tags @@ -221,7 +224,8 @@ GET /projects/:id/registry/repositories/:repository_id/tags | `repository_id` | integer | yes | The ID of registry repository. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" ``` Example response: @@ -256,7 +260,8 @@ GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name | `tag_name` | string | yes | The name of tag. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" ``` Example response: @@ -289,7 +294,8 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name | `tag_name` | string | yes | The name of tag. | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" ``` This action doesn't delete blobs. To delete them and recycle disk space, @@ -350,23 +356,27 @@ Examples: and remove ones that are older than 2 days: ```shell - curl --request DELETE --data 'name_regex_delete=[0-9a-z]{40}' --data 'keep_n=5' --data 'older_than=2d' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + curl --request DELETE --data 'name_regex_delete=[0-9a-z]{40}' --data 'keep_n=5' --data 'older_than=2d' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" ``` 1. Remove all tags, but keep always the latest 5: ```shell - curl --request DELETE --data 'name_regex_delete=.*' --data 'keep_n=5' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + curl --request DELETE --data 'name_regex_delete=.*' --data 'keep_n=5' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" ``` 1. Remove all tags, but keep always tags beginning with `stable`: ```shell - curl --request DELETE --data 'name_regex_delete=.*' --data 'name_regex_keep=stable.*' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + curl --request DELETE --data 'name_regex_delete=.*' --data 'name_regex_keep=stable.*' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" ``` 1. Remove all tags that are older than 1 month: ```shell - curl --request DELETE --data 'name_regex_delete=.*' --data 'older_than=1month' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + curl --request DELETE --data 'name_regex_delete=.*' --data 'older_than=1month' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" ``` diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index a17b3b78b18..56a9f6881cd 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.md @@ -90,7 +90,8 @@ PUT /projects/:id/custom_attributes/:key | `value` | string | yes | The value of the custom attribute | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "value=Greenland" "https://gitlab.example.com/api/v4/users/42/custom_attributes/location" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + --data "value=Greenland" "https://gitlab.example.com/api/v4/users/42/custom_attributes/location" ``` Example response: diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index 8448edef9c5..139669c018c 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -11,7 +11,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11631) in GitLab 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. -Deletes the cached manifests and blobs for a group. This endpoint requires group owner access. +Deletes the cached manifests and blobs for a group. This endpoint requires the [Owner role](../user/permissions.md) +for the group. WARNING: [A bug exists](https://gitlab.com/gitlab-org/gitlab/-/issues/277161) for this API. diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 30a56e6253b..3b063180900 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -124,7 +124,9 @@ POST /projects/:id/deploy_keys | `can_push` | boolean | no | Can deploy key push to the project's repository | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + --data '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' \ + "https://gitlab.example.com/api/v4/projects/5/deploy_keys/" ``` Example response: @@ -154,7 +156,8 @@ PUT /projects/:id/deploy_keys/:key_id | `can_push` | boolean | no | Can deploy key push to the project's repository | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"title": "New deploy key", "can_push": true}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + --data '{"title": "New deploy key", "can_push": true}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11" ``` Example response: @@ -238,7 +241,9 @@ With those IDs, add the same deploy key to all: ```shell for project_id in 321 456 987; do - curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ - --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' "https://gitlab.example.com/api/v4/projects/${project_id}/deploy_keys" + curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ + --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' \ + "https://gitlab.example.com/api/v4/projects/${project_id}/deploy_keys" done ``` diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index ad144946445..d8aab8896a1 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -49,7 +49,8 @@ Example response: ## Project deploy tokens -Project deploy token API endpoints require project maintainer access or higher. +Project deploy token API endpoints require the [Maintainer role](../user/permissions.md) or higher +for the project. ### List project deploy tokens @@ -116,7 +117,9 @@ Parameters: Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "My deploy token", "expires_at": "2021-01-01", "username": "custom-user", "scopes": ["read_repository"]}' "https://gitlab.example.com/api/v4/projects/5/deploy_tokens/" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + --data '{"name": "My deploy token", "expires_at": "2021-01-01", "username": "custom-user", "scopes": ["read_repository"]}' \ + "https://gitlab.example.com/api/v4/projects/5/deploy_tokens/" ``` Example response: @@ -156,7 +159,8 @@ Parameters: Example request: ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_tokens/13" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/5/deploy_tokens/13" ``` ## Group deploy tokens @@ -229,7 +233,9 @@ Parameters: Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "My deploy token", "expires_at": "2021-01-01", "username": "custom-user", "scopes": ["read_repository"]}' "https://gitlab.example.com/api/v4/groups/5/deploy_tokens/" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + --data '{"name": "My deploy token", "expires_at": "2021-01-01", "username": "custom-user", "scopes": ["read_repository"]}' \ + "https://gitlab.example.com/api/v4/groups/5/deploy_tokens/" ``` Example response: diff --git a/doc/api/deployments.md b/doc/api/deployments.md index cf224ad60ab..586f3edf51e 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -9,6 +9,9 @@ type: concepts, howto ## List project deployments +> The `updated_after` and `updated_before` attributes were removed and replaced + by `finished_after` and `finished_before` respectively in GitLab 14.0. + Get a list of deployments in a project. ```plaintext @@ -17,27 +20,19 @@ GET /projects/:id/deployments | 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 | -| `order_by` | string | no | Return deployments ordered by `id` or `iid` or `created_at` or `updated_at` or `ref` fields. Default is `id` | -| `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` | -| `updated_after` | datetime | no | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `updated_before` | datetime | no | Return deployments updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `environment` | string | no | The [name of the environment](../ci/environments/index.md) to filter deployments by | -| `status` | string | no | The status to filter deployments by | - -The status attribute can be one of the following values: - -- created -- running -- success -- failed -- canceled +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `order_by` | string | no | Return deployments ordered by either one of `id`, `iid`, `created_at`, `updated_at` or `ref` fields. Default is `id`. | +| `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc`. | +| `finished_after` | datetime | no | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `finished_before` | datetime | no | Return deployments updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `environment` | string | no | The [name of the environment](../ci/environments/index.md) to filter deployments by. | +| `status` | string | no | The status to filter deployments by. One of `created`, `running`, `success`, `failed`, `canceled`. ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments" ``` -Example of response +Example response: ```json [ @@ -51,16 +46,16 @@ Example of response "author_name": "Administrator", "created_at": "2016-08-11T09:36:01.000+02:00", "id": "99d03678b90d914dbb1b109132516d71a4a03ea8", - "message": "Merge branch 'new-title' into 'master'\r\n\r\nUpdate README\r\n\r\n\r\n\r\nSee merge request !1", + "message": "Merge branch 'new-title' into 'main'\r\n\r\nUpdate README\r\n\r\n\r\n\r\nSee merge request !1", "short_id": "99d03678", - "title": "Merge branch 'new-title' into 'master'\r" + "title": "Merge branch 'new-title' into 'main'\r" }, "coverage": null, "created_at": "2016-08-11T07:36:27.357Z", "finished_at": "2016-08-11T07:36:39.851Z", "id": 657, "name": "deploy", - "ref": "master", + "ref": "main", "runner": null, "stage": "deploy", "started_at": null, @@ -86,7 +81,7 @@ Example of response "pipeline": { "created_at": "2016-08-11T02:12:10.222Z", "id": 36, - "ref": "master", + "ref": "main", "sha": "99d03678b90d914dbb1b109132516d71a4a03ea8", "status": "success", "updated_at": "2016-08-11T02:12:10.222Z", @@ -100,7 +95,7 @@ Example of response }, "id": 41, "iid": 1, - "ref": "master", + "ref": "main", "sha": "99d03678b90d914dbb1b109132516d71a4a03ea8", "user": { "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", @@ -121,16 +116,16 @@ Example of response "author_name": "Administrator", "created_at": "2016-08-11T13:28:26.000+02:00", "id": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", - "message": "Merge branch 'rename-readme' into 'master'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2", + "message": "Merge branch 'rename-readme' into 'main'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2", "short_id": "a91957a8", - "title": "Merge branch 'rename-readme' into 'master'\r" + "title": "Merge branch 'rename-readme' into 'main'\r" }, "coverage": null, "created_at": "2016-08-11T11:32:24.456Z", "finished_at": "2016-08-11T11:32:35.145Z", "id": 664, "name": "deploy", - "ref": "master", + "ref": "main", "runner": null, "stage": "deploy", "started_at": null, @@ -156,7 +151,7 @@ Example of response "pipeline": { "created_at": "2016-08-11T07:43:52.143Z", "id": 37, - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "status": "success", "updated_at": "2016-08-11T07:43:52.143Z", @@ -170,7 +165,7 @@ Example of response }, "id": 42, "iid": 2, - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "user": { "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", @@ -199,13 +194,13 @@ GET /projects/:id/deployments/:deployment_id curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/1" ``` -Example of response +Example response: ```json { "id": 42, "iid": 2, - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "created_at": "2016-08-11T11:32:35.444Z", "updated_at": "2016-08-11T11:34:01.123Z", @@ -227,7 +222,7 @@ Example of response "status": "success", "stage": "deploy", "name": "deploy", - "ref": "master", + "ref": "main", "tag": false, "coverage": null, "created_at": "2016-08-11T11:32:24.456Z", @@ -252,16 +247,16 @@ Example of response "commit": { "id": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "short_id": "a91957a8", - "title": "Merge branch 'rename-readme' into 'master'\r", + "title": "Merge branch 'rename-readme' into 'main'\r", "author_name": "Administrator", "author_email": "admin@example.com", "created_at": "2016-08-11T13:28:26.000+02:00", - "message": "Merge branch 'rename-readme' into 'master'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2" + "message": "Merge branch 'rename-readme' into 'main'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2" }, "pipeline": { "created_at": "2016-08-11T07:43:52.143Z", "id": 42, - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "status": "success", "updated_at": "2016-08-11T07:43:52.143Z", @@ -280,32 +275,25 @@ POST /projects/:id/deployments | 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 | -| `environment` | string | yes | The [name of the environment](../ci/environments/index.md) to create the deployment for | -| `sha` | string | yes | The SHA of the commit that is deployed | -| `ref` | string | yes | The name of the branch or tag that is deployed | -| `tag` | boolean | yes | A boolean that indicates if the deployed ref is a tag (true) or not (false) | -| `status` | string | yes | The status of the deployment | - -The status can be one of the following values: - -- created -- running -- success -- failed -- canceled +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.| +| `environment` | string | yes | The [name of the environment](../ci/environments/index.md) to create the deployment for. | +| `sha` | string | yes | The SHA of the commit that is deployed. | +| `ref` | string | yes | The name of the branch or tag that is deployed. | +| `tag` | boolean | yes | A boolean that indicates if the deployed ref is a tag (`true`) or not (`false`). | +| `status` | string | no | The status to filter deployments by. One of `created`, `running`, `success`, `failed`, or `canceled`. | ```shell -curl --data "environment=production&sha=a91957a858320c0e17f3a0eca7cfacbff50ea29a&ref=master&tag=false&status=success" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments" +curl --data "environment=production&sha=a91957a858320c0e17f3a0eca7cfacbff50ea29a&ref=main&tag=false&status=success" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments" ``` -Example of a response: +Example response: ```json { "id": 42, "iid": 2, - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "created_at": "2016-08-11T11:32:35.444Z", "status": "success", @@ -326,7 +314,7 @@ Example of a response: } ``` -## Updating a deployment +## Update a deployment ```plaintext PUT /projects/:id/deployments/:deployment_id @@ -334,21 +322,21 @@ PUT /projects/:id/deployments/:deployment_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 | -| `deployment_id` | integer | yes | The ID of the deployment to update | -| `status` | string | yes | The new status of the deployment | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `deployment_id` | integer | yes | The ID of the deployment to update. | +| `status` | string | no | The new status of the deployment. One of `created`, `running`, `success`, `failed`, or `canceled`. | ```shell curl --request PUT --data "status=success" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42" ``` -Example of a response: +Example response: ```json { "id": 42, "iid": 2, - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "created_at": "2016-08-11T11:32:35.444Z", "status": "success", @@ -382,5 +370,5 @@ GET /projects/:id/deployments/:deployment_id/merge_requests It supports the same parameters as the [Merge Requests API](merge_requests.md#list-merge-requests) and returns a response using the same format: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42/merge_requests" ``` diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 3d40349ecca..d8d989adfe2 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -156,7 +156,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `body` | string | yes | The content of the thread | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment" @@ -167,7 +167,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla Adds a new note to the thread. This can also [create a thread from a single comment](../user/discussions/#start-a-thread-by-replying-to-a-standard-comment). **WARNING** -Notes can be added to other items than comments (system notes, etc.) making them threads. +Notes can be added to other items than comments, such as system notes, making them threads. ```plaintext POST /projects/:id/issues/:issue_iid/discussions/:discussion_id/notes @@ -182,7 +182,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" @@ -365,7 +365,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `body` | string | yes | The content of a discussion | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment" @@ -388,7 +388,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" @@ -572,7 +572,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `body` | string | yes | The content of the thread | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment" @@ -596,7 +596,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" @@ -847,7 +847,7 @@ Parameters for all comments: | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | | `commit_id` | string | no | SHA referencing commit to start this thread on | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | | `position` | hash | no | Position when creating a diff note | | `position[base_sha]` | string | yes | Base commit SHA in the source branch | | `position[start_sha]` | string | yes | SHA referencing commit in target branch | @@ -902,7 +902,7 @@ To create a new thread: "previous versions are here" ] ``` - + 1. Create a new diff thread. This example creates a thread on an added line: ```shell @@ -981,7 +981,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" @@ -1216,7 +1216,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `commit_id` | integer | yes | The ID of a commit | | `body` | string | yes | The content of the thread | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | | `position` | hash | no | Position when creating a diff note | | `position[base_sha]` | string | yes | Base commit SHA in the source branch | | `position[start_sha]` | string | yes | SHA referencing commit in target branch | @@ -1252,7 +1252,7 @@ Parameters: | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | | `body` | string | yes | The content of the note/reply | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted, such `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 31e6fee66ca..99826550b61 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -7,7 +7,8 @@ type: reference, api # DevOps Research and Assessment (DORA) key metrics API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> - The legacy key/value pair `{ "<date>" => "<value>" }` was removed from the payload in GitLab 14.0. All methods require [reporter permissions and above](../../user/permissions.md). @@ -38,14 +39,14 @@ Example response: ```json [ - { "2021-03-01": 3, "date": "2021-03-01", "value": 3 }, - { "2021-03-02": 6, "date": "2021-03-02", "value": 6 }, - { "2021-03-03": 0, "date": "2021-03-03", "value": 0 }, - { "2021-03-04": 0, "date": "2021-03-04", "value": 0 }, - { "2021-03-05": 0, "date": "2021-03-05", "value": 0 }, - { "2021-03-06": 0, "date": "2021-03-06", "value": 0 }, - { "2021-03-07": 0, "date": "2021-03-07", "value": 0 }, - { "2021-03-08": 4, "date": "2021-03-08", "value": 4 } + { "date": "2021-03-01", "value": 3 }, + { "date": "2021-03-02", "value": 6 }, + { "date": "2021-03-03", "value": 0 }, + { "date": "2021-03-04", "value": 0 }, + { "date": "2021-03-05", "value": 0 }, + { "date": "2021-03-06", "value": 0 }, + { "date": "2021-03-07", "value": 0 }, + { "date": "2021-03-08", "value": 4 } ] ``` @@ -78,14 +79,14 @@ Example response: ```json [ - { "2021-03-01": 3, "date": "2021-03-01", "value": 3 }, - { "2021-03-02": 6, "date": "2021-03-02", "value": 6 }, - { "2021-03-03": 0, "date": "2021-03-03", "value": 0 }, - { "2021-03-04": 0, "date": "2021-03-04", "value": 0 }, - { "2021-03-05": 0, "date": "2021-03-05", "value": 0 }, - { "2021-03-06": 0, "date": "2021-03-06", "value": 0 }, - { "2021-03-07": 0, "date": "2021-03-07", "value": 0 }, - { "2021-03-08": 4, "date": "2021-03-08", "value": 4 } + { "date": "2021-03-01", "value": 3 }, + { "date": "2021-03-02", "value": 6 }, + { "date": "2021-03-03", "value": 0 }, + { "date": "2021-03-04", "value": 0 }, + { "date": "2021-03-05", "value": 0 }, + { "date": "2021-03-06", "value": 0 }, + { "date": "2021-03-07", "value": 0 }, + { "date": "2021-03-08", "value": 4 } ] ``` diff --git a/doc/api/dora4_group_analytics.md b/doc/api/dora4_group_analytics.md index 743dcf728a2..501bf824f03 100644 --- a/doc/api/dora4_group_analytics.md +++ b/doc/api/dora4_group_analytics.md @@ -1,5 +1,6 @@ --- redirect_to: 'dora/metrics.md' +remove_date: '2021-07-25' --- This document was moved to [another location](dora/metrics.md). diff --git a/doc/api/environments.md b/doc/api/environments.md index 7340fe9f9e9..4c93b3b15d5 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -164,7 +164,8 @@ POST /projects/:id/environments | `external_url` | string | no | Place to link to for this environment | ```shell -curl --data "name=deploy&external_url=https://deploy.gitlab.example.com" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments" +curl --data "name=deploy&external_url=https://deploy.gitlab.example.com" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments" ``` Example response: @@ -197,7 +198,8 @@ PUT /projects/:id/environments/:environments_id | `external_url` | string | no | The new `external_url` | ```shell -curl --request PUT --data "name=staging&external_url=https://staging.gitlab.example.com" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" +curl --request PUT --data "name=staging&external_url=https://staging.gitlab.example.com" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" ``` Example response: diff --git a/doc/api/feature_flag_specs.md b/doc/api/feature_flag_specs.md index 45db47f5ffe..33e454d50c4 100644 --- a/doc/api/feature_flag_specs.md +++ b/doc/api/feature_flag_specs.md @@ -8,293 +8,5 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. -WARNING: -This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). - -The API for creating, updating, reading and deleting Feature Flag Specs. -Automation engineers benefit from this API by being able to modify Feature Flag Specs without accessing user interface. -To manage the [Feature Flag](../operations/feature_flags.md) resources via public API, please refer to the [Feature Flags API](feature_flags.md) document. - -Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag Specs API. - -## List all effective feature flag specs under the specified environment - -Get all effective feature flag specs under the specified [environment](../ci/environments/index.md). - -For instance, there are two specs, `staging` and `production`, for a feature flag. -When you pass `production` as a parameter to this endpoint, the system returns -the `production` feature flag spec only. - -```plaintext -GET /projects/:id/feature_flag_scopes -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `environment` | string | yes | The [environment](../ci/environments/index.md) name | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flag_scopes?environment=production" -``` - -Example response: - -```json -[ - { - "id": 88, - "active": true, - "environment_scope": "production", - "strategies": [ - { - "name": "userWithId", - "parameters": { - "userIds": "1,2,3" - } - } - ], - "created_at": "2019-11-04T08:36:41.327Z", - "updated_at": "2019-11-04T08:36:41.327Z", - "name": "awesome_feature" - }, - { - "id": 82, - "active": true, - "environment_scope": "*", - "strategies": [ - { - "name": "default", - "parameters": {} - } - ], - "created_at": "2019-11-04T08:13:51.425Z", - "updated_at": "2019-11-04T08:39:45.751Z", - "name": "merge_train" - }, - { - "id": 81, - "active": false, - "environment_scope": "production", - "strategies": [ - { - "name": "default", - "parameters": {} - } - ], - "created_at": "2019-11-04T08:13:10.527Z", - "updated_at": "2019-11-04T08:13:10.527Z", - "name": "new_live_trace" - } -] -``` - -## List all specs of a feature flag - -Get all specs of a feature flag. - -```plaintext -GET /projects/:id/feature_flags/:name/scopes -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `name` | string | yes | The name of the feature flag. | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes" -``` - -Example response: - -```json -[ - { - "id": 79, - "active": false, - "environment_scope": "*", - "strategies": [ - { - "name": "default", - "parameters": {} - } - ], - "created_at": "2019-11-04T08:13:10.516Z", - "updated_at": "2019-11-04T08:13:10.516Z" - }, - { - "id": 80, - "active": true, - "environment_scope": "staging", - "strategies": [ - { - "name": "default", - "parameters": {} - } - ], - "created_at": "2019-11-04T08:13:10.525Z", - "updated_at": "2019-11-04T08:13:10.525Z" - }, - { - "id": 81, - "active": false, - "environment_scope": "production", - "strategies": [ - { - "name": "default", - "parameters": {} - } - ], - "created_at": "2019-11-04T08:13:10.527Z", - "updated_at": "2019-11-04T08:13:10.527Z" - } -] -``` - -## New feature flag spec - -Creates a new feature flag spec. - -```plaintext -POST /projects/:id/feature_flags/:name/scopes -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `name` | string | yes | The name of the feature flag. | -| `environment_scope` | string | yes | The [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. | -| `active` | boolean | yes | Whether the spec is active. | -| `strategies` | JSON | yes | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. | - -```shell -curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes" \ - --header "PRIVATE-TOKEN: <your_access_token>" \ - --header "Content-type: application/json" \ - --data @- << EOF -{ - "environment_scope": "*", - "active": false, - "strategies": [{ "name": "default", "parameters": {} }] -} -EOF -``` - -Example response: - -```json -{ - "id": 81, - "active": false, - "environment_scope": "*", - "strategies": [ - { - "name": "default", - "parameters": {} - } - ], - "created_at": "2019-11-04T08:13:10.527Z", - "updated_at": "2019-11-04T08:13:10.527Z" -} -``` - -## Single feature flag spec - -Gets a single feature flag spec. - -```plaintext -GET /projects/:id/feature_flags/:name/scopes/:environment_scope -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `name` | string | yes | The name of the feature flag. | -| `environment_scope` | string | yes | The URL-encoded [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/feature_flags/new_live_trace/scopes/production" -``` - -Example response: - -```json -{ - "id": 81, - "active": false, - "environment_scope": "production", - "strategies": [ - { - "name": "default", - "parameters": {} - } - ], - "created_at": "2019-11-04T08:13:10.527Z", - "updated_at": "2019-11-04T08:13:10.527Z" -} -``` - -## Edit feature flag spec - -Updates an existing feature flag spec. - -```plaintext -PUT /projects/:id/feature_flags/:name/scopes/:environment_scope -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `name` | string | yes | The name of the feature flag. | -| `environment_scope` | string | yes | The URL-encoded [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. | -| `active` | boolean | yes | Whether the spec is active. | -| `strategies` | JSON | yes | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. | - -```shell -curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes/production" \ - --header "PRIVATE-TOKEN: <your_access_token>" \ - --header "Content-type: application/json" \ - --data @- << EOF -{ - "active": true, - "strategies": [{ "name": "userWithId", "parameters": { "userIds": "1,2,3" } }] -} -EOF -``` - -Example response: - -```json -{ - "id": 81, - "active": true, - "environment_scope": "production", - "strategies": [ - { - "name": "userWithId", - "parameters": { "userIds": "1,2,3" } - } - ], - "created_at": "2019-11-04T08:13:10.527Z", - "updated_at": "2019-11-04T08:13:10.527Z" -} -``` - -## Delete feature flag spec - -Deletes a feature flag spec. - -```plaintext -DELETE /projects/:id/feature_flags/:name/scopes/:environment_scope -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `name` | string | yes | The name of the feature flag. | -| `environment_scope` | string | yes | The URL-encoded [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes/production" -``` +This API was removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). +Please use [the new API](feature_flags.md) instead. diff --git a/doc/api/feature_flags_legacy.md b/doc/api/feature_flags_legacy.md index 6e0763b6015..262e1c537a4 100644 --- a/doc/api/feature_flags_legacy.md +++ b/doc/api/feature_flags_legacy.md @@ -9,315 +9,5 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in GitLab Premium 12.5. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5. -WARNING: -This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). Use [this API](feature_flags.md) instead. - -API for accessing resources of [GitLab Feature Flags](../operations/feature_flags.md). - -Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag API. - -## Feature Flags pagination - -By default, `GET` requests return 20 results at a time because the API results -are [paginated](README.md#pagination). - -## List feature flags for a project - -Gets all feature flags of the requested project. - -```plaintext -GET /projects/:id/feature_flags -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `scope` | string | no | The condition of feature flags, one of: `enabled`, `disabled`. | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags" -``` - -Example response: - -```json -[ - { - "name":"merge_train", - "description":"This feature is about merge train", - "active": true, - "created_at":"2019-11-04T08:13:51.423Z", - "updated_at":"2019-11-04T08:13:51.423Z", - "scopes":[ - { - "id":82, - "active":false, - "environment_scope":"*", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:51.425Z", - "updated_at":"2019-11-04T08:13:51.425Z" - }, - { - "id":83, - "active":true, - "environment_scope":"review/*", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:51.427Z", - "updated_at":"2019-11-04T08:13:51.427Z" - }, - { - "id":84, - "active":false, - "environment_scope":"production", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:51.428Z", - "updated_at":"2019-11-04T08:13:51.428Z" - } - ] - }, - { - "name":"new_live_trace", - "description":"This is a new live trace feature", - "active": true, - "created_at":"2019-11-04T08:13:10.507Z", - "updated_at":"2019-11-04T08:13:10.507Z", - "scopes":[ - { - "id":79, - "active":false, - "environment_scope":"*", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:10.516Z", - "updated_at":"2019-11-04T08:13:10.516Z" - }, - { - "id":80, - "active":true, - "environment_scope":"staging", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:10.525Z", - "updated_at":"2019-11-04T08:13:10.525Z" - }, - { - "id":81, - "active":false, - "environment_scope":"production", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:10.527Z", - "updated_at":"2019-11-04T08:13:10.527Z" - } - ] - } -] -``` - -## New feature flag - -Creates a new feature flag. - -```plaintext -POST /projects/:id/feature_flags -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `name` | string | yes | The name of the feature flag. | -| `description` | string | no | The description of the feature flag. | -| `active` | boolean | no | The active state of the flag. Defaults to true. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | -| `scopes` | JSON | no | The feature flag specs of the feature flag. | -| `scopes:environment_scope` | string | no | The environment spec. | -| `scopes:active` | boolean | no | Whether the spec is active. | -| `scopes:strategies` | JSON | no | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. | - -```shell -curl "https://gitlab.example.com/api/v4/projects/1/feature_flags" \ - --header "PRIVATE-TOKEN: <your_access_token>" \ - --header "Content-type: application/json" \ - --data @- << EOF -{ - "name": "awesome_feature", - "scopes": [{ "environment_scope": "*", "active": false, "strategies": [{ "name": "default", "parameters": {} }] }, - { "environment_scope": "production", "active": true, "strategies": [{ "name": "userWithId", "parameters": { "userIds": "1,2,3" } }] }] -} -EOF -``` - -Example response: - -```json -{ - "name":"awesome_feature", - "description":null, - "active": true, - "created_at":"2019-11-04T08:32:27.288Z", - "updated_at":"2019-11-04T08:32:27.288Z", - "scopes":[ - { - "id":85, - "active":false, - "environment_scope":"*", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:32:29.324Z", - "updated_at":"2019-11-04T08:32:29.324Z" - }, - { - "id":86, - "active":true, - "environment_scope":"production", - "strategies":[ - { - "name":"userWithId", - "parameters":{ - "userIds":"1,2,3" - } - } - ], - "created_at":"2019-11-04T08:32:29.328Z", - "updated_at":"2019-11-04T08:32:29.328Z" - } - ] -} -``` - -## Single feature flag - -Gets a single feature flag. - -```plaintext -GET /projects/:id/feature_flags/:name -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `name` | string | yes | The name of the feature flag. | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace" -``` - -Example response: - -```json -{ - "name":"new_live_trace", - "description":"This is a new live trace feature", - "active": true, - "created_at":"2019-11-04T08:13:10.507Z", - "updated_at":"2019-11-04T08:13:10.507Z", - "scopes":[ - { - "id":79, - "active":false, - "environment_scope":"*", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:10.516Z", - "updated_at":"2019-11-04T08:13:10.516Z" - }, - { - "id":80, - "active":true, - "environment_scope":"staging", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:10.525Z", - "updated_at":"2019-11-04T08:13:10.525Z" - }, - { - "id":81, - "active":false, - "environment_scope":"production", - "strategies":[ - { - "name":"default", - "parameters":{ - - } - } - ], - "created_at":"2019-11-04T08:13:10.527Z", - "updated_at":"2019-11-04T08:13:10.527Z" - } - ] -} -``` - -## Delete feature flag - -Deletes a feature flag. - -```plaintext -DELETE /projects/:id/feature_flags/:name -``` - -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `name` | string | yes | The name of the feature flag. | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" -``` +This API was removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). +Please use [the new API](feature_flags.md) instead. diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index b48ce48f6c3..85b36346167 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -4,12 +4,13 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Getting started with GitLab GraphQL API +# Get started with GitLab GraphQL API **(FREE)** This guide demonstrates basic usage of the GitLab GraphQL API. -See the [GraphQL API style guide](../../development/api_graphql_styleguide.md) for implementation details -aimed at developers who wish to work on developing the API itself. +Read the [GraphQL API style guide](../../development/api_graphql_styleguide.md) +for implementation details aimed at developers who wish to work on developing +the API itself. ## Running examples @@ -20,38 +21,43 @@ The examples documented here can be run using: ### Command line -You can run GraphQL queries in a `curl` request on the command line on your local machine. -A GraphQL request can be made as a `POST` request to `/api/graphql` with the query as the payload. -You can authorize your request by generating a [personal access token](../../user/profile/personal_access_tokens.md) -to use as a bearer token. +You can run GraphQL queries in a `curl` request on the command line on your +local computer. A GraphQL request can be made as a `POST` request to `/api/graphql` +with the query as the payload. You can authorize your request by generating a +[personal access token](../../user/profile/personal_access_tokens.md) to use as +a bearer token. Example: ```shell GRAPHQL_TOKEN=<your-token> -curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {currentUser {name}}\"}" +curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" \ + --header "Content-Type: application/json" --request POST \ + --data "{\"query\": \"query {currentUser {name}}\"}" ``` ### GraphiQL -GraphiQL (pronounced "graphical") allows you to run queries directly against the server endpoint -with syntax highlighting and autocomplete. It also allows you to explore the schema and types. +GraphiQL (pronounced "graphical") allows you to run queries directly against +the server endpoint with syntax highlighting and autocomplete. It also allows +you to explore the schema and types. The examples below: -- Can be run directly against GitLab 11.0 or later, though some of the types and fields -may not be supported in older versions. -- Works against GitLab.com without any further setup. Make sure you are signed in and -navigate to the [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). +- Can be run directly against GitLab 11.0 or later, though some of the types + and fields may not be supported in older versions. +- Works against GitLab.com without any further setup. Make sure you are signed + in and navigate to the [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). -If you want to run the queries locally, or on a self-managed instance, -you must either: +If you want to run the queries locally, or on a self-managed instance, you must +either: -- Create the `gitlab-org` group with a project called `graphql-sandbox` under it. Create -several issues within the project. -- Edit the queries to replace `gitlab-org/graphql-sandbox` with your own group and project. +- Create the `gitlab-org` group with a project called `graphql-sandbox` under + it. Create several issues in the project. +- Edit the queries to replace `gitlab-org/graphql-sandbox` with your own group + and project. -Please refer to [running GraphiQL](index.md#graphiql) for more information. +Refer to [running GraphiQL](index.md#graphiql) for more information. NOTE: If you are running GitLab 11.0 to 12.0, enable the `graphql` @@ -72,8 +78,8 @@ which is an object identifier in the format of `"gid://gitlab/Issue/123"`. [GitLab GraphQL Schema](reference/index.md) outlines which objects and fields are available for clients to query and their corresponding data types. -Example: Get only the names of all the projects the currently logged in user can access (up to a limit, more on that later) -in the group `gitlab-org`. +Example: Get only the names of all the projects the currently logged in user can +access (up to a limit) in the group `gitlab-org`. ```graphql query { @@ -106,12 +112,12 @@ query { When retrieving child nodes use: -- the `edges { node { } }` syntax. -- the short form `nodes { }` syntax. +- The `edges { node { } }` syntax. +- The short form `nodes { }` syntax. Underneath it all is a graph we are traversing, hence the name GraphQL. -Example: Get a project (only its name) and the titles of all its issues. +Example: Get the name of a project, and the titles of all its issues. ```graphql query { @@ -128,23 +134,24 @@ query { ``` More about queries: -[GraphQL docs](https://graphql.org/learn/queries/) +[GraphQL documentation](https://graphql.org/learn/queries/) ### Authorization -Authorization uses the same engine as the GitLab application (and GitLab.com). So if you've signed in to GitLab -and use GraphiQL, all queries are performed as you, the signed in user. For more information, see the +Authorization uses the same engine as the GitLab application (and GitLab.com). +If you've signed in to GitLab and use GraphiQL, all queries are performed as +you, the signed in user. For more information, read the [GitLab API documentation](../README.md#authentication). ### Mutations -Mutations make changes to data. We can update, delete, or create new records. Mutations -generally use InputTypes and variables, neither of which appear here. +Mutations make changes to data. We can update, delete, or create new records. +Mutations generally use InputTypes and variables, neither of which appear here. Mutations have: - Inputs. For example, arguments, such as which emoji you'd like to award, -and to which object. + and to which object. - Return statements. That is, what you'd like to get back when it's successful. - Errors. Always ask for what went wrong, just in case. @@ -172,8 +179,9 @@ mutation { } ``` -Example: Add a comment to the issue (we're using the ID of the `GitLab.com` issue - but -if you're using a local instance, you must get the ID of an issue you can write to). +Example: Add a comment to the issue. In this example, we use the ID of the +`GitLab.com` issue. If you're using a local instance, you must get the ID of an +issue you can write to. ```graphql mutation { @@ -194,7 +202,8 @@ mutation { #### Update mutations -When you see the result `id` of the note you created - take a note of it. Now let's edit it to sip faster! +When you see the result `id` of the note you created, take a note of it. Let's +edit it to sip faster. ```graphql mutation { @@ -212,7 +221,7 @@ mutation { #### Deletion mutations -Let's delete the comment, since our tea is all gone. +Let's delete the comment, because our tea is all gone. ```graphql mutation { @@ -242,16 +251,18 @@ You should get something like the following output: We've asked for the note details, but it doesn't exist anymore, so we get `null`. More about mutations: -[GraphQL Docs](https://graphql.org/learn/queries/#mutations). +[GraphQL Documentation](https://graphql.org/learn/queries/#mutations). ### Introspective queries Clients can query the GraphQL endpoint for information about its own schema. by making an [introspective query](https://graphql.org/learn/introspection/). +The [GraphiQL Query Explorer](https://gitlab.com/-/graphql-explorer) uses an +introspection query to: -It is through an introspection query that the [GraphiQL Query Explorer](https://gitlab.com/-/graphql-explorer) -gets all of its knowledge about our GraphQL schema to do autocompletion and provide -its interactive `Docs` tab. +- Gain knowledge about our GraphQL schema. +- Do autocompletion. +- Provide its interactive `Docs` tab. Example: Get all the type names in the schema. @@ -265,8 +276,8 @@ Example: Get all the type names in the schema. } ``` -Example: Get all the fields associated with Issue. -`kind` tells us the enum value for the type, like `OBJECT`, `SCALAR` or `INTERFACE`. +Example: Get all the fields associated with Issue. `kind` tells us the enum +value for the type, like `OBJECT`, `SCALAR` or `INTERFACE`. ```graphql query IssueTypes { @@ -285,12 +296,12 @@ query IssueTypes { ``` More about introspection: -[GraphQL docs](https://graphql.org/learn/introspection/) +[GraphQL documentation](https://graphql.org/learn/introspection/) ## Sorting -Some of the GitLab GraphQL endpoints allow you to specify how you'd like a collection of -objects to be sorted. You can only sort by what the schema allows you to. +Some of the GitLab GraphQL endpoints allow you to specify how to sort a +collection of objects. You can only sort by what the schema allows you to. Example: Issues can be sorted by creation date: @@ -310,17 +321,18 @@ query { ## Pagination -Pagination is a way of only asking for a subset of the records (say, the first 10). -If we want more of them, we can make another request for the next 10 from the server -(in the form of something like "please give me the next 10 records"). +Pagination is a way of only asking for a subset of the records, such as the +first ten. If we want more of them, we can make another request for the next +ten from the server in the form of something like `please give me the next ten records`. -By default, the GitLab GraphQL API returns 100 records per page. -This can be changed by using `first` or `last` arguments. Both arguments take a value, -so `first: 10` returns the first 10 records, and `last: 10` the last 10 records. -There is a limit on how many records will be returned per page, which is generally `100`. +By default, the GitLab GraphQL API returns 100 records per page. To change this +behavior, use `first` or `last` arguments. Both arguments take a value, so +`first: 10` returns the first ten records, and `last: 10` the last ten records. +There is a limit on how many records are returned per page, which is generally +`100`. -Example: Retrieve only the first 2 issues (slicing). The `cursor` field gives us a position from which -we can retrieve further records relative to that one. +Example: Retrieve only the first two issues (slicing). The `cursor` field gives +us a position from which we can retrieve further records relative to that one. ```graphql query { @@ -341,9 +353,10 @@ query { } ``` -Example: Retrieve the next 3. (The cursor value +Example: Retrieve the next three. (The cursor value `eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0` -could be different, but it's the `cursor` value returned for the second issue returned above.) +could be different, but it's the `cursor` value returned for the second issue +returned above.) ```graphql query { @@ -365,5 +378,5 @@ query { } ``` -More on pagination and cursors: -[GraphQL docs](https://graphql.org/learn/pagination/) +More about pagination and cursors: +[GraphQL documentation](https://graphql.org/learn/pagination/) diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 5864e5878b7..073f5faf57c 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -78,6 +78,11 @@ where the deprecated part of the schema is supported for a period of time before Clients should familiarize themselves with the process to avoid breaking changes affecting their integrations. +WARNING: +While GitLab will make all attempts to follow the [deprecation and removal process](#deprecation-and-removal-process), +GitLab may on very rare occasions need to make immediate breaking changes to the GraphQL API to patch critical security or performance +concerns and where the deprecation process would be considered to pose significant risk. + NOTE: Fields behind a feature flag and disabled by default are exempt from the deprecation process, and can be removed at any time without notice. @@ -129,7 +134,7 @@ New associations and root level objects are constantly being added. See the [GraphQL API Reference](reference/index.md) for up-to-date information. Root-level queries are defined in -[`app/graphql/types/query_type.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/graphql/types/query_type.rb). +[`app/graphql/types/query_type.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/query_type.rb). ### Multiplex queries diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 7f496e1aded..0069d109e1e 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -83,11 +83,11 @@ Fields related to design management. Returns [`DesignManagement!`](#designmanagement). -### `Query.devopsAdoptionSegments` +### `Query.devopsAdoptionEnabledNamespaces` -Get configured DevOps adoption segments on the instance. **BETA** This endpoint is subject to change without notice. +Get configured DevOps adoption namespaces. **BETA** This endpoint is subject to change without notice. -Returns [`DevopsAdoptionSegmentConnection`](#devopsadoptionsegmentconnection). +Returns [`DevopsAdoptionEnabledNamespaceConnection`](#devopsadoptionenablednamespaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): @@ -97,8 +97,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="querydevopsadoptionsegmentsdirectdescendantsonly"></a>`directDescendantsOnly` | [`Boolean`](#boolean) | Limits segments to direct descendants of specified parent. | -| <a id="querydevopsadoptionsegmentsparentnamespaceid"></a>`parentNamespaceId` | [`NamespaceID`](#namespaceid) | Filter by ancestor namespace. | +| <a id="querydevopsadoptionenablednamespacesdisplaynamespaceid"></a>`displayNamespaceId` | [`NamespaceID`](#namespaceid) | Filter by display namespace. | ### `Query.echo` @@ -284,6 +283,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="queryprojectssearch"></a>`search` | [`String`](#string) | Search query for project name, path, or description. | | <a id="queryprojectssearchnamespaces"></a>`searchNamespaces` | [`Boolean`](#boolean) | Include namespace in project search. | | <a id="queryprojectssort"></a>`sort` | [`String`](#string) | Sort order of results. | +| <a id="queryprojectstopics"></a>`topics` | [`[String!]`](#string) | Filters projects by topics. | ### `Query.runner` @@ -336,6 +336,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="queryrunnerssearch"></a>`search` | [`String`](#string) | Filter by full token or partial text in description field. | | <a id="queryrunnerssort"></a>`sort` | [`CiRunnerSort`](#cirunnersort) | Sort order of results. | | <a id="queryrunnersstatus"></a>`status` | [`CiRunnerStatus`](#cirunnerstatus) | Filter runners by status. | | <a id="queryrunnerstaglist"></a>`tagList` | [`[String!]`](#string) | Filter by tags associated with the runner (comma-separated or array). | @@ -454,30 +455,6 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="queryvulnerabilitiescountbydayenddate"></a>`endDate` | [`ISO8601Date!`](#iso8601date) | Last day for which to fetch vulnerability history. | | <a id="queryvulnerabilitiescountbydaystartdate"></a>`startDate` | [`ISO8601Date!`](#iso8601date) | First day for which to fetch vulnerability history. | -### `Query.vulnerabilitiesCountByDayAndSeverity` - -Number of vulnerabilities per severity level, per day, for the projects on the -current user's instance security dashboard. -. - -WARNING: -**Deprecated** in 13.3. -Use of this is not recommended. -Use: [`Query.vulnerabilitiesCountByDay`](#queryvulnerabilitiescountbyday). - -Returns [`VulnerabilitiesCountByDayAndSeverityConnection`](#vulnerabilitiescountbydayandseverityconnection). - -This field returns a [connection](#connections). It accepts the -four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="queryvulnerabilitiescountbydayandseverityenddate"></a>`endDate` | [`ISO8601Date!`](#iso8601date) | Last day for which to fetch vulnerability history. | -| <a id="queryvulnerabilitiescountbydayandseveritystartdate"></a>`startDate` | [`ISO8601Date!`](#iso8601date) | First day for which to fetch vulnerability history. | - ### `Query.vulnerability` Find a vulnerability. @@ -509,30 +486,6 @@ mutation($id: NoteableID!, $body: String!) { } ``` -### `Mutation.addAwardEmoji` - -WARNING: -**Deprecated** in 13.2. -Use awardEmojiAdd. - -Input type: `AddAwardEmojiInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationaddawardemojiawardableid"></a>`awardableId` | [`AwardableID!`](#awardableid) | The global ID of the awardable resource. | -| <a id="mutationaddawardemojiclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationaddawardemojiname"></a>`name` | [`String!`](#string) | The emoji name. | - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationaddawardemojiawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | The award emoji after mutation. | -| <a id="mutationaddawardemojiclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationaddawardemojierrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | - ### `Mutation.addProjectToSecurityDashboard` Input type: `AddProjectToSecurityDashboardInput` @@ -713,6 +666,28 @@ Input type: `AwardEmojiToggleInput` | <a id="mutationawardemojitoggleerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationawardemojitoggletoggledon"></a>`toggledOn` | [`Boolean!`](#boolean) | Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji. | +### `Mutation.boardEpicCreate` + +Input type: `BoardEpicCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationboardepiccreateboardid"></a>`boardId` | [`BoardsEpicBoardID!`](#boardsepicboardid) | Global ID of the board that the epic is in. | +| <a id="mutationboardepiccreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationboardepiccreategrouppath"></a>`groupPath` | [`ID!`](#id) | Group the epic to create is in. | +| <a id="mutationboardepiccreatelistid"></a>`listId` | [`BoardsEpicListID!`](#boardsepiclistid) | Global ID of the epic board list in which epic will be created. | +| <a id="mutationboardepiccreatetitle"></a>`title` | [`String!`](#string) | Title of the epic. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationboardepiccreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationboardepiccreateepic"></a>`epic` | [`Epic`](#epic) | Epic after creation. | +| <a id="mutationboardepiccreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.boardListCreate` Input type: `BoardListCreateInput` @@ -759,26 +734,27 @@ Input type: `BoardListUpdateLimitMetricsInput` | <a id="mutationboardlistupdatelimitmetricserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationboardlistupdatelimitmetricslist"></a>`list` | [`BoardList`](#boardlist) | The updated list. | -### `Mutation.bulkFindOrCreateDevopsAdoptionSegments` +### `Mutation.bulkEnableDevopsAdoptionNamespaces` **BETA** This endpoint is subject to change without notice. -Input type: `BulkFindOrCreateDevopsAdoptionSegmentsInput` +Input type: `BulkEnableDevopsAdoptionNamespacesInput` #### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationbulkfindorcreatedevopsadoptionsegmentsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationbulkfindorcreatedevopsadoptionsegmentsnamespaceids"></a>`namespaceIds` | [`[NamespaceID!]!`](#namespaceid) | List of Namespace IDs for the segments. | +| <a id="mutationbulkenabledevopsadoptionnamespacesclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationbulkenabledevopsadoptionnamespacesdisplaynamespaceid"></a>`displayNamespaceId` | [`NamespaceID`](#namespaceid) | Display namespace ID. | +| <a id="mutationbulkenabledevopsadoptionnamespacesnamespaceids"></a>`namespaceIds` | [`[NamespaceID!]!`](#namespaceid) | List of Namespace IDs. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationbulkfindorcreatedevopsadoptionsegmentsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationbulkfindorcreatedevopsadoptionsegmentserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationbulkfindorcreatedevopsadoptionsegmentssegments"></a>`segments` | [`[DevopsAdoptionSegment!]`](#devopsadoptionsegment) | Created segments after mutation. | +| <a id="mutationbulkenabledevopsadoptionnamespacesclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationbulkenabledevopsadoptionnamespacesenablednamespaces"></a>`enabledNamespaces` | [`[DevopsAdoptionEnabledNamespace!]`](#devopsadoptionenablednamespace) | Enabled namespaces after mutation. | +| <a id="mutationbulkenabledevopsadoptionnamespaceserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.ciCdSettingsUpdate` @@ -790,6 +766,7 @@ Input type: `CiCdSettingsUpdateInput` | ---- | ---- | ----------- | | <a id="mutationcicdsettingsupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcicdsettingsupdatefullpath"></a>`fullPath` | [`ID!`](#id) | Full Path of the project the settings belong to. | +| <a id="mutationcicdsettingsupdatejobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI job tokens generated in this project have restricted access to resources. | | <a id="mutationcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for this project. | | <a id="mutationcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | @@ -882,6 +859,7 @@ Input type: `CommitCreateInput` | <a id="mutationcommitcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcommitcreatecommit"></a>`commit` | [`Commit`](#commit) | The commit after mutation. | | <a id="mutationcommitcreatecommitpipelinepath"></a>`commitPipelinePath` | [`String`](#string) | ETag path for the commit's pipeline. | +| <a id="mutationcommitcreatecontent"></a>`content` | [`[String!]`](#string) | Contents of the commit. | | <a id="mutationcommitcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.configureSast` @@ -1093,27 +1071,6 @@ Input type: `CreateCustomEmojiInput` | <a id="mutationcreatecustomemojicustomemoji"></a>`customEmoji` | [`CustomEmoji`](#customemoji) | The new custom emoji. | | <a id="mutationcreatecustomemojierrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -### `Mutation.createDevopsAdoptionSegment` - -**BETA** This endpoint is subject to change without notice. - -Input type: `CreateDevopsAdoptionSegmentInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationcreatedevopsadoptionsegmentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcreatedevopsadoptionsegmentnamespaceid"></a>`namespaceId` | [`NamespaceID!`](#namespaceid) | Namespace ID to set for the segment. | - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationcreatedevopsadoptionsegmentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcreatedevopsadoptionsegmenterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationcreatedevopsadoptionsegmentsegment"></a>`segment` | [`DevopsAdoptionSegment`](#devopsadoptionsegment) | The segment after mutation. | - ### `Mutation.createDiffNote` Input type: `CreateDiffNoteInput` @@ -1224,6 +1181,10 @@ Input type: `CreateIssueInput` ### `Mutation.createIteration` +WARNING: +**Deprecated** in 14.0. +Use iterationCreate. + Input type: `CreateIterationInput` #### Arguments @@ -1234,6 +1195,7 @@ Input type: `CreateIterationInput` | <a id="mutationcreateiterationdescription"></a>`description` | [`String`](#string) | The description of the iteration. | | <a id="mutationcreateiterationduedate"></a>`dueDate` | [`String`](#string) | The end date of the iteration. | | <a id="mutationcreateiterationgrouppath"></a>`groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | +| <a id="mutationcreateiterationiterationscadenceid"></a>`iterationsCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global ID of the iterations cadence to be assigned to newly created iteration. | | <a id="mutationcreateiterationprojectpath"></a>`projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | | <a id="mutationcreateiterationstartdate"></a>`startDate` | [`String`](#string) | The start date of the iteration. | | <a id="mutationcreateiterationtitle"></a>`title` | [`String`](#string) | The title of the iteration. | @@ -1476,7 +1438,6 @@ Input type: `DastScannerProfileCreateInput` | ---- | ---- | ----------- | | <a id="mutationdastscannerprofilecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationdastscannerprofilecreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationdastscannerprofilecreateglobalid"></a>`globalId` **{warning-solid}** | [`DastScannerProfileID`](#dastscannerprofileid) | **Deprecated:** Use `id`. Deprecated in 13.6. | | <a id="mutationdastscannerprofilecreateid"></a>`id` | [`DastScannerProfileID`](#dastscannerprofileid) | ID of the scanner profile. | ### `Mutation.dastScannerProfileDelete` @@ -1532,13 +1493,13 @@ Input type: `DastSiteProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationdastsiteprofilecreateauth"></a>`auth` | [`DastSiteProfileAuthInput`](#dastsiteprofileauthinput) | Parameters for authentication. Will be ignored if `security_dast_site_profiles_additional_fields` feature flag is disabled. | +| <a id="mutationdastsiteprofilecreateauth"></a>`auth` | [`DastSiteProfileAuthInput`](#dastsiteprofileauthinput) | Parameters for authentication. | | <a id="mutationdastsiteprofilecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastsiteprofilecreateexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. Defaults to `[]`. Will be ignored if `security_dast_site_profiles_additional_fields` feature flag is disabled. | +| <a id="mutationdastsiteprofilecreateexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. Defaults to `[]`. | | <a id="mutationdastsiteprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site profile belongs to. | | <a id="mutationdastsiteprofilecreateprofilename"></a>`profileName` | [`String!`](#string) | The name of the site profile. | -| <a id="mutationdastsiteprofilecreaterequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. Will be ignored if `security_dast_site_profiles_additional_fields` feature flag is disabled. | -| <a id="mutationdastsiteprofilecreatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. Will be ignored if `security_dast_site_profiles_api_option` feature flag is disabled. | +| <a id="mutationdastsiteprofilecreaterequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | +| <a id="mutationdastsiteprofilecreatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | | <a id="mutationdastsiteprofilecreatetargeturl"></a>`targetUrl` | [`String`](#string) | The URL of the target to be scanned. | #### Fields @@ -1576,14 +1537,14 @@ Input type: `DastSiteProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationdastsiteprofileupdateauth"></a>`auth` | [`DastSiteProfileAuthInput`](#dastsiteprofileauthinput) | Parameters for authentication. Will be ignored if `security_dast_site_profiles_additional_fields` feature flag is disabled. | +| <a id="mutationdastsiteprofileupdateauth"></a>`auth` | [`DastSiteProfileAuthInput`](#dastsiteprofileauthinput) | Parameters for authentication. | | <a id="mutationdastsiteprofileupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdastsiteprofileupdateexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. Will be ignored if `security_dast_site_profiles_additional_fields` feature flag is disabled. | +| <a id="mutationdastsiteprofileupdateexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. | | <a id="mutationdastsiteprofileupdatefullpath"></a>`fullPath` | [`ID!`](#id) | The project the site profile belongs to. | | <a id="mutationdastsiteprofileupdateid"></a>`id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be updated. | | <a id="mutationdastsiteprofileupdateprofilename"></a>`profileName` | [`String!`](#string) | The name of the site profile. | -| <a id="mutationdastsiteprofileupdaterequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. Will be ignored if `security_dast_site_profiles_additional_fields` feature flag is disabled. | -| <a id="mutationdastsiteprofileupdatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. Will be ignored if `security_dast_site_profiles_api_option` feature flag is disabled. | +| <a id="mutationdastsiteprofileupdaterequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | +| <a id="mutationdastsiteprofileupdatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | | <a id="mutationdastsiteprofileupdatetargeturl"></a>`targetUrl` | [`String`](#string) | The URL of the target to be scanned. | #### Fields @@ -1676,26 +1637,6 @@ Input type: `DeleteAnnotationInput` | <a id="mutationdeleteannotationclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationdeleteannotationerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -### `Mutation.deleteDevopsAdoptionSegment` - -**BETA** This endpoint is subject to change without notice. - -Input type: `DeleteDevopsAdoptionSegmentInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationdeletedevopsadoptionsegmentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdeletedevopsadoptionsegmentid"></a>`id` | [`[AnalyticsDevopsAdoptionSegmentID!]!`](#analyticsdevopsadoptionsegmentid) | One or many IDs of the segments to delete. | - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationdeletedevopsadoptionsegmentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdeletedevopsadoptionsegmenterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | - ### `Mutation.designManagementDelete` Input type: `DesignManagementDeleteInput` @@ -1912,6 +1853,26 @@ Input type: `DestroySnippetInput` | <a id="mutationdestroysnippeterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationdestroysnippetsnippet"></a>`snippet` | [`Snippet`](#snippet) | The snippet after mutation. | +### `Mutation.disableDevopsAdoptionNamespace` + +**BETA** This endpoint is subject to change without notice. + +Input type: `DisableDevopsAdoptionNamespaceInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdisabledevopsadoptionnamespaceclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdisabledevopsadoptionnamespaceid"></a>`id` | [`[AnalyticsDevopsAdoptionEnabledNamespaceID!]!`](#analyticsdevopsadoptionenablednamespaceid) | One or many IDs of the enabled namespaces to disable. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdisabledevopsadoptionnamespaceclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdisabledevopsadoptionnamespaceerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.discussionToggleResolve` Toggles the resolved state of a discussion. @@ -1934,30 +1895,27 @@ Input type: `DiscussionToggleResolveInput` | <a id="mutationdiscussiontoggleresolvediscussion"></a>`discussion` | [`Discussion`](#discussion) | The discussion after mutation. | | <a id="mutationdiscussiontoggleresolveerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -### `Mutation.dismissVulnerability` +### `Mutation.enableDevopsAdoptionNamespace` -WARNING: -**Deprecated** in 13.5. -Use vulnerabilityDismiss. +**BETA** This endpoint is subject to change without notice. -Input type: `DismissVulnerabilityInput` +Input type: `EnableDevopsAdoptionNamespaceInput` #### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationdismissvulnerabilityclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdismissvulnerabilitycomment"></a>`comment` | [`String`](#string) | Comment why vulnerability should be dismissed. | -| <a id="mutationdismissvulnerabilitydismissalreason"></a>`dismissalReason` | [`VulnerabilityDismissalReason`](#vulnerabilitydismissalreason) | Reason why vulnerability should be dismissed. | -| <a id="mutationdismissvulnerabilityid"></a>`id` | [`VulnerabilityID!`](#vulnerabilityid) | ID of the vulnerability to be dismissed. | +| <a id="mutationenabledevopsadoptionnamespaceclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationenabledevopsadoptionnamespacedisplaynamespaceid"></a>`displayNamespaceId` | [`NamespaceID`](#namespaceid) | Display namespace ID. | +| <a id="mutationenabledevopsadoptionnamespacenamespaceid"></a>`namespaceId` | [`NamespaceID!`](#namespaceid) | Namespace ID. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationdismissvulnerabilityclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationdismissvulnerabilityerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationdismissvulnerabilityvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after dismissal. | +| <a id="mutationenabledevopsadoptionnamespaceclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationenabledevopsadoptionnamespaceenablednamespace"></a>`enabledNamespace` | [`DevopsAdoptionEnabledNamespace`](#devopsadoptionenablednamespace) | Enabled namespace after mutation. | +| <a id="mutationenabledevopsadoptionnamespaceerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.environmentsCanaryIngressUpdate` @@ -2102,14 +2060,17 @@ Input type: `EpicMoveListInput` | <a id="mutationepicmovelistboardid"></a>`boardId` | [`BoardsEpicBoardID!`](#boardsepicboardid) | Global ID of the board that the epic is in. | | <a id="mutationepicmovelistclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationepicmovelistepicid"></a>`epicId` | [`EpicID!`](#epicid) | ID of the epic to mutate. | -| <a id="mutationepicmovelistfromlistid"></a>`fromListId` | [`BoardsEpicListID!`](#boardsepiclistid) | ID of the board list that the epic will be moved from. | -| <a id="mutationepicmovelisttolistid"></a>`toListId` | [`BoardsEpicListID!`](#boardsepiclistid) | ID of the board list that the epic will be moved to. | +| <a id="mutationepicmovelistfromlistid"></a>`fromListId` | [`BoardsEpicListID`](#boardsepiclistid) | ID of the board list that the epic will be moved from. Required if moving between lists. | +| <a id="mutationepicmovelistmoveafterid"></a>`moveAfterId` | [`EpicID`](#epicid) | ID of epic that should be placed after the current epic. | +| <a id="mutationepicmovelistmovebeforeid"></a>`moveBeforeId` | [`EpicID`](#epicid) | ID of epic that should be placed before the current epic. | +| <a id="mutationepicmovelisttolistid"></a>`toListId` | [`BoardsEpicListID!`](#boardsepiclistid) | ID of the list the epic will be in after mutation. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationepicmovelistclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationepicmovelistepic"></a>`epic` | [`Epic`](#epic) | The epic after mutation. | | <a id="mutationepicmovelisterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicSetSubscription` @@ -2152,6 +2113,69 @@ Input type: `EpicTreeReorderInput` | <a id="mutationepictreereorderclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationepictreereordererrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.escalationPolicyCreate` + +Input type: `EscalationPolicyCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationescalationpolicycreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationescalationpolicycreatedescription"></a>`description` | [`String`](#string) | The description of the escalation policy. | +| <a id="mutationescalationpolicycreatename"></a>`name` | [`String!`](#string) | The name of the escalation policy. | +| <a id="mutationescalationpolicycreateprojectpath"></a>`projectPath` | [`ID!`](#id) | The project to create the escalation policy for. | +| <a id="mutationescalationpolicycreaterules"></a>`rules` | [`[EscalationRuleInput!]!`](#escalationruleinput) | The steps of the escalation policy. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationescalationpolicycreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationescalationpolicycreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationescalationpolicycreateescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | + +### `Mutation.escalationPolicyDestroy` + +Input type: `EscalationPolicyDestroyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationescalationpolicydestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationescalationpolicydestroyid"></a>`id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | The escalation policy internal ID to remove. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationescalationpolicydestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationescalationpolicydestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationescalationpolicydestroyescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | + +### `Mutation.escalationPolicyUpdate` + +Input type: `EscalationPolicyUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationescalationpolicyupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationescalationpolicyupdatedescription"></a>`description` | [`String`](#string) | The description of the escalation policy. | +| <a id="mutationescalationpolicyupdateid"></a>`id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | The ID of the on-call schedule to create the on-call rotation in. | +| <a id="mutationescalationpolicyupdatename"></a>`name` | [`String`](#string) | The name of the escalation policy. | +| <a id="mutationescalationpolicyupdaterules"></a>`rules` | [`[EscalationRuleInput!]`](#escalationruleinput) | The steps of the escalation policy. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationescalationpolicyupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationescalationpolicyupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationescalationpolicyupdateescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | + ### `Mutation.exportRequirements` Input type: `ExportRequirementsInput` @@ -2588,6 +2612,31 @@ Input type: `IterationCadenceUpdateInput` | <a id="mutationiterationcadenceupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationiterationcadenceupdateiterationcadence"></a>`iterationCadence` | [`IterationCadence`](#iterationcadence) | The updated iteration cadence. | +### `Mutation.iterationCreate` + +Input type: `iterationCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationiterationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationiterationcreatedescription"></a>`description` | [`String`](#string) | The description of the iteration. | +| <a id="mutationiterationcreateduedate"></a>`dueDate` | [`String`](#string) | The end date of the iteration. | +| <a id="mutationiterationcreategrouppath"></a>`groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | +| <a id="mutationiterationcreateiterationscadenceid"></a>`iterationsCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global ID of the iterations cadence to be assigned to newly created iteration. | +| <a id="mutationiterationcreateprojectpath"></a>`projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | +| <a id="mutationiterationcreatestartdate"></a>`startDate` | [`String`](#string) | The start date of the iteration. | +| <a id="mutationiterationcreatetitle"></a>`title` | [`String`](#string) | The title of the iteration. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationiterationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationiterationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationiterationcreateiteration"></a>`iteration` | [`Iteration`](#iteration) | The created iteration. | + ### `Mutation.iterationDelete` Input type: `IterationDeleteInput` @@ -2700,7 +2749,6 @@ Input type: `LabelCreateInput` | <a id="mutationlabelcreatedescription"></a>`description` | [`String`](#string) | Description of the label. | | <a id="mutationlabelcreategrouppath"></a>`groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | | <a id="mutationlabelcreateprojectpath"></a>`projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | -| <a id="mutationlabelcreateremoveonclose"></a>`removeOnClose` | [`Boolean`](#boolean) | Whether the label should be removed from an issue when the issue is closed. | | <a id="mutationlabelcreatetitle"></a>`title` | [`String!`](#string) | Title of the label. | #### Fields @@ -3414,30 +3462,6 @@ Input type: `ReleaseUpdateInput` | <a id="mutationreleaseupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationreleaseupdaterelease"></a>`release` | [`Release`](#release) | The release after mutation. | -### `Mutation.removeAwardEmoji` - -WARNING: -**Deprecated** in 13.2. -Use awardEmojiRemove. - -Input type: `RemoveAwardEmojiInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationremoveawardemojiawardableid"></a>`awardableId` | [`AwardableID!`](#awardableid) | The global ID of the awardable resource. | -| <a id="mutationremoveawardemojiclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationremoveawardemojiname"></a>`name` | [`String!`](#string) | The emoji name. | - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationremoveawardemojiawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | The award emoji after mutation. | -| <a id="mutationremoveawardemojiclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationremoveawardemojierrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | - ### `Mutation.removeProjectFromSecurityDashboard` Input type: `RemoveProjectFromSecurityDashboardInput` @@ -3478,54 +3502,75 @@ Input type: `RepositionImageDiffNoteInput` | <a id="mutationrepositionimagediffnoteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationrepositionimagediffnotenote"></a>`note` | [`Note`](#note) | The note after mutation. | -### `Mutation.revertVulnerabilityToDetected` +### `Mutation.runnerDelete` -WARNING: -**Deprecated** in 13.5. -Use vulnerabilityRevertToDetected. +Available only when feature flag `runner_graphql_query` is enabled. -Input type: `RevertVulnerabilityToDetectedInput` +Input type: `RunnerDeleteInput` #### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationrevertvulnerabilitytodetectedclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationrevertvulnerabilitytodetectedid"></a>`id` | [`VulnerabilityID!`](#vulnerabilityid) | ID of the vulnerability to be reverted. | +| <a id="mutationrunnerdeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationrunnerdeleteid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner to delete. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationrevertvulnerabilitytodetectedclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationrevertvulnerabilitytodetectederrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationrevertvulnerabilitytodetectedvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after revert. | +| <a id="mutationrunnerdeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationrunnerdeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -### `Mutation.runDastScan` +### `Mutation.runnerUpdate` -WARNING: -**Deprecated** in 13.4. -Use DastOnDemandScanCreate. +Available only when feature flag `runner_graphql_query` is enabled. -Input type: `RunDASTScanInput` +Input type: `RunnerUpdateInput` #### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationrundastscanbranch"></a>`branch` | [`String!`](#string) | The branch to be associated with the scan. | -| <a id="mutationrundastscanclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationrundastscanprojectpath"></a>`projectPath` | [`ID!`](#id) | The project the DAST scan belongs to. | -| <a id="mutationrundastscanscantype"></a>`scanType` | [`DastScanTypeEnum!`](#dastscantypeenum) | The type of scan to be run. | -| <a id="mutationrundastscantargeturl"></a>`targetUrl` | [`String!`](#string) | The URL of the target to be scanned. | +| <a id="mutationrunnerupdateaccesslevel"></a>`accessLevel` | [`CiRunnerAccessLevel`](#cirunneraccesslevel) | Access level of the runner. | +| <a id="mutationrunnerupdateactive"></a>`active` | [`Boolean`](#boolean) | Indicates the runner is allowed to receive jobs. | +| <a id="mutationrunnerupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationrunnerupdatedescription"></a>`description` | [`String`](#string) | Description of the runner. | +| <a id="mutationrunnerupdateid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner to update. | +| <a id="mutationrunnerupdatelocked"></a>`locked` | [`Boolean`](#boolean) | Indicates the runner is locked. | +| <a id="mutationrunnerupdatemaximumtimeout"></a>`maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. | +| <a id="mutationrunnerupdaterununtagged"></a>`runUntagged` | [`Boolean`](#boolean) | Indicates the runner is able to run untagged jobs. | +| <a id="mutationrunnerupdatetaglist"></a>`tagList` | [`[String!]`](#string) | Tags associated with the runner. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationrundastscanclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationrundastscanerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationrundastscanpipelineurl"></a>`pipelineUrl` | [`String`](#string) | URL of the pipeline that was created. | +| <a id="mutationrunnerupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationrunnerupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationrunnerupdaterunner"></a>`runner` | [`CiRunner`](#cirunner) | The runner after mutation. | + +### `Mutation.runnersRegistrationTokenReset` + +Available only when feature flag `runner_graphql_query` is enabled. + +Input type: `RunnersRegistrationTokenResetInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationrunnersregistrationtokenresetclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationrunnersregistrationtokenresetid"></a>`id` | [`ID`](#id) | ID of the project or group to reset the token for. Omit if resetting instance runner token. | +| <a id="mutationrunnersregistrationtokenresettype"></a>`type` | [`CiRunnerType!`](#cirunnertype) | Scope of the object to reset the token for. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationrunnersregistrationtokenresetclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationrunnersregistrationtokenreseterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationrunnersregistrationtokenresettoken"></a>`token` | [`String`](#string) | The runner token after mutation. | ### `Mutation.terraformStateDelete` @@ -3656,7 +3701,6 @@ Input type: `TodoRestoreManyInput` | <a id="mutationtodorestoremanyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationtodorestoremanyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationtodorestoremanytodos"></a>`todos` | [`[Todo!]!`](#todo) | Updated to-do items. | -| <a id="mutationtodorestoremanyupdatedids"></a>`updatedIds` **{warning-solid}** | [`[TodoID!]!`](#todoid) | **Deprecated:** Use to-do items. Deprecated in 13.2. | ### `Mutation.todosMarkAllDone` @@ -3675,32 +3719,6 @@ Input type: `TodosMarkAllDoneInput` | <a id="mutationtodosmarkalldoneclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationtodosmarkalldoneerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationtodosmarkalldonetodos"></a>`todos` | [`[Todo!]!`](#todo) | Updated to-do items. | -| <a id="mutationtodosmarkalldoneupdatedids"></a>`updatedIds` **{warning-solid}** | [`[TodoID!]!`](#todoid) | **Deprecated:** Use to-do items. Deprecated in 13.2. | - -### `Mutation.toggleAwardEmoji` - -WARNING: -**Deprecated** in 13.2. -Use awardEmojiToggle. - -Input type: `ToggleAwardEmojiInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationtoggleawardemojiawardableid"></a>`awardableId` | [`AwardableID!`](#awardableid) | The global ID of the awardable resource. | -| <a id="mutationtoggleawardemojiclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationtoggleawardemojiname"></a>`name` | [`String!`](#string) | The emoji name. | - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationtoggleawardemojiawardemoji"></a>`awardEmoji` | [`AwardEmoji`](#awardemoji) | The award emoji after mutation. | -| <a id="mutationtoggleawardemojiclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationtoggleawardemojierrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationtoggleawardemojitoggledon"></a>`toggledOn` | [`Boolean!`](#boolean) | Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji. | ### `Mutation.updateAlertStatus` @@ -4251,6 +4269,29 @@ Some of the types in the schema exist solely to model connections. Each connecti has a distinct, named type, with a distinct named edge type. These are listed separately below. +#### `AgentConfigurationConnection` + +The connection type for [`AgentConfiguration`](#agentconfiguration). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="agentconfigurationconnectionedges"></a>`edges` | [`[AgentConfigurationEdge]`](#agentconfigurationedge) | A list of edges. | +| <a id="agentconfigurationconnectionnodes"></a>`nodes` | [`[AgentConfiguration]`](#agentconfiguration) | A list of nodes. | +| <a id="agentconfigurationconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `AgentConfigurationEdge` + +The edge type for [`AgentConfiguration`](#agentconfiguration). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="agentconfigurationedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="agentconfigurationedgenode"></a>`node` | [`AgentConfiguration`](#agentconfiguration) | The item at the end of the edge. | + #### `AlertManagementAlertConnection` The connection type for [`AlertManagementAlert`](#alertmanagementalert). @@ -5037,28 +5078,51 @@ The edge type for [`DesignVersion`](#designversion). | <a id="designversionedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="designversionedgenode"></a>`node` | [`DesignVersion`](#designversion) | The item at the end of the edge. | -#### `DevopsAdoptionSegmentConnection` +#### `DevopsAdoptionEnabledNamespaceConnection` -The connection type for [`DevopsAdoptionSegment`](#devopsadoptionsegment). +The connection type for [`DevopsAdoptionEnabledNamespace`](#devopsadoptionenablednamespace). ##### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="devopsadoptionsegmentconnectionedges"></a>`edges` | [`[DevopsAdoptionSegmentEdge]`](#devopsadoptionsegmentedge) | A list of edges. | -| <a id="devopsadoptionsegmentconnectionnodes"></a>`nodes` | [`[DevopsAdoptionSegment]`](#devopsadoptionsegment) | A list of nodes. | -| <a id="devopsadoptionsegmentconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | +| <a id="devopsadoptionenablednamespaceconnectionedges"></a>`edges` | [`[DevopsAdoptionEnabledNamespaceEdge]`](#devopsadoptionenablednamespaceedge) | A list of edges. | +| <a id="devopsadoptionenablednamespaceconnectionnodes"></a>`nodes` | [`[DevopsAdoptionEnabledNamespace]`](#devopsadoptionenablednamespace) | A list of nodes. | +| <a id="devopsadoptionenablednamespaceconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | -#### `DevopsAdoptionSegmentEdge` +#### `DevopsAdoptionEnabledNamespaceEdge` -The edge type for [`DevopsAdoptionSegment`](#devopsadoptionsegment). +The edge type for [`DevopsAdoptionEnabledNamespace`](#devopsadoptionenablednamespace). ##### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="devopsadoptionsegmentedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | -| <a id="devopsadoptionsegmentedgenode"></a>`node` | [`DevopsAdoptionSegment`](#devopsadoptionsegment) | The item at the end of the edge. | +| <a id="devopsadoptionenablednamespaceedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="devopsadoptionenablednamespaceedgenode"></a>`node` | [`DevopsAdoptionEnabledNamespace`](#devopsadoptionenablednamespace) | The item at the end of the edge. | + +#### `DevopsAdoptionSnapshotConnection` + +The connection type for [`DevopsAdoptionSnapshot`](#devopsadoptionsnapshot). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="devopsadoptionsnapshotconnectionedges"></a>`edges` | [`[DevopsAdoptionSnapshotEdge]`](#devopsadoptionsnapshotedge) | A list of edges. | +| <a id="devopsadoptionsnapshotconnectionnodes"></a>`nodes` | [`[DevopsAdoptionSnapshot]`](#devopsadoptionsnapshot) | A list of nodes. | +| <a id="devopsadoptionsnapshotconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `DevopsAdoptionSnapshotEdge` + +The edge type for [`DevopsAdoptionSnapshot`](#devopsadoptionsnapshot). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="devopsadoptionsnapshotedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="devopsadoptionsnapshotedgenode"></a>`node` | [`DevopsAdoptionSnapshot`](#devopsadoptionsnapshot) | The item at the end of the edge. | #### `DiscussionConnection` @@ -5200,6 +5264,29 @@ The edge type for [`EpicList`](#epiclist). | <a id="epiclistedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="epiclistedgenode"></a>`node` | [`EpicList`](#epiclist) | The item at the end of the edge. | +#### `EscalationPolicyTypeConnection` + +The connection type for [`EscalationPolicyType`](#escalationpolicytype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="escalationpolicytypeconnectionedges"></a>`edges` | [`[EscalationPolicyTypeEdge]`](#escalationpolicytypeedge) | A list of edges. | +| <a id="escalationpolicytypeconnectionnodes"></a>`nodes` | [`[EscalationPolicyType]`](#escalationpolicytype) | A list of nodes. | +| <a id="escalationpolicytypeconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `EscalationPolicyTypeEdge` + +The edge type for [`EscalationPolicyType`](#escalationpolicytype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="escalationpolicytypeedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="escalationpolicytypeedgenode"></a>`node` | [`EscalationPolicyType`](#escalationpolicytype) | The item at the end of the edge. | + #### `EventConnection` The connection type for [`Event`](#event). @@ -5711,6 +5798,29 @@ The edge type for [`Namespace`](#namespace). | <a id="namespaceedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="namespaceedgenode"></a>`node` | [`Namespace`](#namespace) | The item at the end of the edge. | +#### `NetworkPolicyConnection` + +The connection type for [`NetworkPolicy`](#networkpolicy). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="networkpolicyconnectionedges"></a>`edges` | [`[NetworkPolicyEdge]`](#networkpolicyedge) | A list of edges. | +| <a id="networkpolicyconnectionnodes"></a>`nodes` | [`[NetworkPolicy]`](#networkpolicy) | A list of nodes. | +| <a id="networkpolicyconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `NetworkPolicyEdge` + +The edge type for [`NetworkPolicy`](#networkpolicy). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="networkpolicyedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="networkpolicyedgenode"></a>`node` | [`NetworkPolicy`](#networkpolicy) | The item at the end of the edge. | + #### `NoteConnection` The connection type for [`Note`](#note). @@ -6265,6 +6375,29 @@ The edge type for [`Scan`](#scan). | <a id="scanedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="scanedgenode"></a>`node` | [`Scan`](#scan) | The item at the end of the edge. | +#### `ScanExecutionPolicyConnection` + +The connection type for [`ScanExecutionPolicy`](#scanexecutionpolicy). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="scanexecutionpolicyconnectionedges"></a>`edges` | [`[ScanExecutionPolicyEdge]`](#scanexecutionpolicyedge) | A list of edges. | +| <a id="scanexecutionpolicyconnectionnodes"></a>`nodes` | [`[ScanExecutionPolicy]`](#scanexecutionpolicy) | A list of nodes. | +| <a id="scanexecutionpolicyconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ScanExecutionPolicyEdge` + +The edge type for [`ScanExecutionPolicy`](#scanexecutionpolicy). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="scanexecutionpolicyedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="scanexecutionpolicyedgenode"></a>`node` | [`ScanExecutionPolicy`](#scanexecutionpolicy) | The item at the end of the edge. | + #### `ScannedResourceConnection` The connection type for [`ScannedResource`](#scannedresource). @@ -6682,29 +6815,6 @@ The edge type for [`UserCore`](#usercore). | <a id="usercoreedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="usercoreedgenode"></a>`node` | [`UserCore`](#usercore) | The item at the end of the edge. | -#### `VulnerabilitiesCountByDayAndSeverityConnection` - -The connection type for [`VulnerabilitiesCountByDayAndSeverity`](#vulnerabilitiescountbydayandseverity). - -##### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="vulnerabilitiescountbydayandseverityconnectionedges"></a>`edges` | [`[VulnerabilitiesCountByDayAndSeverityEdge]`](#vulnerabilitiescountbydayandseverityedge) | A list of edges. | -| <a id="vulnerabilitiescountbydayandseverityconnectionnodes"></a>`nodes` | [`[VulnerabilitiesCountByDayAndSeverity]`](#vulnerabilitiescountbydayandseverity) | A list of nodes. | -| <a id="vulnerabilitiescountbydayandseverityconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | - -#### `VulnerabilitiesCountByDayAndSeverityEdge` - -The edge type for [`VulnerabilitiesCountByDayAndSeverity`](#vulnerabilitiescountbydayandseverity). - -##### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="vulnerabilitiescountbydayandseverityedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | -| <a id="vulnerabilitiescountbydayandseverityedgenode"></a>`node` | [`VulnerabilitiesCountByDayAndSeverity`](#vulnerabilitiescountbydayandseverity) | The item at the end of the edge. | - #### `VulnerabilitiesCountByDayConnection` The connection type for [`VulnerabilitiesCountByDay`](#vulnerabilitiescountbyday). @@ -6844,6 +6954,16 @@ Represents the access level of a relationship between a User and object that it | <a id="accesslevelintegervalue"></a>`integerValue` | [`Int`](#int) | Integer representation of access level. | | <a id="accesslevelstringvalue"></a>`stringValue` | [`AccessLevelEnum`](#accesslevelenum) | String representation of access level. | +### `AgentConfiguration` + +Configuration details for an Agent. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="agentconfigurationagentname"></a>`agentName` | [`String`](#string) | Name of the agent. | + ### `AlertManagementAlert` Describes an alert from the project's Alert Management. @@ -7181,6 +7301,38 @@ Represents an epic on an issue board. #### Fields with arguments +##### `BoardEpic.ancestors` + +Ancestors (parents) of the epic. + +Returns [`EpicConnection`](#epicconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="boardepicancestorsauthorusername"></a>`authorUsername` | [`String`](#string) | Filter epics by author. | +| <a id="boardepicancestorsconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter epics by given confidentiality. | +| <a id="boardepicancestorsenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | +| <a id="boardepicancestorsiid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | +| <a id="boardepicancestorsiidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | +| <a id="boardepicancestorsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="boardepicancestorsincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | +| <a id="boardepicancestorsincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | +| <a id="boardepicancestorslabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | +| <a id="boardepicancestorsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | +| <a id="boardepicancestorsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="boardepicancestorsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="boardepicancestorssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | +| <a id="boardepicancestorssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | +| <a id="boardepicancestorsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | +| <a id="boardepicancestorsstate"></a>`state` | [`EpicState`](#epicstate) | Filter epics by state. | +| <a id="boardepicancestorstimeframe"></a>`timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | + ##### `BoardEpic.children` Children (sub-epics) of the epic. @@ -7201,10 +7353,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicchildreniid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="boardepicchildreniidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | | <a id="boardepicchildreniids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="boardepicchildrenincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="boardepicchildrenincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="boardepicchildrenlabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | | <a id="boardepicchildrenmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="boardepicchildrenmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="boardepicchildrennot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | | <a id="boardepicchildrensearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | | <a id="boardepicchildrensort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="boardepicchildrenstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -7468,6 +7622,8 @@ Represents the total number of issues and their weights for a particular day. | <a id="cirunneripaddress"></a>`ipAddress` | [`String!`](#string) | IP address of the runner. | | <a id="cirunnerlocked"></a>`locked` | [`Boolean`](#boolean) | Indicates the runner is locked. | | <a id="cirunnermaximumtimeout"></a>`maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. | +| <a id="cirunnerprivateprojectsminutescostfactor"></a>`privateProjectsMinutesCostFactor` | [`Float`](#float) | Private projects' "minutes cost factor" associated with the runner (GitLab.com only). | +| <a id="cirunnerpublicprojectsminutescostfactor"></a>`publicProjectsMinutesCostFactor` | [`Float`](#float) | Public projects' "minutes cost factor" associated with the runner (GitLab.com only). | | <a id="cirunnerrevision"></a>`revision` | [`String!`](#string) | Revision of the runner. | | <a id="cirunnerrununtagged"></a>`runUntagged` | [`Boolean!`](#boolean) | Indicates the runner is able to run untagged jobs. | | <a id="cirunnerrunnertype"></a>`runnerType` | [`CiRunnerType!`](#cirunnertype) | Type of the runner. | @@ -7754,6 +7910,7 @@ Represents the current license. | ---- | ---- | ----------- | | <a id="currentlicenseactivatedat"></a>`activatedAt` | [`Date`](#date) | Date when the license was activated. | | <a id="currentlicensebillableuserscount"></a>`billableUsersCount` | [`Int`](#int) | Number of billable users on the system. | +| <a id="currentlicenseblockchangesat"></a>`blockChangesAt` | [`Date`](#date) | Date, including grace period, when licensed features will be blocked. | | <a id="currentlicensecompany"></a>`company` | [`String`](#string) | Company of the licensee. | | <a id="currentlicenseemail"></a>`email` | [`String`](#string) | Email of the licensee. | | <a id="currentlicenseexpiresat"></a>`expiresAt` | [`Date`](#date) | Date when the license expires. | @@ -7816,7 +7973,6 @@ Represents a DAST scanner profile. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="dastscannerprofileeditpath"></a>`editPath` | [`String`](#string) | Relative web path to the edit page of a scanner profile. | -| <a id="dastscannerprofileglobalid"></a>`globalId` **{warning-solid}** | [`DastScannerProfileID!`](#dastscannerprofileid) | **Deprecated** in 13.6. Use `id`. | | <a id="dastscannerprofileid"></a>`id` | [`DastScannerProfileID!`](#dastscannerprofileid) | ID of the DAST scanner profile. | | <a id="dastscannerprofileprofilename"></a>`profileName` | [`String`](#string) | Name of the DAST scanner profile. | | <a id="dastscannerprofilereferencedinsecuritypolicies"></a>`referencedInSecurityPolicies` | [`[String!]`](#string) | List of security policy names that are referencing given project. | @@ -7834,15 +7990,15 @@ Represents a DAST Site Profile. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="dastsiteprofileauth"></a>`auth` | [`DastSiteProfileAuth`](#dastsiteprofileauth) | Target authentication details. Will always return `null` if `security_dast_site_profiles_additional_fields` feature flag is disabled. | +| <a id="dastsiteprofileauth"></a>`auth` | [`DastSiteProfileAuth`](#dastsiteprofileauth) | Target authentication details. | | <a id="dastsiteprofileeditpath"></a>`editPath` | [`String`](#string) | Relative web path to the edit page of a site profile. | -| <a id="dastsiteprofileexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. Will always return `null` if `security_dast_site_profiles_additional_fields` feature flag is disabled. | +| <a id="dastsiteprofileexcludedurls"></a>`excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. | | <a id="dastsiteprofileid"></a>`id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile. | | <a id="dastsiteprofilenormalizedtargeturl"></a>`normalizedTargetUrl` | [`String`](#string) | Normalized URL of the target to be scanned. | | <a id="dastsiteprofileprofilename"></a>`profileName` | [`String`](#string) | The name of the site profile. | | <a id="dastsiteprofilereferencedinsecuritypolicies"></a>`referencedInSecurityPolicies` | [`[String!]`](#string) | List of security policy names that are referencing given project. | -| <a id="dastsiteprofilerequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. Will always return `null` if `security_dast_site_profiles_additional_fields` feature flag is disabled. | -| <a id="dastsiteprofiletargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. Will always return `null` if `security_dast_site_profiles_api_option` feature flag is disabled. | +| <a id="dastsiteprofilerequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | +| <a id="dastsiteprofiletargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | | <a id="dastsiteprofiletargeturl"></a>`targetUrl` | [`String`](#string) | The URL of the target to be scanned. | | <a id="dastsiteprofileuserpermissions"></a>`userPermissions` | [`DastSiteProfilePermissions!`](#dastsiteprofilepermissions) | Permissions for the current user on the resource. | | <a id="dastsiteprofilevalidationstatus"></a>`validationStatus` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | The current validation status of the site profile. | @@ -8151,17 +8307,37 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="detailedstatustext"></a>`text` | [`String`](#string) | Text of the status. | | <a id="detailedstatustooltip"></a>`tooltip` | [`String`](#string) | Tooltip associated with the status. | -### `DevopsAdoptionSegment` +### `DevopsAdoptionEnabledNamespace` -Segment. +Enabled namespace for DevopsAdoption. #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="devopsadoptionsegmentid"></a>`id` | [`ID!`](#id) | ID of the segment. | -| <a id="devopsadoptionsegmentlatestsnapshot"></a>`latestSnapshot` | [`DevopsAdoptionSnapshot`](#devopsadoptionsnapshot) | The latest adoption metrics for the segment. | -| <a id="devopsadoptionsegmentnamespace"></a>`namespace` | [`Namespace`](#namespace) | Segment namespace. | +| <a id="devopsadoptionenablednamespacedisplaynamespace"></a>`displayNamespace` | [`Namespace`](#namespace) | Namespace where data should be displayed. | +| <a id="devopsadoptionenablednamespaceid"></a>`id` | [`ID!`](#id) | ID of the enabled namespace. | +| <a id="devopsadoptionenablednamespacelatestsnapshot"></a>`latestSnapshot` | [`DevopsAdoptionSnapshot`](#devopsadoptionsnapshot) | Metrics snapshot for previous month for the enabled namespace. | +| <a id="devopsadoptionenablednamespacenamespace"></a>`namespace` | [`Namespace`](#namespace) | Namespace which should be calculated. | + +#### Fields with arguments + +##### `DevopsAdoptionEnabledNamespace.snapshots` + +Data snapshots of the namespace. + +Returns [`DevopsAdoptionSnapshotConnection`](#devopsadoptionsnapshotconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="devopsadoptionenablednamespacesnapshotsendtimeafter"></a>`endTimeAfter` | [`Time`](#time) | Filter to snapshots with month end after the provided date. | +| <a id="devopsadoptionenablednamespacesnapshotsendtimebefore"></a>`endTimeBefore` | [`Time`](#time) | Filter to snapshots with month end before the provided date. | ### `DevopsAdoptionSnapshot` @@ -8336,6 +8512,38 @@ Represents an epic. #### Fields with arguments +##### `Epic.ancestors` + +Ancestors (parents) of the epic. + +Returns [`EpicConnection`](#epicconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="epicancestorsauthorusername"></a>`authorUsername` | [`String`](#string) | Filter epics by author. | +| <a id="epicancestorsconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter epics by given confidentiality. | +| <a id="epicancestorsenddate"></a>`endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | +| <a id="epicancestorsiid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | +| <a id="epicancestorsiidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | +| <a id="epicancestorsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="epicancestorsincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | +| <a id="epicancestorsincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | +| <a id="epicancestorslabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | +| <a id="epicancestorsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | +| <a id="epicancestorsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="epicancestorsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="epicancestorssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | +| <a id="epicancestorssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | +| <a id="epicancestorsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | +| <a id="epicancestorsstate"></a>`state` | [`EpicState`](#epicstate) | Filter epics by state. | +| <a id="epicancestorstimeframe"></a>`timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | + ##### `Epic.children` Children (sub-epics) of the epic. @@ -8356,10 +8564,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicchildreniid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="epicchildreniidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | | <a id="epicchildreniids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="epicchildrenincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="epicchildrenincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="epicchildrenlabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | | <a id="epicchildrenmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="epicchildrenmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="epicchildrennot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | | <a id="epicchildrensearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | | <a id="epicchildrensort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="epicchildrenstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -8426,6 +8636,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="epicboardlistsepicfilters"></a>`epicFilters` | [`EpicFilters`](#epicfilters) | Filters applied when getting epic metadata in the epic board list. | | <a id="epicboardlistsid"></a>`id` | [`BoardsEpicListID`](#boardsepiclistid) | Find an epic board list by ID. | ### `EpicDescendantCount` @@ -8610,6 +8821,32 @@ Check permissions for the current user on an epic. | <a id="epicpermissionsreadepiciid"></a>`readEpicIid` | [`Boolean!`](#boolean) | Indicates the user can perform `read_epic_iid` on this resource. | | <a id="epicpermissionsupdateepic"></a>`updateEpic` | [`Boolean!`](#boolean) | Indicates the user can perform `update_epic` on this resource. | +### `EscalationPolicyType` + +Represents an escalation policy. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="escalationpolicytypedescription"></a>`description` | [`String`](#string) | The description of the escalation policy. | +| <a id="escalationpolicytypeid"></a>`id` | [`IncidentManagementEscalationPolicyID`](#incidentmanagementescalationpolicyid) | ID of the escalation policy. | +| <a id="escalationpolicytypename"></a>`name` | [`String`](#string) | The name of the escalation policy. | +| <a id="escalationpolicytyperules"></a>`rules` | [`[EscalationRuleType!]`](#escalationruletype) | Steps of the escalation policy. | + +### `EscalationRuleType` + +Represents an escalation rule for an escalation policy. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="escalationruletypeelapsedtimeseconds"></a>`elapsedTimeSeconds` | [`Int`](#int) | The time in seconds before the rule is activated. | +| <a id="escalationruletypeid"></a>`id` | [`IncidentManagementEscalationRuleID`](#incidentmanagementescalationruleid) | ID of the escalation policy. | +| <a id="escalationruletypeoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule to notify. | +| <a id="escalationruletypestatus"></a>`status` | [`EscalationRuleStatus`](#escalationrulestatus) | The status required to prevent the rule from activating. | + ### `Event` Representing an event. @@ -8930,10 +9167,12 @@ Returns [`Epic`](#epic). | <a id="groupepiciid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="groupepiciidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | | <a id="groupepiciids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="groupepicincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="groupepicincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="groupepiclabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | | <a id="groupepicmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="groupepicmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="groupepicnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | | <a id="groupepicsearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | | <a id="groupepicsort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="groupepicstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -8972,10 +9211,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupepicsiid"></a>`iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | <a id="groupepicsiidstartswith"></a>`iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | | <a id="groupepicsiids"></a>`iids` | [`[ID!]`](#id) | List of IIDs of epics, e.g., [1, 2]. | +| <a id="groupepicsincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Include epics from ancestor groups. | | <a id="groupepicsincludedescendantgroups"></a>`includeDescendantGroups` | [`Boolean`](#boolean) | Include epics from descendant groups. | | <a id="groupepicslabelname"></a>`labelName` | [`[String!]`](#string) | Filter epics by labels. | | <a id="groupepicsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="groupepicsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="groupepicsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | | <a id="groupepicssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | | <a id="groupepicssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="groupepicsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -9268,27 +9509,6 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupvulnerabilitiescountbydayenddate"></a>`endDate` | [`ISO8601Date!`](#iso8601date) | Last day for which to fetch vulnerability history. | | <a id="groupvulnerabilitiescountbydaystartdate"></a>`startDate` | [`ISO8601Date!`](#iso8601date) | First day for which to fetch vulnerability history. | -##### `Group.vulnerabilitiesCountByDayAndSeverity` - -Number of vulnerabilities per severity level, per day, for the projects in the group and its subgroups. - -WARNING: -**Deprecated** in 13.3. -Use `vulnerabilitiesCountByDay`. - -Returns [`VulnerabilitiesCountByDayAndSeverityConnection`](#vulnerabilitiescountbydayandseverityconnection). - -This field returns a [connection](#connections). It accepts the -four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. - -###### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="groupvulnerabilitiescountbydayandseverityenddate"></a>`endDate` | [`ISO8601Date!`](#iso8601date) | Last day for which to fetch vulnerability history. | -| <a id="groupvulnerabilitiescountbydayandseveritystartdate"></a>`startDate` | [`ISO8601Date!`](#iso8601date) | First day for which to fetch vulnerability history. | - ##### `Group.vulnerabilityGrades` Represents vulnerable project counts for each grade. @@ -9311,9 +9531,12 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="groupvulnerabilityseveritiescounthasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Filter vulnerabilities that do or do not have issues. | +| <a id="groupvulnerabilityseveritiescounthasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Filter vulnerabilities that do or do not have a resolution. | | <a id="groupvulnerabilityseveritiescountprojectid"></a>`projectId` | [`[ID!]`](#id) | Filter vulnerabilities by project. | | <a id="groupvulnerabilityseveritiescountreporttype"></a>`reportType` | [`[VulnerabilityReportType!]`](#vulnerabilityreporttype) | Filter vulnerabilities by report type. | | <a id="groupvulnerabilityseveritiescountscanner"></a>`scanner` | [`[String!]`](#string) | Filter vulnerabilities by scanner. | +| <a id="groupvulnerabilityseveritiescountscannerid"></a>`scannerId` | [`[VulnerabilitiesScannerID!]`](#vulnerabilitiesscannerid) | Filter vulnerabilities by scanner ID. | | <a id="groupvulnerabilityseveritiescountseverity"></a>`severity` | [`[VulnerabilitySeverity!]`](#vulnerabilityseverity) | Filter vulnerabilities by severity. | | <a id="groupvulnerabilityseveritiescountstate"></a>`state` | [`[VulnerabilityState!]`](#vulnerabilitystate) | Filter vulnerabilities by state. | @@ -9332,7 +9555,7 @@ Represents a Group Membership. | <a id="groupmembergroup"></a>`group` | [`Group`](#group) | Group that a User is a member of. | | <a id="groupmemberid"></a>`id` | [`ID!`](#id) | ID of the member. | | <a id="groupmemberupdatedat"></a>`updatedAt` | [`Time`](#time) | Date and time the membership was last updated. | -| <a id="groupmemberuser"></a>`user` | [`UserCore!`](#usercore) | User that is associated with the member object. | +| <a id="groupmemberuser"></a>`user` | [`UserCore`](#usercore) | User that is associated with the member object. | | <a id="groupmemberuserpermissions"></a>`userPermissions` | [`GroupPermissions!`](#grouppermissions) | Permissions for the current user on the resource. | ### `GroupPermissions` @@ -9463,12 +9686,27 @@ A block of time for which a participant is on-call. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="instancesecuritydashboardprojects"></a>`projects` | [`ProjectConnection!`](#projectconnection) | Projects selected in Instance Security Dashboard. (see [Connections](#connections)) | | <a id="instancesecuritydashboardvulnerabilitygrades"></a>`vulnerabilityGrades` | [`[VulnerableProjectsByGrade!]!`](#vulnerableprojectsbygrade) | Represents vulnerable project counts for each grade. | | <a id="instancesecuritydashboardvulnerabilityscanners"></a>`vulnerabilityScanners` | [`VulnerabilityScannerConnection`](#vulnerabilityscannerconnection) | Vulnerability scanners reported on the vulnerabilities from projects selected in Instance Security Dashboard. (see [Connections](#connections)) | #### Fields with arguments +##### `InstanceSecurityDashboard.projects` + +Projects selected in Instance Security Dashboard. + +Returns [`ProjectConnection!`](#projectconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="instancesecuritydashboardprojectssearch"></a>`search` | [`String`](#string) | Search query for project name, path, or description. | + ##### `InstanceSecurityDashboard.vulnerabilitySeveritiesCount` Counts for each vulnerability severity from projects selected in Instance Security Dashboard. @@ -9479,9 +9717,12 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="instancesecuritydashboardvulnerabilityseveritiescounthasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Filter vulnerabilities that do or do not have issues. | +| <a id="instancesecuritydashboardvulnerabilityseveritiescounthasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Filter vulnerabilities that do or do not have a resolution. | | <a id="instancesecuritydashboardvulnerabilityseveritiescountprojectid"></a>`projectId` | [`[ID!]`](#id) | Filter vulnerabilities by project. | | <a id="instancesecuritydashboardvulnerabilityseveritiescountreporttype"></a>`reportType` | [`[VulnerabilityReportType!]`](#vulnerabilityreporttype) | Filter vulnerabilities by report type. | | <a id="instancesecuritydashboardvulnerabilityseveritiescountscanner"></a>`scanner` | [`[String!]`](#string) | Filter vulnerabilities by scanner. | +| <a id="instancesecuritydashboardvulnerabilityseveritiescountscannerid"></a>`scannerId` | [`[VulnerabilitiesScannerID!]`](#vulnerabilitiesscannerid) | Filter vulnerabilities by scanner ID. | | <a id="instancesecuritydashboardvulnerabilityseveritiescountseverity"></a>`severity` | [`[VulnerabilitySeverity!]`](#vulnerabilityseverity) | Filter vulnerabilities by severity. | | <a id="instancesecuritydashboardvulnerabilityseveritiescountstate"></a>`state` | [`[VulnerabilityState!]`](#vulnerabilitystate) | Filter vulnerabilities by state. | @@ -9743,7 +9984,6 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="labeldescription"></a>`description` | [`String`](#string) | Description of the label (Markdown rendered as HTML for caching). | | <a id="labeldescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | | <a id="labelid"></a>`id` | [`ID!`](#id) | Label ID. | -| <a id="labelremoveonclose"></a>`removeOnClose` | [`Boolean!`](#boolean) | Whether the label should be removed from an issue when the issue is closed. | | <a id="labeltextcolor"></a>`textColor` | [`String!`](#string) | Text color of the label. | | <a id="labeltitle"></a>`title` | [`String!`](#string) | Content of the label. | | <a id="labelupdatedat"></a>`updatedAt` | [`Time!`](#time) | When this label was last updated. | @@ -9774,6 +10014,7 @@ Represents an entry from the Cloud License history. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="licensehistoryentryactivatedat"></a>`activatedAt` | [`Date`](#date) | Date when the license was activated. | +| <a id="licensehistoryentryblockchangesat"></a>`blockChangesAt` | [`Date`](#date) | Date, including grace period, when licensed features will be blocked. | | <a id="licensehistoryentrycompany"></a>`company` | [`String`](#string) | Company of the licensee. | | <a id="licensehistoryentryemail"></a>`email` | [`String`](#string) | Email of the licensee. | | <a id="licensehistoryentryexpiresat"></a>`expiresAt` | [`Date`](#date) | Date when the license expires. | @@ -9837,6 +10078,8 @@ Maven metadata. | <a id="mergerequesthasci"></a>`hasCi` | [`Boolean!`](#boolean) | Indicates if the merge request has CI. | | <a id="mergerequesthassecurityreports"></a>`hasSecurityReports` | [`Boolean!`](#boolean) | Indicates if the source branch has any security reports. | | <a id="mergerequestheadpipeline"></a>`headPipeline` | [`Pipeline`](#pipeline) | The pipeline running on the branch HEAD of the merge request. | +| <a id="mergerequesthumantimeestimate"></a>`humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the merge request. | +| <a id="mergerequesthumantotaltimespent"></a>`humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the merge request. | | <a id="mergerequestid"></a>`id` | [`ID!`](#id) | ID of the merge request. | | <a id="mergerequestiid"></a>`iid` | [`String!`](#string) | Internal ID of the merge request. | | <a id="mergerequestinprogressmergecommitsha"></a>`inProgressMergeCommitSha` | [`String`](#string) | Commit SHA of the merge request if merge is in progress. | @@ -9844,7 +10087,8 @@ Maven metadata. | <a id="mergerequestmergecommitsha"></a>`mergeCommitSha` | [`String`](#string) | SHA of the merge request commit (set once merged). | | <a id="mergerequestmergeerror"></a>`mergeError` | [`String`](#string) | Error message due to a merge error. | | <a id="mergerequestmergeongoing"></a>`mergeOngoing` | [`Boolean!`](#boolean) | Indicates if a merge is currently occurring. | -| <a id="mergerequestmergestatus"></a>`mergeStatus` | [`String`](#string) | Status of the merge request. | +| <a id="mergerequestmergestatus"></a>`mergeStatus` **{warning-solid}** | [`String`](#string) | **Deprecated** in 14.0. This was renamed. Use: [`MergeRequest.mergeStatusEnum`](#mergerequestmergestatusenum). | +| <a id="mergerequestmergestatusenum"></a>`mergeStatusEnum` | [`MergeStatus`](#mergestatus) | Merge status of the merge request. | | <a id="mergerequestmergetrainscount"></a>`mergeTrainsCount` | [`Int`](#int) | Number of merge requests in the merge train. | | <a id="mergerequestmergeuser"></a>`mergeUser` | [`UserCore`](#usercore) | User who merged this merge request. | | <a id="mergerequestmergewhenpipelinesucceeds"></a>`mergeWhenPipelineSucceeds` | [`Boolean`](#boolean) | Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS). | @@ -10493,6 +10737,21 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="namespaceprojectssearch"></a>`search` | [`String`](#string) | Search project with most similar names or paths. | | <a id="namespaceprojectssort"></a>`sort` | [`NamespaceProjectSort`](#namespaceprojectsort) | Sort projects by this criteria. | +### `NetworkPolicy` + +Represents the network policy. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="networkpolicyenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether this policy is enabled. | +| <a id="networkpolicyfromautodevops"></a>`fromAutoDevops` | [`Boolean!`](#boolean) | Indicates whether this policy is created from AutoDevops. | +| <a id="networkpolicyname"></a>`name` | [`String!`](#string) | Name of the policy. | +| <a id="networkpolicynamespace"></a>`namespace` | [`String!`](#string) | Namespace of the policy. | +| <a id="networkpolicyupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the policy YAML was last updated. | +| <a id="networkpolicyyaml"></a>`yaml` | [`String!`](#string) | YAML definition of the policy. | + ### `Note` #### Fields @@ -10877,6 +11136,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="pipelinesecurityreportfindingscanner"></a>`scanner` | [`VulnerabilityScanner`](#vulnerabilityscanner) | Scanner metadata for the vulnerability. | | <a id="pipelinesecurityreportfindingseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability finding. | | <a id="pipelinesecurityreportfindingsolution"></a>`solution` | [`String`](#string) | URL to the vulnerability's details page. | +| <a id="pipelinesecurityreportfindingstate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | The finding status. | | <a id="pipelinesecurityreportfindinguuid"></a>`uuid` | [`String`](#string) | Name of the vulnerability finding. | ### `Project` @@ -10886,6 +11146,7 @@ Represents vulnerability finding of a security report on the pipeline. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="projectactualrepositorysizelimit"></a>`actualRepositorySizeLimit` | [`Float`](#float) | Size limit for the repository in bytes. | +| <a id="projectagentconfigurations"></a>`agentConfigurations` | [`AgentConfigurationConnection`](#agentconfigurationconnection) | Agent configurations defined by the project. (see [Connections](#connections)) | | <a id="projectallowmergeonskippedpipeline"></a>`allowMergeOnSkippedPipeline` | [`Boolean`](#boolean) | If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs. | | <a id="projectapifuzzingciconfiguration"></a>`apiFuzzingCiConfiguration` | [`ApiFuzzingCiConfiguration`](#apifuzzingciconfiguration) | API fuzzing configuration for the project. | | <a id="projectarchived"></a>`archived` | [`Boolean`](#boolean) | Indicates the archived status of the project. | @@ -10911,6 +11172,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projecthttpurltorepo"></a>`httpUrlToRepo` | [`String`](#string) | URL to connect to the project via HTTPS. | | <a id="projectid"></a>`id` | [`ID!`](#id) | ID of the project. | | <a id="projectimportstatus"></a>`importStatus` | [`String`](#string) | Status of import background job of the project. | +| <a id="projectincidentmanagementescalationpolicies"></a>`incidentManagementEscalationPolicies` | [`EscalationPolicyTypeConnection`](#escalationpolicytypeconnection) | Incident Management escalation policies of the project. (see [Connections](#connections)) | | <a id="projectissuesenabled"></a>`issuesEnabled` | [`Boolean`](#boolean) | Indicates if Issues are enabled for the current user. | | <a id="projectjiraimportstatus"></a>`jiraImportStatus` | [`String`](#string) | Status of Jira import background job of the project. | | <a id="projectjiraimports"></a>`jiraImports` | [`JiraImportConnection`](#jiraimportconnection) | Jira imports into the project. (see [Connections](#connections)) | @@ -10937,6 +11199,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectrequestaccessenabled"></a>`requestAccessEnabled` | [`Boolean`](#boolean) | Indicates if users can request member access to the project. | | <a id="projectrequirementstatescount"></a>`requirementStatesCount` | [`RequirementStatesCount`](#requirementstatescount) | Number of requirements for the project by their state. | | <a id="projectsastciconfiguration"></a>`sastCiConfiguration` | [`SastCiConfiguration`](#sastciconfiguration) | SAST CI configuration for the project. | +| <a id="projectscanexecutionpolicies"></a>`scanExecutionPolicies` | [`ScanExecutionPolicyConnection`](#scanexecutionpolicyconnection) | Scan Execution Policies of the project. (see [Connections](#connections)) | | <a id="projectsecuritydashboardpath"></a>`securityDashboardPath` | [`String`](#string) | Path to project's security dashboard. | | <a id="projectsecurityscanners"></a>`securityScanners` | [`SecurityScanners`](#securityscanners) | Information about security analyzers used in the project. | | <a id="projectsentryerrors"></a>`sentryErrors` | [`SentryErrorCollection`](#sentryerrorcollection) | Paginated collection of Sentry errors on the project. | @@ -11184,6 +11447,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectenvironmentssearch"></a>`search` | [`String`](#string) | Search query for environment name. | | <a id="projectenvironmentsstates"></a>`states` | [`[String!]`](#string) | States of environments that should be included in result. | +##### `Project.incidentManagementEscalationPolicy` + +Incident Management escalation policy of the project. + +Returns [`EscalationPolicyType`](#escalationpolicytype). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectincidentmanagementescalationpolicyid"></a>`id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | ID of the escalation policy. | + ##### `Project.incidentManagementOncallSchedules` Incident Management On-call schedules of the project. @@ -11454,6 +11729,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectmilestonestimeframe"></a>`timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | | <a id="projectmilestonestitle"></a>`title` | [`String`](#string) | The title of the milestone. | +##### `Project.networkPolicies` + +Network Policies of the project. + +Returns [`NetworkPolicyConnection`](#networkpolicyconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectnetworkpoliciesenvironmentid"></a>`environmentId` | [`EnvironmentID`](#environmentid) | The global ID of the environment to filter policies. | + ##### `Project.packages` Packages of the project. @@ -11616,8 +11907,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectservicesactive"></a>`active` | [`Boolean`](#boolean) | Indicates if the service is active. | -| <a id="projectservicestype"></a>`type` | [`ServiceType`](#servicetype) | Class name of the service. | +| <a id="projectservicesactive"></a>`active` | [`Boolean`](#boolean) | Indicates if the integration is active. | +| <a id="projectservicestype"></a>`type` | [`ServiceType`](#servicetype) | Type of integration. | ##### `Project.snippets` @@ -11699,9 +11990,12 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="projectvulnerabilityseveritiescounthasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Filter vulnerabilities that do or do not have issues. | +| <a id="projectvulnerabilityseveritiescounthasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Filter vulnerabilities that do or do not have a resolution. | | <a id="projectvulnerabilityseveritiescountprojectid"></a>`projectId` | [`[ID!]`](#id) | Filter vulnerabilities by project. | | <a id="projectvulnerabilityseveritiescountreporttype"></a>`reportType` | [`[VulnerabilityReportType!]`](#vulnerabilityreporttype) | Filter vulnerabilities by report type. | | <a id="projectvulnerabilityseveritiescountscanner"></a>`scanner` | [`[String!]`](#string) | Filter vulnerabilities by scanner. | +| <a id="projectvulnerabilityseveritiescountscannerid"></a>`scannerId` | [`[VulnerabilitiesScannerID!]`](#vulnerabilitiesscannerid) | Filter vulnerabilities by scanner ID. | | <a id="projectvulnerabilityseveritiescountseverity"></a>`severity` | [`[VulnerabilitySeverity!]`](#vulnerabilityseverity) | Filter vulnerabilities by severity. | | <a id="projectvulnerabilityseveritiescountstate"></a>`state` | [`[VulnerabilityState!]`](#vulnerabilitystate) | Filter vulnerabilities by state. | @@ -11711,6 +12005,7 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="projectcicdsettingjobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI job tokens generated in this project have restricted access to resources. | | <a id="projectcicdsettingkeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Whether to keep the latest builds artifacts. | | <a id="projectcicdsettingmergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Whether merge pipelines are enabled. | | <a id="projectcicdsettingmergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Whether merge trains are enabled. | @@ -11731,7 +12026,7 @@ Represents a Project Membership. | <a id="projectmemberid"></a>`id` | [`ID!`](#id) | ID of the member. | | <a id="projectmemberproject"></a>`project` | [`Project`](#project) | Project that User is a member of. | | <a id="projectmemberupdatedat"></a>`updatedAt` | [`Time`](#time) | Date and time the membership was last updated. | -| <a id="projectmemberuser"></a>`user` | [`UserCore!`](#usercore) | User that is associated with the member object. | +| <a id="projectmemberuser"></a>`user` | [`UserCore`](#usercore) | User that is associated with the member object. | | <a id="projectmemberuserpermissions"></a>`userPermissions` | [`ProjectPermissions!`](#projectpermissions) | Permissions for the current user on the resource. | ### `ProjectPermissions` @@ -11821,6 +12116,17 @@ Represents rules that commit pushes must follow. | ---- | ---- | ----------- | | <a id="pushrulesrejectunsignedcommits"></a>`rejectUnsignedCommits` | [`Boolean!`](#boolean) | Indicates whether commits not signed through GPG will be rejected. | +### `PypiMetadata` + +Pypi metadata. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pypimetadataid"></a>`id` | [`PackagesPypiMetadatumID!`](#packagespypimetadatumid) | ID of the metadatum. | +| <a id="pypimetadatarequiredpython"></a>`requiredPython` | [`String`](#string) | Required Python version of the Pypi package. | + ### `RecentFailures` Recent failure history of a test case. @@ -12091,18 +12397,6 @@ Counts of requirements by their state. | <a id="rootstoragestatisticsuploadssize"></a>`uploadsSize` | [`Float!`](#float) | The uploads size in bytes. | | <a id="rootstoragestatisticswikisize"></a>`wikiSize` | [`Float!`](#float) | The wiki size in bytes. | -### `RunDASTScanPayload` - -Autogenerated return type of RunDASTScan. - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="rundastscanpayloadclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="rundastscanpayloaderrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="rundastscanpayloadpipelineurl"></a>`pipelineUrl` | [`String`](#string) | URL of the pipeline that was created. | - ### `RunnerArchitecture` #### Fields @@ -12196,6 +12490,20 @@ Represents the security scan information. | <a id="scanerrors"></a>`errors` | [`[String!]!`](#string) | List of errors. | | <a id="scanname"></a>`name` | [`String!`](#string) | Name of the scan. | +### `ScanExecutionPolicy` + +Represents the scan execution policy. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="scanexecutionpolicydescription"></a>`description` | [`String!`](#string) | Description of the policy. | +| <a id="scanexecutionpolicyenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether this policy is enabled. | +| <a id="scanexecutionpolicyname"></a>`name` | [`String!`](#string) | Name of the policy. | +| <a id="scanexecutionpolicyupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the policy YAML was last updated. | +| <a id="scanexecutionpolicyyaml"></a>`yaml` | [`String!`](#string) | YAML definition of the policy. | + ### `ScannedResource` Represents a resource scanned by a security scan. @@ -12431,7 +12739,6 @@ Represents a snippet entry. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="snippetauthor"></a>`author` | [`UserCore`](#usercore) | The owner of the snippet. | -| <a id="snippetblob"></a>`blob` **{warning-solid}** | [`SnippetBlob!`](#snippetblob) | **Deprecated** in 13.3. Use `blobs`. | | <a id="snippetcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp this snippet was created. | | <a id="snippetdescription"></a>`description` | [`String`](#string) | Description of the snippet. | | <a id="snippetdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | @@ -13049,18 +13356,6 @@ Represents the count of vulnerabilities by severity on a particular day. This da | <a id="vulnerabilitiescountbydaytotal"></a>`total` | [`Int!`](#int) | Total number of vulnerabilities on a particular day. | | <a id="vulnerabilitiescountbydayunknown"></a>`unknown` | [`Int!`](#int) | Total number of vulnerabilities on a particular day with unknown severity. | -### `VulnerabilitiesCountByDayAndSeverity` - -Represents the number of vulnerabilities for a particular severity on a particular day. This data is retained for 365 days. - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="vulnerabilitiescountbydayandseveritycount"></a>`count` | [`Int`](#int) | Number of vulnerabilities. | -| <a id="vulnerabilitiescountbydayandseverityday"></a>`day` | [`ISO8601Date`](#iso8601date) | Date for the count. | -| <a id="vulnerabilitiescountbydayandseverityseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the counted vulnerabilities. | - ### `Vulnerability` Represents a vulnerability. @@ -13537,10 +13832,10 @@ Values for sorting alerts. | <a id="alertmanagementalertsortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | | <a id="alertmanagementalertsortupdated_time_asc"></a>`UPDATED_TIME_ASC` | Created time by ascending order. | | <a id="alertmanagementalertsortupdated_time_desc"></a>`UPDATED_TIME_DESC` | Created time by descending order. | -| <a id="alertmanagementalertsortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_ASC`. Deprecated in 13.5. | -| <a id="alertmanagementalertsortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_DESC`. Deprecated in 13.5. | -| <a id="alertmanagementalertsortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_ASC`. Deprecated in 13.5. | -| <a id="alertmanagementalertsortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_DESC`. Deprecated in 13.5. | +| <a id="alertmanagementalertsortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_ASC`. | +| <a id="alertmanagementalertsortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_DESC`. | +| <a id="alertmanagementalertsortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_ASC`. | +| <a id="alertmanagementalertsortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_DESC`. | ### `AlertManagementDomainFilter` @@ -13699,7 +13994,9 @@ Values for sorting runners. | Value | Description | | ----- | ----------- | | <a id="cirunnersortcontacted_asc"></a>`CONTACTED_ASC` | Ordered by contacted_at in ascending order. | -| <a id="cirunnersortcreated_desc"></a>`CREATED_DESC` | Ordered by created_date in descending order. | +| <a id="cirunnersortcontacted_desc"></a>`CONTACTED_DESC` | Ordered by contacted_at in descending order. | +| <a id="cirunnersortcreated_asc"></a>`CREATED_ASC` | Ordered by created_at in ascending order. | +| <a id="cirunnersortcreated_desc"></a>`CREATED_DESC` | Ordered by created_at in descending order. | ### `CiRunnerStatus` @@ -13810,10 +14107,10 @@ Values for sorting container repositories. | <a id="containerrepositorysortname_desc"></a>`NAME_DESC` | Name by descending order. | | <a id="containerrepositorysortupdated_asc"></a>`UPDATED_ASC` | Updated at ascending order. | | <a id="containerrepositorysortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | -| <a id="containerrepositorysortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_ASC`. Deprecated in 13.5. | -| <a id="containerrepositorysortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_DESC`. Deprecated in 13.5. | -| <a id="containerrepositorysortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_ASC`. Deprecated in 13.5. | -| <a id="containerrepositorysortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_DESC`. Deprecated in 13.5. | +| <a id="containerrepositorysortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_ASC`. | +| <a id="containerrepositorysortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_DESC`. | +| <a id="containerrepositorysortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_ASC`. | +| <a id="containerrepositorysortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_DESC`. | ### `ContainerRepositoryStatus` @@ -13935,10 +14232,10 @@ Roadmap sort values. | <a id="epicsortend_date_desc"></a>`END_DATE_DESC` | Sort by end date in descending order. | | <a id="epicsortstart_date_asc"></a>`START_DATE_ASC` | Sort by start date in ascending order. | | <a id="epicsortstart_date_desc"></a>`START_DATE_DESC` | Sort by start date in descending order. | -| <a id="epicsortend_date_asc"></a>`end_date_asc` **{warning-solid}** | **Deprecated:** Use END_DATE_ASC. Deprecated in 13.11. | -| <a id="epicsortend_date_desc"></a>`end_date_desc` **{warning-solid}** | **Deprecated:** Use END_DATE_DESC. Deprecated in 13.11. | -| <a id="epicsortstart_date_asc"></a>`start_date_asc` **{warning-solid}** | **Deprecated:** Use START_DATE_ASC. Deprecated in 13.11. | -| <a id="epicsortstart_date_desc"></a>`start_date_desc` **{warning-solid}** | **Deprecated:** Use START_DATE_DESC. Deprecated in 13.11. | +| <a id="epicsortend_date_asc"></a>`end_date_asc` **{warning-solid}** | **Deprecated** in 13.11. Use END_DATE_ASC. | +| <a id="epicsortend_date_desc"></a>`end_date_desc` **{warning-solid}** | **Deprecated** in 13.11. Use END_DATE_DESC. | +| <a id="epicsortstart_date_asc"></a>`start_date_asc` **{warning-solid}** | **Deprecated** in 13.11. Use START_DATE_ASC. | +| <a id="epicsortstart_date_desc"></a>`start_date_desc` **{warning-solid}** | **Deprecated** in 13.11. Use START_DATE_DESC. | ### `EpicState` @@ -13968,6 +14265,15 @@ Epic ID wildcard values. | <a id="epicwildcardidany"></a>`ANY` | Any epic is assigned. | | <a id="epicwildcardidnone"></a>`NONE` | No epic is assigned. | +### `EscalationRuleStatus` + +Escalation rule statuses. + +| Value | Description | +| ----- | ----------- | +| <a id="escalationrulestatusacknowledged"></a>`ACKNOWLEDGED` | . | +| <a id="escalationrulestatusresolved"></a>`RESOLVED` | . | + ### `EventAction` Event action. @@ -14058,10 +14364,10 @@ Values for sorting issues. | <a id="issuesortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | | <a id="issuesortweight_asc"></a>`WEIGHT_ASC` | Weight by ascending order. | | <a id="issuesortweight_desc"></a>`WEIGHT_DESC` | Weight by descending order. | -| <a id="issuesortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_ASC`. Deprecated in 13.5. | -| <a id="issuesortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_DESC`. Deprecated in 13.5. | -| <a id="issuesortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_ASC`. Deprecated in 13.5. | -| <a id="issuesortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_DESC`. Deprecated in 13.5. | +| <a id="issuesortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_ASC`. | +| <a id="issuesortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_DESC`. | +| <a id="issuesortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_ASC`. | +| <a id="issuesortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_DESC`. | ### `IssueState` @@ -14133,7 +14439,6 @@ Iteration ID wildcard values. | <a id="jobartifactfiletypedependency_scanning"></a>`DEPENDENCY_SCANNING` | DEPENDENCY SCANNING job artifact file type. | | <a id="jobartifactfiletypedotenv"></a>`DOTENV` | DOTENV job artifact file type. | | <a id="jobartifactfiletypejunit"></a>`JUNIT` | JUNIT job artifact file type. | -| <a id="jobartifactfiletypelicense_management"></a>`LICENSE_MANAGEMENT` | LICENSE MANAGEMENT job artifact file type. | | <a id="jobartifactfiletypelicense_scanning"></a>`LICENSE_SCANNING` | LICENSE SCANNING job artifact file type. | | <a id="jobartifactfiletypeload_performance"></a>`LOAD_PERFORMANCE` | LOAD PERFORMANCE job artifact file type. | | <a id="jobartifactfiletypelsif"></a>`LSIF` | LSIF job artifact file type. | @@ -14211,10 +14516,10 @@ Values for sorting merge requests. | <a id="mergerequestsortpriority_desc"></a>`PRIORITY_DESC` | Priority by descending order. | | <a id="mergerequestsortupdated_asc"></a>`UPDATED_ASC` | Updated at ascending order. | | <a id="mergerequestsortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | -| <a id="mergerequestsortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_ASC`. Deprecated in 13.5. | -| <a id="mergerequestsortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_DESC`. Deprecated in 13.5. | -| <a id="mergerequestsortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_ASC`. Deprecated in 13.5. | -| <a id="mergerequestsortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_DESC`. Deprecated in 13.5. | +| <a id="mergerequestsortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_ASC`. | +| <a id="mergerequestsortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_DESC`. | +| <a id="mergerequestsortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_ASC`. | +| <a id="mergerequestsortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_DESC`. | ### `MergeRequestState` @@ -14228,6 +14533,18 @@ State of a GitLab merge request. | <a id="mergerequeststatemerged"></a>`merged` | Merge request has been merged. | | <a id="mergerequeststateopened"></a>`opened` | In open state. | +### `MergeStatus` + +Representation of whether a GitLab merge request can be merged. + +| Value | Description | +| ----- | ----------- | +| <a id="mergestatuscannot_be_merged"></a>`CANNOT_BE_MERGED` | There are conflicts between the source and target branches. | +| <a id="mergestatuscannot_be_merged_recheck"></a>`CANNOT_BE_MERGED_RECHECK` | Currently unchecked. The previous state was `CANNOT_BE_MERGED`. | +| <a id="mergestatuscan_be_merged"></a>`CAN_BE_MERGED` | There are no conflicts between the source and target branches. | +| <a id="mergestatuschecking"></a>`CHECKING` | Currently checking for mergeability. | +| <a id="mergestatusunchecked"></a>`UNCHECKED` | Merge status has not been checked. | + ### `MergeStrategyEnum` | Value | Description | @@ -14301,6 +14618,8 @@ Values for sorting group packages. | <a id="packagegroupsortcreated_desc"></a>`CREATED_DESC` | Ordered by created_at in descending order. | | <a id="packagegroupsortname_asc"></a>`NAME_ASC` | Ordered by name in ascending order. | | <a id="packagegroupsortname_desc"></a>`NAME_DESC` | Ordered by name in descending order. | +| <a id="packagegroupsortproject_path_asc"></a>`PROJECT_PATH_ASC` | Ordered by project path in ascending order. | +| <a id="packagegroupsortproject_path_desc"></a>`PROJECT_PATH_DESC` | Ordered by project path in descending order. | | <a id="packagegroupsorttype_asc"></a>`TYPE_ASC` | Ordered by type in ascending order. | | <a id="packagegroupsorttype_desc"></a>`TYPE_DESC` | Ordered by type in descending order. | | <a id="packagegroupsortversion_asc"></a>`VERSION_ASC` | Ordered by version in ascending order. | @@ -14533,10 +14852,10 @@ Type of a snippet blob input action. | Value | Description | | ----- | ----------- | -| <a id="snippetblobactionenumcreate"></a>`create` | | -| <a id="snippetblobactionenumdelete"></a>`delete` | | -| <a id="snippetblobactionenummove"></a>`move` | | -| <a id="snippetblobactionenumupdate"></a>`update` | | +| <a id="snippetblobactionenumcreate"></a>`create` | Create a snippet blob. | +| <a id="snippetblobactionenumdelete"></a>`delete` | Delete a snippet blob. | +| <a id="snippetblobactionenummove"></a>`move` | Move a snippet blob. | +| <a id="snippetblobactionenumupdate"></a>`update` | Update a snippet blob. | ### `Sort` @@ -14548,10 +14867,10 @@ Common sort values. | <a id="sortcreated_desc"></a>`CREATED_DESC` | Created at descending order. | | <a id="sortupdated_asc"></a>`UPDATED_ASC` | Updated at ascending order. | | <a id="sortupdated_desc"></a>`UPDATED_DESC` | Updated at descending order. | -| <a id="sortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_ASC`. Deprecated in 13.5. | -| <a id="sortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `CREATED_DESC`. Deprecated in 13.5. | -| <a id="sortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_ASC`. Deprecated in 13.5. | -| <a id="sortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated:** This was renamed. Please use `UPDATED_DESC`. Deprecated in 13.5. | +| <a id="sortcreated_asc"></a>`created_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_ASC`. | +| <a id="sortcreated_desc"></a>`created_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_DESC`. | +| <a id="sortupdated_asc"></a>`updated_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_ASC`. | +| <a id="sortupdated_desc"></a>`updated_desc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `UPDATED_DESC`. | ### `TestCaseStatus` @@ -14618,7 +14937,6 @@ Name of the feature that the callout is for. | ----- | ----------- | | <a id="usercalloutfeaturenameenumaccount_recovery_regular_check"></a>`ACCOUNT_RECOVERY_REGULAR_CHECK` | Callout feature name for account_recovery_regular_check. | | <a id="usercalloutfeaturenameenumactive_user_count_threshold"></a>`ACTIVE_USER_COUNT_THRESHOLD` | Callout feature name for active_user_count_threshold. | -| <a id="usercalloutfeaturenameenumadmin_integrations_moved"></a>`ADMIN_INTEGRATIONS_MOVED` | Callout feature name for admin_integrations_moved. | | <a id="usercalloutfeaturenameenumbuy_pipeline_minutes_notification_dot"></a>`BUY_PIPELINE_MINUTES_NOTIFICATION_DOT` | Callout feature name for buy_pipeline_minutes_notification_dot. | | <a id="usercalloutfeaturenameenumcanary_deployment"></a>`CANARY_DEPLOYMENT` | Callout feature name for canary_deployment. | | <a id="usercalloutfeaturenameenumcluster_security_warning"></a>`CLUSTER_SECURITY_WARNING` | Callout feature name for cluster_security_warning. | @@ -14635,6 +14953,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumpipeline_needs_banner"></a>`PIPELINE_NEEDS_BANNER` | Callout feature name for pipeline_needs_banner. | | <a id="usercalloutfeaturenameenumpipeline_needs_hover_tip"></a>`PIPELINE_NEEDS_HOVER_TIP` | Callout feature name for pipeline_needs_hover_tip. | | <a id="usercalloutfeaturenameenumregistration_enabled_callout"></a>`REGISTRATION_ENABLED_CALLOUT` | Callout feature name for registration_enabled_callout. | +| <a id="usercalloutfeaturenameenumsecurity_configuration_upgrade_banner"></a>`SECURITY_CONFIGURATION_UPGRADE_BANNER` | Callout feature name for security_configuration_upgrade_banner. | | <a id="usercalloutfeaturenameenumservice_templates_deprecated_callout"></a>`SERVICE_TEMPLATES_DEPRECATED_CALLOUT` | Callout feature name for service_templates_deprecated_callout. | | <a id="usercalloutfeaturenameenumsuggest_pipeline"></a>`SUGGEST_PIPELINE` | Callout feature name for suggest_pipeline. | | <a id="usercalloutfeaturenameenumsuggest_popover_dismissed"></a>`SUGGEST_POPOVER_DISMISSED` | Callout feature name for suggest_popover_dismissed. | @@ -14642,7 +14961,6 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumthreat_monitoring_info"></a>`THREAT_MONITORING_INFO` | Callout feature name for threat_monitoring_info. | | <a id="usercalloutfeaturenameenumultimate_trial"></a>`ULTIMATE_TRIAL` | Callout feature name for ultimate_trial. | | <a id="usercalloutfeaturenameenumunfinished_tag_cleanup_callout"></a>`UNFINISHED_TAG_CLEANUP_CALLOUT` | Callout feature name for unfinished_tag_cleanup_callout. | -| <a id="usercalloutfeaturenameenumwebhooks_moved"></a>`WEBHOOKS_MOVED` | Callout feature name for webhooks_moved. | | <a id="usercalloutfeaturenameenumweb_ide_alert_dismissed"></a>`WEB_IDE_ALERT_DISMISSED` | Callout feature name for web_ide_alert_dismissed. | | <a id="usercalloutfeaturenameenumweb_ide_ci_environments_guidance"></a>`WEB_IDE_CI_ENVIRONMENTS_GUIDANCE` | Callout feature name for web_ide_ci_environments_guidance. | @@ -14668,9 +14986,9 @@ Possible states of a user. | Value | Description | | ----- | ----------- | -| <a id="visibilityscopesenuminternal"></a>`internal` | | -| <a id="visibilityscopesenumprivate"></a>`private` | | -| <a id="visibilityscopesenumpublic"></a>`public` | | +| <a id="visibilityscopesenuminternal"></a>`internal` | The snippet is visible for any logged in user except external users. | +| <a id="visibilityscopesenumprivate"></a>`private` | The snippet is visible only to the snippet creator. | +| <a id="visibilityscopesenumpublic"></a>`public` | The snippet can be accessed without any authentication. | ### `VulnerabilityDismissalReason` @@ -14802,11 +15120,11 @@ A `AlertManagementHttpIntegrationID` is a global ID. It is encoded as a string. An example `AlertManagementHttpIntegrationID` is: `"gid://gitlab/AlertManagement::HttpIntegration/1"`. -### `AnalyticsDevopsAdoptionSegmentID` +### `AnalyticsDevopsAdoptionEnabledNamespaceID` -A `AnalyticsDevopsAdoptionSegmentID` is a global ID. It is encoded as a string. +A `AnalyticsDevopsAdoptionEnabledNamespaceID` is a global ID. It is encoded as a string. -An example `AnalyticsDevopsAdoptionSegmentID` is: `"gid://gitlab/Analytics::DevopsAdoption::Segment/1"`. +An example `AnalyticsDevopsAdoptionEnabledNamespaceID` is: `"gid://gitlab/Analytics::DevopsAdoption::EnabledNamespace/1"`. ### `AwardableID` @@ -15015,6 +15333,18 @@ Represents a unique identifier that is Base64 obfuscated. It is often used to re An ISO 8601-encoded date. +### `IncidentManagementEscalationPolicyID` + +A `IncidentManagementEscalationPolicyID` is a global ID. It is encoded as a string. + +An example `IncidentManagementEscalationPolicyID` is: `"gid://gitlab/IncidentManagement::EscalationPolicy/1"`. + +### `IncidentManagementEscalationRuleID` + +A `IncidentManagementEscalationRuleID` is a global ID. It is encoded as a string. + +An example `IncidentManagementEscalationRuleID` is: `"gid://gitlab/IncidentManagement::EscalationRule/1"`. + ### `IncidentManagementOncallParticipantID` A `IncidentManagementOncallParticipantID` is a global ID. It is encoded as a string. @@ -15048,6 +15378,7 @@ An example `IssueID` is: `"gid://gitlab/Issue/1"`. A `IterationID` is a global ID. It is encoded as a string. An example `IterationID` is: `"gid://gitlab/Iteration/1"`. +The older format `"gid://gitlab/EEIteration/1"` was deprecated in 13.3. ### `IterationsCadenceID` @@ -15153,6 +15484,12 @@ A `PackagesPackageID` is a global ID. It is encoded as a string. An example `PackagesPackageID` is: `"gid://gitlab/Packages::Package/1"`. +### `PackagesPypiMetadatumID` + +A `PackagesPypiMetadatumID` is a global ID. It is encoded as a string. + +An example `PackagesPypiMetadatumID` is: `"gid://gitlab/Packages::Pypi::Metadatum/1"`. + ### `PathLockID` A `PathLockID` is a global ID. It is encoded as a string. @@ -15284,6 +15621,7 @@ One of: - [`ConanMetadata`](#conanmetadata) - [`MavenMetadata`](#mavenmetadata) - [`NugetMetadata`](#nugetmetadata) +- [`PypiMetadata`](#pypimetadata) #### `VulnerabilityDetail` @@ -15439,7 +15777,7 @@ Implementations: | <a id="memberinterfaceexpiresat"></a>`expiresAt` | [`Time`](#time) | Date and time the membership expires. | | <a id="memberinterfaceid"></a>`id` | [`ID!`](#id) | ID of the member. | | <a id="memberinterfaceupdatedat"></a>`updatedAt` | [`Time`](#time) | Date and time the membership was last updated. | -| <a id="memberinterfaceuser"></a>`user` | [`UserCore!`](#usercore) | User that is associated with the member object. | +| <a id="memberinterfaceuser"></a>`user` | [`UserCore`](#usercore) | User that is associated with the member object. | #### `Noteable` @@ -15843,6 +16181,18 @@ A node of an epic tree. | <a id="epictreenodefieldsinputtypenewparentid"></a>`newParentId` | [`EpicID`](#epicid) | ID of the new parent epic. | | <a id="epictreenodefieldsinputtyperelativeposition"></a>`relativePosition` | [`MoveType`](#movetype) | The type of the switch, after or before allowed. | +### `EscalationRuleInput` + +Represents an escalation rule. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="escalationruleinputelapsedtimeseconds"></a>`elapsedTimeSeconds` | [`Int!`](#int) | The time in seconds before the rule is activated. | +| <a id="escalationruleinputoncallscheduleiid"></a>`oncallScheduleIid` | [`ID!`](#id) | The on-call schedule to notify. | +| <a id="escalationruleinputstatus"></a>`status` | [`EscalationRuleStatus!`](#escalationrulestatus) | The status required to prevent the rule from activating. | + ### `JiraUsersMappingInputType` #### Arguments @@ -15890,6 +16240,16 @@ A node of an epic tree. | <a id="negatedepicboardissueinputlabelname"></a>`labelName` | [`[String]`](#string) | Filter by label name. | | <a id="negatedepicboardissueinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +### `NegatedEpicFilterInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="negatedepicfilterinputauthorusername"></a>`authorUsername` | [`String`](#string) | Filter by author username. | +| <a id="negatedepicfilterinputlabelname"></a>`labelName` | [`[String]`](#string) | Filter by label name. | +| <a id="negatedepicfilterinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | + ### `NegatedIssueFilterInput` #### Arguments diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index a76f1fb7418..d8fc6cb35f8 100644 --- a/doc/api/graphql/removed_items.md +++ b/doc/api/graphql/removed_items.md @@ -10,6 +10,32 @@ GraphQL is a versionless API, unlike the REST API. Occasionally, items have to be updated or removed from the GraphQL API. According to our [process for removing items](index.md#deprecation-and-removal-process), here are the items that have been removed. +## GitLab 14.0 + +Fields removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63293): + +### GraphQL Mutations + +| Argument name | Mutation | Deprecated in | Use instead | +| -------------------- | -------------------- | ------------- | -------------------------- | +| `updated_ids` | `todosMarkAllDone` | 13.2 | `todos` | +| `updated_ids` | `todoRestoreMany` | 13.2 | `todos` | +| `global_id` | `dastScannerProfileCreate`| 13.6 | `todos` | +| - | `addAwardEmoji` | 13.2 | `awardEmojiAdd` | +| - | `removeAwardEmoji` | 13.2 | `awardEmojiRemove` | +| - | `toggleAwardEmoji` | 13.2 | `ToggleAwardEmoji` | +| - | `runDastScan` | 13.5 | `dastOnDemandScanCreate` | +| - | `dismissVulnerability` | 13.5 | `vulnerabilityDismiss` | +| - | `revertVulnerabilityToDetected` | 13.5 | `vulnerabilityRevertToDetected` | + +### GraphQL Types + +| Field name | GraphQL type | Deprecated in | Use instead | +| -------------------- | -------------------- | ------------- | -------------------------- | +| `blob` | `SnippetType` | 13.3 | `blobs` | +| `global_id` | `DastScannerProfileType` | 13.6 | `blobs` | +| `vulnerabilities_count_by_day_and_severity` | `GroupType`, `QueryType` | 13.3 | None. Plaintext tokens no longer supported for security reasons. | + ## GitLab 13.6 Fields removed in [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44866): diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 848d5735096..63ba71797fc 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -102,7 +102,9 @@ POST /groups/:id/badges | `image_url` | string | yes | URL of the badge image | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&position=0" "https://gitlab.example.com/api/v4/groups/:id/badges" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&position=0" \ + "https://gitlab.example.com/api/v4/groups/:id/badges" ``` Example response: @@ -134,7 +136,8 @@ PUT /groups/:id/badges/:badge_id | `image_url` | string | no | URL of the badge image | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id" ``` Example response: diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index ea7c13637c4..6853e38cc32 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -13,7 +13,7 @@ Similarly to [project-level](../user/project/clusters/index.md) and group-level Kubernetes clusters allow you to connect a Kubernetes cluster to your group, enabling you to use the same cluster across multiple projects. -Users need at least [Maintainer](../user/permissions.md) access for the group to use these endpoints. +Users need at least the [Maintainer role](../user/permissions.md) for the group to use these endpoints. ## List group clusters diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 79338df4f7a..d2bcac6332a 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -57,7 +57,8 @@ GET /groups/:id/export/download | `id` | integer/string | yes | ID of the group owned by the authenticated user | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name --remote-name "https://gitlab.example.com/api/v4/groups/1/export/download" +curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ + --remote-name "https://gitlab.example.com/api/v4/groups/1/export/download" ``` ```shell @@ -90,7 +91,9 @@ The `file=` parameter must point to a file on your file system and be preceded by `@`. For example: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "name=imported-group" --form "path=imported-group" --form "file=@/path/to/file" "https://gitlab.example.com/api/v4/groups/import" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "name=imported-group" --form "path=imported-group" \ + --form "file=@/path/to/file" "https://gitlab.example.com/api/v4/groups/import" ``` NOTE: diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 65c28e80f0a..2aca98259e0 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -118,7 +118,9 @@ POST /groups/:id/labels | `description` | string | no | The description of the label, | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "Feature Proposal", "color": "#FFA500", "description": "Describes new ideas" }' "https://gitlab.example.com/api/v4/groups/5/labels" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + --data '{"name": "Feature Proposal", "color": "#FFA500", "description": "Describes new ideas" }' \ + "https://gitlab.example.com/api/v4/groups/5/labels" ``` Example response: @@ -155,7 +157,8 @@ PUT /groups/:id/labels/:label_id | `description` | string | no | The description of the label. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"new_name": "Feature Idea" }' "https://gitlab.example.com/api/v4/groups/5/labels/Feature%20Proposal" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + --data '{"new_name": "Feature Idea" }' "https://gitlab.example.com/api/v4/groups/5/labels/Feature%20Proposal" ``` Example response: diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index b548372b02d..6425e022170 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -92,7 +92,8 @@ POST /groups/:id/variables | `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" ``` ```json @@ -125,7 +126,8 @@ PUT /groups/:id/variables/:key | `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/variables/README.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/NEW_VARIABLE" --form "value=updated value" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/1/variables/NEW_VARIABLE" --form "value=updated value" ``` ```json @@ -153,5 +155,6 @@ DELETE /groups/:id/variables/:key | `key` | string | yes | The `key` of a variable | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1" ``` diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md new file mode 100644 index 00000000000..d4e27a7200a --- /dev/null +++ b/doc/api/group_protected_environments.md @@ -0,0 +1,154 @@ +--- +stage: Release +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: concepts, howto +--- + +# Group-level protected environments API **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in [GitLab Premium](https://about.gitlab.com/pricing/) 14.0. +> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../ci/environments/protected_environments.md#enable-or-disable-group-level-protected-environments). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../user/feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments), + +## Valid access levels + +The access levels are defined in the `ProtectedEnvironment::DeployAccessLevel::ALLOWED_ACCESS_LEVELS` method. +Currently, these levels are recognized: + +```plaintext +30 => Developer access +40 => Maintainer access +60 => Admin access +``` + +## List group-level protected environments + +Gets a list of protected environments from a group. + +```shell +GET /groups/:id/protected_environments +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/" +``` + +Example response: + +```json +[ + { + "name":"production", + "deploy_access_levels":[ + { + "access_level":40, + "access_level_description":"Maintainers", + "user_id":null, + "group_id":null + } + ] + } +] +``` + +## Get a single protected environment + +Gets a single protected environment. + +```shell +GET /groups/:id/protected_environments/:name +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. | +| `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/production" +``` + +Example response: + +```json +{ + "name":"production", + "deploy_access_levels":[ + { + "access_level":40, + "access_level_description":"Maintainers", + "user_id":null, + "group_id":null + } + ] +} +``` + +## Protect an environment + +Protects a single environment. + +```shell +POST /groups/:id/protected_environments +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. | +| `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| +| `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. | + +The assignable `user_id` are the users who belong to the given group with the Maintainer role (or above). +The assignable `group_id` are the sub-groups under the given group. + +```shell +curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_environments" +``` + +Example response: + +```json +{ + "name":"production", + "deploy_access_levels":[ + { + "access_level":40, + "access_level_description":"protected-access-group", + "user_id":null, + "group_id":9899826 + } + ] +} +``` + +## Unprotect environment + +Unprotects the given protected environment. + +```shell +DELETE /groups/:id/protected_environments/:name +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) maintained by the authenticated user. | +| `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/staging" +``` + +The response should return a 200 code. diff --git a/doc/api/group_relations_export.md b/doc/api/group_relations_export.md index bb19f7f0923..2f9c1e381df 100644 --- a/doc/api/group_relations_export.md +++ b/doc/api/group_relations_export.md @@ -48,7 +48,8 @@ GET /groups/:id/export_relations/status | `id` | integer/string | yes | ID of the group owned by the authenticated user. | ```shell -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/export_relations/status" +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/1/export_relations/status" ``` The status can be one of the following: @@ -92,7 +93,8 @@ GET /groups/:id/export_relations/download | `relation` | string | yes | Name of the group top-level relation to download. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name --remote-name "https://gitlab.example.com/api/v4/groups/1/export_relations/download?relation=labels" +curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ + --remote-name "https://gitlab.example.com/api/v4/groups/1/export_relations/download?relation=labels" ``` ```shell diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index 0388bf46a1b..2373fa25e15 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -202,8 +202,10 @@ Supported attributes: Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ ---data '{"destination_storage_name":"storage2"}' "https://gitlab.example.com/api/v4/groups/1/repository_storage_moves" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ + --data '{"destination_storage_name":"storage2"}' \ + "https://gitlab.example.com/api/v4/groups/1/repository_storage_moves" ``` Example response: @@ -241,8 +243,10 @@ Supported attributes: Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ ---data '{"source_storage_name":"default"}' "https://gitlab.example.com/api/v4/group_repository_storage_moves" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ + --data '{"source_storage_name":"default"}' \ + "https://gitlab.example.com/api/v4/group_repository_storage_moves" ``` Example response: diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index f0c38d4d4b9..58192425786 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -64,7 +64,7 @@ GET /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `slug` | string | yes | The slug (a unique string) of the wiki page | +| `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/wikis/home" @@ -127,7 +127,7 @@ PUT /groups/:id/wikis/:slug | `content` | string | yes if `title` is not provided | The content of the wiki page | | `title` | string | yes if `content` is not provided | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | -| `slug` | string | yes | The slug (a unique identifier) of the wiki page | +| `slug` | string | yes | URL encoded slug (a unique string) of the wiki page. Ex. dir%2Fpage_name | ```shell curl --request PUT --data "format=rdoc&content=documentation&title=Docs" \ @@ -157,7 +157,7 @@ DELETE /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `slug` | string | yes | The slug (a unique identifier) of the wiki page | +| `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/wikis/foo" @@ -186,7 +186,8 @@ The `file=` parameter must point to a file on your file system and be preceded by `@`. For example: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "file=@dk.png" "https://gitlab.example.com/api/v4/groups/1/wikis/attachments" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "file=@dk.png" "https://gitlab.example.com/api/v4/groups/1/wikis/attachments" ``` Example response: diff --git a/doc/api/groups.md b/doc/api/groups.md index 6bec6e0f6f8..de2c6c95bcd 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -302,7 +302,8 @@ Example response: "id": 9, "description": "foo", "default_branch": "master", - "tag_list": [], + "tag_list": [], //deprecated, use `topics` instead + "topics": [], "archived": false, "visibility": "internal", "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git", @@ -381,9 +382,8 @@ Example response: "path_with_namespace":"h5bp/html5-boilerplate", "created_at":"2020-04-27T06:13:22.642Z", "default_branch":"master", - "tag_list":[ - - ], + "tag_list":[], //deprecated, use `topics` instead + "topics":[], "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git", "http_url_to_repo":"http://gitlab.com/h5bp/html5-boilerplate.git", "web_url":"http://gitlab.com/h5bp/html5-boilerplate", @@ -540,7 +540,8 @@ Example response: "id": 7, "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.", "default_branch": "master", - "tag_list": [], + "tag_list": [], //deprecated, use `topics` instead + "topics": [], "archived": false, "visibility": "public", "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git", @@ -578,7 +579,8 @@ Example response: "id": 6, "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.", "default_branch": "master", - "tag_list": [], + "tag_list": [], //deprecated, use `topics` instead + "topics": [], "archived": false, "visibility": "internal", "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git", @@ -618,7 +620,8 @@ Example response: "id": 8, "description": "Velit eveniet provident fugiat saepe eligendi autem.", "default_branch": "master", - "tag_list": [], + "tag_list": [], //deprecated, use `topics` instead + "topics": [], "archived": false, "visibility": "private", "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git", @@ -722,6 +725,28 @@ Example response: } ``` +### Download a Group avatar + +Get a group avatar. This endpoint can be accessed without authentication if the +group is publicly accessible. + +```plaintext +GET /groups/:id/avatar +``` + +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | --------------------- | +| `id` | integer/string | yes | ID of the group | + +Example: + +```shell +curl --header "PRIVATE-TOKEN: $GITLAB_LOCAL_TOKEN" \ + --remote-header-name \ + --remote-name \ + "https://gitlab.example.com/api/v4/groups/4/avatar" +``` + ### Disable the results limit **(FREE SELF)** The 100 results limit can break integrations developed using GitLab 12.4 and earlier. @@ -752,7 +777,7 @@ Parameters: | `name` | string | yes | The name of the group. | | `path` | string | yes | The path of the group. | | `description` | string | no | The group's description. | -| `membership_lock` | boolean | no | **(STARTER)** Prevent adding new members to project membership within this group. | +| `membership_lock` | boolean | no | **(PREMIUM)** Prevent adding new members to project membership within this group. | | `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | | `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | | `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | @@ -770,6 +795,10 @@ Parameters: | `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | | `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +NOTE: +On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot +use the API to do this. + ### Options for `default_branch_protection` The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table: @@ -788,9 +817,10 @@ This is similar to creating a [New group](#new-group). You need the `parent_id` - `subgroup_name` ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ - --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \ - "https://gitlab.example.com/api/v4/groups/" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ + --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \ + "https://gitlab.example.com/api/v4/groups/" ``` ## Transfer project to group @@ -809,7 +839,8 @@ Parameters: | `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/projects/56" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/4/projects/56" ``` ## Update group @@ -826,7 +857,7 @@ 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 | **(PREMIUM)** 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`. | | `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | @@ -851,7 +882,8 @@ The `projects` and `shared_projects` attributes in the response are deprecated a To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/5?name=Experimental" ``` This endpoint returns: @@ -883,7 +915,8 @@ Example response: "id": 9, "description": "foo", "default_branch": "master", - "tag_list": [], + "tag_list": [], //deprecated, use `topics` instead + "topics": [], "public": false, "archived": false, "visibility": "internal", @@ -956,7 +989,8 @@ curl to post data using the header `Content-Type: multipart/form-data`. The `@`. For example: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22" --form "avatar=@/tmp/example.png" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22" \ + --form "avatar=@/tmp/example.png" ``` ## Remove group @@ -1142,7 +1176,7 @@ DELETE /groups/:id/hooks/:hook_id | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the group hook. | -## Group Audit Events **(STARTER)** +## Group Audit Events **(PREMIUM)** Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events) @@ -1298,11 +1332,11 @@ DELETE /groups/:id/share/:group_id | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | -## Push Rules **(STARTER)** +## Push Rules **(PREMIUM)** -> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. +> Introduced in [GitLab](https://about.gitlab.com/pricing/) 13.4. -### Get group push rules **(STARTER)** +### Get group push rules **(PREMIUM)** Get the [push rules](../user/group/index.md#group-push-rules) of a group. @@ -1345,7 +1379,7 @@ the `commit_committer_check` and `reject_unsigned_commits` parameters: } ``` -### Add group push rule **(STARTER)** +### Add group push rule **(PREMIUM)** Adds [push rules](../user/group/index.md#group-push-rules) to the specified group. @@ -1358,17 +1392,17 @@ POST /groups/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | -| `member_check` **(STARTER)** | boolean | no | Allows only GitLab users to author commits | -| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | -| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | -| `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | -| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | -| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails are allowed | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG are allowed | +| `deny_delete_tag` | boolean | no | Deny deleting a tag | +| `member_check` | boolean | no | Allows only GitLab users to author commits | +| `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | +| `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | +| `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | +| `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | +| `author_email_regex` | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | +| `file_name_regex` | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | +| `max_file_size` | integer | no | Maximum file size (MB) allowed | +| `commit_committer_check` | boolean | no | Only commits pushed using verified emails are allowed | +| `reject_unsigned_commits` | boolean | no | Only commits signed through GPG are allowed | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" @@ -1392,7 +1426,7 @@ Response: } ``` -### Edit group push rule **(STARTER)** +### Edit group push rule **(PREMIUM)** Edit push rules for a specified group. @@ -1405,17 +1439,17 @@ PUT /groups/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) | -| `deny_delete_tag` **(STARTER)** | boolean | no | Deny deleting a tag | -| `member_check` **(STARTER)** | boolean | no | Restricts commits to be authored by existing GitLab users only | -| `prevent_secrets` **(STARTER)** | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | -| `commit_message_regex` **(STARTER)** | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | -| `commit_message_negative_regex` **(STARTER)** | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | -| `branch_name_regex` **(STARTER)** | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | -| `author_email_regex` **(STARTER)** | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | -| `file_name_regex` **(STARTER)** | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | -| `max_file_size` **(STARTER)** | integer | no | Maximum file size (MB) allowed | -| `commit_committer_check` **(PREMIUM)** | boolean | no | Only commits pushed using verified emails are allowed | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | no | Only commits signed through GPG are allowed | +| `deny_delete_tag` | boolean | no | Deny deleting a tag | +| `member_check` | boolean | no | Restricts commits to be authored by existing GitLab users only | +| `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | +| `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, e.g. `Fixed \d+\..*` | +| `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, e.g. `ssh\:\/\/` | +| `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, e.g. `(feature|hotfix)\/*` | +| `author_email_regex` | string | no | All commit author emails must match the regular expression provided in this attribute, e.g. `@my-company.com$` | +| `file_name_regex` | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, e.g. `(jar|exe)$` | +| `max_file_size` | integer | no | Maximum file size (MB) allowed | +| `commit_committer_check` | boolean | no | Only commits pushed using verified emails are allowed | +| `reject_unsigned_commits` | boolean | no | Only commits signed through GPG are allowed | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" @@ -1439,7 +1473,7 @@ Response: } ``` -### Delete group push rule **(STARTER)** +### Delete group push rule **(PREMIUM)** Deletes the [push rules](../user/group/index.md#group-push-rules) of a group. diff --git a/doc/api/instance_level_ci_variables.md b/doc/api/instance_level_ci_variables.md index 58e69e22a15..de6fd958aa6 100644 --- a/doc/api/instance_level_ci_variables.md +++ b/doc/api/instance_level_ci_variables.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -85,7 +85,8 @@ POST /admin/ci/variables | `masked` | boolean | no | Whether the variable is masked. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/admin/ci/variables" --form "key=NEW_VARIABLE" --form "value=new value" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/admin/ci/variables" --form "key=NEW_VARIABLE" --form "value=new value" ``` ```json @@ -115,7 +116,8 @@ PUT /admin/ci/variables/:key | `masked` | boolean | no | Whether the variable is masked. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/admin/ci/variables/NEW_VARIABLE" --form "value=updated value" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/admin/ci/variables/NEW_VARIABLE" --form "value=updated value" ``` ```json diff --git a/doc/api/invitations.md b/doc/api/invitations.md index fbdecd0e3fa..36ff2d5bda4 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -4,7 +4,7 @@ group: Expansion info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Invitations API +# Invitations API **(FREE)** Use the Invitations API to send email to users you want to join a group or project, and to list pending invitations. @@ -41,10 +41,13 @@ POST /projects/:id/invitations | `email` | string | yes | The email of the new member or multiple emails separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | +| `invite_source` | string | no | The source of the invitation that starts the member creation process. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327120). | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "email=test@example.com&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations" -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "email=test@example.com&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --data "email=test@example.com&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --data "email=test@example.com&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations" ``` Example responses: diff --git a/doc/api/issues.md b/doc/api/issues.md index acfca50cb5e..f321c00e7f2 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -65,7 +65,6 @@ GET /issues?state=opened | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `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](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | @@ -996,7 +995,7 @@ POST /projects/:id/issues | `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | | `labels` | string | no | Comma-separated label names for an issue | | `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these values take precedence over the default values.| -| `milestone_id` | integer | no | The global ID of a milestone to assign issue | +| `milestone_id` | integer | no | The global ID of a milestone to assign issue. To find the `milestone_id` associated with a milestone, view an issue with the milestone assigned and [use the API](#single-project-issue) to retrieve the issue's details. | | `title` | string | yes | The title of an issue | | `weight` **(PREMIUM)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | @@ -2081,6 +2080,7 @@ Example response: "source_project_id": 1, "target_project_id": 1, "labels": [], + "draft": false, "work_in_progress": false, "milestone": { "id": 27, @@ -2232,6 +2232,7 @@ Example response: "closed_at": null, "closed_by": null, "labels": [], + "draft": false, "work_in_progress": false, "milestone": null, "merge_when_pipeline_succeeds": false, diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 0dbb35a62cd..54404559577 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Testing info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -90,7 +90,7 @@ Parameters Example request using the `PRIVATE-TOKEN` header: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test" ``` To use this in a [`script` definition](../ci/yaml/README.md#script) inside @@ -98,25 +98,25 @@ To use this in a [`script` definition](../ci/yaml/README.md#script) inside - The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. For example, the following job downloads the artifacts of the `test` job - of the `master` branch. Note that the command is wrapped into single quotes + of the `main` branch. Note that the command is wrapped into single quotes because it contains a colon (`:`): ```yaml artifact_download: stage: test script: - - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test"' + - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test"' ``` - Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. For example, the following job downloads the artifacts of the `test` job - of the `master` branch: + of the `main` branch: ```yaml artifact_download: stage: test script: - - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN"' + - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"' ``` Possible response status codes: @@ -193,7 +193,7 @@ Parameters: Example request: ```shell -curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/raw/some/release/file.pdf?job=pdf" +curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/raw/some/release/file.pdf?job=pdf" ``` Possible response status codes: @@ -243,7 +243,7 @@ Example response: "download_url": null, "id": 42, "name": "rubocop", - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 6647b53bcb4..b92f2a72c03 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -1,10 +1,10 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Jobs API +# Jobs API **(FREE)** ## List project jobs @@ -63,11 +63,11 @@ Example of response "pipeline": { "id": 6, "project_id": 1, - "ref": "master", + "ref": "main", "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", "status": "pending" }, - "ref": "master", + "ref": "main", "runner": null, "stage": "test", "status": "failed", @@ -117,11 +117,11 @@ Example of response "pipeline": { "id": 6, "project_id": 1, - "ref": "master", + "ref": "main", "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", "status": "pending" }, - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", @@ -198,11 +198,11 @@ Example of response "pipeline": { "id": 6, "project_id": 1, - "ref": "master", + "ref": "main", "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", "status": "pending" }, - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", @@ -263,11 +263,11 @@ Example of response "pipeline": { "id": 6, "project_id": 1, - "ref": "master", + "ref": "main", "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", "status": "pending" }, - "ref": "master", + "ref": "main", "runner": null, "stage": "test", "status": "failed", @@ -348,14 +348,14 @@ Example of response "pipeline": { "id": 6, "project_id": 1, - "ref": "master", + "ref": "main", "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", "status": "pending", "created_at": "2015-12-24T15:50:16.123Z", "updated_at": "2015-12-24T18:00:44.432Z", "web_url": "https://example.com/foo/bar/pipelines/6" }, - "ref": "master", + "ref": "main", "stage": "test", "status": "pending", "tag": false, @@ -380,7 +380,7 @@ Example of response "downstream_pipeline": { "id": 5, "sha": "f62a4b2fb89754372a346f24659212eb8da13601", - "ref": "master", + "ref": "main", "status": "pending", "created_at": "2015-12-24T17:54:27.722Z", "updated_at": "2015-12-24T17:58:27.896Z", @@ -433,11 +433,11 @@ Example of response "pipeline": { "id": 6, "project_id": 1, - "ref": "master", + "ref": "main", "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", "status": "pending" }, - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", @@ -518,7 +518,7 @@ Example response: "id": 1, "project_id": 1, "sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0", - "ref": "master", + "ref": "main", "status": "pending", "created_at": "2021-03-26T14:51:51.107Z", "updated_at": "2021-03-26T14:51:51.107Z", @@ -590,11 +590,11 @@ Example of response "pipeline": { "id": 6, "project_id": 1, - "ref": "master", + "ref": "main", "sha": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", "status": "pending" }, - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", @@ -684,7 +684,7 @@ Example of response "queued_duration": 0.010, "id": 42, "name": "rubocop", - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", @@ -734,7 +734,7 @@ Example of response "queued_duration": 0.010, "id": 42, "name": "rubocop", - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", @@ -784,7 +784,7 @@ Example of response "download_url": null, "id": 42, "name": "rubocop", - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", @@ -839,7 +839,7 @@ Example of response "queued_duration": 0.010, "id": 42, "name": "rubocop", - "ref": "master", + "ref": "main", "artifacts": [], "runner": null, "stage": "test", diff --git a/doc/api/labels.md b/doc/api/labels.md index a9f2698a270..5abab7a79c4 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -46,8 +46,7 @@ Example response: "open_merge_requests_count": 1, "subscribed": false, "priority": 10, - "is_project_label": true, - "remove_on_close": false + "is_project_label": true }, { "id" : 4, @@ -61,8 +60,7 @@ Example response: "open_merge_requests_count": 0, "subscribed": false, "priority": null, - "is_project_label": true, - "remove_on_close": false + "is_project_label": true }, { "id" : 7, @@ -76,8 +74,7 @@ Example response: "open_merge_requests_count": 1, "subscribed": false, "priority": null, - "is_project_label": true, - "remove_on_close": true + "is_project_label": true }, { "id" : 8, @@ -91,8 +88,7 @@ Example response: "open_merge_requests_count": 2, "subscribed": false, "priority": null, - "is_project_label": false, - "remove_on_close": false + "is_project_label": false }, { "id" : 9, @@ -106,8 +102,7 @@ Example response: "open_merge_requests_count": 1, "subscribed": true, "priority": null, - "is_project_label": true, - "remove_on_close": false + "is_project_label": true } ] ``` @@ -145,8 +140,7 @@ Example response: "open_merge_requests_count": 1, "subscribed": false, "priority": 10, - "is_project_label": true, - "remove_on_close": true + "is_project_label": true } ``` @@ -165,7 +159,6 @@ POST /projects/:id/labels | `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label | | `priority` | integer | no | The priority of the label. Must be greater or equal than zero or `null` to remove the priority. | -| `remove_on_close` | boolean | no | Whether the label should be removed from an issue when the issue is closed. _([Introduced in GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/17461))_ | ```shell curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels" @@ -186,8 +179,7 @@ Example response: "open_merge_requests_count": 0, "subscribed": false, "priority": null, - "is_project_label": true, - "remove_on_close": true + "is_project_label": true } ``` @@ -228,10 +220,10 @@ PUT /projects/:id/labels/:label_id | `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The new description of the label | | `priority` | integer | no | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. | -| `remove_on_close` | boolean | no | Boolean option specifying whether the label should be removed from issues when they are closed. | ```shell -curl --request PUT --data "new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation" +curl --request PUT --data "new_name=docs&color=#8E44AD&description=Documentation" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation" ``` Example response: @@ -249,8 +241,7 @@ Example response: "open_merge_requests_count": 2, "subscribed": false, "priority": null, - "is_project_label": true, - "remove_on_close": true + "is_project_label": true } ``` @@ -291,8 +282,7 @@ Example response: "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, - "subscribed": false, - "remove_on_close": true + "subscribed": false } ``` @@ -333,8 +323,7 @@ Example response: "open_merge_requests_count": 1, "subscribed": true, "priority": null, - "is_project_label": true, - "remove_on_close": true + "is_project_label": true } ``` diff --git a/doc/api/lint.md b/doc/api/lint.md index 867a5e54663..57d11d15adc 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -1,19 +1,26 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CI Lint API +# CI Lint API **(FREE)** ## Validate the CI YAML configuration -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5953) in GitLab 8.12. - Checks if CI/CD YAML configuration is valid. This endpoint validates basic CI/CD configuration syntax. It doesn't have any namespace specific context. -Access to this endpoint requires authentication. +Access to this endpoint does not require authentication when the instance +[allows new sign ups](../user/admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups) +and: + +- Does not have an [allowlist or denylist](../user/admin_area/settings/sign_up_restrictions.md#allow-or-deny-sign-ups-using-specific-email-domains). +- Does not [require administrator approval for new sign ups](../user/admin_area/settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups). +- Does not have additional [sign up + restrictions](../user/admin_area/settings/sign_up_restrictions.html#sign-up-restrictions). + +Otherwise, authentication is required. ```plaintext POST /ci/lint @@ -111,7 +118,7 @@ Example response: { "status": "valid", "errors": [], - "merged_config": "---\n:another_test:\n :stage: test\n :script: echo 2\n:test:\n :stage: test\n :script: echo 1\n" + "merged_yaml": "---\n:another_test:\n :stage: test\n :script: echo 2\n:test:\n :stage: test\n :script: echo 1\n" } ``` diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index 68a19b9912f..4be4f83b4ce 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -128,7 +128,8 @@ PATCH /projects/:id/managed_licenses/:managed_license_id | `approval_status` | string | yes | The approval status. "approved" or "blacklisted" | ```shell -curl --request PATCH --data "approval_status=blacklisted" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses/6" +curl --request PATCH --data "approval_status=blacklisted" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses/6" ``` Example response: diff --git a/doc/api/members.md b/doc/api/members.md index 2a70e35b287..627c9a12b5e 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -415,10 +415,13 @@ POST /projects/:id/members | `user_id` | integer/string | yes | The user ID of the new member or multiple IDs separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | +| `invite_source` | string | no | The source of the invitation that starts the member creation process. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327120). | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "user_id=1&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/members" -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "user_id=1&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/members" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --data "user_id=1&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/members" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --data "user_id=1&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/members" ``` Example response: diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 978cbff625c..8947e5b382f 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -29,7 +29,7 @@ GET /projects/:id/approvals | Attribute | Type | Required | Description | | --------- | ------- | -------- | ------------------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | ```json { @@ -58,7 +58,7 @@ POST /projects/:id/approvals | Attribute | Type | Required | Description | | ------------------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `approvals_before_merge` | integer | no | How many approvals are required before an MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. | | `reset_approvals_on_push` | boolean | no | Reset approvals on a new push | | `disable_overriding_approvers_per_merge_request` | boolean | no | Allow/Disallow overriding approvers per MR | @@ -93,7 +93,7 @@ GET /projects/:id/approval_rules | Attribute | Type | Required | Description | |----------------------|---------|----------|-----------------------------------------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | ```json [ @@ -192,7 +192,7 @@ GET /projects/:id/approval_rules/:approval_rule_id | Attribute | Type | Required | Description | |----------------------|---------|----------|-----------------------------------------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `approval_rule_id` | integer | yes | The ID of a approval rule | ```json @@ -291,7 +291,7 @@ POST /projects/:id/approval_rules | Attribute | Type | Required | Description | |------------------------|---------|----------|------------------------------------------------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | | `user_ids` | Array | no | The ids of users as approvers | @@ -396,7 +396,7 @@ PUT /projects/:id/approval_rules/:approval_rule_id | Attribute | Type | Required | Description | |------------------------|---------|----------|------------------------------------------------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `approval_rule_id` | integer | yes | The ID of a approval rule | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | @@ -500,123 +500,9 @@ DELETE /projects/:id/approval_rules/:approval_rule_id | Attribute | Type | Required | Description | |----------------------|---------|----------|-----------------------------------------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `approval_rule_id` | integer | yes | The ID of a approval rule -## External Project-level MR approvals **(ULTIMATE)** - -Configuration for approvals on a specific Merge Request which makes a call to an external HTTP resource. - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 13.10. -> - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** - -### Get project external approval rules **(ULTIMATE)** - -You can request information about a project's external approval rules using the following endpoint: - -```plaintext -GET /projects/:id/external_approval_rules -``` - -**Parameters:** - -| Attribute | Type | Required | Description | -|---------------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | - -```json -[ - { - "id": 1, - "name": "Compliance Check", - "project_id": 6, - "external_url": "https://gitlab.com/example/test.json", - "protected_branches": [ - { - "id": 14, - "project_id": 6, - "name": "master", - "created_at": "2020-10-12T14:04:50.787Z", - "updated_at": "2020-10-12T14:04:50.787Z", - "code_owner_approval_required": false - } - ] - } -] -``` - -### Create external approval rule **(ULTIMATE)** - -You can create a new external approval rule for a project using the following endpoint: - -```plaintext -POST /projects/:id/external_approval_rules -``` - -| Attribute | Type | Required | Description | -|------------------------|----------------|----------|----------------------------------------------------| -| `id` | integer | yes | The ID of a project | -| `name` | string | yes | Display name of approval rule | -| `external_url` | string | yes | URL of external approval resource | -| `protected_branch_ids` | `array<Integer>` | no | The ids of protected branches to scope the rule by | - -### Delete external approval rule **(ULTIMATE)** - -You can delete an external approval rule for a project using the following endpoint: - -```plaintext -DELETE /projects/:id/external_approval_rules/:rule_id -``` - -| Attribute | Type | Required | Description | -|------------------------|----------------|----------|----------------------------------------------------| -| `rule_id` | integer | yes | The ID of an approval rule | -| `id` | integer | yes | The ID of a project | - -### Update external approval rule **(ULTIMATE)** - -You can update an existing external approval rule for a project using the following endpoint: - -```plaintext -PUT /projects/:id/external_approval_rules/:rule_id -``` - -| Attribute | Type | Required | Description | -|------------------------|----------------|----------|----------------------------------------------------| -| `id` | integer | yes | The ID of a project | -| `rule_id` | integer | yes | The ID of an external approval rule | -| `name` | string | no | Display name of approval rule | -| `external_url` | string | no | URL of external approval resource | -| `protected_branch_ids` | `array<Integer>` | no | The ids of protected branches to scope the rule by | - -### Enable or disable External Project-level MR approvals **(ULTIMATE SELF)** - -Enable or disable External Project-level MR approvals is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../user/feature_flags.md) -can enable it. - -To enable it: - -```ruby -# For the instance -Feature.enable(:ff_compliance_approval_gates) -# For a single project -Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:ff_compliance_approval_gates) -# For a single project -Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>)) -``` - ## Merge Request-level MR approvals Configuration for approvals on a specific Merge Request. Must be authenticated for all endpoints. @@ -637,7 +523,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | ```json @@ -684,7 +570,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals | Attribute | Type | Required | Description | |----------------------|---------|----------|--------------------------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | | `approvals_required` | integer | yes | Approvals required before MR can be merged. Deprecated in 12.0 in favor of Approval Rules API. | @@ -726,7 +612,7 @@ This includes additional information about the users who have already approved | Attribute | Type | Required | Description | |----------------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | ```json @@ -793,7 +679,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approval_rules | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | ```json @@ -871,7 +757,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approval_rules | Attribute | Type | Required | Description | |----------------------------|---------|----------|------------------------------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of MR | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | @@ -961,7 +847,7 @@ These are system generated rules. | Attribute | Type | Required | Description | |----------------------|---------|----------|------------------------------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The ID of MR | | `approval_rule_id` | integer | yes | The ID of a approval rule | | `name` | string | yes | The name of the approval rule | @@ -1045,9 +931,9 @@ These are system generated rules. | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------------| -| `id` | integer | yes | The ID of a project | -| `merge_request_iid` | integer | yes | The ID of MR | -| `approval_rule_id` | integer | yes | The ID of a approval rule | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `merge_request_iid` | integer | yes | The IID of the merge request | +| `approval_rule_id` | integer | yes | The ID of an approval rule | ## Approve Merge Request @@ -1065,9 +951,9 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------------------| -| `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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `merge_request_iid` | integer | yes | The IID of the merge request | +| `sha` | string | no | The `HEAD` of the merge request | | `approval_password` **(PREMIUM)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-authentication-for-approvals) is enabled in the project settings. | The `sha` parameter works in the same way as @@ -1129,5 +1015,5 @@ POST /projects/:id/merge_requests/:merge_request_iid/unapprove | Attribute | Type | Required | Description | |---------------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | -| `merge_request_iid` | integer | yes | The IID of MR | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding) | +| `merge_request_iid` | integer | yes | The IID of a merge request | diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index c4cb7753fc9..57754f62d5a 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -16,6 +16,7 @@ type: reference, api > - `with_merge_status_recheck` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. > - `reviewer_username` and `reviewer_id` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. > - `reviewer_ids` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51186) in GitLab 13.8. +> - `draft` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63473) as an eventual replacement for `work_in_progress` in GitLab 14.0 Every API call to merge requests must be authenticated. @@ -174,6 +175,7 @@ Parameters: "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -357,6 +359,7 @@ Parameters: "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -405,6 +408,16 @@ Parameters: ] ``` +The `merge_status` field may hold one of the following values: + +| Value | Interpretation | +|----------------------------|-----------------------------------------------------------------------| +| `unchecked` | We have not checked this yet | +| `checking` | We are currently checking if the merge request can be merged | +| `can_be_merged` | This merge request can be merged without conflict | +| `cannot_be_merged` | There are merge conflicts between the source and target branches | +| `cannot_be_merged_recheck` | Currently unchecked. Before the current changes, there were conflicts | + Users on GitLab Premium or higher also see the `approvals_before_merge` parameter: @@ -532,6 +545,7 @@ Parameters: "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -670,6 +684,7 @@ Parameters: "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -902,6 +917,7 @@ Parameters: "target_project_id": 4, "labels": [ ], "description": "Qui voluptatibus placeat ipsa alias quasi. Deleniti rem ut sint. Optio velit qui distinctio.", + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -1112,6 +1128,7 @@ POST /projects/:id/merge_requests "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -1282,6 +1299,7 @@ Must include at least one non-required attribute from above. "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -1467,6 +1485,7 @@ Parameters: "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -1655,6 +1674,7 @@ Parameters: "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -1956,6 +1976,7 @@ Example response: "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -2115,6 +2136,7 @@ Example response: "Community contribution", "Manage" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 5, @@ -2291,6 +2313,7 @@ Example response: "source_project_id": 3, "target_project_id": 3, "labels": [], + "draft": false, "work_in_progress": false, "milestone": { "id": 27, diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index 9fc17930c92..f74f7785d30 100644 --- a/doc/api/merge_trains.md +++ b/doc/api/merge_trains.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 298c0ead8c1..69bed193f07 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -123,7 +123,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](README.md#namespaced-path-encoding). | Example response: @@ -149,7 +149,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](README.md#namespaced-path-encoding) | | `level` | string | no | The global notification level | | `new_note` | boolean | no | Enable/disable this notification | | `new_issue` | boolean | no | Enable/disable this notification | diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 61eaf0f36d7..f5c75aac0d9 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -284,7 +284,8 @@ HTTP Basic Authentication with the application's `client_id` and `client_secret` ```shell echo 'grant_type=password&username=<your_username>&password=<your_password>' > auth.txt -curl --data "@auth.txt" --user client_id:client_secret --request POST "https://gitlab.example.com/oauth/token" +curl --data "@auth.txt" --user client_id:client_secret \ + --request POST "https://gitlab.example.com/oauth/token" ``` Then, you receive a response containing the access token: diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md index ebf3ffba92f..4f8e0a23c9c 100644 --- a/doc/api/packages/composer.md +++ b/doc/api/packages/composer.md @@ -71,7 +71,7 @@ Example response: ## V1 packages list -Given the V1 provider sha, returns a list of packages within the repository. Using Composer V2 is +Given the V1 provider SHA, returns a list of packages in the repository. Using Composer V2 is recommended over V1. ```plaintext @@ -81,7 +81,7 @@ GET group/:id/-/packages/composer/p/:sha | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | string | yes | The ID or full path of the group. | -| `sha` | string | yes | The provider sha, provided by the Composer [base request](#base-repository-request). | +| `sha` | string | yes | The provider SHA, provided by the Composer [base request](#base-repository-request). | ```shell curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/group/1/-/packages/composer/p/082df4a5035f8725a12i4a3d2da5e6aaa966d06843d0a5c6d499313810427bd6" @@ -115,7 +115,7 @@ the symbol `%24` (see example below). | -------------- | ------ | -------- | ----------- | | `id` | string | yes | The ID or full path of the group. | | `package_name` | string | yes | The name of the package. | -| `sha` | string | yes | The sha digest of the package, provided by the [V1 packages list](#v1-packages-list). | +| `sha` | string | yes | The SHA digest of the package, provided by the [V1 packages list](#v1-packages-list). | ```shell curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/group/1/-/packages/composer/my-org/my-composer-package%245c873497cdaa82eda35af5de24b789be92dfb6510baf117c42f03899c166b6e7" @@ -247,7 +247,8 @@ POST projects/:id/packages/composer | `branch` | string | no | The name of the branch to target for the package. | ```shell -curl --request POST --user <username>:<personal_access_token> --data tag=v1.0.0 "https://gitlab.example.com/api/v4/projects/1/packages/composer" +curl --request POST --user <username>:<personal_access_token> \ + --data tag=v1.0.0 "https://gitlab.example.com/api/v4/projects/1/packages/composer" ``` Example response: @@ -272,7 +273,7 @@ GET projects/:id/packages/composer/archives/:package_name | -------------- | ------ | -------- | ----------- | | `id` | string | yes | The ID or full path of the group. | | `package_name` | string | yes | The name of the package. | -| `sha` | string | yes | The target sha of the requested package version. | +| `sha` | string | yes | The target SHA of the requested package version. | ```shell curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab" diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index ed61704770b..bbcb2cb9bc4 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -82,7 +82,7 @@ This writes the downloaded file to `MyNuGetPkg.1.3.0.17.nupkg` in the current di > Introduced in GitLab 12.8. -Download a NuGet package file: +Upload a NuGet package file: ```plaintext PUT projects/:id/packages/nuget diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index 531193e59e2..77ba028c447 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -20,11 +20,82 @@ These endpoints do not adhere to the standard API authentication methods. See the [PyPI package registry documentation](../../user/packages/pypi_repository/index.md) for details on which headers and token types are supported. -## Download a package file +## Download a package file from a group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225545) in GitLab 13.12. + +Download a PyPI package file. The [simple API](#group-level-simple-api-entry-point) +normally supplies this URL. + +```plaintext +GET groups/:id/packages/pypi/files/:sha256/:file_identifier +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the group. | +| `sha256` | string | yes | The PyPI package file's sha256 checksum. | +| `file_identifier` | string | yes | The PyPI package file's name. | + +```shell +curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/groups/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" +``` + +To write the output to a file: + +```shell +curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/groups/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" >> my.pypi.package-0.0.1.tar.gz +``` + +This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory. + +## Group level simple API entry point + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225545) in GitLab 13.12. + +Returns the package descriptor as an HTML file: + +```plaintext +GET groups/:id/packages/pypi/simple/:package_name +``` + +| Attribute | Type | Required | Description | +| -------------- | ------ | -------- | ----------- | +| `id` | string | yes | The ID or full path of the group. | +| `package_name` | string | yes | The name of the package. | + +```shell +curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/groups/1/packages/pypi/simple/my.pypi.package" +``` + +Example response: + +```html +<!DOCTYPE html> +<html> + <head> + <title>Links for my.pypi.package</title> + </head> + <body> + <h1>Links for my.pypi.package</h1> + <a href="https://gitlab.example.com/api/v4/groups/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1-py3-none-any.whl#sha256=5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff" data-requires-python=">=3.6">my.pypi.package-0.0.1-py3-none-any.whl</a><br><a href="https://gitlab.example.com/api/v4/groups/1/packages/pypi/files/9s9w01b0bcd52b709ec052084e33a5517ffca96f7728ddd9f8866a30cdf76f2/my.pypi.package-0.0.1.tar.gz#sha256=9s9w011b0bcd52b709ec052084e33a5517ffca96f7728ddd9f8866a30cdf76f2" data-requires-python=">=3.6">my.pypi.package-0.0.1.tar.gz</a><br> + </body> +</html> +``` + +To write the output to a file: + +```shell +curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/groups/1/packages/pypi/simple/my.pypi.package" >> simple.html +``` + +This writes the downloaded file to `simple.html` in the current directory. + +## Download a package file from a project > Introduced in GitLab 12.10. -Download a PyPI package file. The [simple API](#simple-api-entry-point) +Download a PyPI package file. The [simple API](#project-level-simple-api-entry-point) normally supplies this URL. ```plaintext @@ -49,7 +120,7 @@ curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory. -## Simple API entry point +## Project-level simple API entry point > Introduced in GitLab 12.10. diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index f9bb8521a1f..fbea365e3d5 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -134,19 +134,24 @@ POST /projects/:id/pages/domains Create a new Pages domain with a certificate from a `.pem` file: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" \ + --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains" ``` Create a new Pages domain by using a variable containing the certificate: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" \ + --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains" ``` Create a new Pages domain with an [automatic certificate](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md#enabling-lets-encrypt-integration-for-your-custom-domain): ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" \ + --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains" ``` ```json @@ -184,13 +189,15 @@ PUT /projects/:id/pages/domains/:domain Add a certificate for a Pages domain from a `.pem` file: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=@/path/to/cert.pem" \ + --form "key=@/path/to/key.pem" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" ``` Add a certificate for a Pages domain by using a variable containing the certificate: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=$CERT_PEM" \ + --form "key=$KEY_PEM" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" ``` ```json @@ -210,7 +217,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi ### Enabling Let's Encrypt integration for Pages custom domains ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "auto_ssl_enabled=true" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" ``` ```json @@ -226,7 +234,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "auto_ss To remove the SSL certificate attached to the Pages domain, run: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=" --form "key=" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=" \ + --form "key=" "https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example" ``` ```json diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index 6b3b6f4f36b..afb5d434fe7 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -1,10 +1,10 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Pipeline schedules API +# Pipeline schedules API **(FREE)** You can read more about [pipeline schedules](../ci/pipelines/schedules.md). @@ -30,7 +30,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a { "id": 13, "description": "Test schedule pipeline", - "ref": "master", + "ref": "main", "cron": "* * * * *", "cron_timezone": "Asia/Tokyo", "next_run_at": "2017-05-19T13:41:00.000Z", @@ -70,7 +70,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a { "id": 13, "description": "Test schedule pipeline", - "ref": "master", + "ref": "main", "cron": "* * * * *", "cron_timezone": "Asia/Tokyo", "next_run_at": "2017-05-19T13:41:00.000Z", @@ -80,7 +80,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a "last_pipeline": { "id": 332, "sha": "0e788619d0b5ec17388dffb973ecd505946156db", - "ref": "master", + "ref": "main", "status": "pending" }, "owner": { @@ -119,14 +119,16 @@ POST /projects/:id/pipeline_schedules | `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: `true`). | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form description="Build packages" --form ref="master" --form cron="0 1 * * 5" --form cron_timezone="UTC" --form active="true" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form description="Build packages" --form ref="main" --form cron="0 1 * * 5" --form cron_timezone="UTC" \ + --form active="true" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" ``` ```json { "id": 14, "description": "Build packages", - "ref": "master", + "ref": "main", "cron": "0 1 * * 5", "cron_timezone": "UTC", "next_run_at": "2017-05-26T01:00:00.000Z", @@ -164,14 +166,15 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id | `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" ``` ```json { "id": 13, "description": "Test schedule pipeline", - "ref": "master", + "ref": "main", "cron": "0 2 * * *", "cron_timezone": "Asia/Tokyo", "next_run_at": "2017-05-19T17:00:00.000Z", @@ -181,7 +184,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form cron="0 "last_pipeline": { "id": 332, "sha": "0e788619d0b5ec17388dffb973ecd505946156db", - "ref": "master", + "ref": "main", "status": "pending" }, "owner": { @@ -216,7 +219,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla { "id": 13, "description": "Test schedule pipeline", - "ref": "master", + "ref": "main", "cron": "0 2 * * *", "cron_timezone": "Asia/Tokyo", "next_run_at": "2017-05-19T17:00:00.000Z", @@ -226,7 +229,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla "last_pipeline": { "id": 332, "sha": "0e788619d0b5ec17388dffb973ecd505946156db", - "ref": "master", + "ref": "main", "status": "pending" }, "owner": { @@ -261,7 +264,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git { "id": 13, "description": "Test schedule pipeline", - "ref": "master", + "ref": "main", "cron": "0 2 * * *", "cron_timezone": "Asia/Tokyo", "next_run_at": "2017-05-19T17:00:00.000Z", @@ -271,7 +274,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git "last_pipeline": { "id": 332, "sha": "0e788619d0b5ec17388dffb973ecd505946156db", - "ref": "master", + "ref": "main", "status": "pending" }, "owner": { @@ -317,8 +320,6 @@ Example response: ## Pipeline schedule variables -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34518) in GitLab 10.0. - ## Create a new pipeline schedule variable Create a new variable of a pipeline schedule. @@ -336,7 +337,8 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "key=NEW_VARIABLE" --form "value=new value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "key=NEW_VARIABLE" \ + --form "value=new value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables" ``` ```json @@ -364,7 +366,9 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "value=updated value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "value=updated value" \ + "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE" ``` ```json diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index ea10b14bc2e..94122a40b2d 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -1,10 +1,10 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Pipeline triggers API +# Pipeline triggers API **(FREE)** You can read more about [triggering pipelines through the API](../ci/triggers/README.md). @@ -81,7 +81,8 @@ POST /projects/:id/triggers | `description` | string | yes | The trigger name | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers" ``` ```json @@ -111,7 +112,8 @@ PUT /projects/:id/triggers/:trigger_id | `description` | string | no | The trigger name | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers/10" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers/10" ``` ```json diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 497c70b19ba..57c356ccf29 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -1,10 +1,10 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Pipelines API +# Pipelines API **(FREE)** ## Single Pipeline Requests @@ -23,8 +23,6 @@ Read more on [pagination](README.md#pagination). ## List project pipelines -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837) in GitLab 8.11 - ```plaintext GET /projects/:id/pipelines ``` @@ -77,8 +75,6 @@ Example of response ## Get a single pipeline -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837) in GitLab 8.11 - ```plaintext GET /projects/:id/pipelines/:pipeline_id ``` @@ -99,7 +95,7 @@ Example of response "id": 46, "project_id": 1, "status": "success", - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "tag": false, @@ -213,8 +209,6 @@ Sample response: ## Create a new pipeline -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7209) in GitLab 8.14 - ```plaintext POST /projects/:id/pipeline ``` @@ -226,7 +220,7 @@ POST /projects/:id/pipeline | `variables` | array | no | An array containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }]` | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=master" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=main" ``` Example of response @@ -236,7 +230,7 @@ Example of response "id": 61, "project_id": 1, "sha": "384c444e840a515b23f21915ee5766b87068a70d", - "ref": "master", + "ref": "main", "status": "pending", "before_sha": "0000000000000000000000000000000000000000", "tag": false, @@ -263,8 +257,6 @@ Example of response ## Retry jobs in a pipeline -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837) in GitLab 8.11 - ```plaintext POST /projects/:id/pipelines/:pipeline_id/retry ``` @@ -285,7 +277,7 @@ Response: "id": 46, "project_id": 1, "status": "pending", - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "tag": false, @@ -312,8 +304,6 @@ Response: ## Cancel a pipeline's jobs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5837) in GitLab 8.11 - ```plaintext POST /projects/:id/pipelines/:pipeline_id/cancel ``` @@ -334,7 +324,7 @@ Response: "id": 46, "project_id": 1, "status": "canceled", - "ref": "master", + "ref": "main", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "tag": false, diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index 439f34ad93b..1638bb644c2 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -68,8 +68,8 @@ Example response: ## Create a project alias -Add a new alias for a project. Responds with a 201 when successful, -400 when there are validation errors (e.g. alias already exists): +Add a new alias for a project. When successful, responds with `201 Created`. +When there are validation errors, for example, when the alias already exists, responds with `400 Bad Request`: ```plaintext POST /project_aliases @@ -81,13 +81,15 @@ POST /project_aliases | `name` | string | yes | The name of the alias. Must be unique. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=1" --form "name=gitlab" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=1" --form "name=gitlab" ``` or ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=gitlab-org/gitlab" --form "name=gitlab" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=gitlab-org/gitlab" --form "name=gitlab" ``` Example response: diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index a17f7d15e76..c6bcaa1ae9c 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -109,7 +109,9 @@ POST /projects/:id/badges | `name` | string | no | Name of the badge | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&name=mybadge" "https://gitlab.example.com/api/v4/projects/:id/badges" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&name=mybadge" \ + "https://gitlab.example.com/api/v4/projects/:id/badges" ``` Example response: diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index a431e754774..f31b3ccd0bb 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23922) in GitLab 11.7. -Users need at least [Maintainer](../user/permissions.md) access to use these endpoints. +Users need at least the [Maintainer](../user/permissions.md) role to use these endpoints. ## List project clusters @@ -22,7 +22,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | ----------------------------------------------------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -92,7 +92,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -151,7 +151,8 @@ Example response: "path_with_namespace":"root/project-with-clusters-api", "created_at":"2019-01-02T20:13:32.600Z", "default_branch":null, - "tag_list":[], + "tag_list":[], //deprecated, use `topics` instead + "topics":[], "ssh_url_to_repo":"ssh://gitlab.example.com/root/project-with-clusters-api.git", "http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git", "web_url":"https://gitlab.example.com/root/project-with-clusters-api", @@ -185,7 +186,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the cluster | | `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | @@ -247,7 +248,8 @@ Example response: "path_with_namespace":"root/project-with-clusters-api", "created_at":"2019-01-02T20:13:32.600Z", "default_branch":null, - "tag_list":[], + "tag_list":[], //deprecated, use `topics` instead + "topics":[], "ssh_url_to_repo":"ssh:://gitlab.example.com/root/project-with-clusters-api.git", "http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git", "web_url":"https://gitlab.example.com/root/project-with-clusters-api", @@ -281,7 +283,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ | -| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | string | no | The name of the cluster | | `domain` | string | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | @@ -357,7 +359,8 @@ Example response: "path_with_namespace":"root/project-with-clusters-api", "created_at":"2019-01-02T20:13:32.600Z", "default_branch":null, - "tag_list":[], + "tag_list":[], //deprecated, use `topics` instead + "topics":[], "ssh_url_to_repo":"ssh:://gitlab.example.com/root/project-with-clusters-api.git", "http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git", "web_url":"https://gitlab.example.com/root/project-with-clusters-api", @@ -392,7 +395,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ----------------------------------------------------- | -| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index a4ad496b667..b20ce9896dc 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -18,7 +18,7 @@ See also: Start a new export. -The endpoint also accepts an `upload` parameter. This parameter is a hash that contains +The endpoint also accepts an `upload` parameter. This parameter is a hash. It contains all the necessary information to upload the exported project to a web server or to any S3-compatible platform. At the moment we only support binary data file uploads to the final server. @@ -70,23 +70,14 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a Status can be one of: -- `none` -- `queued` -- `started` -- `finished` -- `regeneration_in_progress` - -`queued` state represents the request for export is received, and is currently in the queue to be processed. - -The `started` state represents that the export process has started and is currently in progress. -It includes the process of exporting, actions performed on the resultant file such as sending -an email notifying the user to download the file, uploading the exported file to a web server, etc. - -`finished` state is after the export process has completed and the user has been notified. - -`regeneration_in_progress` is when an export file is available to download, and a request to generate a new export is in process. - -`none` is when there are no exports _queued_, _started_, _finished_, or _being regenerated_ +- `none`: No exports _queued_, _started_, _finished_, or _being regenerated_. +- `queued`: The request for export is received, and is in the queue to be processed. +- `started`: The export process has started and is in progress. It includes: + - The process of exporting. + - Actions performed on the resulting file, such as sending an email notifying + the user to download the file, or uploading the exported file to a web server. +- `finished`: After the export process has completed and the user has been notified. +- `regeneration_in_progress`: An export file is available to download, and a request to generate a new export is in process. `_links` are only present when export has finished. @@ -122,7 +113,8 @@ GET /projects/:id/export/download | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name --remote-name "https://gitlab.example.com/api/v4/projects/5/export/download" +curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ + --remote-name "https://gitlab.example.com/api/v4/projects/5/export/download" ``` ```shell @@ -153,7 +145,8 @@ The `file=` parameter must point to a file on your file system and be preceded by `@`. For example: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "path=api-project" --form "file=@/path/to/file" "https://gitlab.example.com/api/v4/projects/import" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "path=api-project" \ + --form "file=@/path/to/file" "https://gitlab.example.com/api/v4/projects/import" ``` cURL doesn't support posting a file from a remote server. Importing a project from a remote server can be accomplished through something like the following: @@ -288,7 +281,7 @@ NOTE: An element's `id` field in `failed_relations` references the failure record, not the relation. NOTE: -The `failed_relations` array is currently capped to 100 items. +The `failed_relations` array is capped to 100 items. ```json { diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 8ef887675e9..0b7193ad5bc 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, api --- @@ -85,7 +85,8 @@ POST /projects/:id/variables | `environment_scope` | string | no | The `environment_scope` of the variable. Default: `*` | ```shell -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" +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" ``` ```json @@ -119,7 +120,8 @@ PUT /projects/:id/variables/:key | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value" ``` ```json diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index dd8954f2f0f..31c306bb14f 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -221,7 +221,8 @@ Example request: ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ ---data '{"destination_storage_name":"storage2"}' "https://gitlab.example.com/api/v4/projects/1/repository_storage_moves" + --data '{"destination_storage_name":"storage2"}' \ + "https://gitlab.example.com/api/v4/projects/1/repository_storage_moves" ``` Example response: @@ -266,7 +267,8 @@ Example request: ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ ---data '{"source_storage_name":"default"}' "https://gitlab.example.com/api/v4/project_repository_storage_moves" + --data '{"source_storage_name":"default"}' \ + "https://gitlab.example.com/api/v4/project_repository_storage_moves" ``` Example response: diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 070429eafd5..156d3c57a43 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -16,7 +16,7 @@ Constants for snippet visibility levels are: | visibility | Description | | ---------- | ----------- | -| `private` | The snippet is visible only the snippet creator | +| `private` | The snippet is visible only to the snippet creator | | `internal` | The snippet is visible for any logged in user except [external users](../user/permissions.md#external-users) | | `public` | The snippet can be accessed without any authentication | @@ -225,7 +225,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet -- `ref` (required) - The name of a branch, tag or commit, such as `master` +- `ref` (required) - The name of a branch, tag or commit, such as `main` - `file_path` (required) - The URL-encoded path to the file, such as `snippet%2Erb` Example request: @@ -239,7 +239,7 @@ curl "https://gitlab.com/api/v4/projects/1/snippets/2/files/master/snippet%2Erb/ > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29508) in GitLab 9.4. -Available only for users with Administrator [permissions](../user/permissions.md). +Available only for users with the Administrator [role](../user/permissions.md). ```plaintext GET /projects/:id/snippets/:snippet_id/user_agent_detail @@ -247,7 +247,7 @@ GET /projects/:id/snippets/:snippet_id/user_agent_detail | Attribute | Type | Required | Description | |---------------|---------|----------|--------------------------------------| -| `id` | Integer | yes | The ID of a project | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](README.md#namespaced-path-encoding). | | `snippet_id` | Integer | yes | The ID of a snippet | Example request: diff --git a/doc/api/projects.md b/doc/api/projects.md index b686d17a4a1..e5cb2c8e1eb 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -59,7 +59,7 @@ GET /projects | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | -| `topic` | string | **{dotted-circle}** No | Comma-separated topic names. Limit results to projects that match all of given topics. See `tag_list` attribute. | +| `topic` | string | **{dotted-circle}** No | Comma-separated topic names. Limit results to projects that match all of given topics. See `topics` attribute. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2). | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | @@ -82,7 +82,11 @@ When `simple=true` or the user is unauthenticated this returns something like: "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git", "web_url": "http://example.com/diaspora/diaspora-client", "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora client" + ], + "topics": [ "example", "disapora client" ], @@ -116,7 +120,11 @@ When the user is authenticated and `simple` is not set this returns something li "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git", "web_url": "http://example.com/diaspora/diaspora-client", "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora client" + ], + "topics": [ "example", "disapora client" ], @@ -166,6 +174,7 @@ When the user is authenticated and `simple` is not set this returns something li "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "autoclose_referenced_issues": true, "suggestion_commit_message": null, "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on @@ -200,7 +209,11 @@ When the user is authenticated and `simple` is not set this returns something li "http_url_to_repo": "http://example.com/brightbox/puppet.git", "web_url": "http://example.com/brightbox/puppet", "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "puppet" + ], + "topics": [ "example", "puppet" ], @@ -261,6 +274,7 @@ When the user is authenticated and `simple` is not set this returns something li "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "auto_devops_enabled": true, "auto_devops_deploy_strategy": "continuous", "repository_storage": "default", @@ -301,6 +315,10 @@ When the user is authenticated and `simple` is not set this returns something li ``` NOTE: +The `tag_list` attribute has been deprecated +and is removed in API v5 in favor of the `topics` attribute. + +NOTE: For users of [GitLab Premium or higher](https://about.gitlab.com/pricing/), the `marked_for_deletion_at` attribute has been deprecated, and is removed in API v5 in favor of the `marked_for_deletion_on` attribute. @@ -378,7 +396,11 @@ GET /users/:user_id/projects "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git", "web_url": "http://example.com/diaspora/diaspora-client", "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora client" + ], + "topics": [ "example", "disapora client" ], @@ -428,6 +450,7 @@ GET /users/:user_id/projects "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "autoclose_referenced_issues": true, "suggestion_commit_message": null, "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on @@ -462,7 +485,11 @@ GET /users/:user_id/projects "http_url_to_repo": "http://example.com/brightbox/puppet.git", "web_url": "http://example.com/brightbox/puppet", "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "puppet" + ], + "topics": [ "example", "puppet" ], @@ -523,6 +550,7 @@ GET /users/:user_id/projects "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "auto_devops_enabled": true, "auto_devops_deploy_strategy": "continuous", "repository_storage": "default", @@ -606,7 +634,11 @@ Example response: "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git", "web_url": "http://example.com/diaspora/diaspora-client", "readme_url": "http://example.com/diaspora/diaspora-client/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora client" + ], + "topics": [ "example", "disapora client" ], @@ -654,6 +686,7 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "autoclose_referenced_issues": true, "suggestion_commit_message": null, "statistics": { @@ -683,7 +716,11 @@ Example response: "http_url_to_repo": "http://example.com/brightbox/puppet.git", "web_url": "http://example.com/brightbox/puppet", "readme_url": "http://example.com/brightbox/puppet/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "puppet" + ], + "topics": [ "example", "puppet" ], @@ -742,6 +779,7 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "auto_devops_enabled": true, "auto_devops_deploy_strategy": "continuous", "repository_storage": "default", @@ -789,7 +827,7 @@ GET /projects/:id | Attribute | Type | Required | Description | |--------------------------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `license` | boolean | **{dotted-circle}** No | Include project license data. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | @@ -804,7 +842,11 @@ GET /projects/:id "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git", "web_url": "http://example.com/diaspora/diaspora-project-site", "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora project" + ], + "topics": [ "example", "disapora project" ], @@ -900,6 +942,7 @@ GET /projects/:id "printing_merge_requests_link_enabled": true, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "auto_devops_enabled": true, "auto_devops_deploy_strategy": "continuous", "approvals_before_merge": 0, @@ -940,6 +983,10 @@ GET /projects/:id } ``` +NOTE: +The `tag_list` attribute has been deprecated +and is removed in API v5 in favor of the `topics` attribute. + Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) can also see the `approvals_before_merge` parameter: @@ -974,12 +1021,13 @@ If the project is a fork, and you provide a valid token to authenticate, the "path_with_namespace":"gitlab-org/gitlab-foss", "created_at":"2013-09-26T06:02:36.000Z", "default_branch":"master", - "tag_list":[], + "tag_list":[], //deprecated, use `topics` instead + "topics":[], "ssh_url_to_repo":"git@gitlab.com:gitlab-org/gitlab-foss.git", "http_url_to_repo":"https://gitlab.com/gitlab-org/gitlab-foss.git", "web_url":"https://gitlab.com/gitlab-org/gitlab-foss", "avatar_url":"https://assets.gitlab-static.net/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png", - "license_url": "https://gitlab.com/gitlab-org/gitlab/blob/master/LICENSE", + "license_url": "https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE", "license": { "key": "mit", "name": "MIT License", @@ -1032,7 +1080,7 @@ GET /projects/:id/users | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | | `skip_users` | integer array | **{dotted-circle}** No | Filter out users with the specified IDs. | @@ -1067,7 +1115,7 @@ GET /projects/:id/groups | Attribute | Type | Required | Description | |-----------------------------|-------------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific groups. | | `skip_groups` | array of integers | **{dotted-circle}** No | Skip the group IDs passed. | | `with_shared` | boolean | **{dotted-circle}** No | Include projects shared with this group. Default is `false`. | @@ -1117,7 +1165,7 @@ POST /projects | `path` | string | **{check-circle}** Yes (if name isn't provided) | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | -| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. | +| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | | `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`). | | `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | @@ -1130,7 +1178,7 @@ POST /projects | `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | | `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). Valid values for `cadence` are: `1d` (every day), `7d` (every week), `14d` (every two weeks), `1month` (every month), or `3month` (every quarter). | | `container_registry_enabled` | boolean | **{dotted-circle}** No | Enable container registry for this project. | -| `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. | +| `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. Requires `initialize_with_readme` to be `true`. | | `description` | string | **{dotted-circle}** No | Short project description. | | `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | @@ -1165,9 +1213,11 @@ POST /projects | `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | -| `tag_list` | array | **{dotted-circle}** No | The list of tags for a project; put array of tags, that should be finally assigned to a project. | +| `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | +| `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | | `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | | `template_project_id` **(PREMIUM)** | integer | **{dotted-circle}** No | When used with `use_custom_template`, project ID of a custom project template. This is preferable to using `template_name` since `template_name` may be ambiguous. | +| `topics` | array | **{dotted-circle}** No | The list of topics for a project; put array of topics, that should be finally assigned to a project. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0.)_ | | `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | | `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | | `wiki_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | @@ -1191,7 +1241,7 @@ POST /projects/user/:user_id | `name` | string | **{check-circle}** Yes | The name of the new project. | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | -| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. | +| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | | `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`). | | `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | @@ -1204,6 +1254,7 @@ POST /projects/user/:user_id | `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | | `container_registry_enabled` | boolean | **{dotted-circle}** No | Enable container registry for this project. | | `description` | string | **{dotted-circle}** No | Short project description. | +| `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. Requires `initialize_with_readme` to be `true`. | | `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | @@ -1238,9 +1289,11 @@ POST /projects/user/:user_id | `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | -| `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request suggestions. | -| `tag_list` | array | **{dotted-circle}** No | The list of tags for a project; put array of tags, that should be finally assigned to a project. | +| `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | +| `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request [suggestions](../user/project/merge_requests/reviews/suggestions.md). | +| `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | | `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | +| `topics` | array | **{dotted-circle}** No | The list of topics for the project. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0.)_ | | `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | | `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | | `wiki_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | @@ -1262,7 +1315,7 @@ PUT /projects/:id |-------------------------------------------------------------|----------------|------------------------|-------------| | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | -| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge request by default. | +| `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge request by default. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | | `auto_devops_deploy_strategy` | string | **{dotted-circle}** No | Auto Deploy strategy (`continuous`, `manual`, or `timed_incremental`). | | `auto_devops_enabled` | boolean | **{dotted-circle}** No | Enable Auto DevOps for this project. | @@ -1282,7 +1335,7 @@ PUT /projects/:id | `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `import_url` | string | **{dotted-circle}** No | URL to import repository from. | | `issues_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `issues_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable issues for this project. Use `issues_access_level` instead. | @@ -1316,13 +1369,16 @@ PUT /projects/:id | `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | +| `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | | `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request suggestions. | -| `tag_list` | array | **{dotted-circle}** No | The list of tags for a project; put array of tags, that should be finally assigned to a project. | +| `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | +| `topics` | array | **{dotted-circle}** No | The list of topics for the project. This replaces any existing topics that are already added to the project. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0.)_ | | `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | | `wiki_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `wiki_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable wiki for this project. Use `wiki_access_level` instead. | | `issues_template` **(PREMIUM)** | string | **{dotted-circle}** No | Default description for Issues. Description is parsed with GitLab Flavored Markdown. See [Templates for issues and merge requests](#templates-for-issues-and-merge-requests). | | `merge_requests_template` **(PREMIUM)** | string | **{dotted-circle}** No | Default description for Merge Requests. Description is parsed with GitLab Flavored Markdown. See [Templates for issues and merge requests](#templates-for-issues-and-merge-requests). | +| `keep_latest_artifact` | boolean | **{dotted-circle}** No | Disable or enable the ability to keep the latest artifact for this project. | ## Fork project @@ -1338,11 +1394,11 @@ POST /projects/:id/fork | Attribute | Type | Required | Description | |------------------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `name` | string | **{dotted-circle}** No | The name assigned to the resultant project after forking. | | `namespace_id` | integer | **{dotted-circle}** No | The ID of the namespace that the project is forked to. | | `namespace_path` | string | **{dotted-circle}** No | The path of the namespace that the project is forked to. | -| `namespace` | integer/string | **{dotted-circle}** No | _(Deprecated)_ The ID or path of the namespace that the project is forked to. | +| `namespace` | integer or string | **{dotted-circle}** No | _(Deprecated)_ The ID or path of the namespace that the project is forked to. | | `path` | string | **{dotted-circle}** No | The path assigned to the resultant project after forking. | | `description` | string | **{dotted-circle}** No | The description assigned to the resultant project after forking. | | `visibility` | string | **{dotted-circle}** No | The [visibility level](#project-visibility-level) assigned to the resultant project after forking. | @@ -1361,7 +1417,7 @@ GET /projects/:id/forks | Attribute | Type | Required | Description | |-------------------------------|----------------|------------------------|-------------| | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | @@ -1393,7 +1449,11 @@ Example responses: "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git", "web_url": "http://example.com/diaspora/diaspora-project-site", "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora project" + ], + "topics": [ "example", "disapora project" ], @@ -1435,6 +1495,7 @@ Example responses: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "autoclose_referenced_issues": true, "suggestion_commit_message": null, "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site", @@ -1462,7 +1523,7 @@ POST /projects/:id/star | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star" @@ -1480,7 +1541,11 @@ Example response: "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git", "web_url": "http://example.com/diaspora/diaspora-project-site", "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora project" + ], + "topics": [ "example", "disapora project" ], @@ -1530,6 +1595,7 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "autoclose_referenced_issues": true, "suggestion_commit_message": null, "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site", @@ -1555,7 +1621,7 @@ POST /projects/:id/unstar | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar" @@ -1573,7 +1639,11 @@ Example response: "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git", "web_url": "http://example.com/diaspora/diaspora-project-site", "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora project" + ], + "topics": [ "example", "disapora project" ], @@ -1623,6 +1693,7 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "autoclose_referenced_issues": true, "suggestion_commit_message": null, "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site", @@ -1648,7 +1719,7 @@ GET /projects/:id/starrers | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | ```shell @@ -1694,7 +1765,7 @@ GET /projects/:id/languages | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages" @@ -1723,7 +1794,7 @@ POST /projects/:id/archive | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive" @@ -1741,7 +1812,11 @@ Example response: "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git", "web_url": "http://example.com/diaspora/diaspora-project-site", "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora project" + ], + "topics": [ "example", "disapora project" ], @@ -1810,6 +1885,7 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "autoclose_referenced_issues": true, "suggestion_commit_message": null, "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site", @@ -1837,7 +1913,7 @@ POST /projects/:id/unarchive | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive" @@ -1855,7 +1931,11 @@ Example response: "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git", "web_url": "http://example.com/diaspora/diaspora-project-site", "readme_url": "http://example.com/diaspora/diaspora-project-site/blob/master/README.md", - "tag_list": [ + "tag_list": [ //deprecated, use `topics` instead + "example", + "disapora project" + ], + "topics": [ "example", "disapora project" ], @@ -1924,6 +2004,7 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "squash_option": "default_on", "autoclose_referenced_issues": true, "suggestion_commit_message": null, "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-project-site", @@ -1963,7 +2044,7 @@ DELETE /projects/:id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Restore project marked for deletion **(PREMIUM)** @@ -1977,12 +2058,13 @@ POST /projects/:id/restore | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Upload a file Uploads a file to the specified project to be used in an issue or merge request -description, or a comment. +description, or a comment. GitLab versions 14.0 and later +[enforce](#max-attachment-size-enforcement) this limit. ```plaintext POST /projects/:id/uploads @@ -1991,7 +2073,7 @@ POST /projects/:id/uploads | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `file` | string | **{check-circle}** Yes | The file to be uploaded. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | To upload a file from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The @@ -1999,7 +2081,8 @@ cURL to post data using the header `Content-Type: multipart/form-data`. The `@`. For example: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/5/uploads" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/5/uploads" ``` Returned object: @@ -2021,7 +2104,8 @@ the format in `markdown` is used. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57250) in GitLab 13.11. -GitLab 13.11 added enforcement of the [maximum attachment size limit](../user/admin_area/settings/account_and_limit_settings.md#max-attachment-size) behind the `enforce_max_attachment_size_upload_api` feature flag. GitLab 14.0 will enable this by default. +GitLab 13.11 added enforcement of the [maximum attachment size limit](../user/admin_area/settings/account_and_limit_settings.md#max-attachment-size) behind the `enforce_max_attachment_size_upload_api` feature flag. GitLab 14.0 enables this by default. +To disable this enforcement: **In Omnibus installations:** @@ -2031,10 +2115,10 @@ GitLab 13.11 added enforcement of the [maximum attachment size limit](../user/ad sudo gitlab-rails console ``` -1. Enable the feature flag: +1. Disable the feature flag: ```ruby - Feature.enable(:enforce_max_attachment_size_upload_api) + Feature.disable(:enforce_max_attachment_size_upload_api) ``` **In installations from source:** @@ -2046,10 +2130,10 @@ GitLab 13.11 added enforcement of the [maximum attachment size limit](../user/ad sudo -u git -H bundle exec rails console -e production ``` -1. Enable the feature flag to disable the validation: +1. Disable the feature flag: ```ruby - Feature.enable(:enforce_max_attachment_size_upload_api) + Feature.disable(:enforce_max_attachment_size_upload_api) ``` ## Upload a project avatar @@ -2063,7 +2147,7 @@ PUT /projects/:id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `avatar` | string | **{check-circle}** Yes | The file to be uploaded. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | To upload an avatar from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The @@ -2073,7 +2157,8 @@ preceded by `@`. For example: Example request: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "avatar=@dk.png" "https://gitlab.example.com/api/v4/projects/5" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "avatar=@dk.png" "https://gitlab.example.com/api/v4/projects/5" ``` Returned object: @@ -2097,7 +2182,7 @@ POST /projects/:id/share | `expires_at` | string | **{dotted-circle}** No | Share expiration date in ISO 8601 format: 2016-09-26 | | `group_access` | integer | **{check-circle}** Yes | The [access level](members.md#valid-access-levels) to grant the group. | | `group_id` | integer | **{check-circle}** Yes | The ID of the group to share with. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Delete a shared project link within a group @@ -2110,7 +2195,7 @@ DELETE /projects/:id/share/:group_id | Attribute | Type | Required | Description | |------------|----------------|------------------------|-------------| | `group_id` | integer | **{check-circle}** Yes | The ID of the group. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" @@ -2131,7 +2216,7 @@ GET /projects/:id/hooks | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ### Get project hook @@ -2144,7 +2229,7 @@ GET /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|---------------------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of a project hook. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```json { @@ -2183,7 +2268,7 @@ POST /projects/:id/hooks | `confidential_note_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential note events. | | `deployment_events` | boolean | **{dotted-circle}** No | Trigger hook on deployment events. | | `enable_ssl_verification` | boolean | **{dotted-circle}** No | Do SSL verification when triggering the hook. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `issues_events` | boolean | **{dotted-circle}** No | Trigger hook on issues events. | | `job_events` | boolean | **{dotted-circle}** No | Trigger hook on job events. | | `merge_requests_events` | boolean | **{dotted-circle}** No | Trigger hook on merge requests events. | @@ -2211,7 +2296,7 @@ PUT /projects/:id/hooks/:hook_id | `deployment_events` | boolean | **{dotted-circle}** No | Trigger hook on deployment events. | | `enable_ssl_verification` | boolean | **{dotted-circle}** No | Do SSL verification when triggering the hook. | | `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `issues_events` | boolean | **{dotted-circle}** No | Trigger hook on issues events. | | `job_events` | boolean | **{dotted-circle}** No | Trigger hook on job events. | | `merge_requests_events` | boolean | **{dotted-circle}** No | Trigger hook on merge requests events. | @@ -2237,7 +2322,7 @@ DELETE /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | Note the JSON response differs if the hook is available or not. If the project hook is available before it's returned in the JSON response or an empty response @@ -2257,7 +2342,7 @@ POST /projects/:id/fork/:forked_from_id | Attribute | Type | Required | Description | |------------------|----------------|------------------------|-------------| | `forked_from_id` | ID | **{check-circle}** Yes | The ID of the project that was forked from. | -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ### Delete an existing forked from relationship @@ -2267,7 +2352,7 @@ DELETE /projects/:id/fork | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Search for projects by name @@ -2297,7 +2382,7 @@ POST /projects/:id/housekeeping | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Push Rules **(PREMIUM)** @@ -2312,7 +2397,7 @@ GET /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```json { @@ -2364,7 +2449,7 @@ POST /projects/:id/push_rule | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | | `file_name_regex` | string | **{dotted-circle}** No | All committed filenames must **not** match this, for example `(jar|exe)$`. | -| `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding), | | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | @@ -2387,7 +2472,7 @@ PUT /projects/:id/push_rule | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | | `file_name_regex` | string | **{dotted-circle}** No | All committed filenames must **not** match this, for example `(jar|exe)$`. | -| `id` | integer/string | **{check-circle}** Yes | The ID of the project or NAMESPACE/PROJECT_NAME. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | @@ -2406,7 +2491,7 @@ DELETE /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ## Transfer a project to a new namespace @@ -2418,8 +2503,8 @@ PUT /projects/:id/transfer | Attribute | Type | Required | Description | |-------------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `namespace` | integer/string | **{check-circle}** Yes | The ID or path of the namespace to transfer to project to. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `namespace` | integer or string | **{check-circle}** Yes | The ID or path of the namespace to transfer to project to. | Example request: @@ -2439,7 +2524,8 @@ Example response: "path_with_namespace": "cute-cats/hello-world", "created_at": "2020-10-15T16:25:22.415Z", "default_branch": "master", - "tag_list": [], + "tag_list": [], //deprecated, use `topics` instead + "topics": [], "ssh_url_to_repo": "git@gitlab.example.com:cute-cats/hello-world.git", "http_url_to_repo": "https://gitlab.example.com/cute-cats/hello-world.git", "web_url": "https://gitlab.example.com/cute-cats/hello-world", @@ -2521,6 +2607,7 @@ Example response: "remove_source_branch_after_merge": true, "printing_merge_request_link_enabled": true, "merge_method": "merge", + "squash_option": "default_on", "suggestion_commit_message": null, "auto_devops_enabled": true, "auto_devops_deploy_strategy": "continuous", @@ -2566,7 +2653,7 @@ POST /projects/:id/mirror/pull | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" @@ -2595,5 +2682,30 @@ GET /projects/:id/snapshot | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `wiki` | boolean | **{dotted-circle}** No | Whether to download the wiki, rather than project, repository. | + +## Get the path to repository storage + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29861) in GitLab 14.0. + +Get the path to repository storage for specified project. Available for administrators only. + +```plaintext +GET /projects/:id/storage +``` + +| Attribute | Type | Required | Description | +|--------------|----------------|------------------------|-------------| +| `id` | integer or string | **{check-circle}** Yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | + +```json +[ + { + "project_id": 1, + "disk_path": "@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b", + "created_at": "2012-10-12T17:04:47Z", + "repository_storage": "default" + } +] +``` diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index e5560360532..2fe821a7758 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -22,7 +22,7 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` ## List protected branches -Gets a list of protected branches from a project. +Gets a list of protected branches from a project as they are defined [in the UI](../user/project/protected_branches.md#configure-a-protected-branch). If a wildcard is set, it is returned instead of the exact name of the branches that match that wildcard. ```plaintext GET /projects/:id/protected_branches @@ -59,6 +59,24 @@ Example response: "allow_force_push":false, "code_owner_approval_required": false }, + { + "id": 1, + "name": "release/*", + "push_access_levels": [ + { + "access_level": 40, + "access_level_description": "Maintainers" + } + ], + "merge_access_levels": [ + { + "access_level": 40, + "access_level_description": "Maintainers" + } + ], + "allow_force_push":false, + "code_owner_approval_required": false + }, ... ] ``` @@ -183,10 +201,10 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch or wildcard | -| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) | -| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) | -| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, maintainer access level) | -| `allow_force_push` | boolean | no | Allow force push for all users with push access. (defaults: false) | +| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, Maintainer role) | +| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | +| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, Maintainer role) | +| `allow_force_push` | boolean | no | Allow all users with push access to force push. (default: `false`) | | `allowed_to_push` | array | no | **(PREMIUM)** Array of access levels allowed to push, with each described by a hash | | `allowed_to_merge` | array | no | **(PREMIUM)** Array of access levels allowed to merge, with each described by a hash | | `allowed_to_unprotect` | array | no | **(PREMIUM)** Array of access levels allowed to unprotect, with each described by a hash | diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 487537cd3f5..52fcdad1ad6 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -96,7 +96,10 @@ POST /projects/:id/protected_environments ``` ```shell -curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/22034114/protected_environments" +curl --header 'Content-Type: application/json' --request POST \ + --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/22034114/protected_environments" ``` | Attribute | Type | Required | Description | diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index 63fa7183aab..e04f418258d 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -102,7 +102,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag or wildcard | -| `create_access_level` | string | no | Access levels allowed to create (defaults: `40`, maintainer access level) | +| `create_access_level` | string | no | Access levels allowed to create (defaults: `40`, Maintainer role) | Example response: diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index bc37f1aa0a9..0cbf613c598 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -542,7 +542,8 @@ PUT /projects/:id/releases/:tag_name Example request: ```shell -curl --header 'Content-Type: application/json' --request PUT --data '{"name": "new name", "milestones": ["v1.2"]}' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1" +curl --header 'Content-Type: application/json' --request PUT --data '{"name": "new name", "milestones": ["v1.2"]}' \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1" ``` Example response: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 911aa8bbbd0..f4a2df5558f 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -148,7 +148,9 @@ You have to specify at least one of `name` or `url` Example request: ```shell -curl --request PUT --data name="new name" --data link_type="runbook" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1" +curl --request PUT --data name="new name" --data link_type="runbook" \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1" ``` Example response: diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index c85454d66ee..5e5b44fec8a 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -71,7 +71,8 @@ POST /projects/:id/remote_mirrors Example request: ```shell -curl --request POST --data "url=https://username:token@example.com/gitlab/example.git" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors" +curl --request POST --data "url=https://username:token@example.com/gitlab/example.git" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors" ``` Example response: diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 857cd3883c8..1868f33373c 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -311,6 +311,11 @@ Supported attributes: | `file` | string | no | The file to commit the changes to, defaults to `CHANGELOG.md`. | | `message` | string | no | The commit message to produce when committing the changes, defaults to `Add changelog for version X` where X is the value of the `version` argument. | +WARNING: +GitLab treats trailers case-sensitively. If you set the `trailer` field to +`Example`, GitLab _won't_ include commits that use the trailer `example`, +`eXaMpLE`, or anything else that isn't _exactly_ `Example`. + If the `from` attribute is unspecified, GitLab uses the Git tag of the last stable version that came before the version specified in the `version` attribute. This requires that Git tag names follow a specific format, allowing diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 70b804c368e..0dc50543f1e 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -183,10 +183,11 @@ POST /projects/:id/repository/files/:file_path ``` ```shell -curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \ - --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ - "content": "some content", "commit_message": "create a new file"}' \ - "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" +curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' \ + --header "Content-Type: application/json" \ + --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ + "content": "some content", "commit_message": "create a new file"}' \ + "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" ``` Example response: @@ -218,10 +219,11 @@ PUT /projects/:id/repository/files/:file_path ``` ```shell -curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \ - --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ - "content": "some content", "commit_message": "update file"}' \ - "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" +curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' \ + --header "Content-Type: application/json" \ + --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ + "content": "some content", "commit_message": "update file"}' \ + "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" ``` Example response: @@ -253,7 +255,7 @@ error message. Possible causes for a failed commit include: user tried to make an empty commit; - the branch was updated by a Git push while the file edit was in progress. -Currently GitLab Shell has a boolean return code, preventing GitLab from specifying the error. +GitLab Shell has a boolean return code, preventing GitLab from specifying the error. ## Delete existing file in repository @@ -264,10 +266,11 @@ DELETE /projects/:id/repository/files/:file_path ``` ```shell -curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' --header "Content-Type: application/json" \ - --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ - "commit_message": "delete file"}' \ - "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" +curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \ + --header "Content-Type: application/json" \ + --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ + "commit_message": "delete file"}' \ + "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" ``` Parameters: diff --git a/doc/api/resource_access_tokens.md b/doc/api/resource_access_tokens.md index ecc5b3bf172..3b443dbb8f8 100644 --- a/doc/api/resource_access_tokens.md +++ b/doc/api/resource_access_tokens.md @@ -10,7 +10,7 @@ You can read more about [project access tokens](../user/project/settings/project ## List project access tokens -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. Get a list of project access tokens. @@ -20,7 +20,7 @@ GET projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID of the project | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" @@ -45,7 +45,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ## Create a project access token -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55408) in GitLab 13.10. Create a project access token. @@ -55,9 +55,9 @@ POST projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID of the project | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `name` | String | yes | The name of the project access token | -| `scopes` | Array\[String] | yes | [List of scopes](../user/project/settings/project_access_tokens.md#limiting-scopes-of-a-project-access-token) | +| `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#limiting-scopes-of-a-project-access-token) | | `expires_at` | Date | no | The token expires at midnight UTC on that date | ```shell @@ -86,7 +86,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ## Revoke a project access token -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. Revoke a project access token. @@ -96,8 +96,8 @@ DELETE projects/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID of the project | -| `token_id` | integer/string | yes | The ID of the project access token | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `token_id` | integer or string | yes | The ID of the project access token | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>" diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index 0c1735c0664..5fc7a0a52bd 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -1,12 +1,13 @@ --- stage: Manage -group: Compilance +group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Resource label events API +# Resource label events API **(FREE)** -Resource label events keep track about who, when, and which label was added to, or removed from, an issuable. +Resource label events keep track about who, when, and which label was added to (or removed from) +an issue, merge request, or epic. ## Issues diff --git a/doc/api/runners.md b/doc/api/runners.md index 1f0209c3cae..951e72edcb5 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -41,6 +41,7 @@ GET /runners?scope=active GET /runners?type=project_type GET /runners?status=active GET /runners?tag_list=tag1,tag2 +GET /runners?search=gitlab ``` | Attribute | Type | Required | Description | @@ -49,6 +50,7 @@ GET /runners?tag_list=tag1,tag2 | `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | | `tag_list` | string array | no | List of the runner's tags | +| `search` | string | no | The full token or partial description text to match | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners" @@ -62,8 +64,9 @@ Example response: "active": true, "description": "test-1-20150125", "id": 6, - "is_shared": false, "ip_address": "127.0.0.1", + "is_shared": false, + "runner_type": "project_type", "name": null, "online": true, "status": "online" @@ -74,6 +77,7 @@ Example response: "id": 8, "ip_address": "127.0.0.1", "is_shared": false, + "runner_type": "group_type", "name": null, "online": false, "status": "offline" @@ -115,6 +119,7 @@ Example response: "id": 1, "ip_address": "127.0.0.1", "is_shared": true, + "runner_type": "instance_type", "name": null, "online": true, "status": "online" @@ -125,6 +130,7 @@ Example response: "id": 3, "ip_address": "127.0.0.1", "is_shared": true, + "runner_type": "instance_type", "name": null, "online": false, "status": "offline" @@ -135,6 +141,7 @@ Example response: "id": 6, "ip_address": "127.0.0.1", "is_shared": false, + "runner_type": "project_type", "name": null, "online": true, "status": "paused" @@ -145,6 +152,7 @@ Example response: "id": 8, "ip_address": "127.0.0.1", "is_shared": false, + "runner_type": "group_type", "name": null, "online": false, "status": "offline" @@ -156,7 +164,8 @@ Example response: Get details of a runner. -[Maintainer access or higher](../user/permissions.md) is required to get runner details at the project and group level. +The [Maintainer role or higher](../user/permissions.md) is required to get runner details at the +project and group level. Instance-level runner details via this endpoint are available to all signed in users. @@ -186,6 +195,7 @@ Example response: "id": 6, "ip_address": "127.0.0.1", "is_shared": false, + "runner_type": "project_type", "contacted_at": "2016-01-25T16:39:48.066Z", "name": null, "online": true, @@ -231,7 +241,8 @@ PUT /runners/:id | `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" \ + --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" ``` NOTE: @@ -248,6 +259,7 @@ Example response: "id": 6, "ip_address": "127.0.0.1", "is_shared": false, + "runner_type": "group_type", "contacted_at": "2016-01-25T16:39:48.066Z", "name": null, "online": true, @@ -288,7 +300,8 @@ PUT --form "active=false" /runners/:runner_id | `runner_id` | integer | yes | The ID of a runner | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "active=false" "https://gitlab.example.com/api/v4/runners/6" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "active=false" "https://gitlab.example.com/api/v4/runners/6" ``` ## List runner's jobs @@ -417,6 +430,7 @@ Example response: "id": 8, "ip_address": "127.0.0.1", "is_shared": false, + "runner_type": "project_type", "name": null, "online": false, "status": "offline" @@ -427,6 +441,7 @@ Example response: "id": 5, "ip_address": "127.0.0.1", "is_shared": true, + "runner_type": "instance_type", "name": null, "online": true, "status": "paused" @@ -448,7 +463,8 @@ POST /projects/:id/runners | `runner_id` | integer | yes | The ID of a runner | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" \ + --form "runner_id=9" ``` Example response: @@ -460,6 +476,7 @@ Example response: "id": 9, "ip_address": "127.0.0.1", "is_shared": false, + "runner_type": "project_type", "name": null, "online": true, "status": "online" @@ -518,6 +535,7 @@ Example response: "ip_address": "127.0.0.1", "active": true, "is_shared": true, + "runner_type": "instance_type", "name": "gitlab-runner", "online": null, "status": "not_connected" @@ -528,6 +546,7 @@ Example response: "ip_address": "127.0.0.1", "active": true, "is_shared": true, + "runner_type": "instance_type", "name": "gitlab-runner", "online": false, "status": "offline" @@ -538,6 +557,7 @@ Example response: "ip_address": "127.0.0.1", "active": true, "is_shared": false, + "runner_type": "group_type", "name": "gitlab-runner", "online": null, "status": "not_connected" @@ -566,7 +586,9 @@ POST /runners | `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job | ```shell -curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" +curl --request POST "https://gitlab.example.com/api/v4/runners" \ + --form "token=<registration_token>" --form "description=test-1-20150125-test" \ + --form "tag_list=ruby,mysql,tag1,tag2" ``` Response: @@ -620,7 +642,8 @@ DELETE /runners | `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). | ```shell -curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>" +curl --request DELETE "https://gitlab.example.com/api/v4/runners" \ + --form "token=<authentication_token>" ``` Response: @@ -642,7 +665,8 @@ POST /runners/verify | `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). | ```shell -curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>" +curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \ + --form "token=<authentication_token>" ``` Response: diff --git a/doc/api/scim.md b/doc/api/scim.md index d00a0988d2b..42580ba65b6 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -39,7 +39,9 @@ Pagination follows the [SCIM spec](https://tools.ietf.org/html/rfc7644#section-3 Example request: ```shell -curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \ + --header "Authorization: Bearer <your_scim_token>" \ + --header "Content-Type: application/scim+json" ``` Example response: @@ -90,7 +92,8 @@ Parameters: Example request: ```shell -curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` Example response: @@ -134,7 +137,9 @@ Parameters: Example request: ```shell -curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/groups/test_group/Users" --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/groups/test_group/Users" \ + --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` Example response: @@ -188,7 +193,9 @@ Parameters: Example request: ```shell -curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --data '{ "Operations": [{"op":"Add","path":"name.formatted","value":"New Name"}] }' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --data '{ "Operations": [{"op":"Add","path":"name.formatted","value":"New Name"}] }' \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` Returns an empty response with a `204` status code if successful. @@ -211,7 +218,8 @@ Parameters: Example request: ```shell -curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` Returns an empty response with a `204` status code if successful. diff --git a/doc/api/search.md b/doc/api/search.md index c8f24c0924a..9714bc17f62 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -54,7 +54,8 @@ Example response: "path_with_namespace": "twitter/flight", "created_at": "2017-09-05T07:58:01.621Z", "default_branch": "master", - "tag_list":[], + "tag_list":[], //deprecated, use `topics` instead + "topics":[], "ssh_url_to_repo": "ssh://jarka@localhost:2222/twitter/flight.git", "http_url_to_repo": "http://localhost:3000/twitter/flight.git", "web_url": "http://localhost:3000/twitter/flight", @@ -177,6 +178,7 @@ Example response: "ruby", "tests" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 13, @@ -475,7 +477,8 @@ Example response: "path_with_namespace": "twitter/flight", "created_at": "2017-09-05T07:58:01.621Z", "default_branch": "master", - "tag_list":[], + "tag_list":[], //deprecated, use `topics` instead + "topics":[], "ssh_url_to_repo": "ssh://jarka@localhost:2222/twitter/flight.git", "http_url_to_repo": "http://localhost:3000/twitter/flight.git", "web_url": "http://localhost:3000/twitter/flight", @@ -598,6 +601,7 @@ Example response: "ruby", "tests" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 13, @@ -956,6 +960,7 @@ Example response: "ruby", "tests" ], + "draft": false, "work_in_progress": false, "milestone": { "id": 13, diff --git a/doc/api/services.md b/doc/api/services.md index e658c51f7e6..0a26a88de70 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Services API **(FREE)** NOTE: -This API requires an access token with Maintainer or Owner permissions. +This API requires an access token with the [Maintainer or Owner role](../user/permissions.md). ## List all active services @@ -754,7 +754,7 @@ Set Jira service for a project. > Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and > `project_url` are replaced by `url`. If you are using an -> older version, [follow this documentation](https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable-ee/doc/api/services.md#jira). +> older version, [follow this documentation](https://gitlab.com/gitlab-org/gitlab/-/blob/8-13-stable-ee/doc/api/services.md#jira). ```plaintext PUT /projects/:id/services/jira diff --git a/doc/api/settings.md b/doc/api/settings.md index ada1d0e7fc4..8225713fc00 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -241,16 +241,19 @@ listed in the descriptions of the relevant settings. | `check_namespace_plan` | boolean | no | **(PREMIUM)** Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | +| `deactivate_dormant_users` | boolean | no | Enable [atomatic deactivation of dormant users](../user/admin_area/moderate_users.md#automatically-deactivate-dormant-users). | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts. | | `default_branch_protection` | integer | no | Determine if developers can push to the default branch. Can take: `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push, or delete, the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. | -| `default_ci_config_path` | string | no | Default CI configuration path for new projects (`.gitlab-ci.yml` if not set). | +| `default_ci_config_path` | string | no | Default CI/CD configuration file and path for new projects (`.gitlab-ci.yml` if not set). | | `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_project_creation` | integer | no | Default project creation protection. Can take: `0` _(No one)_, `1` _(Maintainers)_ or `2` _(Developers + Maintainers)_| | `default_project_visibility` | string | no | What visibility level new projects receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_projects_limit` | integer | no | Project limit per user. Default is `100000`. | | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `deletion_adjourned_period` | integer | no | **(PREMIUM SELF)** The number of days to wait before deleting a project or group that is marked for deletion. Value must be between 0 and 90. -| `diff_max_patch_bytes` | integer | no | Maximum diff patch size (Bytes). | +| `diff_max_patch_bytes` | integer | no | Maximum [diff patch size](../user/admin_area/diff_limits.md), in bytes. | +| `diff_max_files` | integer | no | Maximum [files in a diff](../user/admin_area/diff_limits.md). | +| `diff_max_lines` | integer | no | Maximum [lines in a diff](../user/admin_area/diff_limits.md). | | `disable_feed_token` | boolean | no | Disable display of RSS/Atom and calendar feed tokens ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231493) in GitLab 13.7) | | `disabled_oauth_sign_in_sources` | array of strings | no | Disabled OAuth sign-in sources. | | `dns_rebinding_protection_enabled` | boolean | no | Enforce DNS rebinding attack protection. | diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md index cc7f703f334..3454073cc8c 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -230,8 +230,10 @@ Supported attributes: Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ ---data '{"destination_storage_name":"storage2"}' "https://gitlab.example.com/api/v4/snippets/1/repository_storage_moves" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ + --data '{"destination_storage_name":"storage2"}' \ + "https://gitlab.example.com/api/v4/snippets/1/repository_storage_moves" ``` Example response: @@ -279,8 +281,10 @@ Supported attributes: Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ ---data '{"source_storage_name":"default"}' "https://gitlab.example.com/api/v4/snippet_repository_storage_moves" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ + --data '{"source_storage_name":"default"}' \ + "https://gitlab.example.com/api/v4/snippet_repository_storage_moves" ``` Example response: diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md new file mode 100644 index 00000000000..f4e384a2efb --- /dev/null +++ b/doc/api/status_checks.md @@ -0,0 +1,201 @@ +--- +stage: Manage +group: Compliance +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, api +--- + +# External Status Checks API **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0. +> - It's [deployed behind a feature flag](../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-status-checks). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +## List status checks for a merge request + +For a single merge request, list the external status checks that apply to it and their status. + +```plaintext +GET /projects/:id/merge_requests/:merge_request_iid/status_checks +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +| ------------------------ | ------- | -------- | -------------------------- | +| `id` | integer | yes | ID of a project | +| `merge_request_iid` | integer | yes | IID of a merge request | + +```json +[ + { + "id": 2, + "name": "Rule 1", + "external_url": "https://gitlab.com/test-endpoint", + "status": "approved" + }, + { + "id": 1, + "name": "Rule 2", + "external_url": "https://gitlab.com/test-endpoint-2", + "status": "pending" + } +] +``` + +## Set approval status of an external status check + +For a single merge request, use the API to inform GitLab that a merge request has been approved by an external service. + +```plaintext +POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +| ------------------------ | ------- | -------- | -------------------------------------- | +| `id` | integer | yes | ID of a project | +| `merge_request_iid` | integer | yes | IID of a merge request | +| `sha` | string | yes | SHA at `HEAD` of the source branch | + +NOTE: +`sha` must be the SHA at the `HEAD` of the merge request's source branch. + +## Enable or disable status checks **(ULTIMATE SELF)** + +Status checks are under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) +can enable it. + +## Get project external status checks **(ULTIMATE)** + +You can request information about a project's external status checks using the following endpoint: + +```plaintext +GET /projects/:id/external_status_checks +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | + +```json +[ + { + "id": 1, + "name": "Compliance Check", + "project_id": 6, + "external_url": "https://gitlab.com/example/test.json", + "protected_branches": [ + { + "id": 14, + "project_id": 6, + "name": "master", + "created_at": "2020-10-12T14:04:50.787Z", + "updated_at": "2020-10-12T14:04:50.787Z", + "code_owner_approval_required": false + } + ] + } +] +``` + +### Create external status check **(ULTIMATE)** + +You can create a new external status check for a project using the following endpoint: + +```plaintext +POST /projects/:id/external_status_checks +``` + +| Attribute | Type | Required | Description | +|------------------------|----------------|----------|----------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `name` | string | yes | Display name of status check | +| `external_url` | string | yes | URL of status check resource | +| `protected_branch_ids` | `array<Integer>` | no | The ids of protected branches to scope the rule by | + +### Delete external status check **(ULTIMATE)** + +You can delete an external status check for a project using the following endpoint: + +```plaintext +DELETE /projects/:id/external_status_checks/:check_id +``` + +| Attribute | Type | Required | Description | +|------------------------|----------------|----------|----------------------------------------------------| +| `rule_id` | integer | yes | The ID of an status check | +| `id` | integer | yes | The ID of a project | + +### Update external status check **(ULTIMATE)** + +You can update an existing external status check for a project using the following endpoint: + +```plaintext +PUT /projects/:id/external_status_checks/:check_id +``` + +| Attribute | Type | Required | Description | +|------------------------|----------------|----------|----------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `rule_id` | integer | yes | The ID of an external status check | +| `name` | string | no | Display name of status check | +| `external_url` | string | no | URL of external status check resource | +| `protected_branch_ids` | `array<Integer>` | no | The ids of protected branches to scope the rule by | + +### Enable or disable External Project-level MR status checks **(ULTIMATE SELF)** + +Enable or disable External Project-level MR status checks is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../user/feature_flags.md) +can enable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:ff_compliance_approval_gates) +# For a single project +Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:ff_compliance_approval_gates) +# For a single project +Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>)) +``` + +To enable it: + +```ruby +# For the instance +Feature.enable(:ff_compliance_approval_gates) +# For a single project +Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:ff_compliance_approval_gates) +# For a single project +Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>) +``` + +## Related links + +- [External status checks](../user/project/merge_requests/status_checks.md) diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md index 0fcb6122505..ea9baa79b4a 100644 --- a/doc/api/suggestions.md +++ b/doc/api/suggestions.md @@ -7,6 +7,8 @@ type: reference, api # Suggest Changes API **(FREE)** +This page describes the API for [suggesting changes](../user/project/merge_requests/reviews/suggestions.md). + Every API call to suggestions must be authenticated. ## Applying suggestions diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 101769e6323..1f0bce1c78f 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -8,8 +8,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w All methods require administrator authorization. -The URL endpoint of the system hooks can also be configured using the UI in -the **Admin Area > System Hooks** (`/admin/hooks`). +You can configure the URL endpoint of the system hooks from the GitLab user interface: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. Select **System Hooks** (`/admin/hooks`). Read more about [system hooks](../system_hooks/system_hooks.md). diff --git a/doc/api/tags.md b/doc/api/tags.md index 3ac4e8bb6ab..53a981256aa 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -123,7 +123,6 @@ Parameters: | `tag_name` | string | yes | The name of a tag | | `ref` | string | yes | Create tag using commit SHA, another tag name, or branch name | | `message` | string | no | Creates annotated tag | -| `release_description` | string | no | This parameter is [deprecated](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) for use in GitLab 11.7, and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/290311) in GitLab 14.0. Use the [Releases API](../api/releases/index.md) instead. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/tags?tag_name=test&ref=master" @@ -149,10 +148,7 @@ Example response: "committer_email": "jack@example.com", "committed_date": "2012-05-28T04:42:42-07:00" }, - "release": { - "tag_name": "1.0.0", - "description": "Amazing release. Wow" - }, + "release": null, "name": "v1.0.0", "target": "2695effb5807a22ff3d138d593fd856244e155e7", "message": null, @@ -182,82 +178,3 @@ Parameters: | ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of a tag | - -## Create a new release - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) -for use in GitLab 11.7, and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/290311) -in GitLab 14.0. Use the [Releases API](../api/releases/index.md) instead. - -Add release notes to the existing Git tag. If there -already exists a release for the given tag, status code `409` is returned. - -```plaintext -POST /projects/:id/repository/tags/:tag_name/release -``` - -Parameters: - -| 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 | -| `tag_name` | string | yes | The name of a tag | - -Request body: - -- `description` (required) - Release notes with Markdown support - -```json -{ - "description": "Amazing release. Wow" -} -``` - -Response: - -```json -{ - "tag_name": "1.0.0", - "description": "Amazing release. Wow" -} -``` - -## Update a release - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) -for use in GitLab 11.7, and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/290311) -in GitLab 14.0. Use the [Releases API](../api/releases/index.md) instead. - -Updates the release notes of a given release. - -```plaintext -PUT /projects/:id/repository/tags/:tag_name/release -``` - -Parameters: - -| 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 | -| `tag_name` | string | yes | The name of a tag | - -Request body: - -- `description` (required) - Release notes with Markdown support - -```json -{ - "description": "Amazing release. Wow" -} -``` - -Response: - -```json -{ - "tag_name": "1.0.0", - "description": "Amazing release. Wow" -} -``` diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index 6eedf8d2bc0..2d7e926561f 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.md @@ -75,10 +75,6 @@ Example response: "name": "OpenJDK" }, { - "key": "OpenJDK-alpine", - "name": "OpenJDK-alpine" - }, - { "key": "PHP", "name": "PHP" }, diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index 9475febdaec..388556d354f 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/api/todos.md b/doc/api/todos.md index 864f87f988e..69c0f760a29 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -88,6 +88,7 @@ Example Response: "source_project_id": 2, "target_project_id": 2, "labels": [], + "draft": false, "work_in_progress": false, "milestone": { "id": 32, @@ -161,6 +162,7 @@ Example Response: "source_project_id": 2, "target_project_id": 2, "labels": [], + "draft": false, "work_in_progress": false, "milestone": { "id": 32, @@ -259,6 +261,7 @@ Example Response: "source_project_id": 2, "target_project_id": 2, "labels": [], + "draft": false, "work_in_progress": false, "milestone": { "id": 32, diff --git a/doc/api/users.md b/doc/api/users.md index ac8fbe8492f..0e7b197b106 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -207,7 +207,7 @@ Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see ``` Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see -the `group_saml` provider option: +the `group_saml` provider option and `provisioned_by_group_id` parameter: ```json [ @@ -220,6 +220,7 @@ the `group_saml` provider option: {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}, {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10} ], + "provisioned_by_group_id": 123789 ... } ] @@ -374,7 +375,7 @@ the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minu ``` Users on GitLab.com [Premium or higher](https://about.gitlab.com/pricing/) also -see the `group_saml` option: +see the `group_saml` option and `provisioned_by_group_id` parameter: ```json { @@ -388,6 +389,7 @@ see the `group_saml` option: {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}, {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10} ], + "provisioned_by_group_id": 123789 ... } ``` @@ -630,7 +632,14 @@ GET /user } ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, `is_auditor`, and `using_license_seat` parameters. +Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see these +parameters: + +- `shared_runners_minutes_limit` +- `extra_shared_runners_minutes_limit` +- `is_auditor` +- `provisioned_by_group_id` +- `using_license_seat` ## User status @@ -684,6 +693,29 @@ Example response: } ``` +## Get user preferences + +Get a list of currently authenticated user's preferences. + +```plaintext +GET /user/preferences +``` + +Example response: + +```json +{ + "id": 1, + "user_id": 1 + "view_diffs_file_by_file": true, + "show_whitespace_in_diffs": false +} +``` + +Parameters: + +- **none** + ## User preference modification Update the current user's preferences. @@ -696,7 +728,8 @@ PUT /user/preferences { "id": 1, "user_id": 1 - "view_diffs_file_by_file": true + "view_diffs_file_by_file": true, + "show_whitespace_in_diffs": false } ``` @@ -705,6 +738,7 @@ Parameters: | Attribute | Required | Description | | :--------------------------- | :------- | :---------------------------------------------------------- | | `view_diffs_file_by_file` | Yes | Flag indicating the user sees only one file diff per page. | +| `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. | ## Set user status @@ -723,7 +757,8 @@ PUT /user/status When both parameters `emoji` and `message` are empty, the status is cleared. When the `clear_status_after` parameter is missing from the request, the previously set value for `"clear_status_after` is cleared. ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "clear_status_after=1_day" --data "emoji=coffee" --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "clear_status_after=1_day" --data "emoji=coffee" \ + --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status" ``` Example responses @@ -1058,7 +1093,8 @@ Parameters: | key | string | yes | The new GPG key | ```shell -curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys" +curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys" ``` Example response: @@ -1169,7 +1205,8 @@ Parameters: | `key_id` | integer | yes | The ID of the GPG key | ```shell -curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys" +curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys" ``` Example response: @@ -1579,7 +1616,8 @@ POST /users/:user_id/impersonation_tokens | `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user`) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \ + --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens" ``` Example response: @@ -1643,7 +1681,8 @@ POST /users/:user_id/personal_access_tokens | `scopes` | array | yes | The array of scopes of the personal access token (`api`, `read_user`, `read_api`, `read_repository`, `write_repository`) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/personal_access_tokens" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \ + --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/personal_access_tokens" ``` Example response: diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index f70662c7c61..6d01d7e7d96 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -199,13 +199,13 @@ Example response: ```csv Group Name,Project Name,Scanner Type,Scanner Name,Status,Vulnerability,Details,Additional Info,Severity,CVE,CWE,Other Identifiers -Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2017-16997 in glibc,,CVE-2017-16997 in glibc,critical,CVE-2017-16997 -Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2017-18269 in glibc,,CVE-2017-18269 in glibc,critical,CVE-2017-18269 -Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2018-1000001 in glibc,,CVE-2018-1000001 in glibc,high,CVE-2018-1000001 -Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2016-10228 in glibc,,CVE-2016-10228 in glibc,medium,CVE-2016-10228 -Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2010-4052 in glibc,,CVE-2010-4052 in glibc,low,CVE-2010-4052 -Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2018-18520 in elfutils,,CVE-2018-18520 in elfutils,low,CVE-2018-18520 -Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2018-16869 in nettle,,CVE-2018-16869 in nettle,unknown,CVE-2018-16869,CWE-1 +Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2017-16997 in glibc,,CVE-2017-16997 in glibc,critical,CVE-2017-16997 +Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2017-18269 in glibc,,CVE-2017-18269 in glibc,critical,CVE-2017-18269 +Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2018-1000001 in glibc,,CVE-2018-1000001 in glibc,high,CVE-2018-1000001 +Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2016-10228 in glibc,,CVE-2016-10228 in glibc,medium,CVE-2016-10228 +Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2010-4052 in glibc,,CVE-2010-4052 in glibc,low,CVE-2010-4052 +Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2018-18520 in elfutils,,CVE-2018-18520 in elfutils,low,CVE-2018-18520 +Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2018-16869 in nettle,,CVE-2018-16869 in nettle,unknown,CVE-2018-16869,CWE-1 Gitlab.org,Defend,dependency_scanning,Gemnasium,detected,Regular Expression Denial of Service in debug,,Regular Expression Denial of Service in debug,unknown,CVE-2021-1234,CWE-2,"""yarn.lock:debug:gemnasium:37283ed4-0380-40d7-ada7-2d994afcc62a""" Gitlab.org,Defend,dependency_scanning,Gemnasium,detected,Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js,,Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js,unknown,,,"""yarn.lock:saml2-js:gemnasium:9952e574-7b5b-46fa-a270-aeb694198a98""" Gitlab.org,Defend,sast,Find Security Bugs,detected,Predictable pseudorandom number generator,,Predictable pseudorandom number generator,medium,,,"""818bf5dacb291e15d9e6dc3c5ac32178:PREDICTABLE_RANDOM:src/main/java/com/gitlab/security_products/tests/App.java:47""" diff --git a/doc/api/wikis.md b/doc/api/wikis.md index 569708cdfcc..d6cc6f938b8 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -64,7 +64,7 @@ GET /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `slug` | string | yes | The slug (a unique string) of the wiki page | +| `slug` | string | yes | URLencoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/home" @@ -97,7 +97,8 @@ POST /projects/:id/wikis | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | ```shell -curl --data "format=rdoc&title=Hello&content=Hello world" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis" +curl --data "format=rdoc&title=Hello&content=Hello world" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis" ``` Example response: @@ -125,10 +126,11 @@ PUT /projects/:id/wikis/:slug | `content` | string | yes if `title` is not provided | The content of the wiki page | | `title` | string | yes if `content` is not provided | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | -| `slug` | string | yes | The slug (a unique string) of the wiki page | +| `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell -curl --request PUT --data "format=rdoc&content=documentation&title=Docs" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" +curl --request PUT --data "format=rdoc&content=documentation&title=Docs" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" ``` Example response: @@ -153,7 +155,7 @@ DELETE /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `slug` | string | yes | The slug (a unique string) of the wiki page | +| `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" @@ -182,7 +184,8 @@ The `file=` parameter must point to a file on your file system and be preceded by `@`. For example: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/1/wikis/attachments" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/1/wikis/attachments" ``` Example response: |