diff options
Diffstat (limited to 'doc/api')
41 files changed, 881 insertions, 397 deletions
diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 32411a2f557..adaae78f1b5 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -17,7 +17,7 @@ following levels are recognized: - Reporter (`20`) - Developer (`30`) - Maintainer (`40`) -- Owner (`50`) - Only valid to set for groups +- Owner (`50`). Valid for projects in [GitLab 14.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/21432). ## List access requests for a group or project diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 9408e7c25a6..aa942582e9c 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -24,7 +24,7 @@ The following API resources are available in the project context: | Resource | Available endpoints | |:------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | -| [Access tokens](project_access_tokens.md) | `/projects/:id/access_tokens` (also available for groups) | +| [Access tokens](project_access_tokens.md) | `/projects/:id/access_tokens` (also available for groups) | | [Agents](cluster_agents.md) | `/projects/:id/cluster_agents` | | [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | | [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | @@ -57,6 +57,7 @@ The following API resources are available in the project context: | [Merge request approvals](merge_request_approvals.md) **(PREMIUM)** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | | [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | | [Merge trains](merge_trains.md) | `/projects/:id/merge_trains` | +| [Metadata](metadata.md) | `/metadata` | | [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups) | | [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | | [Packages](packages.md) | `/projects/:id/packages` | @@ -70,7 +71,7 @@ The following API resources are available in the project context: | [Project milestones](milestones.md) | `/projects/:id/milestones` | | [Project snippets](project_snippets.md) | `/projects/:id/snippets` | | [Project templates](project_templates.md) | `/projects/:id/templates` | -| [Project vulnerabilities](project_vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/vulnerabilities` | +| [Project vulnerabilities](project_vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/vulnerabilities` | | [Project wikis](wikis.md) | `/projects/:id/wikis` | | [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | | [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 4ddd851ebda..753e01a15aa 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -131,7 +131,8 @@ Example response: ## Group Audit Events -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34078) in GitLab 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34078) in GitLab 12.5. +> - [Support for keyset pagination added](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2. 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. @@ -139,6 +140,10 @@ 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. +This endpoint optionally supports [keyset pagination](index.md#keyset-based-pagination): + +- When requesting consecutive pages of results, we recommend you use keyset pagination. + ### Retrieve all group audit events ```plaintext diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 61f84dfb812..5b350dd88c6 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -23,7 +23,10 @@ See [Award Emoji on Comments](#award-emoji-on-comments) for information on using ### List an awardable's award emojis -Get a list of all award emojis for a specified awardable. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public awardables. + +Get a list of all award emojis for a specified awardable. This endpoint can +be accessed without authentication if the awardable is publicly accessible. ```plaintext GET /projects/:id/issues/:issue_iid/award_emoji @@ -85,7 +88,10 @@ Example response: ### Get single award emoji -Get a single award emoji from an issue, snippet, or merge request. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public awardables. + +Get a single award emoji from an issue, snippet, or merge request. This endpoint can +be accessed without authentication if the awardable is publicly accessible. ```plaintext GET /projects/:id/issues/:issue_iid/award_emoji/:award_id @@ -206,7 +212,10 @@ adapted to comments on merge requests and snippets. Therefore, you have to repla ### List a comment's award emojis -Get all award emojis for a comment (note). +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public comments. + +Get all award emojis for a comment (note). This endpoint can +be accessed without authentication if the comment is publicly accessible. ```plaintext GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji @@ -251,7 +260,10 @@ Example response: ### Get an award emoji for a comment -Get a single award emoji for a comment (note). +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/335068) in GitLab 15.1 to allow unauthenticated access to public comments. + +Get a single award emoji for a comment (note). This endpoint can +be accessed without authentication if the comment is publicly accessible. ```plaintext GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index 2252568be61..6c95bf2fda5 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -1,6 +1,6 @@ --- stage: Growth -group: Activation +group: Acquisition 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/deploy_keys.md b/doc/api/deploy_keys.md index adeda014af0..40641c6e2f7 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -6,6 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Deploy keys API **(FREE)** +The deploy keys API can return in responses fingerprints of the public key in the following fields: + +- `fingerprint` (MD5 hash). Not available on FIPS-enabled systems. +- `fingerprint_sha256` (SHA256 hash). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91302) in GitLab 15.2. + ## List all deploy keys **(FREE SELF)** Get a list of all deploy keys across all projects of the GitLab instance. This @@ -34,8 +39,9 @@ Example response: { "id": 1, "title": "Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "fingerprint": "7f:72:08:7d:0e:47:48:ec:37:79:b2:76:68:b5:87:65", + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDNJAkI3Wdf0r13c8a5pEExB2YowPWCSVzfZV22pNBc1CuEbyYLHpUyaD0GwpGvFdx2aP7lMEk35k6Rz3ccBF6jRaVJyhsn5VNnW92PMpBJ/P1UebhXwsFHdQf5rTt082cSxWuk61kGWRQtk4ozt/J2DF/dIUVaLvc+z4HomT41fQ==", + "fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9", + "fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU", "created_at": "2013-10-02T10:12:29Z", "projects_with_write_access": [ { @@ -61,8 +67,9 @@ Example response: { "id": 3, "title": "Another Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "fingerprint": "64:d3:73:d4:83:70:ab:41:96:68:d5:3d:a5:b0:34:ea", + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDIJFwIL6YNcCgVBLTHgM6hzmoL5vf0ThDKQMWT3HrwCjUCGPwR63vBwn6+/Gx+kx+VTo9FuojzR0O4XfwD3LrYA+oT3ETbn9U4e/VS4AH/G4SDMzgSLwu0YuPe517FfGWhWGQhjiXphkaQ+6bXPmcASWb0RCO5+pYlGIfxv4eFGQ==" + "fingerprint": "0b:cf:58:40:b9:23:96:c7:ba:44:df:0e:9e:87:5e:75", + "fingerprint_sha256": "SHA256:lGI/Ys/Wx7PfMhUO1iuBH92JQKYN+3mhJZvWO4Q5ims", "created_at": "2013-10-02T11:12:29Z", "projects_with_write_access": [] } @@ -92,14 +99,18 @@ Example response: { "id": 1, "title": "Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDNJAkI3Wdf0r13c8a5pEExB2YowPWCSVzfZV22pNBc1CuEbyYLHpUyaD0GwpGvFdx2aP7lMEk35k6Rz3ccBF6jRaVJyhsn5VNnW92PMpBJ/P1UebhXwsFHdQf5rTt082cSxWuk61kGWRQtk4ozt/J2DF/dIUVaLvc+z4HomT41fQ==", + "fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9", + "fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU", "created_at": "2013-10-02T10:12:29Z", "can_push": false }, { "id": 3, "title": "Another Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDIJFwIL6YNcCgVBLTHgM6hzmoL5vf0ThDKQMWT3HrwCjUCGPwR63vBwn6+/Gx+kx+VTo9FuojzR0O4XfwD3LrYA+oT3ETbn9U4e/VS4AH/G4SDMzgSLwu0YuPe517FfGWhWGQhjiXphkaQ+6bXPmcASWb0RCO5+pYlGIfxv4eFGQ==" + "fingerprint": "0b:cf:58:40:b9:23:96:c7:ba:44:df:0e:9e:87:5e:75", + "fingerprint_sha256": "SHA256:lGI/Ys/Wx7PfMhUO1iuBH92JQKYN+3mhJZvWO4Q5ims", "created_at": "2013-10-02T11:12:29Z", "can_push": false } @@ -129,16 +140,18 @@ Parameters: "title": "Key A", "created_at": "2022-05-30T12:28:27.855Z", "expires_at": null, - "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTEVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57 Key", - "fingerprint": "60:8e:10:f0:6a:82:c8:29:5f:bf:c0:38:72:00:6f:8f" + "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILkYXU2fVeO4/0rDCSsswP5iIX2+B6tv15YT3KObgyDl Key", + "fingerprint": "40:8e:fa:df:70:f7:a7:06:1e:0d:6f:ae:f2:27:92:01", + "fingerprint_sha256": "SHA256:Ojq2LZW43BFK/AMP81jBkDGn9YpPWYRNcViKBB44LPU" }, { "id": 2, "title": "Key B", "created_at": "2022-05-30T13:34:56.219Z", "expires_at": null, - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "fingerprint": "75:33:44:7e:55:84:dd:70:29:a3:8e:a3:c0:b9:8b:65" + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDNJAkI3Wdf0r13c8a5pEExB2YowPWCSVzfZV22pNBc1CuEbyYLHpUyaD0GwpGvFdx2aP7lMEk35k6Rz3ccBF6jRaVJyhsn5VNnW92PMpBJ/P1UebhXwsFHdQf5rTt082cSxWuk61kGWRQtk4ozt/J2DF/dIUVaLvc+z4HomT41fQ==", + "fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9", + "fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU", } ] ``` @@ -156,8 +169,9 @@ Example response: "title": "Key A", "created_at": "2022-05-30T12:28:27.855Z", "expires_at": "2022-10-30T12:28:27.855Z", - "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTEVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57 Key", - "fingerprint": "60:8e:10:f0:6a:82:c8:29:5f:bf:c0:38:72:00:6f:8f" + "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILkYXU2fVeO4/0rDCSsswP5iIX2+B6tv15YT3KObgyDl Key", + "fingerprint": "40:8e:fa:df:70:f7:a7:06:1e:0d:6f:ae:f2:27:92:01", + "fingerprint_sha256": "SHA256:Ojq2LZW43BFK/AMP81jBkDGn9YpPWYRNcViKBB44LPU" } ] ``` @@ -187,7 +201,9 @@ Example response: { "id": 1, "title": "Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDNJAkI3Wdf0r13c8a5pEExB2YowPWCSVzfZV22pNBc1CuEbyYLHpUyaD0GwpGvFdx2aP7lMEk35k6Rz3ccBF6jRaVJyhsn5VNnW92PMpBJ/P1UebhXwsFHdQf5rTt082cSxWuk61kGWRQtk4ozt/J2DF/dIUVaLvc+z4HomT41fQ==", + "fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9", + "fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU", "created_at": "2013-10-02T10:12:29Z", "can_push": false } diff --git a/doc/api/deployments.md b/doc/api/deployments.md index fb255bfa226..6831f86e4ea 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -345,7 +345,7 @@ POST /projects/:id/deployments | `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`. | +| `status` | string | yes | The status to filter deployments by. One of `running`, `success`, `failed`, or `canceled`. | ```shell curl --data "environment=production&sha=a91957a858320c0e17f3a0eca7cfacbff50ea29a&ref=main&tag=false&status=success" \ @@ -400,7 +400,7 @@ PUT /projects/:id/deployments/:deployment_id |------------------|----------------|----------|---------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.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`. | +| `status` | string | yes | The new status of the deployment. One of `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" diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index f5373d02156..99473ca7b4c 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -21,14 +21,15 @@ Get project-level DORA metrics. GET /projects/:id/dora/metrics ``` -| Attribute | Type | Required | Description | -|-------------- |-------- |----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | -| `metric` | string | yes | The metric name: `deployment_frequency`, `lead_time_for_changes` or `time_to_restore_service`.| -| `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | -| `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | -| `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | -| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | +| Attribute | Type | Required | Description | +|:---------------------|:-----------------|:---------|:------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `metric` | string | yes | One of `deployment_frequency`, `lead_time_for_changes`, `time_to_restore_service` or `change_failure_rate`. | +| `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | +| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, please use `environment_tiers`. | +| `environment_tiers` | array of strings | no | The [tiers of the environments](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | +| `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | +| `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | Example request: @@ -61,14 +62,15 @@ Get group-level DORA metrics. GET /groups/:id/dora/metrics ``` -| Attribute | Type | Required | Description | -|-------------- |-------- |----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | -| `metric` | string | yes | One of `deployment_frequency`, `lead_time_for_changes`, `time_to_restore_service` or `change_failure_rate`. | -| `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | -| `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | -| `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | -| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | +| Attribute | Type | Required | Description | +|:--------------------|:-----------------|:---------|:------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `metric` | string | yes | One of `deployment_frequency`, `lead_time_for_changes`, `time_to_restore_service` or `change_failure_rate`. | +| `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | +| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, please use `environment_tiers`. | +| `environment_tiers` | array of strings | no | The [tiers of the environments](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | +| `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | +| `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | Example request: @@ -97,9 +99,9 @@ For both the project and group-level endpoints above, the `value` field in the API response has a different meaning depending on the provided `metric` query parameter: -| `metric` query parameter | Description of `value` in response | -| ------------------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `deployment_frequency` | The number of successful deployments during the time period. | -| `lead_time_for_changes` | The median number of seconds between the merge of the merge request (MR) and the deployment of the MR's commits for all MRs deployed during the time period. | -| `time_to_restore_service` | The median number of seconds an incident was open during the time period. Available only for production environment. | -| `change_failure_rate` | The number of incidents divided by the number of deployments during the time period. Available only for production environment. | +| `metric` query parameter | Description of `value` in response | +|:---------------------------|:-----------------------------------| +| `change_failure_rate` | The number of incidents divided by the number of deployments during the time period. Available only for production environment. | +| `deployment_frequency` | The number of successful deployments during the time period. | +| `lead_time_for_changes` | The median number of seconds between the merge of the merge request (MR) and the deployment of the MR's commits for all MRs deployed during the time period. | +| `time_to_restore_service` | The median number of seconds an incident was open during the time period. Available only for production environment. | diff --git a/doc/api/dora4_project_analytics.md b/doc/api/dora4_project_analytics.md deleted file mode 100644 index 19c7afd9d22..00000000000 --- a/doc/api/dora4_project_analytics.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -stage: Manage -group: Optimize -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 -remove_date: '2022-05-18' -redirect_to: 'dora/metrics.md' ---- - -# DORA4 Analytics Project API (removed) **(ULTIMATE)** - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.11 and removed in GitLab 14.0. Use the [DORA metrics API](dora/metrics.md) instead. diff --git a/doc/api/experiments.md b/doc/api/experiments.md index 669d00454bd..6393a358e51 100644 --- a/doc/api/experiments.md +++ b/doc/api/experiments.md @@ -1,6 +1,6 @@ --- stage: Growth -group: Expansion +group: Acquisition 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/feature_flags.md b/doc/api/feature_flags.md index 0ad7b04d4f7..b00917674b0 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -144,7 +144,7 @@ POST /projects/:id/feature_flags | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the feature flag. | -| `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit or set to `legacy_flag` to create a [Legacy Feature Flag](feature_flags_legacy.md). | +| `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit or set to `legacy_flag` to create a Legacy 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. | | `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). | diff --git a/doc/api/feature_flags_legacy.md b/doc/api/feature_flags_legacy.md deleted file mode 100644 index 1cf05144a1b..00000000000 --- a/doc/api/feature_flags_legacy.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'feature_flags.md' -remove_date: '2022-06-22' ---- - -This document was moved to [another location](feature_flags). - -<!-- This redirect file can be deleted after <2022-06-22>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 09b97a78e04..be1bfc79aeb 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -61,14 +61,6 @@ You can work with sample queries that pull data from public projects on GitLab.c The [get started](getting_started.md) page includes different methods to customize GraphQL queries. -### Update the GraphQL API reference - -If you change the GraphQL schema, create a merge request to get your changes approved. -To generate the required documentation and schema, see -[Rake tasks for developers](../../development/rake_tasks.md#update-graphql-documentation-and-schema-definitions). - -Run the commands using the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/). - ## Breaking changes The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible. diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 805f6a506b7..fbf6bc116f4 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -87,6 +87,16 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="queryciminutesusagenamespaceid"></a>`namespaceId` | [`NamespaceID`](#namespaceid) | Global ID of the Namespace for the monthly CI/CD minutes usage. | +### `Query.ciVariables` + +List of the instance's CI/CD variables. + +Returns [`CiVariableConnection`](#civariableconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + ### `Query.containerRepository` Find a container repository. @@ -377,6 +387,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <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). | | <a id="queryrunnerstype"></a>`type` | [`CiRunnerType`](#cirunnertype) | Filter runners by type. | +| <a id="queryrunnersupgradestatus"></a>`upgradeStatus` | [`CiRunnerUpgradeStatusType`](#cirunnerupgradestatustype) | Filter by upgrade status. | ### `Query.snippets` @@ -431,6 +442,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="querytimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="querytimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | +### `Query.todo` + +Retrieve a single to-do item. + +Returns [`Todo`](#todo). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querytodoid"></a>`id` | [`TodoID!`](#todoid) | ID of the to-do item. | + ### `Query.topics` Find project topics. @@ -756,6 +779,27 @@ Input type: `AuditEventsStreamingHeadersDestroyInput` | <a id="mutationauditeventsstreamingheadersdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationauditeventsstreamingheadersdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.auditEventsStreamingHeadersUpdate` + +Input type: `AuditEventsStreamingHeadersUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsstreamingheadersupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsstreamingheadersupdateheaderid"></a>`headerId` | [`AuditEventsStreamingHeaderID!`](#auditeventsstreamingheaderid) | Header to update. | +| <a id="mutationauditeventsstreamingheadersupdatekey"></a>`key` | [`String!`](#string) | Header key. | +| <a id="mutationauditeventsstreamingheadersupdatevalue"></a>`value` | [`String!`](#string) | Header value. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsstreamingheadersupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsstreamingheadersupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationauditeventsstreamingheadersupdateheader"></a>`header` | [`AuditEventStreamingHeader`](#auditeventstreamingheader) | Updates header. | + ### `Mutation.awardEmojiAdd` Input type: `AwardEmojiAddInput` @@ -1391,6 +1435,7 @@ Input type: `CreateEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcreateepicaddlabelids"></a>`addLabelIds` | [`[ID!]`](#id) | IDs of labels to be added to the epic. | +| <a id="mutationcreateepicaddlabels"></a>`addLabels` | [`[String!]`](#string) | Array of labels to be added to the epic. | | <a id="mutationcreateepicclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcreateepiccolor"></a>`color` | [`Color`](#color) | Color of the epic. Available only when feature flag `epic_color_highlight` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | | <a id="mutationcreateepicconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | @@ -2904,6 +2949,25 @@ Input type: `IssuableResourceLinkCreateInput` | <a id="mutationissuableresourcelinkcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationissuableresourcelinkcreateissuableresourcelink"></a>`issuableResourceLink` | [`IssuableResourceLink`](#issuableresourcelink) | Issuable resource link. | +### `Mutation.issuableResourceLinkDestroy` + +Input type: `IssuableResourceLinkDestroyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuableresourcelinkdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuableresourcelinkdestroyid"></a>`id` | [`IncidentManagementIssuableResourceLinkID!`](#incidentmanagementissuableresourcelinkid) | Issuable resource link ID to remove. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuableresourcelinkdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuableresourcelinkdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationissuableresourcelinkdestroyissuableresourcelink"></a>`issuableResourceLink` | [`IssuableResourceLink`](#issuableresourcelink) | Issuable resource link. | + ### `Mutation.issueMove` Input type: `IssueMoveInput` @@ -3782,6 +3846,25 @@ Input type: `MergeRequestUpdateInput` | <a id="mutationmergerequestupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationmergerequestupdatemergerequest"></a>`mergeRequest` | [`MergeRequest`](#mergerequest) | Merge request after mutation. | +### `Mutation.namespaceBanDestroy` + +Input type: `NamespaceBanDestroyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationnamespacebandestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationnamespacebandestroyid"></a>`id` | [`NamespacesNamespaceBanID!`](#namespacesnamespacebanid) | Global ID of the namespace ban to remove. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationnamespacebandestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationnamespacebandestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationnamespacebandestroynamespaceban"></a>`namespaceBan` | [`NamespaceBan`](#namespaceban) | Namespace Ban. | + ### `Mutation.namespaceCiCdSettingsUpdate` Input type: `NamespaceCiCdSettingsUpdateInput` @@ -3958,6 +4041,25 @@ Input type: `OncallScheduleUpdateInput` | <a id="mutationoncallscheduleupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationoncallscheduleupdateoncallschedule"></a>`oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule. | +### `Mutation.pagesMarkOnboardingComplete` + +Input type: `PagesMarkOnboardingCompleteInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpagesmarkonboardingcompleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpagesmarkonboardingcompleteprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpagesmarkonboardingcompleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpagesmarkonboardingcompleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationpagesmarkonboardingcompleteonboardingcomplete"></a>`onboardingComplete` | [`Boolean!`](#boolean) | Indicates the new onboarding_complete state of the project's Pages metadata. | + ### `Mutation.pipelineCancel` Input type: `PipelineCancelInput` @@ -5016,6 +5118,7 @@ Input type: `UpdateEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationupdateepicaddlabelids"></a>`addLabelIds` | [`[ID!]`](#id) | IDs of labels to be added to the epic. | +| <a id="mutationupdateepicaddlabels"></a>`addLabels` | [`[String!]`](#string) | Array of labels to be added to the epic. | | <a id="mutationupdateepicclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationupdateepiccolor"></a>`color` | [`Color`](#color) | Color of the epic. Available only when feature flag `epic_color_highlight` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | | <a id="mutationupdateepicconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | @@ -5025,6 +5128,7 @@ Input type: `UpdateEpicInput` | <a id="mutationupdateepicgrouppath"></a>`groupPath` | [`ID!`](#id) | Group the epic to mutate is in. | | <a id="mutationupdateepiciid"></a>`iid` | [`ID!`](#id) | IID of the epic to mutate. | | <a id="mutationupdateepicremovelabelids"></a>`removeLabelIds` | [`[ID!]`](#id) | IDs of labels to be removed from the epic. | +| <a id="mutationupdateepicremovelabels"></a>`removeLabels` | [`[String!]`](#string) | Array of labels to be removed from the epic. | | <a id="mutationupdateepicstartdatefixed"></a>`startDateFixed` | [`String`](#string) | Start date of the epic. | | <a id="mutationupdateepicstartdateisfixed"></a>`startDateIsFixed` | [`Boolean`](#boolean) | Indicates start date should be sourced from start_date_fixed field not the issue milestones. | | <a id="mutationupdateepicstateevent"></a>`stateEvent` | [`EpicStateEvent`](#epicstateevent) | State event for the epic. | @@ -5419,7 +5523,8 @@ Input type: `VulnerabilityFindingDismissInput` | <a id="mutationvulnerabilityfindingdismissclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvulnerabilityfindingdismisscomment"></a>`comment` | [`String`](#string) | Comment why finding should be dismissed. | | <a id="mutationvulnerabilityfindingdismissdismissalreason"></a>`dismissalReason` | [`VulnerabilityDismissalReason`](#vulnerabilitydismissalreason) | Reason why finding should be dismissed. | -| <a id="mutationvulnerabilityfindingdismissid"></a>`id` | [`VulnerabilitiesFindingID!`](#vulnerabilitiesfindingid) | ID of the finding to be dismissed. | +| <a id="mutationvulnerabilityfindingdismissid"></a>`id` **{warning-solid}** | [`VulnerabilitiesFindingID`](#vulnerabilitiesfindingid) | **Deprecated:** Use `uuid`. Deprecated in 15.2. | +| <a id="mutationvulnerabilityfindingdismissuuid"></a>`uuid` | [`String`](#string) | UUID of the finding to be dismissed. | #### Fields @@ -5483,6 +5588,7 @@ Input type: `WorkItemCreateInput` | ---- | ---- | ----------- | | <a id="mutationworkitemcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationworkitemcreatedescription"></a>`description` | [`String`](#string) | Description of the work item. | +| <a id="mutationworkitemcreatehierarchywidget"></a>`hierarchyWidget` | [`WorkItemWidgetHierarchyCreateInput`](#workitemwidgethierarchycreateinput) | Input for hierarchy widget. | | <a id="mutationworkitemcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project the work item is associated with. | | <a id="mutationworkitemcreatetitle"></a>`title` | [`String!`](#string) | Title of the work item. | | <a id="mutationworkitemcreateworkitemtypeid"></a>`workItemTypeId` | [`WorkItemsTypeID!`](#workitemstypeid) | Global ID of a work item type. | @@ -5589,9 +5695,12 @@ Input type: `WorkItemUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationworkitemupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemupdatedescriptionwidget"></a>`descriptionWidget` | [`WorkItemWidgetDescriptionInput`](#workitemwidgetdescriptioninput) | Input for description widget. | +| <a id="mutationworkitemupdatehierarchywidget"></a>`hierarchyWidget` | [`WorkItemWidgetHierarchyUpdateInput`](#workitemwidgethierarchyupdateinput) | Input for hierarchy widget. | | <a id="mutationworkitemupdateid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | | <a id="mutationworkitemupdatestateevent"></a>`stateEvent` | [`WorkItemStateEvent`](#workitemstateevent) | Close or reopen a work item. | | <a id="mutationworkitemupdatetitle"></a>`title` | [`String`](#string) | Title of the work item. | +| <a id="mutationworkitemupdateweightwidget"></a>`weightWidget` | [`WorkItemWidgetWeightInput`](#workitemwidgetweightinput) | Input for weight widget. | #### Fields @@ -6216,6 +6325,29 @@ The edge type for [`CiStage`](#cistage). | <a id="cistageedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="cistageedgenode"></a>`node` | [`CiStage`](#cistage) | The item at the end of the edge. | +#### `CiVariableConnection` + +The connection type for [`CiVariable`](#civariable). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="civariableconnectionedges"></a>`edges` | [`[CiVariableEdge]`](#civariableedge) | A list of edges. | +| <a id="civariableconnectionnodes"></a>`nodes` | [`[CiVariable]`](#civariable) | A list of nodes. | +| <a id="civariableconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `CiVariableEdge` + +The edge type for [`CiVariable`](#civariable). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="civariableedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="civariableedgenode"></a>`node` | [`CiVariable`](#civariable) | The item at the end of the edge. | + #### `ClusterAgentActivityEventConnection` The connection type for [`ClusterAgentActivityEvent`](#clusteragentactivityevent). @@ -7166,6 +7298,29 @@ The edge type for [`IncidentManagementOncallShift`](#incidentmanagementoncallshi | <a id="incidentmanagementoncallshiftedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="incidentmanagementoncallshiftedgenode"></a>`node` | [`IncidentManagementOncallShift`](#incidentmanagementoncallshift) | The item at the end of the edge. | +#### `IssuableResourceLinkConnection` + +The connection type for [`IssuableResourceLink`](#issuableresourcelink). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="issuableresourcelinkconnectionedges"></a>`edges` | [`[IssuableResourceLinkEdge]`](#issuableresourcelinkedge) | A list of edges. | +| <a id="issuableresourcelinkconnectionnodes"></a>`nodes` | [`[IssuableResourceLink]`](#issuableresourcelink) | A list of nodes. | +| <a id="issuableresourcelinkconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `IssuableResourceLinkEdge` + +The edge type for [`IssuableResourceLink`](#issuableresourcelink). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="issuableresourcelinkedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="issuableresourcelinkedgenode"></a>`node` | [`IssuableResourceLink`](#issuableresourcelink) | The item at the end of the edge. | + #### `IssueConnection` The connection type for [`Issue`](#issue). @@ -9422,7 +9577,7 @@ Represents an epic on an issue board. | <a id="boardepicblockedbyepics"></a>`blockedByEpics` | [`EpicConnection`](#epicconnection) | Epics blocking this epic. (see [Connections](#connections)) | | <a id="boardepicblockingcount"></a>`blockingCount` | [`Int`](#int) | Count of epics that this epic is blocking. | | <a id="boardepicclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the epic was closed. | -| <a id="boardepiccolor"></a>`color` | [`String!`](#string) | Color of the epic. Available only when feature flag `epic_color_highlight` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| <a id="boardepiccolor"></a>`color` | [`String`](#string) | Color of the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | | <a id="boardepicconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | | <a id="boardepiccreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of when the epic was created. | | <a id="boardepicdescendantcounts"></a>`descendantCounts` | [`EpicDescendantCount`](#epicdescendantcount) | Number of open and closed descendant epics and issues. | @@ -9458,7 +9613,7 @@ Represents an epic on an issue board. | <a id="boardepicstartdateisfixed"></a>`startDateIsFixed` | [`Boolean`](#boolean) | Indicates if the start date has been manually set. | | <a id="boardepicstate"></a>`state` | [`EpicState!`](#epicstate) | State of the epic. | | <a id="boardepicsubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Indicates the currently logged in user is subscribed to the epic. | -| <a id="boardepictextcolor"></a>`textColor` | [`String!`](#string) | Text color generated for the epic. Available only when feature flag `epic_color_highlight` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| <a id="boardepictextcolor"></a>`textColor` | [`String`](#string) | Text color generated for the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | | <a id="boardepictitle"></a>`title` | [`String`](#string) | Title of the epic. | | <a id="boardepictitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | | <a id="boardepicupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the epic was updated. | @@ -9782,6 +9937,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="cijobid"></a>`id` | [`JobID`](#jobid) | ID of the job. | | <a id="cijobkind"></a>`kind` | [`CiJobKind!`](#cijobkind) | Indicates the type of job. | | <a id="cijobmanualjob"></a>`manualJob` | [`Boolean`](#boolean) | Whether the job has a manual action. | +| <a id="cijobmanualvariables"></a>`manualVariables` | [`CiVariableConnection`](#civariableconnection) | Variables added to a manual job when the job is triggered. (see [Connections](#connections)) | | <a id="cijobname"></a>`name` | [`String`](#string) | Name of the job. | | <a id="cijobneeds"></a>`needs` | [`CiBuildNeedConnection`](#cibuildneedconnection) | References to builds that must complete before the jobs run. (see [Connections](#connections)) | | <a id="cijobpipeline"></a>`pipeline` | [`Pipeline`](#pipeline) | Pipeline the job belongs to. | @@ -9791,6 +9947,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="cijobqueuedduration"></a>`queuedDuration` | [`Duration`](#duration) | How long the job was enqueued before starting. | | <a id="cijobrefname"></a>`refName` | [`String`](#string) | Ref name of the job. | | <a id="cijobrefpath"></a>`refPath` | [`String`](#string) | Path to the ref. | +| <a id="cijobretried"></a>`retried` | [`Boolean`](#boolean) | Indicates that the job has been retried. | | <a id="cijobretryable"></a>`retryable` | [`Boolean!`](#boolean) | Indicates the job can be retried. | | <a id="cijobscheduledat"></a>`scheduledAt` | [`Time`](#time) | Schedule for the build. | | <a id="cijobschedulingtype"></a>`schedulingType` | [`String`](#string) | Type of job scheduling. Value is `dag` if the job uses the `needs` keyword, and `stage` otherwise. | @@ -9937,6 +10094,21 @@ GitLab CI/CD configuration template. | <a id="citemplatecontent"></a>`content` | [`String!`](#string) | Contents of the CI template. | | <a id="citemplatename"></a>`name` | [`String!`](#string) | Name of the CI template. | +### `CiVariable` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="civariableenvironmentscope"></a>`environmentScope` | [`String`](#string) | Scope defining the environments in which the variable can be used. | +| <a id="civariableid"></a>`id` | [`ID!`](#id) | ID of the variable. | +| <a id="civariablekey"></a>`key` | [`String`](#string) | Name of the variable. | +| <a id="civariablemasked"></a>`masked` | [`Boolean`](#boolean) | Indicates whether the variable is masked. | +| <a id="civariableprotected"></a>`protected` | [`Boolean`](#boolean) | Indicates whether the variable is protected. | +| <a id="civariableraw"></a>`raw` | [`Boolean`](#boolean) | Indicates whether the variable is raw. | +| <a id="civariablevalue"></a>`value` | [`String`](#string) | Value of the variable. | +| <a id="civariablevariabletype"></a>`variableType` | [`CiVariableType`](#civariabletype) | Type of the variable. | + ### `ClusterAgent` #### Fields @@ -10950,7 +11122,8 @@ Returns [`[DoraMetric!]`](#dorametric). | Name | Type | Description | | ---- | ---- | ----------- | | <a id="dorametricsenddate"></a>`endDate` | [`Date`](#date) | Date range to end at. Default is the current date. | -| <a id="dorametricsenvironmenttier"></a>`environmentTier` | [`DeploymentTier`](#deploymenttier) | Deployment tier of the environments to return. Defaults to `PRODUCTION`. | +| <a id="dorametricsenvironmenttier"></a>`environmentTier` | [`DeploymentTier`](#deploymenttier) | Deployment tier of the environments to return. Deprecated, please update to `environment_tiers` param. | +| <a id="dorametricsenvironmenttiers"></a>`environmentTiers` | [`[DeploymentTier!]`](#deploymenttier) | Deployment tiers of the environments to return. Defaults to [`PRODUCTION`]. | | <a id="dorametricsinterval"></a>`interval` | [`DoraMetricBucketingInterval`](#dorametricbucketinginterval) | How the metric should be aggregrated. Defaults to `DAILY`. In the case of `ALL`, the `date` field in the response will be `null`. | | <a id="dorametricsmetric"></a>`metric` | [`DoraMetricType!`](#dorametrictype) | Type of metric to return. | | <a id="dorametricsstartdate"></a>`startDate` | [`Date`](#date) | Date range to start from. Default is 3 months ago. | @@ -11007,7 +11180,7 @@ Represents an epic. | <a id="epicblockedbyepics"></a>`blockedByEpics` | [`EpicConnection`](#epicconnection) | Epics blocking this epic. (see [Connections](#connections)) | | <a id="epicblockingcount"></a>`blockingCount` | [`Int`](#int) | Count of epics that this epic is blocking. | | <a id="epicclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the epic was closed. | -| <a id="epiccolor"></a>`color` | [`String!`](#string) | Color of the epic. Available only when feature flag `epic_color_highlight` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| <a id="epiccolor"></a>`color` | [`String`](#string) | Color of the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | | <a id="epicconfidential"></a>`confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | | <a id="epiccreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of when the epic was created. | | <a id="epicdescendantcounts"></a>`descendantCounts` | [`EpicDescendantCount`](#epicdescendantcount) | Number of open and closed descendant epics and issues. | @@ -11043,7 +11216,7 @@ Represents an epic. | <a id="epicstartdateisfixed"></a>`startDateIsFixed` | [`Boolean`](#boolean) | Indicates if the start date has been manually set. | | <a id="epicstate"></a>`state` | [`EpicState!`](#epicstate) | State of the epic. | | <a id="epicsubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Indicates the currently logged in user is subscribed to the epic. | -| <a id="epictextcolor"></a>`textColor` | [`String!`](#string) | Text color generated for the epic. Available only when feature flag `epic_color_highlight` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| <a id="epictextcolor"></a>`textColor` | [`String`](#string) | Text color generated for the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | | <a id="epictitle"></a>`title` | [`String`](#string) | Title of the epic. | | <a id="epictitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | | <a id="epicupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the epic was updated. | @@ -11322,6 +11495,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="epicissuecurrentusertodosstate"></a>`state` | [`TodoStateEnum`](#todostateenum) | State of the to-do items. | +##### `EpicIssue.issuableResourceLinks` + +Issuable resource links of the incident issue. + +Returns [`IssuableResourceLinkConnection`](#issuableresourcelinkconnection). + +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="epicissueissuableresourcelinksincidentid"></a>`incidentId` | [`IssueID!`](#issueid) | ID of the incident. | + ##### `EpicIssue.reference` Internal reference of the issue. Returned in shortened format by default. @@ -11448,7 +11637,7 @@ Represents an external resource to send audit events to. | ---- | ---- | ----------- | | <a id="externalauditeventdestinationdestinationurl"></a>`destinationUrl` | [`String!`](#string) | External destination to send audit events to. | | <a id="externalauditeventdestinationgroup"></a>`group` | [`Group!`](#group) | Group the destination belongs to. | -| <a id="externalauditeventdestinationheaders"></a>`headers` | [`AuditEventStreamingHeaderConnection!`](#auditeventstreamingheaderconnection) | List of additional HTTP headers sent with each event. Available only when feature flag `streaming_audit_event_headers` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) | +| <a id="externalauditeventdestinationheaders"></a>`headers` | [`AuditEventStreamingHeaderConnection!`](#auditeventstreamingheaderconnection) | List of additional HTTP headers sent with each event. Available only when feature flag `streaming_audit_event_headers` is enabled. This flag is enabled by default. (see [Connections](#connections)) | | <a id="externalauditeventdestinationid"></a>`id` | [`ID!`](#id) | ID of the destination. | | <a id="externalauditeventdestinationverificationtoken"></a>`verificationToken` | [`String!`](#string) | Verification token to validate source of event. | @@ -11675,6 +11864,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupallowstalerunnerpruning"></a>`allowStaleRunnerPruning` | [`Boolean!`](#boolean) | Indicates whether to regularly prune stale group runners. Defaults to false. | | <a id="groupautodevopsenabled"></a>`autoDevopsEnabled` | [`Boolean`](#boolean) | Indicates whether Auto DevOps is enabled for all projects within this group. | | <a id="groupavatarurl"></a>`avatarUrl` | [`String`](#string) | Avatar URL of the group. | +| <a id="groupcivariables"></a>`ciVariables` | [`CiVariableConnection`](#civariableconnection) | List of the group's CI/CD variables. (see [Connections](#connections)) | | <a id="groupcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the group. | | <a id="groupcontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. | | <a id="groupcrossprojectpipelineavailable"></a>`crossProjectPipelineAvailable` | [`Boolean!`](#boolean) | Indicates if the cross_project_pipeline feature is available for the namespace. | @@ -11691,6 +11881,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | | <a id="groupdora"></a>`dora` | [`Dora`](#dora) | Group's DORA metrics. | | <a id="groupemailsdisabled"></a>`emailsDisabled` | [`Boolean`](#boolean) | Indicates if a group has email notifications disabled. | +| <a id="groupenforcefreeusercap"></a>`enforceFreeUserCap` | [`Boolean`](#boolean) | Indicates whether the group has limited users for a free plan. | | <a id="groupepicboards"></a>`epicBoards` | [`EpicBoardConnection`](#epicboardconnection) | Find epic boards. (see [Connections](#connections)) | | <a id="groupepicsenabled"></a>`epicsEnabled` | [`Boolean`](#boolean) | Indicates if Epics are enabled for namespace. | | <a id="groupexternalauditeventdestinations"></a>`externalAuditEventDestinations` | [`ExternalAuditEventDestinationConnection`](#externalauditeventdestinationconnection) | External locations that receive audit events belonging to the group. (see [Connections](#connections)) | @@ -11766,6 +11957,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="groupboardsid"></a>`id` | [`BoardID`](#boardid) | Find a board by its ID. | +##### `Group.clusterAgents` + +Cluster agents associated with projects in the group and its subgroups. + +Returns [`ClusterAgentConnection`](#clusteragentconnection). + +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="groupclusteragentshasvulnerabilities"></a>`hasVulnerabilities` | [`Boolean`](#boolean) | Returns only cluster agents which have vulnerabilities. | + ##### `Group.codeCoverageActivities` Represents the code coverage activity for this group. @@ -12236,6 +12443,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="grouprunnersstatus"></a>`status` | [`CiRunnerStatus`](#cirunnerstatus) | Filter runners by status. | | <a id="grouprunnerstaglist"></a>`tagList` | [`[String!]`](#string) | Filter by tags associated with the runner (comma-separated or array). | | <a id="grouprunnerstype"></a>`type` | [`CiRunnerType`](#cirunnertype) | Filter runners by type. | +| <a id="grouprunnersupgradestatus"></a>`upgradeStatus` | [`CiRunnerUpgradeStatusType`](#cirunnerupgradestatustype) | Filter by upgrade status. | ##### `Group.scanExecutionPolicies` @@ -12559,6 +12767,22 @@ A block of time for which a participant is on-call. #### Fields with arguments +##### `InstanceSecurityDashboard.clusterAgents` + +Cluster agents associated with projects selected in the Instance Security Dashboard. + +Returns [`ClusterAgentConnection`](#clusteragentconnection). + +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="instancesecuritydashboardclusteragentshasvulnerabilities"></a>`hasVulnerabilities` | [`Boolean`](#boolean) | Returns only cluster agents which have vulnerabilities. | + ##### `InstanceSecurityDashboard.projects` Projects selected in Instance Security Dashboard. @@ -12695,6 +12919,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="issuecurrentusertodosstate"></a>`state` | [`TodoStateEnum`](#todostateenum) | State of the to-do items. | +##### `Issue.issuableResourceLinks` + +Issuable resource links of the incident issue. + +Returns [`IssuableResourceLinkConnection`](#issuableresourcelinkconnection). + +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="issueissuableresourcelinksincidentid"></a>`incidentId` | [`IssueID!`](#issueid) | ID of the incident. | + ##### `Issue.reference` Internal reference of the issue. Returned in shortened format by default. @@ -14289,6 +14529,16 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="namespacescanexecutionpoliciesactionscantypes"></a>`actionScanTypes` | [`[SecurityReportTypeEnum!]`](#securityreporttypeenum) | Filters policies by the action scan type. Only these scan types are supported: `dast`, `secret_detection`, `cluster_image_scanning`, `container_scanning`, `sast`. | | <a id="namespacescanexecutionpoliciesrelationship"></a>`relationship` | [`SecurityPolicyRelationType`](#securitypolicyrelationtype) | Filter policies by the given policy relationship. | +### `NamespaceBan` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="namespacebanid"></a>`id` | [`GlobalID!`](#globalid) | Global ID of the namespace ban. | +| <a id="namespacebannamespace"></a>`namespace` | [`Namespace!`](#namespace) | Root namespace to which the ban applies. | +| <a id="namespacebanuser"></a>`user` | [`UserCore!`](#usercore) | User to which the namespace ban applies. | + ### `NamespaceCiCdSetting` #### Fields @@ -14757,6 +15007,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="pipelinejobsretried"></a>`retried` | [`Boolean`](#boolean) | Filter jobs by retry-status. | | <a id="pipelinejobssecurityreporttypes"></a>`securityReportTypes` | [`[SecurityReportTypeEnum!]`](#securityreporttypeenum) | Filter jobs by the type of security report they produce. | | <a id="pipelinejobsstatuses"></a>`statuses` | [`[CiJobStatus!]`](#cijobstatus) | Filter jobs by status. | @@ -14913,7 +15164,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectcicdsettings"></a>`ciCdSettings` | [`ProjectCiCdSetting`](#projectcicdsetting) | CI/CD settings for the project. | | <a id="projectciconfigpathordefault"></a>`ciConfigPathOrDefault` | [`String!`](#string) | Path of the CI configuration file. | | <a id="projectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | The CI Job Tokens scope of access. | -| <a id="projectclusteragents"></a>`clusterAgents` | [`ClusterAgentConnection`](#clusteragentconnection) | Cluster agents associated with the project. (see [Connections](#connections)) | +| <a id="projectcivariables"></a>`ciVariables` | [`CiVariableConnection`](#civariableconnection) | List of the project's CI/CD variables. (see [Connections](#connections)) | | <a id="projectcodecoveragesummary"></a>`codeCoverageSummary` | [`CodeCoverageSummary`](#codecoveragesummary) | Code coverage summary associated with the project. | | <a id="projectcomplianceframeworks"></a>`complianceFrameworks` | [`ComplianceFrameworkConnection`](#complianceframeworkconnection) | Compliance frameworks associated with the project. (see [Connections](#connections)) | | <a id="projectcontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy of the project. | @@ -14966,8 +15217,8 @@ Represents vulnerability finding of a security report on the pipeline. | <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. | -| <a id="projectservicedeskaddress"></a>`serviceDeskAddress` | [`String`](#string) | E-mail address of the service desk. | -| <a id="projectservicedeskenabled"></a>`serviceDeskEnabled` | [`Boolean`](#boolean) | Indicates if the project has service desk enabled. | +| <a id="projectservicedeskaddress"></a>`serviceDeskAddress` | [`String`](#string) | E-mail address of the Service Desk. | +| <a id="projectservicedeskenabled"></a>`serviceDeskEnabled` | [`Boolean`](#boolean) | Indicates if the project has Service Desk enabled. | | <a id="projectsharedrunnersenabled"></a>`sharedRunnersEnabled` | [`Boolean`](#boolean) | Indicates if shared runners are enabled for the project. | | <a id="projectsnippetsenabled"></a>`snippetsEnabled` | [`Boolean`](#boolean) | Indicates if Snippets are enabled for the current user. | | <a id="projectsquashcommittemplate"></a>`squashCommitTemplate` | [`String`](#string) | Template used to create squash commit message in merge requests. | @@ -15133,8 +15384,25 @@ Returns [`ClusterAgent`](#clusteragent). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="projectclusteragenthasvulnerabilities"></a>`hasVulnerabilities` | [`Boolean`](#boolean) | Returns only cluster agents which have vulnerabilities. | | <a id="projectclusteragentname"></a>`name` | [`String!`](#string) | Name of the cluster agent. | +##### `Project.clusterAgents` + +Cluster agents associated with the project. + +Returns [`ClusterAgentConnection`](#clusteragentconnection). + +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="projectclusteragentshasvulnerabilities"></a>`hasVulnerabilities` | [`Boolean`](#boolean) | Returns only cluster agents which have vulnerabilities. | + ##### `Project.containerRepositories` Container repositories of the project. @@ -16206,6 +16474,7 @@ Represents a release. | <a id="releasedescription"></a>`description` | [`String`](#string) | Description (also known as "release notes") of the release. | | <a id="releasedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | | <a id="releaseevidences"></a>`evidences` | [`ReleaseEvidenceConnection`](#releaseevidenceconnection) | Evidence for the release. (see [Connections](#connections)) | +| <a id="releasehistoricalrelease"></a>`historicalRelease` | [`Boolean`](#boolean) | Indicates the release is an historical release. | | <a id="releaseid"></a>`id` | [`ReleaseID!`](#releaseid) | Global ID of the release. | | <a id="releaselinks"></a>`links` | [`ReleaseLinks`](#releaselinks) | Links of the release. | | <a id="releasemilestones"></a>`milestones` | [`MilestoneConnection`](#milestoneconnection) | Milestones associated to the release. (see [Connections](#connections)) | @@ -16628,8 +16897,10 @@ Represents the scan result policy. | ---- | ---- | ----------- | | <a id="scanresultpolicydescription"></a>`description` | [`String!`](#string) | Description of the policy. | | <a id="scanresultpolicyenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether this policy is enabled. | +| <a id="scanresultpolicygroupapprovers"></a>`groupApprovers` | [`[Group!]`](#group) | Approvers of the group type. | | <a id="scanresultpolicyname"></a>`name` | [`String!`](#string) | Name of the policy. | | <a id="scanresultpolicyupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the policy YAML was last updated. | +| <a id="scanresultpolicyuserapprovers"></a>`userApprovers` | [`[UserCore!]`](#usercore) | Approvers of the user type. | | <a id="scanresultpolicyyaml"></a>`yaml` | [`String!`](#string) | YAML definition of the policy. | ### `ScannedResource` @@ -18273,6 +18544,19 @@ Check permissions for the current user on a work item. | <a id="workitemtypeid"></a>`id` | [`WorkItemsTypeID!`](#workitemstypeid) | Global ID of the work item type. | | <a id="workitemtypename"></a>`name` | [`String!`](#string) | Name of the work item type. | +### `WorkItemWidgetAssignees` + +Represents an assignees widget. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetassigneesallowsmultipleassignees"></a>`allowsMultipleAssignees` | [`Boolean`](#boolean) | Indicates whether multiple assignees are allowed. | +| <a id="workitemwidgetassigneesassignees"></a>`assignees` | [`UserCoreConnection`](#usercoreconnection) | Assignees of the work item. (see [Connections](#connections)) | +| <a id="workitemwidgetassigneescaninvitemembers"></a>`canInviteMembers` | [`Boolean!`](#boolean) | Indicates whether the current user can invite members to the work item's project. | +| <a id="workitemwidgetassigneestype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | + ### `WorkItemWidgetDescription` Represents a description widget. @@ -18297,6 +18581,17 @@ Represents a hierarchy widget. | <a id="workitemwidgethierarchyparent"></a>`parent` | [`WorkItem`](#workitem) | Parent work item. | | <a id="workitemwidgethierarchytype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | +### `WorkItemWidgetWeight` + +Represents a weight widget. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetweighttype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | +| <a id="workitemwidgetweightweight"></a>`weight` | [`Int`](#int) | Weight of the work item. | + ## Enumeration types Also called _Enums_, enumeration types are a special kind of scalar that @@ -18568,6 +18863,13 @@ Values for sorting runners. | <a id="cirunnerupgradestatustyperecommended"></a>`RECOMMENDED` | Upgrade is available and recommended for the runner. | | <a id="cirunnerupgradestatustypeunknown"></a>`UNKNOWN` | Upgrade status is unknown. | +### `CiVariableType` + +| Value | Description | +| ----- | ----------- | +| <a id="civariabletypeenv_var"></a>`ENV_VAR` | Env var type. | +| <a id="civariabletypefile"></a>`FILE` | File type. | + ### `CodeQualityDegradationSeverity` | Value | Description | @@ -19005,6 +19307,7 @@ User permission on groups. | Value | Description | | ----- | ----------- | | <a id="grouppermissioncreate_projects"></a>`CREATE_PROJECTS` | Groups where the user can create projects. | +| <a id="grouppermissiontransfer_projects"></a>`TRANSFER_PROJECTS` | Groups where the user can transfer projects to. | ### `HealthStatus` @@ -19148,6 +19451,7 @@ Issue type. | <a id="issuetypeincident"></a>`INCIDENT` | Incident issue type. | | <a id="issuetypeissue"></a>`ISSUE` | Issue issue type. | | <a id="issuetyperequirement"></a>`REQUIREMENT` | Requirement issue type. | +| <a id="issuetypetask"></a>`TASK` **{warning-solid}** | **Introduced** in 15.2. This feature is in Alpha. It can be changed or removed at any time. | | <a id="issuetypetest_case"></a>`TEST_CASE` | Test Case issue type. | ### `IterationSearchableField` @@ -19669,8 +19973,9 @@ The status of the security scan. | Value | Description | | ----- | ----------- | -| <a id="securitypolicyrelationtypedirect"></a>`DIRECT` | Policies defined for the project only. | -| <a id="securitypolicyrelationtypeinherited"></a>`INHERITED` | Policies defined for the project and project's ancestor groups. | +| <a id="securitypolicyrelationtypedirect"></a>`DIRECT` | Policies defined for the project/group only. | +| <a id="securitypolicyrelationtypeinherited"></a>`INHERITED` | Policies defined for the project/group and ancestor groups. | +| <a id="securitypolicyrelationtypeinherited_only"></a>`INHERITED_ONLY` | Policies defined for the project/group's ancestor groups only. | ### `SecurityReportTypeEnum` @@ -19911,7 +20216,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumgeo_migrate_hashed_storage"></a>`GEO_MIGRATE_HASHED_STORAGE` | Callout feature name for geo_migrate_hashed_storage. | | <a id="usercalloutfeaturenameenumgke_cluster_integration"></a>`GKE_CLUSTER_INTEGRATION` | Callout feature name for gke_cluster_integration. | | <a id="usercalloutfeaturenameenumgold_trial_billings"></a>`GOLD_TRIAL_BILLINGS` | Callout feature name for gold_trial_billings. | -| <a id="usercalloutfeaturenameenumminute_limit_banner"></a>`MINUTE_LIMIT_BANNER` | Callout feature name for minute_limit_banner. | +| <a id="usercalloutfeaturenameenummr_experience_survey"></a>`MR_EXPERIENCE_SURVEY` | Callout feature name for mr_experience_survey. | | <a id="usercalloutfeaturenameenumnew_user_signups_cap_reached"></a>`NEW_USER_SIGNUPS_CAP_REACHED` | Callout feature name for new_user_signups_cap_reached. | | <a id="usercalloutfeaturenameenumpersonal_access_token_expiry"></a>`PERSONAL_ACCESS_TOKEN_EXPIRY` | Callout feature name for personal_access_token_expiry. | | <a id="usercalloutfeaturenameenumpersonal_project_limitations_banner"></a>`PERSONAL_PROJECT_LIMITATIONS_BANNER` | Callout feature name for personal_project_limitations_banner. | @@ -20138,8 +20443,10 @@ Type of a work item widget. | Value | Description | | ----- | ----------- | +| <a id="workitemwidgettypeassignees"></a>`ASSIGNEES` | Assignees widget. | | <a id="workitemwidgettypedescription"></a>`DESCRIPTION` | Description widget. | | <a id="workitemwidgettypehierarchy"></a>`HIERARCHY` | Hierarchy widget. | +| <a id="workitemwidgettypeweight"></a>`WEIGHT` | Weight widget. | ## Scalar types @@ -20541,6 +20848,12 @@ A `NamespaceID` is a global ID. It is encoded as a string. An example `NamespaceID` is: `"gid://gitlab/Namespace/1"`. +### `NamespacesNamespaceBanID` + +A `NamespacesNamespaceBanID` is a global ID. It is encoded as a string. + +An example `NamespacesNamespaceBanID` is: `"gid://gitlab/Namespaces::NamespaceBan/1"`. + ### `NoteID` A `NoteID` is a global ID. It is encoded as a string. @@ -21358,8 +21671,10 @@ four standard [pagination arguments](#connection-pagination-arguments): Implementations: +- [`WorkItemWidgetAssignees`](#workitemwidgetassignees) - [`WorkItemWidgetDescription`](#workitemwidgetdescription) - [`WorkItemWidgetHierarchy`](#workitemwidgethierarchy) +- [`WorkItemWidgetWeight`](#workitemwidgetweight) ##### Fields @@ -21845,9 +22160,12 @@ A time-frame defined as a closed inclusive range of two dates. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="workitemupdatedtaskinputdescriptionwidget"></a>`descriptionWidget` | [`WorkItemWidgetDescriptionInput`](#workitemwidgetdescriptioninput) | Input for description widget. | +| <a id="workitemupdatedtaskinputhierarchywidget"></a>`hierarchyWidget` | [`WorkItemWidgetHierarchyUpdateInput`](#workitemwidgethierarchyupdateinput) | Input for hierarchy widget. | | <a id="workitemupdatedtaskinputid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | | <a id="workitemupdatedtaskinputstateevent"></a>`stateEvent` | [`WorkItemStateEvent`](#workitemstateevent) | Close or reopen a work item. | | <a id="workitemupdatedtaskinputtitle"></a>`title` | [`String`](#string) | Title of the work item. | +| <a id="workitemupdatedtaskinputweightwidget"></a>`weightWidget` | [`WorkItemWidgetWeightInput`](#workitemwidgetweightinput) | Input for weight widget. | ### `WorkItemWidgetDescriptionInput` @@ -21856,3 +22174,28 @@ A time-frame defined as a closed inclusive range of two dates. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="workitemwidgetdescriptioninputdescription"></a>`description` | [`String!`](#string) | Description of the work item. | + +### `WorkItemWidgetHierarchyCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgethierarchycreateinputparentid"></a>`parentId` | [`WorkItemID`](#workitemid) | Global ID of the parent work item. | + +### `WorkItemWidgetHierarchyUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgethierarchyupdateinputchildrenids"></a>`childrenIds` | [`[WorkItemID!]`](#workitemid) | Global IDs of children work items. | +| <a id="workitemwidgethierarchyupdateinputparentid"></a>`parentId` | [`WorkItemID`](#workitemid) | Global ID of the parent work item. Use `null` to remove the association. | + +### `WorkItemWidgetWeightInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetweightinputweight"></a>`weight` | [`Int!`](#int) | Weight of the work item. | diff --git a/doc/api/groups.md b/doc/api/groups.md index 8372d6deddd..c51f23decb9 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -823,7 +823,7 @@ Parameters: | `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#create-a-subgroup). Can be `owner` (Owners), or `maintainer` (users with the Maintainer role). | | `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | | `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | -| `membership_lock` **(PREMIUM)** | boolean | no | Prevent adding new members to projects within this group. | +| `membership_lock` **(PREMIUM)** | boolean | no | Users cannot be added to projects in this group. | | `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | | `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | @@ -930,7 +930,7 @@ PUT /groups/:id | `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | | `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | | `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | -| `membership_lock` **(PREMIUM)** | boolean | no | Prevent adding new members to projects within this group. | +| `membership_lock` **(PREMIUM)** | boolean | no | Users cannot be added to projects in this group. | | `prevent_forking_outside_group` **(PREMIUM)** | boolean | no | When enabled, users can **not** fork projects from this group to external namespaces. | | `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | diff --git a/doc/api/index.md b/doc/api/index.md index c29e43d3f8e..26447a2223d 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -441,7 +441,7 @@ GitLab also returns the following additional pagination headers: | `x-next-page` | The index of the next page. | | `x-page` | The index of the current page (starting at 1). | | `x-per-page` | The number of items per page. | -| `X-prev-page` | The index of the previous page. | +| `x-prev-page` | The index of the previous page. | | `x-total` | The total number of items. | | `x-total-pages` | The total number of pages. | @@ -453,12 +453,14 @@ Keyset-pagination allows for more efficient retrieval of pages and - in contrast to offset-based pagination - runtime is independent of the size of the collection. -This method is controlled by the following parameters: +This method is controlled by the following parameters. `order_by` and `sort` are both mandatory. -| Parameter | Description | -|--------------| ------------| -| `pagination` | `keyset` (to enable keyset pagination). | -| `per_page` | Number of items to list per page (default: `20`, max: `100`). | +| Parameter | Required | Description | +|--------------| ------------ | --------- | +| `pagination` | yes | `keyset` (to enable keyset pagination). | +| `per_page` | no | Number of items to list per page (default: `20`, max: `100`). | +| `order_by` | yes | Column by which to order by. | +| `sort` | yes | Sort order (`asc` or `desc`) | In the following example, we list 50 [projects](projects.md) per page, ordered by `id` ascending. @@ -520,10 +522,20 @@ pagination headers. Keyset-based pagination is supported only for selected resources and ordering options: -| Resource | Options | Availability | -|:-------------------------|:---------------------------------|:----------------------------------------| -| [Projects](projects.md) | `order_by=id` only | Authenticated and unauthenticated users | -| [Groups](groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | +| Resource | Options | Availability | +|:---------------------------------------------------------|:---------------------------------|:------------------------------------------------------------------------------------------------------------| +| [Projects](projects.md) | `order_by=id` only | Authenticated and unauthenticated users | +| [Groups](groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | +| [Group audit events](audit_events.md#group-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2 | + +### Pagination response headers + +For performance reasons, if a query returns more than 10,000 records, GitLab +doesn't return the following headers: + +- `x-total`. +- `x-total-pages`. +- `rel="last"` `link` ## Path parameters diff --git a/doc/api/integrations.md b/doc/api/integrations.md index eaa826b3686..fca1d02161b 100644 --- a/doc/api/integrations.md +++ b/doc/api/integrations.md @@ -1033,7 +1033,6 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `recipients` | string | yes | Comma-separated list of recipient email addresses | -| `add_pusher` | boolean | no | Add pusher to recipients list | | `notify_only_broken_pipelines` | boolean | no | Notify only broken pipelines | | `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected. The default value is "default" | | `notify_only_default_branch` | boolean | no | Send notifications only for the default branch ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28271)) | diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 5a39a86d039..96c820536de 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -1,6 +1,6 @@ --- stage: Growth -group: Expansion +group: Acquisition 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 --- @@ -20,7 +20,7 @@ levels are defined in the `Gitlab::Access` module. Currently, these levels are v - Reporter (`20`) - Developer (`30`) - Maintainer (`40`) -- Owner (`50`) - Only valid to set for groups +- Owner (`50`). Valid for projects in [GitLab 14.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/21432). NOTE: From [GitLab 14.9](https://gitlab.com/gitlab-org/gitlab/-/issues/351211) and later, projects have a maximum role of Owner. diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 85cdf7d892a..b23c33ddc0d 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -692,7 +692,7 @@ Example of response "finished_at": null, "duration": 8, "queued_duration": 0.010, - "id": 42, + "id": 1, "name": "rubocop", "ref": "main", "artifacts": [], @@ -742,7 +742,7 @@ Example of response "finished_at": null, "duration": null, "queued_duration": 0.010, - "id": 42, + "id": 1, "name": "rubocop", "ref": "main", "artifacts": [], @@ -792,7 +792,7 @@ Example of response "coverage": null, "allow_failure": false, "download_url": null, - "id": 42, + "id": 1, "name": "rubocop", "ref": "main", "artifacts": [], @@ -873,7 +873,7 @@ Example response: "finished_at": null, "duration": null, "queued_duration": 0.010, - "id": 42, + "id": 1, "name": "rubocop", "ref": "main", "artifacts": [], diff --git a/doc/api/members.md b/doc/api/members.md index 5002e1003e3..a9817918d0b 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -18,7 +18,7 @@ The access levels are defined in the `Gitlab::Access` module. Currently, these l - Reporter (`20`) - Developer (`30`) - Maintainer (`40`) -- Owner (`50`) - Only valid to set for groups +- Owner (`50`). Valid for projects in [GitLab 14.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/21432). NOTE: In [GitLab 14.9](https://gitlab.com/gitlab-org/gitlab/-/issues/351211) and later, projects in personal namespaces have an `access_level` of `50`(Owner). diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index eb4b7a3dd7e..c6714459643 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -450,6 +450,7 @@ Parameters: | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | | `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | +| `approved_by_usernames` **(PREMIUM)** | string array | no | Returns merge requests which have been approved by all the users with the given `username`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | | `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | @@ -785,6 +786,8 @@ the `approvals_before_merge` parameter: field `merge_user` can be either user who merged this merge request, user who set it to merge when pipeline succeeds or `null`. Field `merged_by` (user who merged this merge request or `null`) has been deprecated. +- `pipeline` is an old parameter and should not be used. Use `head_pipeline` instead, + as it is faster and returns more information. ## Get single MR participants diff --git a/doc/api/metadata.md b/doc/api/metadata.md new file mode 100644 index 00000000000..70c29ef5748 --- /dev/null +++ b/doc/api/metadata.md @@ -0,0 +1,46 @@ +--- +stage: Ecosystem +group: Integrations +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 +--- + +# Metadata API **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357032) in GitLab 15.2. + +Retrieve metadata information for this GitLab instance. + +```plaintext +GET /metadata +``` + +Response body attributes: + +| Attribute | Type | Description | +|:------------------|:---------------|:-----------------------------------------------------------------------------------------| +| `version` | string | Version of the GitLab instance. | +| `revision` | string | Revision of the GitLab instance. | +| `kas` | object | Metadata about the GitLab agent server for Kubernetes (KAS). | +| `kas.enabled` | boolean | Indicates whether KAS is enabled. | +| `kas.externalUrl` | string or null | URL used by the agents to communicate with KAS. It's `null` if `kas.enabled` is `false`. | +| `kas.version` | string or null | Version of KAS. It's `null` if `kas.enabled` is `false`. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/metadata" +``` + +Example response: + +```json +{ + "version": "15.2-pre", + "revision": "c401a659d0c", + "kas": { + "enabled": true, + "externalUrl": "grpc://gitlab.example.com:8150", + "version": "15.0.0" + } +} +``` diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 3e54ec74b24..4f5fe1c909a 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -12,7 +12,7 @@ by displaying favorited dashboards at the top of the select list. ## Add a star to a dashboard -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31316) in GitLab 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31316) in GitLab 13.0. ```plaintext POST /projects/:id/metrics/user_starred_dashboards diff --git a/doc/api/notes.md b/doc/api/notes.md index fbcf5e28f79..f7caae59b4d 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -146,7 +146,7 @@ Parameters: | `issue_iid` | integer | yes | The IID of an issue. | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `confidential` | boolean | no | The confidential flag of a note. Default is false. | -| `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | +| `created_at` | string | no | Date time string, ISO 8601 formatted. It must be after 1970-01-01. Example: `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/notes?body=note" diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index be58d75333d..35c6eb4a982 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -15,16 +15,21 @@ To configure GitLab for this, see This functionality is based on the [doorkeeper Ruby gem](https://github.com/doorkeeper-gem/doorkeeper). -## CORS preflight requests +## Cross-origin resource sharing -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364680) in GitLab 15.1. +> CORS preflight request support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364680) in GitLab 15.1. -The following endpoints support [CORS preflight requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS): +Many `/oauth` endpoints support cross-origin resource sharing (CORS). From GitLab 15.1, the following endpoints also +support [CORS preflight requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS): - `/oauth/revoke` - `/oauth/token` - `/oauth/userinfo` +In addition to the headers listed for [simple requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests), +only the `Authorization` header can be used for preflight requests. For example, the `X-Requested-With` header +can't be used for preflight requests. + ## Supported OAuth 2.0 flows GitLab supports the following authorization flows: diff --git a/doc/api/openapi/openapi.yaml b/doc/api/openapi/openapi.yaml index cc6a161c783..a3a0485428d 100644 --- a/doc/api/openapi/openapi.yaml +++ b/doc/api/openapi/openapi.yaml @@ -1,5 +1,7 @@ openapi: 3.0.0 tags: + - name: metadata + description: Metadata of the GitLab instance - name: version description: Version - name: access_requests @@ -39,6 +41,10 @@ components: name: Private-Token paths: + # METADATA + /v4/metadata: + $ref: 'v4/metadata.yaml' + # VERSION /v4/version: $ref: 'v4/version.yaml' @@ -49,7 +55,7 @@ paths: /v4/projects/{id}/access_requests/{user_id}/approve: $ref: 'v4/access_requests.yaml#/accessRequestsProjectsApprove' - + /v4/projects/{id}/access_requests/{user_id}: $ref: 'v4/access_requests.yaml#/accessRequestsProjectsDeny' @@ -59,7 +65,7 @@ paths: /v4/groups/{id}/access_requests/{user_id}/approve: $ref: 'v4/access_requests.yaml#/accessRequestsGroupsApprove' - + /v4/groups/{id}/access_requests/{user_id}: $ref: 'v4/access_requests.yaml#/accessRequestsGroupsDeny' @@ -68,4 +74,4 @@ paths: $ref: 'v4/access_tokens.yaml#/accessTokens' /v4/projects/{id}/access_tokens/{token_id}: - $ref: 'v4/access_tokens.yaml#/accessTokensRevoke'
\ No newline at end of file + $ref: 'v4/access_tokens.yaml#/accessTokensRevoke' diff --git a/doc/api/openapi/v4/metadata.yaml b/doc/api/openapi/v4/metadata.yaml new file mode 100644 index 00000000000..6a5ef9f3355 --- /dev/null +++ b/doc/api/openapi/v4/metadata.yaml @@ -0,0 +1,43 @@ +# Markdown documentation: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/metadata.md + +get: + tags: + - metadata + summary: "Retrieve metadata information for this GitLab instance." + operationId: "getMetadata" + responses: + "401": + description: "unauthorized operation" + "200": + description: "successful operation" + content: + "application/json": + schema: + title: "MetadataResponse" + type: "object" + properties: + version: + type: "string" + revision: + type: "string" + kas: + type: "object" + properties: + enabled: + type: "boolean" + externalUrl: + type: "string" + nullable: true + version: + type: "string" + nullable: true + examples: + Example: + value: + version: "15.0-pre" + revision: "c401a659d0c" + kas: + enabled: true + externalUrl: "grpc://gitlab.example.com:8150" + version: "15.0.0" + diff --git a/doc/api/packages/conan.md b/doc/api/packages/conan.md index 546a472ea53..1590893d006 100644 --- a/doc/api/packages/conan.md +++ b/doc/api/packages/conan.md @@ -19,6 +19,10 @@ NOTE: These endpoints do not adhere to the standard API authentication methods. See each route for details on how credentials are expected to be passed. +NOTE: +The Conan registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. +These endpoints will all return 404 Not Found. + ## Route prefix There are two sets of identical routes that each make requests in different scopes: diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md index 66377850c49..4abb7bc7112 100644 --- a/doc/api/packages/debian.md +++ b/doc/api/packages/debian.md @@ -22,6 +22,10 @@ For instructions on how to upload and install Debian packages from the GitLab package registry, see the [Debian registry documentation](../../user/packages/debian_repository/index.md). NOTE: +The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. +These endpoints will all return `404 Not Found`. + +NOTE: These endpoints do not adhere to the standard API authentication methods. See the [Debian registry documentation](../../user/packages/debian_repository/index.md) for details on which headers and token types are supported. diff --git a/doc/api/packages/debian_group_distributions.md b/doc/api/packages/debian_group_distributions.md index 0a1b7b4571e..0d0a4cb2cde 100644 --- a/doc/api/packages/debian_group_distributions.md +++ b/doc/api/packages/debian_group_distributions.md @@ -18,6 +18,10 @@ This API is under development and is not meant for production use. For more information about working with Debian packages, see the [Debian package registry documentation](../../user/packages/debian_repository/index.md). +NOTE: +The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. +These endpoints will all return `404 Not Found`. + ## Enable the Debian group API Debian group repository support is still a work in progress. It's gated behind a feature flag that's diff --git a/doc/api/packages/debian_project_distributions.md b/doc/api/packages/debian_project_distributions.md index 533742642fd..4f3ac62f576 100644 --- a/doc/api/packages/debian_project_distributions.md +++ b/doc/api/packages/debian_project_distributions.md @@ -18,6 +18,10 @@ This API is under development and is not meant for production use. For more information about working with Debian packages, see the [Debian package registry documentation](../../user/packages/debian_repository/index.md). +NOTE: +The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. +These endpoints will all return `404 Not Found`. + ## Enable the Debian API The Debian API is behind a feature flag that is disabled by default. diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index 3e23ded61f4..e6204d87e1f 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -20,6 +20,10 @@ 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. +NOTE: +[Twine 3.4.2](https://twine.readthedocs.io/en/stable/changelog.html?highlight=FIPS#id28) or greater +is recommended when [FIPS mode](../../development/fips_compliance.md) is enabled. + ## Download a package file from a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225545) in GitLab 13.12. diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 4205e6699fe..81bb4a26614 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -170,5 +170,5 @@ This parameter is used for filtering by attributes, such as `environment_scope`. Example usage: ```shell -curl --request DELETE --globoff --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1?filter[environment_scope]=production" +curl --globoff --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1?filter[environment_scope]=production" ``` diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index ebb15e1c1d6..48c22ff2d93 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -1,8 +1,7 @@ --- -stage: Create +stage: Systems group: Gitaly 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 --- # Project repository storage moves API **(FREE SELF)** diff --git a/doc/api/projects.md b/doc/api/projects.md index 3cb75c39980..8a8fe522b63 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -15,7 +15,7 @@ The visibility level is determined by the `visibility` field in the project. Values for the project visibility level are: -- `private`: project access must be granted explicitly for each user. +- `private`: project access must be granted explicitly to each user. - `internal`: the project can be cloned by any signed-in user except [external users](../user/permissions.md#external-users). - `public`: the project can be accessed without any authentication. @@ -28,11 +28,10 @@ There are three options for `merge_method` to choose from: - `merge`: a merge commit is created for every merge, and merging is allowed if there are no conflicts. - `rebase_merge`: a merge commit is created for every merge, but merging is only - allowed if fast-forward merge is possible. This way you could make sure that - if this merge request would build, after merging to target branch it would - also build. -- `ff`: no merge commits are created and all merges are fast-forwarded, which - means that merging is only allowed if the branch could be fast-forwarded. + allowed if fast-forward merge is possible. You can make sure that the target + branch would build after this merge request builds and merges. +- `ff`: no merge commits are created and all merges are fast-forwarded. Merging + is only allowed if the branch could be fast-forwarded. ## List all projects @@ -68,6 +67,7 @@ GET /projects | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `topic` | string | **{dotted-circle}** No | Comma-separated topic names. Limit results to projects that match all of given topics. See `topics` attribute. | +| `topic_id` | integer | **{dotted-circle}** No | Limit results to projects with the assigned topic given by the topic ID. | | `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. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | @@ -80,17 +80,26 @@ for selected `order_by` options. When `simple=true` or the user is unauthenticated this returns something like: +Example request: + +```shell +curl --request GET "https://gitlab.example.com/api/v4/projects" +``` + +Example response: + ```json [ { "id": 4, "description": null, - "default_branch": "master", - "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git", - "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": [ //deprecated, use `topics` instead + "name": "Diaspora Client", + "name_with_namespace": "Diaspora / Diaspora Client", + "path": "diaspora-client", + "path_with_namespace": "diaspora/diaspora-client", + "created_at": "2013-09-30T13:46:02Z", + "default_branch": "main", + "tag_list": [ "example", "disapora client" ], @@ -98,21 +107,28 @@ When `simple=true` or the user is unauthenticated this returns something like: "example", "disapora client" ], - "name": "Diaspora Client", - "name_with_namespace": "Diaspora / Diaspora Client", - "path": "diaspora-client", - "path_with_namespace": "diaspora/diaspora-client", - "created_at": "2013-09-30T13:46:02Z", - "last_activity_at": "2013-09-30T13:46:02Z", + "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git", + "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git", + "web_url": "https://gitlab.example.com/diaspora/diaspora-client", + "readme_url": "https://gitlab.example.com/diaspora/diaspora-client/blob/master/README.md", + "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png", "forks_count": 0, - "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", - "star_count": 0 + "star_count": 0, + "last_activity_at": "2013-09-30T13:46:02Z", + "namespace": { + "id": 2, + "name": "Diaspora", + "path": "diaspora", + "kind": "group", + "full_path": "diaspora", + "parent_id": null, + "avatar_url": null, + "web_url": "https://gitlab.example.com/diaspora" + } }, { - "id": 6, - "description": null, - "default_branch": "master", -... + ... + } ``` When the user is authenticated and `simple` is not set this returns something like: @@ -122,12 +138,12 @@ When the user is authenticated and `simple` is not set this returns something li { "id": 4, "description": null, - "default_branch": "master", - "visibility": "private", - "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git", - "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", + "name": "Diaspora Client", + "name_with_namespace": "Diaspora / Diaspora Client", + "path": "diaspora-client", + "path_with_namespace": "diaspora/diaspora-client", + "created_at": "2013-09-30T13:46:02Z", + "default_branch": "main", "tag_list": [ //deprecated, use `topics` instead "example", "disapora client" @@ -136,202 +152,115 @@ When the user is authenticated and `simple` is not set this returns something li "example", "disapora client" ], - "owner": { - "id": 3, - "name": "Diaspora", - "created_at": "2013-09-30T13:46:02Z" - }, - "name": "Diaspora Client", - "name_with_namespace": "Diaspora / Diaspora Client", - "path": "diaspora-client", - "path_with_namespace": "diaspora/diaspora-client", - "issues_enabled": true, - "open_issues_count": 1, - "merge_requests_enabled": true, - "jobs_enabled": true, - "wiki_enabled": true, - "snippets_enabled": false, - "can_create_merge_request_in": true, - "resolve_outdated_diff_discussions": false, - "container_registry_enabled": false, // deprecated, use container_registry_access_level instead - "container_registry_access_level": "disabled", - "security_and_compliance_access_level": "disabled", - "created_at": "2013-09-30T13:46:02Z", - "last_activity_at": "2013-09-30T13:46:02Z", - "creator_id": 3, + "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git", + "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git", + "web_url": "https://gitlab.example.com/diaspora/diaspora-client", + "readme_url": "https://gitlab.example.com/diaspora/diaspora-client/blob/master/README.md", + "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png", + "forks_count": 0, + "star_count": 0, + "last_activity_at": "2022-06-24T17:11:26.841Z", "namespace": { "id": 3, "name": "Diaspora", "path": "diaspora", "kind": "group", - "full_path": "diaspora" - }, - "import_status": "none", - "archived": false, - "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", - "shared_runners_enabled": true, - "forks_count": 0, - "star_count": 0, - "runners_token": "b8547b1dc37721d05889db52fa2f02", - "ci_default_git_depth": 50, - "ci_forward_deployment_enabled": true, - "public_jobs": true, - "shared_with_groups": [], - "only_allow_merge_if_pipeline_succeeds": false, - "allow_merge_on_skipped_pipeline": false, - "restrict_user_defined_variables": false, - "only_allow_merge_if_all_discussions_are_resolved": false, - "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, - "merge_commit_template": null, - "squash_commit_template": null, - "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on - "marked_for_deletion_on": "2020-04-03", - "statistics": { - "commit_count": 37, - "storage_size": 1038090, - "repository_size": 1038090, - "wiki_size" : 0, - "lfs_objects_size": 0, - "job_artifacts_size": 0, - "pipeline_artifacts_size": 0, - "packages_size": 0, - "snippets_size": 0, - "uploads_size": 0 + "full_path": "diaspora", + "parent_id": null, + "avatar_url": "https://gitlab.example.com/uploads/project/avatar/6/uploads/avatar.png", + "web_url": "https://gitlab.example.com/diaspora" }, - "container_registry_image_prefix": "registry.example.com/diaspora/diaspora-client", + "container_registry_image_prefix": "registry.gitlab.example.com/diaspora/diaspora-client", "_links": { - "self": "http://example.com/api/v4/projects", - "issues": "http://example.com/api/v4/projects/1/issues", - "merge_requests": "http://example.com/api/v4/projects/1/merge_requests", - "repo_branches": "http://example.com/api/v4/projects/1/repository_branches", - "labels": "http://example.com/api/v4/projects/1/labels", - "events": "http://example.com/api/v4/projects/1/events", - "members": "http://example.com/api/v4/projects/1/members", - "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents" - } - }, - { - "id": 6, - "description": null, - "default_branch": "master", - "visibility": "private", - "ssh_url_to_repo": "git@example.com:brightbox/puppet.git", - "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": [ //deprecated, use `topics` instead - "example", - "puppet" - ], - "topics": [ - "example", - "puppet" - ], - "owner": { - "id": 4, - "name": "Brightbox", - "created_at": "2013-09-30T13:46:02Z" + "self": "https://gitlab.example.com/api/v4/projects/4", + "issues": "https://gitlab.example.com/api/v4/projects/4/issues", + "merge_requests": "https://gitlab.example.com/api/v4/projects/4/merge_requests", + "repo_branches": "https://gitlab.example.com/api/v4/projects/4/repository/branches", + "labels": "https://gitlab.example.com/api/v4/projects/4/labels", + "events": "https://gitlab.example.com/api/v4/projects/4/events", + "members": "https://gitlab.example.com/api/v4/projects/4/members", + "cluster_agents": "https://gitlab.example.com/api/v4/projects/4/cluster_agents" + }, + "packages_enabled": true, + "empty_repo": false, + "archived": false, + "visibility": "public", + "resolve_outdated_diff_discussions": false, + "container_expiration_policy": { + "cadence": "1month", + "enabled": true, + "keep_n": 1, + "older_than": "14d", + "name_regex": "", + "name_regex_keep": ".*-main", + "next_run_at": "2022-06-25T17:11:26.865Z" }, - "name": "Puppet", - "name_with_namespace": "Brightbox / Puppet", - "path": "puppet", - "path_with_namespace": "brightbox/puppet", "issues_enabled": true, - "open_issues_count": 1, "merge_requests_enabled": true, - "jobs_enabled": true, "wiki_enabled": true, - "snippets_enabled": false, + "jobs_enabled": true, + "snippets_enabled": true, + "container_registry_enabled": true, + "service_desk_enabled": true, "can_create_merge_request_in": true, - "resolve_outdated_diff_discussions": false, - "container_registry_enabled": false, // deprecated, use container_registry_access_level instead - "container_registry_access_level": "disabled", - "security_and_compliance_access_level": "disabled", - "created_at": "2013-09-30T13:46:02Z", - "last_activity_at": "2013-09-30T13:46:02Z", - "creator_id": 3, - "namespace": { - "id": 4, - "name": "Brightbox", - "path": "brightbox", - "kind": "group", - "full_path": "brightbox" - }, - "import_status": "none", - "import_error": null, - "permissions": { - "project_access": { - "access_level": 10, - "notification_level": 3 - }, - "group_access": { - "access_level": 50, - "notification_level": 3 - } - }, - "archived": false, - "avatar_url": null, + "issues_access_level": "enabled", + "repository_access_level": "enabled", + "merge_requests_access_level": "enabled", + "forking_access_level": "enabled", + "wiki_access_level": "enabled", + "builds_access_level": "enabled", + "snippets_access_level": "enabled", + "pages_access_level": "enabled", + "operations_access_level": "enabled", + "analytics_access_level": "enabled", + "container_registry_access_level": "enabled", + "security_and_compliance_access_level": "private", + "emails_disabled": null, "shared_runners_enabled": true, - "forks_count": 0, - "star_count": 0, - "runners_token": "b8547b1dc37721d05889db52fa2f02", - "ci_default_git_depth": 0, + "lfs_enabled": true, + "creator_id": 1, + "import_status": "none", + "open_issues_count": 0, + "ci_default_git_depth": 20, "ci_forward_deployment_enabled": true, + "ci_job_token_scope_enabled": false, + "ci_separated_caches": true, "public_jobs": true, + "build_timeout": 3600, + "auto_cancel_pending_pipelines": "enabled", + "build_coverage_regex": null, + "ci_config_path": "", "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, - "allow_merge_on_skipped_pipeline": false, + "allow_merge_on_skipped_pipeline": null, "restrict_user_defined_variables": false, + "request_access_enabled": true, "only_allow_merge_if_all_discussions_are_resolved": false, - "remove_source_branch_after_merge": false, - "request_access_enabled": false, + "remove_source_branch_after_merge": true, + "printing_merge_request_link_enabled": true, "merge_method": "merge", - "squash_option": "default_on", - "auto_devops_enabled": true, - "auto_devops_deploy_strategy": "continuous", - "repository_storage": "default", - "approvals_before_merge": 0, - "mirror": false, - "mirror_user_id": 45, - "mirror_trigger_builds": false, - "only_mirror_protected_branches": false, - "mirror_overwrites_diverged_branches": false, - "external_authorization_classification_label": null, - "packages_enabled": true, - "service_desk_enabled": false, - "service_desk_address": null, - "autoclose_referenced_issues": true, + "squash_option": "default_off", + "enforce_auth_checks_on_uploads": true, "suggestion_commit_message": null, "merge_commit_template": null, "squash_commit_template": null, - "statistics": { - "commit_count": 12, - "storage_size": 2066080, - "repository_size": 2066080, - "wiki_size" : 0, - "lfs_objects_size": 0, - "job_artifacts_size": 0, - "pipeline_artifacts_size": 0, - "packages_size": 0, - "snippets_size": 0, - "uploads_size": 0 - }, - "container_registry_image_prefix": "registry.example.com/brightbox/puppet", - "_links": { - "self": "http://example.com/api/v4/projects", - "issues": "http://example.com/api/v4/projects/1/issues", - "merge_requests": "http://example.com/api/v4/projects/1/merge_requests", - "repo_branches": "http://example.com/api/v4/projects/1/repository_branches", - "labels": "http://example.com/api/v4/projects/1/labels", - "events": "http://example.com/api/v4/projects/1/events", - "members": "http://example.com/api/v4/projects/1/members", - "cluster_agents": "http://example.com/api/v4/projects/1/cluster_agents" + "auto_devops_enabled": false, + "auto_devops_deploy_strategy": "continuous", + "autoclose_referenced_issues": true, + "keep_latest_artifact": true, + "runner_token_expiration_interval": null, + "external_authorization_classification_label": "", + "requirements_enabled": false, + "requirements_access_level": "enabled", + "security_and_compliance_enabled": false, + "compliance_frameworks": [], + "permissions": { + "project_access": null, + "group_access": null } + }, + { + ... } ] ``` @@ -365,6 +294,12 @@ You can filter by [custom attributes](custom_attributes.md) with: GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value ``` +Example request: + +```shell +curl --globoff --request GET "https://gitlab.example.com/api/v4/projects?custom_attributes[location]=Antarctica&custom_attributes[role]=Developer" +``` + ### Pagination limits In GitLab 13.0 and later, [offset-based pagination](index.md#offset-based-pagination) @@ -470,6 +405,7 @@ GET /users/:user_id/projects "runners_token": "b8547b1dc37721d05889db52fa2f02", "ci_default_git_depth": 50, "ci_forward_deployment_enabled": true, + "ci_separated_caches": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -577,6 +513,7 @@ GET /users/:user_id/projects "runners_token": "b8547b1dc37721d05889db52fa2f02", "ci_default_git_depth": 0, "ci_forward_deployment_enabled": true, + "ci_separated_caches": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -983,6 +920,7 @@ GET /projects/:id "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, "ci_forward_deployment_enabled": true, + "ci_separated_caches": true, "public_jobs": true, "shared_with_groups": [ { @@ -1422,6 +1360,7 @@ Supported attributes: | `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | | `ci_default_git_depth` | integer | **{dotted-circle}** No | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). | | `ci_forward_deployment_enabled` | boolean | **{dotted-circle}** No | When a new deployment job starts, [skip older deployment jobs](../ci/pipelines/settings.md#skip-outdated-deployment-jobs) that are still pending | +| `ci_separated_caches` | boolean | **{dotted-circle}** No | Set whether or not caches should be [separated](../ci/caching/index.md#cache-key-names) by branch protection status. | | `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). | | `container_registry_access_level` | string | **{dotted-circle}** No | Set visibility of container registry, for this project, to one of `disabled`, `private` or `enabled`. | | `container_registry_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | @@ -1997,6 +1936,7 @@ Example response: "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, "ci_forward_deployment_enabled": true, + "ci_separated_caches": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -2122,6 +2062,7 @@ Example response: "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, "ci_forward_deployment_enabled": true, + "ci_separated_caches": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -2637,7 +2578,7 @@ PUT /projects/:id/push_rule ### Delete project push rule -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. Removes a push rule from a project. This is an idempotent method and can be called multiple times. Either the push rule is available or not. @@ -2654,7 +2595,7 @@ DELETE /projects/:id/push_rule > The `_links.cluster_agents` attribute in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 14.10. -See the [Project documentation](../user/project/settings/index.md#transferring-an-existing-project-into-another-namespace) +See the [Project documentation](../user/project/settings/index.md#transfer-a-project-to-another-namespace) for prerequisites to transfer a project. ```plaintext @@ -2820,7 +2761,7 @@ with the API scope enabled. ## Start the pull mirroring process for a Project **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. ```plaintext POST /projects/:id/mirror/pull diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index e2b27692373..b2ab3227a7e 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -100,6 +100,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](index.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 role) | +| `allowed_to_create` | array | no | Array of access levels allowed to create tags, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | Example response: diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 1a1eee175f7..34b86902271 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -319,6 +319,7 @@ Supported attributes: | `date` | datetime | no | The date and time of the release, defaults to the current time. | | `branch` | string | no | The branch to commit the changelog changes to, defaults to the project's default branch. | | `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | +| `config_file` | string | no | The path of changelog configuration file in the project's Git repository, defaults to `.gitlab/changelog_config.yml`. | | `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. | @@ -453,7 +454,7 @@ If a revert commit includes the trailer used for generating changelogs ### Customize the changelog output The output is customized using a YAML configuration file stored in your -project's Git repository. This file must reside in +project's Git repository. This default configuration file path is `.gitlab/changelog_config.yml`. You can set the following variables in this file: @@ -736,6 +737,7 @@ Supported attributes: | `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the branch specified in the `branch` attribute. | | `date` | datetime | no | The date and time of the release, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z`. Defaults to the current time. | | `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | +| `config_file` | string | no | The path of changelog configuration file in the project's Git repository, defaults to `.gitlab/changelog_config.yml`. | ```shell curl --header "PRIVATE-TOKEN: token" "https://gitlab.com/api/v4/projects/42/repository/changelog?version=1.0.0" diff --git a/doc/api/settings.md b/doc/api/settings.md index 805797792de..28a33e4deb4 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -175,6 +175,7 @@ Example response: "container_registry_expiration_policies_caching": true, "container_registry_expiration_policies_worker_capacity": 4, "container_registry_token_expire_delay": 5, + "package_registry_cleanup_policies_worker_capacity": 2, "repository_storages": ["default"], "plantuml_enabled": false, "plantuml_url": null, @@ -271,6 +272,7 @@ listed in the descriptions of the relevant settings. | `container_registry_expiration_policies_caching` | boolean | no | Caching during the execution of [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | | `container_registry_expiration_policies_worker_capacity` | integer | no | Number of workers for [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | +| `package_registry_cleanup_policies_worker_capacity` | integer | no | Number of workers assigned to the packages cleanup policies. | | `deactivate_dormant_users` | boolean | no | Enable [automatic 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_name` | string | no | [Instance-level custom initial branch name](../user/project/repository/branches/default.md#instance-level-custom-initial-branch-name) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225258) in GitLab 13.2). | @@ -379,6 +381,9 @@ listed in the descriptions of the relevant settings. | `max_personal_access_token_lifetime` **(ULTIMATE SELF)** | integer | no | Maximum allowable lifetime for access tokens in days. | | `max_ssh_key_lifetime` **(ULTIMATE SELF)** | integer | no | Maximum allowable lifetime for SSH keys in days. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.6. | | `metrics_method_call_threshold` | integer | no | A method call is only tracked when it takes longer than the given amount of milliseconds. | +| `max_number_of_repository_downloads` **(ULTIMATE SELF)** | integer | no | Maximum number of unique repositories a user can download in the specified time period before they are banned. Default: 0, Maximum: 10,000 repositories. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | +| `max_number_of_repository_downloads_within_time_period` **(ULTIMATE SELF)** | integer | no | Reporting time period (in seconds). Default: 0, Maximum: 864000 seconds (10 days). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | +| `git_rate_limit_users_allowlist` **(ULTIMATE SELF)** | array of strings | no | List of usernames excluded from Git anti-abuse rate limits. Default: `[]`, Maximum: 100 usernames. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90815) in GitLab 15.2. | | `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Administrators can configure repository mirroring. | | `mirror_capacity_threshold` **(PREMIUM)** | integer | no | Minimum capacity to be available before scheduling more mirrors preemptively. | | `mirror_max_capacity` **(PREMIUM)** | integer | no | Maximum number of mirrors that can be synchronizing at the same time. | diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 52bcd072de9..e3bc3573ed7 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -31,6 +31,15 @@ Get a list of the current user's snippets. GET /snippets ``` +Parameters: + +| Attribute | Type | Required | Description | +|------------------|----------|----------|-----------------------------------------------------------------------------------------------------| +| `per_page` | integer | no | Number of snippets to return per page. | +| `page` | integer | no | Page to retrieve. | +| `created_after` | datetime | no | Return snippets created after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return snippets created before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | + Example request: ```shell @@ -389,10 +398,12 @@ GET /snippets/public Parameters: -| Attribute | Type | Required | Description | -|:-----------|:--------|:---------|:---------------------------------------| -| `per_page` | integer | no | Number of snippets to return per page. | -| `page` | integer | no | Page to retrieve. | +| Attribute | Type | Required | Description | +|------------------|----------|----------|-----------------------------------------------------------------------------------------------------| +| `per_page` | integer | no | Number of snippets to return per page. | +| `page` | integer | no | Page to retrieve. | +| `created_after` | datetime | no | Return snippets created after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | +| `created_before` | datetime | no | Return snippets created before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | Example request: diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md index be816a0f864..a01ed3e83a5 100644 --- a/doc/api/usage_data.md +++ b/doc/api/usage_data.md @@ -1,5 +1,5 @@ --- -stage: Growth +stage: Analytics group: Product Intelligence 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 @@ -34,7 +34,7 @@ Example response: by month product_section: enablement product_stage: enablement - product_group: group::global search + product_group: global_search product_category: global_search value_type: number status: active @@ -79,6 +79,7 @@ Example response: "active_user_count": "SELECT COUNT(\"users\".\"id\") FROM \"users\" WHERE (\"users\".\"state\" IN ('active')) AND (\"users\".\"user_type\" IS NULL OR \"users\".\"user_type\" IN (NULL, 6, 4))", "edition": "EE", "license_md5": "c701acc03844c45366dd175ef7a4e19c", + "license_sha256": "366dd175ef7a4e19cc701acc03844c45366dd175ef7a4e19cc701acc03844c45", "license_id": null, "historical_max_users": 0, "licensee": { @@ -138,6 +139,7 @@ Sample response: "active_user_count": -3, "edition": "EE", "license_md5": "bb8cd0d8a6d9569ff3f70b8927a1f949", + "license_sha256": "366dd175ef7a4e19cc701acc03844c45366dd175ef7a4e19cc701acc03844c45", "license_id": null, "historical_max_users": 0, "licensee": { diff --git a/doc/api/users.md b/doc/api/users.md index 5e41a0f6258..06c0fadbbbf 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -57,8 +57,7 @@ NOTE: Username search is case insensitive. In addition, you can filter users based on the states `blocked` and `active`. -It does not support `active=false` or `blocked=false`. The list of billable users -is the total number of users minus the blocked users. +It does not support `active=false` or `blocked=false`. ```plaintext GET /users?active=true @@ -105,7 +104,7 @@ parameter `without_project_bots=true`. GET /users?without_project_bots=true ``` -### For administrators +### For administrators **(FREE SELF)** > The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. @@ -284,7 +283,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|---------|----------|------------------| -| `id` | integer | yes | The ID of a user | +| `id` | integer | yes | ID of a user | ```json { @@ -314,7 +313,7 @@ Parameters: } ``` -### For administrator +### For administrators **(FREE SELF)** > The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. @@ -326,7 +325,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|---------|----------|------------------| -| `id` | integer | yes | The ID of a user | +| `id` | integer | yes | ID of a user | Example Responses: @@ -477,7 +476,7 @@ Parameters: | `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | | `skip_confirmation` | No | Skip confirmation - true or false (default) | | `skype` | No | Skype ID | -| `theme_id` | No | The GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) | +| `theme_id` | No | GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) | | `twitter` | No | Twitter account | | `username` | Yes | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | @@ -507,7 +506,7 @@ Parameters: | `external` | No | Flags the user as external - true or false (default) | | `extra_shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Additional CI/CD minutes for this user. | | `group_id_for_saml` | No | ID of group where SAML has been configured | -| `id` | Yes | The ID of the user | +| `id` | Yes | ID of the user | | `linkedin` | No | LinkedIn | | `location` | No | User's location | | `name` | No | Name | @@ -517,11 +516,11 @@ Parameters: | `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) | | `projects_limit` | No | Limit projects each user can create | | `provider` | No | External provider name | -| `public_email` | No | The public email of the user (must be already verified) | +| `public_email` | No | Public email of the user (must be already verified) | | `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0`. | | `skip_reconfirmation` | No | Skip reconfirmation - true or false (default) | | `skype` | No | Skype ID | -| `theme_id` | No | The GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) | +| `theme_id` | No | GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) | | `twitter` | No | Twitter account | | `username` | No | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | @@ -544,7 +543,7 @@ Parameters: | Attribute | Type | Required | Description | |------------|---------|----------|------------------------| -| `id` | integer | yes | The ID of a user | +| `id` | integer | yes | ID of a user | | `provider` | string | yes | External provider name | ## User deletion @@ -560,10 +559,14 @@ Parameters: | Attribute | Type | Required | Description | |---------------|---------|----------|----------------------------------------------| -| `id` | integer | yes | The ID of a user | +| `id` | integer | yes | ID of a user | | `hard_delete` | boolean | no | If true, contributions that would usually be [moved to Ghost User](../user/profile/account/delete_account.md#associated-records) are deleted instead, as well as groups owned solely by this user. | -## List current user (for normal users) +## List current user + +Get current user. + +### For normal users Gets currently authenticated user. @@ -619,7 +622,7 @@ 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` parameters. -## List current user (for administrators) +### For administrators **(FREE SELF)** > The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. @@ -631,7 +634,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|---------|----------|--------------------------------------------------| -| `sudo` | integer | no | the ID of a user to make the call in their place | +| `sudo` | integer | no | ID of a user to make the call in their place | ```json { @@ -696,7 +699,7 @@ GET /user/status ``` ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user/status" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/status" ``` Example response: @@ -721,7 +724,7 @@ GET /users/:id_or_username/status | Attribute | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------- | -| `id_or_username` | string | yes | The ID or username of the user to get a status of | +| `id_or_username` | string | yes | ID or username of the user to get a status of | ```shell curl "https://gitlab.example.com/users/janedoe/status" @@ -749,8 +752,8 @@ PUT /user/status | Attribute | Type | Required | Description | | -------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `emoji` | string | no | The name of the emoji to use as status. If omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index](https://github.com/bonusly/gemojione/blob/master/config/index.json). | -| `message` | string | no | The message to set as a status. It can also contain emoji codes. | +| `emoji` | string | no | Name of the emoji to use as status. If omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index](https://github.com/bonusly/gemojione/blob/master/config/index.json). | +| `message` | string | no | Message to set as a status. It can also contain emoji codes. | | `clear_status_after` | string | no | Automatically clean up the status after a given time interval, allowed values: `30_minutes`, `3_hours`, `8_hours`, `1_day`, `3_days`, `7_days`, `30_days` 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. @@ -818,7 +821,7 @@ Parameters: | `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. | -## User Follow +## User follow ### Follow and unfollow users @@ -836,7 +839,7 @@ POST /users/:id/unfollow | Attribute | Type | Required | Description | | --------- | ------- | -------- | ---------------------------- | -| `id` | integer | yes | The ID of the user to follow | +| `id` | integer | yes | ID of the user to follow | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/follow" @@ -871,7 +874,7 @@ GET /users/:id/following | Attribute | Type | Required | Description | | --------- | ------- | -------- | ---------------------------- | -| `id` | integer | yes | The ID of the user to follow | +| `id` | integer | yes | ID of the user to follow | ```shell curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/followers" @@ -975,7 +978,7 @@ GET /users/:id_or_username/keys | Attribute | Type | Required | Description | | ---------------- | ------ | -------- | ------------------------------------------------------- | -| `id_or_username` | string | yes | The ID or username of the user to get the SSH keys for. | +| `id_or_username` | string | yes | ID or username of the user to get the SSH keys for. | ## Single SSH key @@ -989,7 +992,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|--------|----------|----------------------| -| `key_id` | string | yes | The ID of an SSH key | +| `key_id` | string | yes | ID of an SSH key | ```json { @@ -1038,9 +1041,9 @@ Parameters: | Attribute | Type | Required | Description | |--------------|--------|----------|--------------------------------------------------------------------------------| -| `title` | string | yes | new SSH key's title | -| `key` | string | yes | new SSH key | -| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | +| `title` | string | yes | New SSH key's title | +| `key` | string | yes | New SSH key | +| `expires_at` | string | no | Expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | ```json { @@ -1079,9 +1082,9 @@ Parameters: | Attribute | Type | Required | Description | |--------------|---------|----------|--------------------------------------------------------------------------------| | `id` | integer | yes | ID of specified user | -| `title` | string | yes | new SSH key's title | -| `key` | string | yes | new SSH key | -| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | +| `title` | string | yes | New SSH key's title | +| `key` | string | yes | New SSH key | +| `expires_at` | string | no | Expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | NOTE: This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events). **(PREMIUM)** @@ -1152,7 +1155,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `key_id` | integer | yes | The ID of the GPG key | +| `key_id` | integer | yes | ID of the GPG key | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys/1" @@ -1180,7 +1183,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|--------|----------|-----------------| -| `key` | string | yes | The new GPG key | +| `key` | string | yes | New GPG key | ```shell curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \ @@ -1211,7 +1214,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `key_id` | integer | yes | The ID of the GPG key | +| `key_id` | integer | yes | ID of the GPG key | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys/1" @@ -1231,7 +1234,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | ------------------ | -| `id` | integer | yes | The ID of the user | +| `id` | integer | yes | ID of the user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys" @@ -1262,8 +1265,8 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID of the user | -| `key_id` | integer | yes | The ID of the GPG key | +| `id` | integer | yes | ID of the user | +| `key_id` | integer | yes | ID of the GPG key | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys/1" @@ -1291,8 +1294,8 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID of the user | -| `key_id` | integer | yes | The ID of the GPG key | +| `id` | integer | yes | ID of the user | +| `key_id` | integer | yes | ID of the GPG key | ```shell curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \ @@ -1323,8 +1326,8 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID of the user | -| `key_id` | integer | yes | The ID of the GPG key | +| `id` | integer | yes | ID of the user | +| `key_id` | integer | yes | ID of the GPG key | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys/1" @@ -1627,8 +1630,8 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------------------- | -| `user_id` | integer | yes | The ID of the user | -| `state` | string | no | filter tokens based on state (`all`, `active`, `inactive`) | +| `user_id` | integer | yes | ID of the user | +| `state` | string | no | Filter tokens based on state (`all`, `active`, `inactive`) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens" @@ -1761,8 +1764,8 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | ------- | -------- | --------------------------------- | -| `user_id` | integer | yes | The ID of the user | -| `impersonation_token_id` | integer | yes | The ID of the impersonation token | +| `user_id` | integer | yes | ID of the user | +| `impersonation_token_id` | integer | yes | ID of the impersonation token | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2" @@ -1802,10 +1805,10 @@ POST /users/:user_id/impersonation_tokens | Attribute | Type | Required | Description | | ------------ | ------- | -------- | --------------------------------------------------------------------------- | -| `user_id` | integer | yes | The ID of the user | -| `name` | string | yes | The name of the impersonation token | -| `expires_at` | date | no | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`) | -| `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user`) | +| `user_id` | integer | yes | ID of the user | +| `name` | string | yes | Name of the impersonation token | +| `expires_at` | date | no | Expiration date of the impersonation token in ISO format (`YYYY-MM-DD`) | +| `scopes` | array | yes | 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" \ @@ -1845,8 +1848,8 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | ------- | -------- | --------------------------------- | -| `user_id` | integer | yes | The ID of the user | -| `impersonation_token_id` | integer | yes | The ID of the impersonation token | +| `user_id` | integer | yes | ID of the user | +| `impersonation_token_id` | integer | yes | ID of the impersonation token | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1" @@ -1867,10 +1870,10 @@ POST /users/:user_id/personal_access_tokens | Attribute | Type | Required | Description | | ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | -| `user_id` | integer | yes | The ID of the user | -| `name` | string | yes | The name of the personal access token | -| `expires_at` | date | no | The expiration date of the personal access token in ISO format (`YYYY-MM-DD`) | -| `scopes` | array | yes | The array of scopes of the personal access token. See [personal access token scopes](../user/profile/personal_access_tokens.md#personal-access-token-scopes) for possible values. | +| `user_id` | integer | yes | ID of the user | +| `name` | string | yes | Name of the personal access token | +| `expires_at` | date | no | Expiration date of the personal access token in ISO format (`YYYY-MM-DD`) | +| `scopes` | array | yes | Array of scopes of the personal access token. See [personal access token scopes](../user/profile/personal_access_tokens.md#personal-access-token-scopes) for possible values. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \ @@ -1895,10 +1898,11 @@ Example response: } ``` -## Get user activities (administrator only) +## Get user activities -NOTE: -This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above. +Pre-requisite: + +- You must be an administrator. Get the last activity date for all users, sorted from oldest to newest. @@ -1921,7 +1925,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------------------------------------------------------- | -| `from` | string | no | Date string in the format YEAR-MONTH-DAY. For example, `2016-03-11`. Defaults to 6 months ago. | +| `from` | string | no | Date string in the format `YEAR-MM-DD`. For example, `2016-03-11`. Defaults to 6 months ago. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/activities" @@ -1951,11 +1955,15 @@ Example response: `last_activity_at` is deprecated. Use `last_activity_on` instead. -## User memberships (administrator only) +## User memberships > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20532) in GitLab 12.8. -Lists all projects and groups a user is a member of. This endpoint is available for administrators only. +Pre-requisite: + +- You must be an administrator. + +Lists all projects and groups a user is a member of. It returns the `source_id`, `source_name`, `source_type` and `access_level` of a membership. Source can be of type `Namespace` (representing a group) or `Project`. The response represents only direct memberships. Inherited memberships, for example in subgroups, are not included. Access levels are represented by an integer value. For more details, read about the meaning of [access level values](access_requests.md#valid-access-levels). @@ -1968,7 +1976,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------- | -------- | ------------------------------------------------------------------ | -| `id` | integer | yes | The ID of a specified user | +| `id` | integer | yes | ID of a specified user | | `type` | string | no | Filter memberships by type. Can be either `Project` or `Namespace` | Returns: @@ -2000,3 +2008,37 @@ Example response: } ] ``` + +## Disable two factor authentication + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295260) in GitLab 15.2. + +Pre-requisite: + +- You must be an administrator. + +Disables two factor authentication (2FA) for the specified user. + +Administrators cannot disable 2FA for their own user account or other administrators using the API. Instead, they can disable an +administrator's 2FA [using the Rails console](../security/two_factor_authentication.md#for-a-single-user). + +```plaintext +PATCH /users/:id/disable_two_factor +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | --------------------- | +| `id` | integer | yes | ID of the user | + +```shell +curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/1/disable_two_factor" +``` + +Returns: + +- `204 No content` on success. +- `400 Bad request` if two factor authentication is not enabled for the specified user. +- `403 Forbidden` if not authenticated as an administrator. +- `404 User Not Found` if user cannot be found. |