From a7b3560714b4d9cc4ab32dffcd1f74a284b93580 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Fri, 18 Feb 2022 09:45:46 +0000 Subject: Add latest changes from gitlab-org/gitlab@14-8-stable-ee --- doc/api/access_requests.md | 2 +- doc/api/api_resources.md | 1 - doc/api/appearance.md | 2 +- doc/api/applications.md | 2 +- doc/api/audit_events.md | 2 +- doc/api/avatar.md | 2 +- doc/api/commits.md | 10 +- doc/api/container_registry.md | 33 +- doc/api/dependency_proxy.md | 3 +- doc/api/deploy_keys.md | 2 +- doc/api/deploy_tokens.md | 6 +- doc/api/deployments.md | 77 +++- doc/api/dora/metrics.md | 2 +- doc/api/epics.md | 9 +- doc/api/error_tracking.md | 8 +- doc/api/geo_nodes.md | 39 ++ doc/api/graphql/index.md | 2 +- doc/api/graphql/reference/index.md | 587 +++++++++++++++++++++++++++-- doc/api/group_access_tokens.md | 4 +- doc/api/group_badges.md | 2 +- doc/api/group_clusters.md | 2 +- doc/api/groups.md | 80 +++- doc/api/index.md | 15 +- doc/api/instance_clusters.md | 3 +- doc/api/integrations.md | 7 +- doc/api/issues.md | 51 ++- doc/api/job_artifacts.md | 6 +- doc/api/jobs.md | 88 ++--- doc/api/lint.md | 6 +- doc/api/members.md | 2 +- doc/api/merge_request_approvals.md | 40 +- doc/api/merge_requests.md | 144 +++---- doc/api/metrics_dashboard_annotations.md | 2 +- doc/api/metrics_user_starred_dashboards.md | 2 +- doc/api/namespaces.md | 2 +- doc/api/notes.md | 2 +- doc/api/oauth2.md | 35 +- doc/api/pages.md | 2 +- doc/api/pages_domains.md | 2 +- doc/api/plan_limits.md | 5 +- doc/api/project_access_tokens.md | 2 +- doc/api/project_clusters.md | 2 +- doc/api/project_import_export.md | 8 +- doc/api/project_relations_export.md | 2 +- doc/api/project_snippets.md | 2 +- doc/api/projects.md | 109 +++--- doc/api/repository_files.md | 64 ++-- doc/api/runners.md | 200 +++++++--- doc/api/scim.md | 2 +- doc/api/settings.md | 9 +- doc/api/statistics.md | 2 +- doc/api/status_checks.md | 5 +- doc/api/suggestions.md | 4 +- doc/api/tags.md | 2 +- doc/api/usage_data.md | 2 +- doc/api/users.md | 87 ++--- doc/api/v3_to_v4.md | 19 +- doc/api/visual_review_discussions.md | 5 +- 58 files changed, 1355 insertions(+), 462 deletions(-) (limited to 'doc/api') diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 9c217a98c3d..08f3b78787b 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/api_resources.md b/doc/api/api_resources.md index 783823f80fb..3d54402ea0b 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -14,7 +14,6 @@ Available resources for the [GitLab REST API](index.md) can be grouped in the fo See also: -- [V3 to V4](v3_to_v4.md). - Adding [deploy keys for multiple projects](deploy_keys.md#add-deploy-keys-to-multiple-projects). - [API Resources for various templates](#templates-api-resources). diff --git a/doc/api/appearance.md b/doc/api/appearance.md index 5e7ffbff25c..7b98b226cde 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/applications.md b/doc/api/applications.md index bbf12438f28..aeb6a0452c5 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/audit_events.md b/doc/api/audit_events.md index 888323f9362..4ddd851ebda 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -312,7 +312,7 @@ Example response: ### Retrieve a specific project audit event -Only available to users with at least the [Maintainer role](../user/permissions.md) for the project. +Only available to users with at least the Maintainer role for the project. ```plaintext GET /projects/:id/audit_events/:audit_event_id diff --git a/doc/api/avatar.md b/doc/api/avatar.md index 5db8c30cb9a..bc47d3a4d9e 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/commits.md b/doc/api/commits.md index 6347af451a2..d7be9559527 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -8,6 +8,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository). Read more about [GitLab-specific information](../user/project/repository/index.md#commit-changes-to-a-repository) for commits. +## Responses + +In commit responses, `created_at` and `committed_date` are identical. +However, `committed_date` and `authored_date` are generated from different sources, +and may not be identical. + ## List repository commits Get a list of repository commits in a project. @@ -740,9 +746,9 @@ Example response: } ``` -## List Merge Requests associated with a commit +## List merge requests associated with a commit -Get a list of Merge Requests related to the specified commit. +Get a list of merge requests related to the specified commit. ```plaintext GET /projects/:id/repository/commits/:sha/merge_requests diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 68d339837b2..b61ec34b882 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -372,7 +372,8 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags | `keep_n` | integer | no | The amount of latest tags of given name to keep. | | `older_than` | string | no | Tags to delete that are older than the given time, written in human readable form `1h`, `1d`, `1month`. | -This API call performs the following operations: +This API returns [HTTP response status code 202](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202) +if successful, and performs the following operations: - It orders all tags by creation date. The creation date is the time of the manifest creation, not the time of tag push. @@ -396,10 +397,6 @@ If your Container Registry has a large number of tags to delete, only some of them will be deleted, and you might need to call this API multiple times. To schedule tags for automatic deletion, use a [cleanup policy](../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy) instead. -NOTE: -In GitLab 12.4 and later, individual tags are deleted. -For more details, see the [discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/15737). - Examples: 1. Remove tag names that are matching the regex (Git SHA), keep always at least 5, @@ -430,3 +427,29 @@ Examples: curl --request DELETE --data 'name_regex_delete=.*' --data 'older_than=1month' \ --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" ``` + +## Instance-wide endpoints + +Beside the group- and project-specific GitLab APIs explained above, +the Container Registry has its own endpoints. +To query those, follow the Registry's built-in mechanism to obtain and use an +[authentication token](https://docs.docker.com/registry/spec/auth/token/). + +NOTE: +These are different from project or personal access tokens in the GitLab application. + +### Listing all container repositories + +```plaintext +GET /v2/_catalog +``` + +To list all container repositories on your GitLab instance, admin credentials are required: + +```shell +$ curl --request GET --user ":" "https://gitlab.example.com/jwt/auth?service=container_registry&scope=registry:catalog:*" +{"token":" ... "} + +$ curl --header "Authorization: Bearer " https://gitlab.example.com:5050/v2/_catalog +{"repositories":["user/project1", "group/subgroup/project2", ... ]} +``` diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index 5401c007c0d..028584e69ff 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -12,8 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. Schedules for deletion the cached manifests and blobs for a group. This endpoint requires the -[Owner role](../user/permissions.md) -for the group. +Owner role for the group. ```plaintext DELETE /groups/:id/dependency_proxy/cache diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index b244384bd6a..ee6887e9d04 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## List all deploy keys **(FREE SELF)** Get a list of all deploy keys across all projects of the GitLab instance. This -endpoint requires an administrator role and is not available on GitLab.com. +endpoint requires administrator access and is not available on GitLab.com. ```plaintext GET /deploy_keys diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index 0f2b9a13a3f..77c2fe5e162 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9. -Get a list of all deploy tokens across the GitLab instance. This endpoint requires the Administrator role. +Get a list of all deploy tokens across the GitLab instance. This endpoint requires administrator access. ```plaintext GET /deploy_tokens @@ -49,7 +49,7 @@ Example response: ## Project deploy tokens -Project deploy token API endpoints require the [Maintainer role](../user/permissions.md) or higher +Project deploy token API endpoints require the Maintainer role or higher for the project. ### List project deploy tokens @@ -165,7 +165,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: " \ ## Group deploy tokens -Users with at least the [Maintainer role](../user/permissions.md) for the group can list group deploy +Users with at least the Maintainer role for the group can list group deploy tokens. Only group Owners can create and delete group deploy tokens. ### List group deploy tokens diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 70b3e76c3dd..29f9bd3e2ee 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -23,7 +23,7 @@ GET /projects/:id/deployments | `updated_after` | datetime | no | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `updated_before` | datetime | no | Return deployments updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `environment` | string | no | The [name of the environment](../ci/environments/index.md) to filter deployments by. | -| `status` | string | no | The status to filter deployments by. One of `created`, `running`, `success`, `failed`, `canceled`. +| `status` | string | no | The status to filter deployments by. One of `created`, `running`, `success`, `failed`, `canceled`, `blocked`. ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/deployments" @@ -201,6 +201,7 @@ Example response: "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "created_at": "2016-08-11T11:32:35.444Z", "updated_at": "2016-08-11T11:34:01.123Z", + "status": "success", "user": { "name": "Administrator", "username": "root", @@ -264,6 +265,29 @@ Example response: } ``` +Deployments created by users on GitLab Premium or higher include the `approvals` and `pending_approval_count` properties: + +```json +{ + "status": "created", + "pending_approval_count": 0, + "approvals": [ + { + "user": { + "id": 49, + "username": "project_6_bot", + "name": "****", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e83ac685f68ea07553ad3054c738c709?s=80&d=identicon", + "web_url": "http://localhost:3000/project_6_bot" + }, + "status": "approved" + } + ], + ... +} +``` + ## Create a deployment ```plaintext @@ -311,6 +335,29 @@ Example response: } ``` +Deployments created by users on GitLab Premium or higher include the `approvals` and `pending_approval_count` properties: + +```json +{ + "status": "created", + "pending_approval_count": 0, + "approvals": [ + { + "user": { + "id": 49, + "username": "project_6_bot", + "name": "****", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e83ac685f68ea07553ad3054c738c709?s=80&d=identicon", + "web_url": "http://localhost:3000/project_6_bot" + }, + "status": "approved" + } + ], + ... +} +``` + ## Update a deployment ```plaintext @@ -354,6 +401,29 @@ Example response: } ``` +Deployments created by users on GitLab Premium or higher include the `approvals` and `pending_approval_count` properties: + +```json +{ + "status": "created", + "pending_approval_count": 0, + "approvals": [ + { + "user": { + "id": 49, + "username": "project_6_bot", + "name": "****", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e83ac685f68ea07553ad3054c738c709?s=80&d=identicon", + "web_url": "http://localhost:3000/project_6_bot" + }, + "status": "approved" + } + ], + ... +} +``` + ## List of merge requests associated with a deployment > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35739) in GitLab 12.7. @@ -378,7 +448,10 @@ curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/a ## Approve or reject a blocked deployment **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `deployment_approvals`. Disabled by default. This feature is not ready for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `deployment_approvals`. Disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8. + +See [Deployment Approvals](../ci/environments/deployment_approvals.md) for more information about this feature. ```plaintext POST /projects/:id/deployments/:deployment_id/approval diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 3e7b7800034..3f078945b0f 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -10,7 +10,7 @@ type: reference, api > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab 13.10. > - The legacy key/value pair `{ "" => "" }` was removed from the payload in GitLab 14.0. -All methods require at least the Reporter [role](../../user/permissions.md). +All methods require at least the Reporter role. ## Get project-level DORA metrics diff --git a/doc/api/epics.md b/doc/api/epics.md index f3137559220..deb74cf21e9 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -40,12 +40,13 @@ are paginated. Read more on [pagination](index.md#pagination). WARNING: -> `reference` attribute in response is deprecated in favour of `references`. -> Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) +In [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) and later, +the `reference` attribute in responses is deprecated in favor of `references`. NOTE: -> `references.relative` is relative to the group that the epic is being requested. When epic is fetched from its origin group -> `relative` format would be the same as `short` format and when requested cross groups it is expected to be the same as `full` format. +`references.relative` is relative to the group that the epic is being requested from. When an epic +is fetched from its origin group, the `relative` format is the same as the `short` format. +When an epic is requested across groups, the `relative` format is expected to be the same as the `full` format. ## List epics for a group diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index c62d33f82f4..dbf832b301f 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond 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 --- @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Error Tracking project settings The project settings API allows you to retrieve the [Error Tracking](../operations/error_tracking.md) -settings for a project. Only for users with [Maintainer role](../user/permissions.md) for the project. +settings for a project. Only for users with Maintainer role for the project. ### Get Error Tracking settings @@ -42,7 +42,7 @@ Example response: ### Enable or disable the Error Tracking project settings The API allows you to enable or disable the Error Tracking settings for a project. Only for users with the -[Maintainer role](../user/permissions.md) for the project. +Maintainer role for the project. ```plaintext PATCH /projects/:id/error_tracking/settings @@ -75,7 +75,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68384) in GitLab 14.3. For [integrated error tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) feature. Only for users with the -[Maintainer role](../user/permissions.md) for the project. +Maintainer role for the project. ### List project client keys diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index fe1674649b6..a152c443902 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -467,6 +467,19 @@ Example response: "uploads_verified_count": null, "uploads_verification_failed_count": null, "uploads_verified_in_percentage": "0.00%", + "job_artifacts_count": 5, + "job_artifacts_checksum_total_count": 5, + "job_artifacts_checksummed_count": 5, + "job_artifacts_checksum_failed_count": 0, + "job_artifacts_synced_count": 5, + "job_artifacts_failed_count": 0, + "job_artifacts_registry_count": 5, + "job_artifacts_verification_total_count": 5, + "job_artifacts_verified_count": 5, + "job_artifacts_verification_failed_count": 0, + "job_artifacts_synced_in_percentage": "100.00%", + "job_artifacts_verified_in_percentage": "100.00%", + "job_artifacts_synced_missing_on_primary_count": 0, }, { "geo_node_id": 2, @@ -623,6 +636,19 @@ Example response: "uploads_verified_count": null, "uploads_verification_failed_count": null, "uploads_verified_in_percentage": "0.00%", + "job_artifacts_count": 5, + "job_artifacts_checksum_total_count": 5, + "job_artifacts_checksummed_count": 5, + "job_artifacts_checksum_failed_count": 0, + "job_artifacts_synced_count": 5, + "job_artifacts_failed_count": 0, + "job_artifacts_registry_count": 5, + "job_artifacts_verification_total_count": 5, + "job_artifacts_verified_count": 5, + "job_artifacts_verification_failed_count": 0, + "job_artifacts_synced_in_percentage": "100.00%", + "job_artifacts_verified_in_percentage": "100.00%", + "job_artifacts_synced_missing_on_primary_count": 0, } ] ``` @@ -776,6 +802,19 @@ Example response: "uploads_verified_count": null, "uploads_verification_failed_count": null, "uploads_verified_in_percentage": "0.00%", + "job_artifacts_count": 5, + "job_artifacts_checksum_total_count": 5, + "job_artifacts_checksummed_count": 5, + "job_artifacts_checksum_failed_count": 0, + "job_artifacts_synced_count": 5, + "job_artifacts_failed_count": 0, + "job_artifacts_registry_count": 5, + "job_artifacts_verification_total_count": 5, + "job_artifacts_verified_count": 5, + "job_artifacts_verification_failed_count": 0, + "job_artifacts_synced_in_percentage": "100.00%", + "job_artifacts_verified_in_percentage": "100.00%", + "job_artifacts_synced_missing_on_primary_count": 0, } ``` diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 14512286ade..d0e65b8c4eb 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -152,7 +152,7 @@ Root-level queries are defined in ### Multiplex queries GitLab supports batching queries into a single request using -[apollo-link-batch-http](https://www.apollographql.com/docs/link/links/batch-http/). More +[`@apollo/client/link/batch-http`](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http/). More information about multiplexed queries is also available for [GraphQL Ruby](https://graphql-ruby.org/queries/multiplex.html), the library GitLab uses on the backend. diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 4ca40d1fa11..18c99b7d151 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -376,7 +376,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `active` | [`Boolean`](#boolean) | Filter runners by active (true) or paused (false) status. | +| `active` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 14.8. This was renamed. Use: `paused`. | +| `paused` | [`Boolean`](#boolean) | Filter runners by `paused` (true) or `active` (false) status. | | `search` | [`String`](#string) | Filter by full token or partial text in description field. | | `sort` | [`CiRunnerSort`](#cirunnersort) | Sort order of results. | | `status` | [`CiRunnerStatus`](#cirunnerstatus) | Filter runners by status. | @@ -1017,6 +1018,30 @@ Input type: `CommitCreateInput` | `content` | [`[String!]`](#string) | Contents of the commit. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.configureContainerScanning` + +Configure Container Scanning for a project by enabling Container Scanning in a new or modified +`.gitlab-ci.yml` file in a new branch. The new branch and a URL to +create a merge request are part of the response. + +Input type: `ConfigureContainerScanningInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `projectPath` | [`ID!`](#id) | Full path of the project. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `branch` | [`String`](#string) | Branch that has the new/modified `.gitlab-ci.yml` file. | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `successPath` | [`String`](#string) | Redirect path to use when the response is successful. | + ### `Mutation.configureDependencyScanning` Configure Dependency Scanning for a project by enabling Dependency Scanning in a new or modified @@ -1118,7 +1143,7 @@ Input type: `ConfigureSecretDetectionInput` ### `Mutation.corpusCreate` -Available only when feature flag `corpus_management` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. +Available only when feature flag `corpus_management` is enabled. This flag is enabled by default. Input type: `CorpusCreateInput` @@ -1395,6 +1420,8 @@ Input type: `CreateIssueInput` | `locked` | [`Boolean`](#boolean) | Indicates discussion is locked on the issue. | | `mergeRequestToResolveDiscussionsOf` | [`MergeRequestID`](#mergerequestid) | IID of a merge request for which to resolve discussions. | | `milestoneId` | [`MilestoneID`](#milestoneid) | ID of the milestone to assign to the issue. On update milestone will be removed if set to null. | +| `moveAfterId` | [`IssueID`](#issueid) | Global ID of issue that should be placed after the current issue. | +| `moveBeforeId` | [`IssueID`](#issueid) | Global ID of issue that should be placed before the current issue. | | `projectPath` | [`ID!`](#id) | Project full path the issue is associated with. | | `title` | [`String!`](#string) | Title of the issue. | | `type` | [`IssueType`](#issuetype) | Type of the issue. | @@ -1489,11 +1516,9 @@ Input type: `CreateSnippetInput` | Name | Type | Description | | ---- | ---- | ----------- | | `blobActions` | [`[SnippetBlobActionInputType!]`](#snippetblobactioninputtype) | Actions to perform over the snippet repository and blobs. | -| `captchaResponse` **{warning-solid}** | [`String`](#string) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `description` | [`String`](#string) | Description of the snippet. | | `projectPath` | [`ID`](#id) | Full path of the project the snippet is associated with. | -| `spamLogId` **{warning-solid}** | [`Int`](#int) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | | `title` | [`String!`](#string) | Title of the snippet. | | `uploadedFiles` | [`[String!]`](#string) | Paths to files uploaded in the snippet description. | | `visibilityLevel` | [`VisibilityLevelsEnum!`](#visibilitylevelsenum) | Visibility level of the snippet. | @@ -1502,13 +1527,9 @@ Input type: `CreateSnippetInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `captchaSiteKey` **{warning-solid}** | [`String`](#string) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `needsCaptchaResponse` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | | `snippet` | [`Snippet`](#snippet) | Snippet after mutation. | -| `spam` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | -| `spamLogId` **{warning-solid}** | [`Int`](#int) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | ### `Mutation.createTestCase` @@ -4157,12 +4178,13 @@ Input type: `RunnerUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `accessLevel` | [`CiRunnerAccessLevel`](#cirunneraccesslevel) | Access level of the runner. | -| `active` | [`Boolean`](#boolean) | Indicates the runner is allowed to receive jobs. | +| `active` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated:** This was renamed. Please use `paused`. Deprecated in 14.8. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `description` | [`String`](#string) | Description of the runner. | | `id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner to update. | | `locked` | [`Boolean`](#boolean) | Indicates the runner is locked. | | `maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. | +| `paused` | [`Boolean`](#boolean) | Indicates the runner is not allowed to receive jobs. | | `privateProjectsMinutesCostFactor` | [`Float`](#float) | Private projects' "minutes cost factor" associated with the runner (GitLab.com only). | | `publicProjectsMinutesCostFactor` | [`Float`](#float) | Public projects' "minutes cost factor" associated with the runner (GitLab.com only). | | `runUntagged` | [`Boolean`](#boolean) | Indicates the runner is able to run untagged jobs. | @@ -4282,6 +4304,28 @@ Input type: `SecurityPolicyProjectUnassignInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.securityTrainingUpdate` + +Input type: `SecurityTrainingUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `isEnabled` | [`Boolean!`](#boolean) | Sets the training provider as enabled for the project. | +| `isPrimary` | [`Boolean`](#boolean) | Sets the training provider as primary for the project. | +| `projectPath` | [`ID!`](#id) | Full path of the project. | +| `providerId` | [`SecurityTrainingProviderID!`](#securitytrainingproviderid) | ID of the provider. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `training` | [`ProjectSecurityTraining`](#projectsecuritytraining) | Represents the training entity subject to mutation. | + ### `Mutation.terraformStateDelete` Input type: `TerraformStateDeleteInput` @@ -4336,6 +4380,27 @@ Input type: `TerraformStateUnlockInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.timelineEventCreate` + +Input type: `TimelineEventCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `incidentId` | [`IssueID!`](#issueid) | Incident ID of the timeline event. | +| `note` | [`String!`](#string) | Text note of the timeline event. | +| `occurredAt` | [`Time!`](#time) | Timestamp of when the event occurred. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `timelineEvent` | [`TimelineEventType`](#timelineeventtype) | Timeline event. | + ### `Mutation.timelineEventDestroy` Input type: `TimelineEventDestroyInput` @@ -4355,6 +4420,27 @@ Input type: `TimelineEventDestroyInput` | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | `timelineEvent` | [`TimelineEventType`](#timelineeventtype) | Timeline event. | +### `Mutation.timelineEventUpdate` + +Input type: `TimelineEventUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `id` | [`IncidentManagementTimelineEventID!`](#incidentmanagementtimelineeventid) | ID of the timeline event to update. | +| `note` | [`String`](#string) | Text note of the timeline event. | +| `occurredAt` | [`Time`](#time) | Timestamp when the event occurred. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `timelineEvent` | [`TimelineEventType`](#timelineeventtype) | Timeline event. | + ### `Mutation.todoCreate` Input type: `TodoCreateInput` @@ -4846,11 +4932,9 @@ Input type: `UpdateSnippetInput` | Name | Type | Description | | ---- | ---- | ----------- | | `blobActions` | [`[SnippetBlobActionInputType!]`](#snippetblobactioninputtype) | Actions to perform over the snippet repository and blobs. | -| `captchaResponse` **{warning-solid}** | [`String`](#string) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `description` | [`String`](#string) | Description of the snippet. | | `id` | [`SnippetID!`](#snippetid) | Global ID of the snippet to update. | -| `spamLogId` **{warning-solid}** | [`Int`](#int) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | | `title` | [`String`](#string) | Title of the snippet. | | `visibilityLevel` | [`VisibilityLevelsEnum`](#visibilitylevelsenum) | Visibility level of the snippet. | @@ -4858,13 +4942,9 @@ Input type: `UpdateSnippetInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `captchaSiteKey` **{warning-solid}** | [`String`](#string) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `needsCaptchaResponse` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | | `snippet` | [`Snippet`](#snippet) | Snippet after mutation. | -| `spam` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | -| `spamLogId` **{warning-solid}** | [`Int`](#int) | **Deprecated:** Use spam protection with HTTP headers instead. Deprecated in 13.11. | ### `Mutation.userCalloutCreate` @@ -4885,6 +4965,25 @@ Input type: `UserCalloutCreateInput` | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | `userCallout` | [`UserCallout!`](#usercallout) | User callout dismissed. | +### `Mutation.userPreferencesUpdate` + +Input type: `UserPreferencesUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `issuesSort` | [`IssueSort`](#issuesort) | Sort order for issue lists. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `userPreferences` | [`UserPreferences`](#userpreferences) | User preferences after mutation. | + ### `Mutation.vulnerabilityConfirm` Input type: `VulnerabilityConfirmInput` @@ -5057,7 +5156,7 @@ Input type: `VulnerabilityRevertToDetectedInput` ### `Mutation.workItemCreate` -Available only when feature flag `work_items` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. +Creates a work item. Available only when feature flag `work_items` is enabled. The feature is experimental and is subject to change without notice. Input type: `WorkItemCreateInput` @@ -5079,6 +5178,50 @@ Input type: `WorkItemCreateInput` | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | `workItem` | [`WorkItem`](#workitem) | Created work item. | +### `Mutation.workItemDelete` + +Deletes a work item. Available only when feature flag `work_items` is enabled. The feature is experimental and is subject to change without notice. + +Input type: `WorkItemDeleteInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `project` | [`Project`](#project) | Project the deleted work item belonged to. | + +### `Mutation.workItemUpdate` + +Updates a work item by Global ID. Available only when feature flag `work_items` is enabled. The feature is experimental and is subject to change without notice. + +Input type: `WorkItemUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | +| `stateEvent` | [`WorkItemStateEvent`](#workitemstateevent) | Close or reopen a work item. | +| `title` | [`String`](#string) | Title of the work item. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `workItem` | [`WorkItem`](#workitem) | Updated work item. | + ## Connections Some types in our schema are `Connection` types - they represent a paginated @@ -6648,6 +6791,29 @@ The edge type for [`JiraProject`](#jiraproject). | `cursor` | [`String!`](#string) | A cursor for use in pagination. | | `node` | [`JiraProject`](#jiraproject) | The item at the end of the edge. | +#### `JobArtifactRegistryConnection` + +The connection type for [`JobArtifactRegistry`](#jobartifactregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `edges` | [`[JobArtifactRegistryEdge]`](#jobartifactregistryedge) | A list of edges. | +| `nodes` | [`[JobArtifactRegistry]`](#jobartifactregistry) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `JobArtifactRegistryEdge` + +The edge type for [`JobArtifactRegistry`](#jobartifactregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`JobArtifactRegistry`](#jobartifactregistry) | The item at the end of the edge. | + #### `JobNeedUnionConnection` The connection type for [`JobNeedUnion`](#jobneedunion). @@ -8490,6 +8656,18 @@ Describes a rule for who can approve merge requests. | `type` | [`ApprovalRuleType`](#approvalruletype) | Type of the rule. | | `users` | [`UserCoreConnection`](#usercoreconnection) | List of users added as approvers for the rule. (see [Connections](#connections)) | +### `AssetType` + +Represents a vulnerability asset type. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `name` | [`String!`](#string) | Name of the asset. | +| `type` | [`String!`](#string) | Type of the asset. | +| `url` | [`String!`](#string) | URL of the asset. | + ### `AwardEmoji` An emoji awarded by a user. @@ -8680,6 +8858,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `authorUsername` | [`String`](#string) | Filter epics by author. | | `confidential` | [`Boolean`](#boolean) | Filter epics by given confidentiality. | +| `createdAfter` | [`Time`](#time) | Epics created after this date. | +| `createdBefore` | [`Time`](#time) | Epics created before this date. | | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | `iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | @@ -8696,6 +8876,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`EpicState`](#epicstate) | Filter epics by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | +| `updatedAfter` | [`Time`](#time) | Epics updated after this date. | +| `updatedBefore` | [`Time`](#time) | Epics updated before this date. | ##### `BoardEpic.children` @@ -8713,6 +8895,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `authorUsername` | [`String`](#string) | Filter epics by author. | | `confidential` | [`Boolean`](#boolean) | Filter epics by given confidentiality. | +| `createdAfter` | [`Time`](#time) | Epics created after this date. | +| `createdBefore` | [`Time`](#time) | Epics created before this date. | | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | `iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | @@ -8729,6 +8913,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`EpicState`](#epicstate) | Filter epics by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | +| `updatedAfter` | [`Time`](#time) | Epics updated after this date. | +| `updatedBefore` | [`Time`](#time) | Epics updated before this date. | ##### `BoardEpic.currentUserTodos` @@ -9015,31 +9201,51 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | | `accessLevel` | [`CiRunnerAccessLevel!`](#cirunneraccesslevel) | Access level of the runner. | -| `active` | [`Boolean!`](#boolean) | Indicates the runner is allowed to receive jobs. | +| `active` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 14.8. Use paused. | | `adminUrl` | [`String`](#string) | Admin URL of the runner. Only available for administrators. | | `contactedAt` | [`Time`](#time) | Timestamp of last contact from this runner. | | `createdAt` | [`Time`](#time) | Timestamp of creation of this runner. | | `description` | [`String`](#string) | Description of the runner. | | `editAdminUrl` | [`String`](#string) | Admin form URL of the runner. Only available for administrators. | | `executorName` | [`String`](#string) | Executor last advertised by the runner. Available only when feature flag `graphql_ci_runner_executor` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| `groups` | [`GroupConnection`](#groupconnection) | Groups the runner is associated with. For group runners only. (see [Connections](#connections)) | | `id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner. | | `ipAddress` | [`String`](#string) | IP address of the runner. | | `jobCount` | [`Int`](#int) | Number of jobs processed by the runner (limited to 1000, plus one to indicate that more items exist). | | `locked` | [`Boolean`](#boolean) | Indicates the runner is locked. | | `maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. | +| `paused` | [`Boolean!`](#boolean) | Indicates the runner is paused and not available to run jobs. | | `privateProjectsMinutesCostFactor` | [`Float`](#float) | Private projects' "minutes cost factor" associated with the runner (GitLab.com only). | | `projectCount` | [`Int`](#int) | Number of projects that the runner is associated with. | +| `projects` | [`ProjectConnection`](#projectconnection) | Projects the runner is associated with. For project runners only. (see [Connections](#connections)) | | `publicProjectsMinutesCostFactor` | [`Float`](#float) | Public projects' "minutes cost factor" associated with the runner (GitLab.com only). | | `revision` | [`String`](#string) | Revision of the runner. | | `runUntagged` | [`Boolean!`](#boolean) | Indicates the runner is able to run untagged jobs. | | `runnerType` | [`CiRunnerType!`](#cirunnertype) | Type of the runner. | | `shortSha` | [`String`](#string) | First eight characters of the runner's token used to authenticate new job requests. Used as the runner's unique ID. | | `tagList` | [`[String!]`](#string) | Tags associated with the runner. | +| `tokenExpiresAt` | [`Time`](#time) | Runner token expiration time. | | `userPermissions` | [`RunnerPermissions!`](#runnerpermissions) | Permissions for the current user on the resource. | | `version` | [`String`](#string) | Version of the runner. | #### Fields with arguments +##### `CiRunner.jobs` + +Jobs assigned to the runner. + +Returns [`CiJobConnection`](#cijobconnection). + +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 | +| ---- | ---- | ----------- | +| `statuses` | [`[CiJobStatus!]`](#cijobstatus) | Filter jobs by status. | + ##### `CiRunner.status` Status of the runner. @@ -9174,7 +9380,7 @@ Represents a code quality degradation on the pipeline. | `fingerprint` | [`String!`](#string) | Unique fingerprint to identify the code quality degradation. For example, an MD5 hash. | | `line` | [`Int!`](#int) | Line on which the code quality degradation occurred. | | `path` | [`String!`](#string) | Relative path to the file containing the code quality degradation. | -| `severity` | [`CodeQualityDegradationSeverity!`](#codequalitydegradationseverity) | Status of the degradation (BLOCKER, CRITICAL, MAJOR, MINOR, INFO). | +| `severity` | [`CodeQualityDegradationSeverity!`](#codequalitydegradationseverity) | Status of the degradation (BLOCKER, CRITICAL, MAJOR, MINOR, INFO, UNKNOWN). | ### `Commit` @@ -9518,6 +9724,7 @@ Represents a DAST profile schedule. | `cadence` | [`DastProfileCadence`](#dastprofilecadence) | Cadence of the DAST profile schedule. | | `id` | [`DastProfileScheduleID!`](#dastprofilescheduleid) | ID of the DAST profile schedule. | | `nextRunAt` | [`Time`](#time) | Next run time of the DAST profile schedule in the given timezone. | +| `ownerValid` | [`Boolean`](#boolean) | Status of the current owner of the DAST profile schedule. | | `startsAt` | [`Time`](#time) | Start time of the DAST profile schedule in the given timezone. | | `timezone` | [`String`](#string) | Time zone of the start time of the DAST profile schedule. | @@ -10177,6 +10384,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `authorUsername` | [`String`](#string) | Filter epics by author. | | `confidential` | [`Boolean`](#boolean) | Filter epics by given confidentiality. | +| `createdAfter` | [`Time`](#time) | Epics created after this date. | +| `createdBefore` | [`Time`](#time) | Epics created before this date. | | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | `iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | @@ -10193,6 +10402,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`EpicState`](#epicstate) | Filter epics by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | +| `updatedAfter` | [`Time`](#time) | Epics updated after this date. | +| `updatedBefore` | [`Time`](#time) | Epics updated before this date. | ##### `Epic.children` @@ -10210,6 +10421,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `authorUsername` | [`String`](#string) | Filter epics by author. | | `confidential` | [`Boolean`](#boolean) | Filter epics by given confidentiality. | +| `createdAfter` | [`Time`](#time) | Epics created after this date. | +| `createdBefore` | [`Time`](#time) | Epics created before this date. | | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | `iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | @@ -10226,6 +10439,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`EpicState`](#epicstate) | Filter epics by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | +| `updatedAfter` | [`Time`](#time) | Epics updated after this date. | +| `updatedBefore` | [`Time`](#time) | Epics updated before this date. | ##### `Epic.currentUserTodos` @@ -10531,6 +10746,7 @@ Represents an external resource to send audit events to. | `destinationUrl` | [`String!`](#string) | External destination to send audit events to. | | `group` | [`Group!`](#group) | Group the destination belongs to. | | `id` | [`ID!`](#id) | ID of the destination. | +| `verificationToken` | [`String!`](#string) | Verification token to validate source of event. | ### `ExternalIssue` @@ -10588,6 +10804,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `ids` | [`[ID!]`](#id) | Filters registries by their ID. | +##### `GeoNode.jobArtifactRegistries` + +Find Job Artifact registries on this Geo node Available only when feature flag `geo_job_artifact_replication` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. + +Returns [`JobArtifactRegistryConnection`](#jobartifactregistryconnection). + +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 | +| ---- | ---- | ----------- | +| `ids` | [`[ID!]`](#id) | Filters registries by their ID. | + ##### `GeoNode.lfsObjectRegistries` Find LFS object registries on this Geo node. @@ -10770,6 +11002,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `parent` | [`Group`](#group) | Parent group. | | `path` | [`String!`](#string) | Path of the namespace. | | `projectCreationLevel` | [`String`](#string) | Permission level required to create projects in the group. | +| `recentIssueBoards` | [`BoardConnection`](#boardconnection) | List of recently visited boards of the group. Maximum size is 4. (see [Connections](#connections)) | | `repositorySizeExcessProjectCount` | [`Int!`](#int) | Number of projects in the root namespace where the repository size exceeds the limit. | | `requestAccessEnabled` | [`Boolean`](#boolean) | Indicates if users can request access to namespace. | | `requireTwoFactorAuthentication` | [`Boolean`](#boolean) | Indicates if all users in this group are required to set up two-factor authentication. | @@ -10898,6 +11131,8 @@ Returns [`Epic`](#epic). | ---- | ---- | ----------- | | `authorUsername` | [`String`](#string) | Filter epics by author. | | `confidential` | [`Boolean`](#boolean) | Filter epics by given confidentiality. | +| `createdAfter` | [`Time`](#time) | Epics created after this date. | +| `createdBefore` | [`Time`](#time) | Epics created before this date. | | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | `iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | @@ -10914,6 +11149,8 @@ Returns [`Epic`](#epic). | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`EpicState`](#epicstate) | Filter epics by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | +| `updatedAfter` | [`Time`](#time) | Epics updated after this date. | +| `updatedBefore` | [`Time`](#time) | Epics updated before this date. | ##### `Group.epicBoard` @@ -10943,6 +11180,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `authorUsername` | [`String`](#string) | Filter epics by author. | | `confidential` | [`Boolean`](#boolean) | Filter epics by given confidentiality. | +| `createdAfter` | [`Time`](#time) | Epics created after this date. | +| `createdBefore` | [`Time`](#time) | Epics created before this date. | | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `iid` | [`ID`](#id) | IID of the epic, e.g., "1". | | `iidStartsWith` | [`String`](#string) | Filter epics by IID for autocomplete. | @@ -10959,6 +11198,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`EpicState`](#epicstate) | Filter epics by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | +| `updatedAfter` | [`Time`](#time) | Epics updated after this date. | +| `updatedBefore` | [`Time`](#time) | Epics updated before this date. | ##### `Group.groupMembers` @@ -11058,12 +11299,15 @@ four standard [pagination arguments](#connection-pagination-arguments): | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `id` | [`ID`](#id) | Global ID of the Iteration to look up. | | `iid` | [`ID`](#id) | Internal ID of the Iteration to look up. | +| `in` | [`[IterationSearchableField!]`](#iterationsearchablefield) | Fields in which the fuzzy-search should be performed with the query given in the argument `search`. Defaults to `[title]`. | | `includeAncestors` | [`Boolean`](#boolean) | Whether to include ancestor iterations. Defaults to true. | | `iterationCadenceIds` | [`[IterationsCadenceID!]`](#iterationscadenceid) | Global iteration cadence IDs by which to look up the iterations. | +| `search` | [`String`](#string) | Query used for fuzzy-searching in the fields selected in the argument `in`. Returns all iterations if empty. | +| `sort` | [`IterationSort`](#iterationsort) | List iterations by sort order. If unspecified, an arbitrary order (subject to change) is used. | | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`IterationState`](#iterationstate) | Filter iterations by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | -| `title` | [`String`](#string) | Fuzzy search by title. | +| `title` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.4. The argument will be removed in 15.4. Please use `search` and `in` fields instead. | ##### `Group.label` @@ -11126,6 +11370,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `Group.milestones` @@ -11208,8 +11454,9 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `active` | [`Boolean`](#boolean) | Filter runners by active (true) or paused (false) status. | +| `active` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 14.8. This was renamed. Use: `paused`. | | `membership` | [`RunnerMembershipFilter`](#runnermembershipfilter) | Control which runners to include in the results. | +| `paused` | [`Boolean`](#boolean) | Filter runners by `paused` (true) or `active` (false) status. | | `search` | [`String`](#string) | Filter by full token or partial text in description field. | | `sort` | [`CiRunnerSort`](#cirunnersort) | Sort order of results. | | `status` | [`CiRunnerStatus`](#cirunnerstatus) | Filter runners by status. | @@ -11331,6 +11578,20 @@ Represents a Group Membership. | `user` | [`UserCore`](#usercore) | User that is associated with the member object. | | `userPermissions` | [`GroupPermissions!`](#grouppermissions) | Permissions for the current user on the resource. | +#### Fields with arguments + +##### `GroupMember.mergeRequestInteraction` + +Find a merge request. + +Returns [`UserMergeRequestInteraction`](#usermergerequestinteraction). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `id` | [`MergeRequestID!`](#mergerequestid) | Global ID of the merge request. | + ### `GroupPermissions` #### Fields @@ -11749,6 +12010,23 @@ four standard [pagination arguments](#connection-pagination-arguments): | `jiraDisplayName` | [`String!`](#string) | Display name of the Jira user. | | `jiraEmail` | [`String`](#string) | Email of the Jira user, returned only for users with public emails. | +### `JobArtifactRegistry` + +Represents the Geo replication and verification state of a job_artifact. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `artifactId` | [`ID!`](#id) | ID of the Job Artifact. | +| `createdAt` | [`Time`](#time) | Timestamp when the JobArtifactRegistry was created. | +| `id` | [`ID!`](#id) | ID of the JobArtifactRegistry. | +| `lastSyncFailure` | [`String`](#string) | Error message during sync of the JobArtifactRegistry. | +| `lastSyncedAt` | [`Time`](#time) | Timestamp of the most recent successful sync of the JobArtifactRegistry. | +| `retryAt` | [`Time`](#time) | Timestamp after which the JobArtifactRegistry should be resynced. | +| `retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the JobArtifactRegistry. | +| `state` | [`RegistryState`](#registrystate) | Sync state of the JobArtifactRegistry. | + ### `JobPermissions` #### Fields @@ -12022,7 +12300,7 @@ A user assigned to a merge request. | `id` | [`ID!`](#id) | ID of the user. | | `location` | [`String`](#string) | Location of the user. | | `mergeRequestInteraction` | [`UserMergeRequestInteraction`](#usermergerequestinteraction) | Details of this user's interactions with the merge request. | -| `name` | [`String!`](#string) | Human-readable name of the user. Will return `****` if the user is a project bot and the requester does not have permission to read resource access tokens. | +| `name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | `namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | | `projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | `publicEmail` | [`String`](#string) | User's public email. | @@ -12066,6 +12344,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `MergeRequestAssignee.authoredMergeRequests` @@ -12098,6 +12378,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `MergeRequestAssignee.groups` @@ -12147,6 +12429,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `MergeRequestAssignee.snippets` @@ -12277,7 +12561,7 @@ A user assigned to a merge request as a reviewer. | `id` | [`ID!`](#id) | ID of the user. | | `location` | [`String`](#string) | Location of the user. | | `mergeRequestInteraction` | [`UserMergeRequestInteraction`](#usermergerequestinteraction) | Details of this user's interactions with the merge request. | -| `name` | [`String!`](#string) | Human-readable name of the user. Will return `****` if the user is a project bot and the requester does not have permission to read resource access tokens. | +| `name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | `namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | | `projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | `publicEmail` | [`String`](#string) | User's public email. | @@ -12321,6 +12605,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `MergeRequestReviewer.authoredMergeRequests` @@ -12353,6 +12639,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `MergeRequestReviewer.groups` @@ -12402,6 +12690,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `MergeRequestReviewer.snippets` @@ -13157,6 +13447,19 @@ Represents the Geo sync and verification state of a pipeline artifact. | `retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the PipelineArtifactRegistry. | | `state` | [`RegistryState`](#registrystate) | Sync state of the PipelineArtifactRegistry. | +### `PipelineCounts` + +Represents pipeline counts for the project. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `all` | [`Int`](#int) | Total number of pipelines for the project. | +| `finished` | [`Int`](#int) | Number of pipelines with scope FINISHED for the project. | +| `pending` | [`Int`](#int) | Number of pipelines with scope PENDING for the project. | +| `running` | [`Int`](#int) | Number of pipelines with scope RUNNING for the project. | + ### `PipelineMessage` #### Fields @@ -13184,10 +13487,13 @@ Represents vulnerability finding of a security report on the pipeline. | Name | Type | Description | | ---- | ---- | ----------- | +| `assets` | [`[AssetType!]`](#assettype) | List of assets associated with the vulnerability. | | `confidence` | [`String`](#string) | Type of the security report that found the vulnerability. | | `description` | [`String`](#string) | Description of the vulnerability finding. | +| `evidence` | [`VulnerabilityEvidence`](#vulnerabilityevidence) | Evidence for the vulnerability. | | `falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. | -| `identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerabilit finding. | +| `identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerability finding. | +| `links` | [`[VulnerabilityLink!]`](#vulnerabilitylink) | List of links associated with the vulnerability. | | `location` | [`VulnerabilityLocation`](#vulnerabilitylocation) | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability. | | `name` | [`String`](#string) | Name of the vulnerability finding. | | `project` | [`Project`](#project) | Project on which the vulnerability finding was found. | @@ -13197,6 +13503,7 @@ Represents vulnerability finding of a security report on the pipeline. | `severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability finding. | | `solution` | [`String`](#string) | URL to the vulnerability's details page. | | `state` | [`VulnerabilityState`](#vulnerabilitystate) | Finding status. | +| `title` | [`String`](#string) | Title of the vulnerability finding. | | `uuid` | [`String`](#string) | Name of the vulnerability finding. | ### `Project` @@ -13213,6 +13520,7 @@ Represents vulnerability finding of a security report on the pipeline. | `autocloseReferencedIssues` | [`Boolean`](#boolean) | Indicates if issues referenced by merge requests and commits within the default branch are closed automatically. | | `avatarUrl` | [`String`](#string) | URL to avatar image file of the project. | | `ciCdSettings` | [`ProjectCiCdSetting`](#projectcicdsetting) | CI/CD settings for the project. | +| `ciConfigPathOrDefault` | [`String!`](#string) | Path of the CI configuration file. | | `ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | The CI Job Tokens scope of access. | | `clusterAgents` | [`ClusterAgentConnection`](#clusteragentconnection) | Cluster agents associated with the project. (see [Connections](#connections)) | | `codeCoverageSummary` | [`CodeCoverageSummary`](#codecoveragesummary) | Code coverage summary associated with the project. | @@ -13220,7 +13528,7 @@ Represents vulnerability finding of a security report on the pipeline. | `containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy of the project. | | `containerRegistryEnabled` | [`Boolean`](#boolean) | Indicates if Container Registry is enabled for the current user. | | `containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the project. | -| `corpuses` | [`CoverageFuzzingCorpusConnection`](#coveragefuzzingcorpusconnection) | Find corpuses of the project. Available only when feature flag `corpus_management` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) | +| `corpuses` | [`CoverageFuzzingCorpusConnection`](#coveragefuzzingcorpusconnection) | Find corpuses of the project. Available only when feature flag `corpus_management` is enabled. This flag is enabled by default. (see [Connections](#connections)) | | `createdAt` | [`Time`](#time) | Timestamp of the project creation. | | `dastScannerProfiles` | [`DastScannerProfileConnection`](#dastscannerprofileconnection) | DAST scanner profiles associated with the project. (see [Connections](#connections)) | | `dastSiteProfiles` | [`DastSiteProfileConnection`](#dastsiteprofileconnection) | DAST Site Profiles associated with the project. (see [Connections](#connections)) | @@ -13234,7 +13542,6 @@ Represents vulnerability finding of a security report on the pipeline. | `httpUrlToRepo` | [`String`](#string) | URL to connect to the project via HTTPS. | | `id` | [`ID!`](#id) | ID of the project. | | `importStatus` | [`String`](#string) | Status of import background job of the project. | -| `incidentManagementEscalationPolicies` | [`EscalationPolicyTypeConnection`](#escalationpolicytypeconnection) | Incident Management escalation policies of the project. (see [Connections](#connections)) | | `issuesEnabled` | [`Boolean`](#boolean) | Indicates if Issues are enabled for the current user. | | `jiraImportStatus` | [`String`](#string) | Status of Jira import background job of the project. | | `jiraImports` | [`JiraImportConnection`](#jiraimportconnection) | Jira imports into the project. (see [Connections](#connections)) | @@ -13256,6 +13563,7 @@ Represents vulnerability finding of a security report on the pipeline. | `printingMergeRequestLinkEnabled` | [`Boolean`](#boolean) | Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line. | | `publicJobs` | [`Boolean`](#boolean) | Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts. | | `pushRules` | [`PushRules`](#pushrules) | Project's push rules settings. | +| `recentIssueBoards` | [`BoardConnection`](#boardconnection) | List of recently visited boards of the project. Maximum size is 4. (see [Connections](#connections)) | | `removeSourceBranchAfterMerge` | [`Boolean`](#boolean) | Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project. | | `repository` | [`Repository`](#repository) | Git repository of the project. | | `repositorySizeExcess` | [`Float`](#float) | Size of repository that exceeds the limit in bytes. | @@ -13542,6 +13850,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | `search` | [`String`](#string) | Search query for environment name. | | `states` | [`[String!]`](#string) | States of environments that should be included in result. | +##### `Project.incidentManagementEscalationPolicies` + +Incident Management escalation policies of the project. + +Returns [`EscalationPolicyTypeConnection`](#escalationpolicytypeconnection). + +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 | +| ---- | ---- | ----------- | +| `name` | [`String`](#string) | Fuzzy search by escalation policy name. | + ##### `Project.incidentManagementEscalationPolicy` Incident Management escalation policy of the project. @@ -13553,6 +13877,7 @@ Returns [`EscalationPolicyType`](#escalationpolicytype). | Name | Type | Description | | ---- | ---- | ----------- | | `id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | ID of the escalation policy. | +| `name` | [`String`](#string) | Fuzzy search by escalation policy name. | ##### `Project.incidentManagementOncallSchedules` @@ -13754,12 +14079,15 @@ four standard [pagination arguments](#connection-pagination-arguments): | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `id` | [`ID`](#id) | Global ID of the Iteration to look up. | | `iid` | [`ID`](#id) | Internal ID of the Iteration to look up. | +| `in` | [`[IterationSearchableField!]`](#iterationsearchablefield) | Fields in which the fuzzy-search should be performed with the query given in the argument `search`. Defaults to `[title]`. | | `includeAncestors` | [`Boolean`](#boolean) | Whether to include ancestor iterations. Defaults to true. | | `iterationCadenceIds` | [`[IterationsCadenceID!]`](#iterationscadenceid) | Global iteration cadence IDs by which to look up the iterations. | +| `search` | [`String`](#string) | Query used for fuzzy-searching in the fields selected in the argument `in`. Returns all iterations if empty. | +| `sort` | [`IterationSort`](#iterationsort) | List iterations by sort order. If unspecified, an arbitrary order (subject to change) is used. | | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`IterationState`](#iterationstate) | Filter iterations by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | -| `title` | [`String`](#string) | Fuzzy search by title. | +| `title` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.4. The argument will be removed in 15.4. Please use `search` and `in` fields instead. | ##### `Project.jobs` @@ -13848,6 +14176,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `Project.milestones` @@ -13923,6 +14253,20 @@ Returns [`Pipeline`](#pipeline). | `iid` | [`ID`](#id) | IID of the Pipeline. For example, "1". | | `sha` | [`String`](#string) | SHA of the Pipeline. For example, "dyd0f15ay83993f5ab66k927w28673882x99100b". | +##### `Project.pipelineCounts` + +Build pipeline counts of the project. + +Returns [`PipelineCounts`](#pipelinecounts). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | +| `sha` | [`String`](#string) | Filter pipelines by the SHA of the commit they are run for. | +| `source` | [`String`](#string) | Filter pipelines by their source. | + ##### `Project.pipelines` Build pipelines of the project. @@ -14229,6 +14573,20 @@ Represents a Project Membership. | `user` | [`UserCore`](#usercore) | User that is associated with the member object. | | `userPermissions` | [`ProjectPermissions!`](#projectpermissions) | Permissions for the current user on the resource. | +#### Fields with arguments + +##### `ProjectMember.mergeRequestInteraction` + +Find a merge request. + +Returns [`UserMergeRequestInteraction`](#usermergerequestinteraction). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `id` | [`MergeRequestID!`](#mergerequestid) | Global ID of the merge request. | + ### `ProjectPermissions` #### Fields @@ -14539,6 +14897,8 @@ Returns [`Tree`](#tree). | `canModifyBlob` | [`Boolean`](#boolean) | Whether the current user can modify the blob. | | `codeOwners` | [`[UserCore!]`](#usercore) | List of code owners for the blob. | | `editBlobPath` | [`String`](#string) | Web path to edit the blob in the old-style editor. | +| `environmentExternalUrlForRouteMap` | [`String`](#string) | Web path to blob on an environment. | +| `environmentFormattedExternalUrl` | [`String`](#string) | Environment on which the blob is available. | | `externalStorage` | [`String`](#string) | External storage being used, if enabled (for instance, 'LFS'). | | `externalStorageUrl` | [`String`](#string) | Web path to download the raw blob via external storage, if enabled. | | `fileType` | [`String`](#string) | Expected format of the blob based on the extension. | @@ -14548,6 +14908,7 @@ Returns [`Tree`](#tree). | `id` | [`ID!`](#id) | ID of the blob. | | `ideEditPath` | [`String`](#string) | Web path to edit this blob in the Web IDE. | | `ideForkAndEditPath` | [`String`](#string) | Web path to edit this blob in the Web IDE using a forked project. | +| `language` | [`String`](#string) | Blob language. | | `lfsOid` | [`String`](#string) | LFS OID of the blob. | | `mode` | [`String`](#string) | Blob mode. | | `name` | [`String`](#string) | Blob name. | @@ -14640,6 +15001,7 @@ Counts of requirements by their state. | Name | Type | Description | | ---- | ---- | ----------- | | `buildArtifactsSize` | [`Float!`](#float) | CI artifacts size in bytes. | +| `dependencyProxySize` | [`Float!`](#float) | Dependency Proxy sizes in bytes. | | `lfsObjectsSize` | [`Float!`](#float) | LFS objects size in bytes. | | `packagesSize` | [`Float!`](#float) | Packages size in bytes. | | `pipelineArtifactsSize` | [`Float!`](#float) | CI pipeline artifacts size in bytes. | @@ -15497,7 +15859,7 @@ Core represention of a GitLab user. | `groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | `id` | [`ID!`](#id) | ID of the user. | | `location` | [`String`](#string) | Location of the user. | -| `name` | [`String!`](#string) | Human-readable name of the user. Will return `****` if the user is a project bot and the requester does not have permission to read resource access tokens. | +| `name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | `namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | | `projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | `publicEmail` | [`String`](#string) | User's public email. | @@ -15541,6 +15903,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `UserCore.authoredMergeRequests` @@ -15573,6 +15937,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `UserCore.groups` @@ -15622,6 +15988,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ##### `UserCore.snippets` @@ -15726,6 +16094,14 @@ fields relate to interactions between the two entities. | ---- | ---- | ----------- | | `createSnippet` | [`Boolean!`](#boolean) | Indicates the user can perform `create_snippet` on this resource. | +### `UserPreferences` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `issuesSort` | [`IssueSort`](#issuesort) | Sort order for issue lists. | + ### `UserStatus` #### Fields @@ -15988,6 +16364,44 @@ Represents the vulnerability details URL field. | `name` | [`String`](#string) | Name of the field. | | `text` | [`String`](#string) | Text of the URL. | +### `VulnerabilityEvidence` + +Represents a Vulnerability Evidence. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `request` | [`VulnerabilityRequest`](#vulnerabilityrequest) | HTTP request of the Vulnerability Evidence. | +| `response` | [`VulnerabilityResponse`](#vulnerabilityresponse) | HTTP response of the Vulnerability Evidence. | +| `source` | [`VulnerabilityEvidenceSource`](#vulnerabilityevidencesource) | Source of the Vulnerability Evidence. | +| `summary` | [`String`](#string) | Summary of the Vulnerability Evidence. | +| `supportingMessages` | [`[VulnerabilityEvidenceSupportingMessage!]`](#vulnerabilityevidencesupportingmessage) | Supporting messages of the Vulnerability Evidence. | + +### `VulnerabilityEvidenceSource` + +Represents a vulnerability evidence. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `identifier` | [`String!`](#string) | ID of the Vulnerability Evidence Source. | +| `name` | [`String!`](#string) | Name of the Vulnerability Evidence Source. | +| `url` | [`String`](#string) | URL of the Vulnerability Evidence Source. | + +### `VulnerabilityEvidenceSupportingMessage` + +Represents a vulnerability evidence supporting message. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `name` | [`String!`](#string) | Name of the vulnerability supporting message. | +| `request` | [`VulnerabilityRequest`](#vulnerabilityrequest) | HTTP request of the vulnerability evidence supporting message. | +| `response` | [`VulnerabilityResponse`](#vulnerabilityresponse) | HTTP response of the vulnerability evidence supporting message. | + ### `VulnerabilityExternalIssueLink` Represents an external issue link of a vulnerability. @@ -16070,8 +16484,11 @@ Represents the location of a vulnerability found by a Coverage Fuzzing scan. | Name | Type | Description | | ---- | ---- | ----------- | | `blobPath` | [`String`](#string) | Blob path to the vulnerable file. | +| `crashAddress` | [`String`](#string) | Relative address in memory were the crash occurred. | +| `crashType` | [`String`](#string) | Type of the crash. | | `endLine` | [`String`](#string) | Number of the last relevant line in the vulnerable file. | | `file` | [`String`](#string) | Path to the vulnerable file. | +| `stacktraceSnippet` | [`String`](#string) | Stack trace recorded during fuzzing resulting the crash. | | `startLine` | [`String`](#string) | Number of the first relevant line in the vulnerable file. | | `vulnerableClass` | [`String`](#string) | Class containing the vulnerability. | | `vulnerableMethod` | [`String`](#string) | Method containing the vulnerability. | @@ -16159,6 +16576,43 @@ Check permissions for the current user on a vulnerability. | `readVulnerabilityFeedback` | [`Boolean!`](#boolean) | Indicates the user can perform `read_vulnerability_feedback` on this resource. | | `updateVulnerabilityFeedback` | [`Boolean!`](#boolean) | Indicates the user can perform `update_vulnerability_feedback` on this resource. | +### `VulnerabilityRequest` + +Represents a Vulnerability Request. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `body` | [`String`](#string) | Body of the Vulnerability Request. | +| `headers` | [`[VulnerabilityRequestResponseHeader!]!`](#vulnerabilityrequestresponseheader) | HTTP headers of the Vulnerability Request. | +| `method` | [`String`](#string) | Method of the Vulnerability Request. | +| `url` | [`String`](#string) | URL of the Vulnerability Request. | + +### `VulnerabilityRequestResponseHeader` + +Represents a Vulnerability Request/Response Header. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `name` | [`String`](#string) | Name of the Vulnerability Request/Response Header. | +| `value` | [`String`](#string) | Value of the Vulnerability Request/Response Header. | + +### `VulnerabilityResponse` + +Represents a Vulnerability Response. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `body` | [`String`](#string) | Body of the Vulnerability Response. | +| `headers` | [`[VulnerabilityRequestResponseHeader!]!`](#vulnerabilityrequestresponseheader) | HTTP headers of the Vulnerability Response. | +| `reasonPhrase` | [`String`](#string) | Reason Phrase of the Vulnerability Response. | +| `statusCode` | [`Int`](#int) | Status Code of the Vulnerability Response. | + ### `VulnerabilityScanner` Represents a vulnerability scanner. @@ -16246,6 +16700,7 @@ Represents vulnerability letter grades with associated projects. | `descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | | `id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | | `iid` | [`ID!`](#id) | Internal ID of the work item. | +| `state` | [`WorkItemState!`](#workitemstate) | State of the work item. | | `title` | [`String!`](#string) | Title of the work item. | | `titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | | `workItemType` | [`WorkItemType!`](#workitemtype) | Type assigned to the work item. | @@ -16481,17 +16936,19 @@ Values for sorting runners. | `CONTACTED_DESC` | Ordered by contacted_at in descending order. | | `CREATED_ASC` | Ordered by created_at in ascending order. | | `CREATED_DESC` | Ordered by created_at in descending order. | +| `TOKEN_EXPIRES_AT_ASC` | Ordered by token_expires_at in ascending order. | +| `TOKEN_EXPIRES_AT_DESC` | Ordered by token_expires_at in descending order. | ### `CiRunnerStatus` | Value | Description | | ----- | ----------- | -| `ACTIVE` **{warning-solid}** | **Deprecated** in 14.6. Use CiRunnerType.active instead. | +| `ACTIVE` **{warning-solid}** | **Deprecated** in 14.6. This was renamed. Use: [`CiRunner.paused`](#cirunnerpaused). | | `NEVER_CONTACTED` | Runner that has never contacted this instance. Set legacyMode to null to utilize this value. Will replace NOT_CONNECTED starting in 15.0. | | `NOT_CONNECTED` **{warning-solid}** | **Deprecated** in 14.6. Use NEVER_CONTACTED instead. NEVER_CONTACTED will have a slightly different scope starting in 15.0, with STALE being returned instead after 3 months of no contact. | | `OFFLINE` **{warning-solid}** | **Deprecated** in 14.6. This field will have a slightly different scope starting in 15.0, with STALE being returned after a certain period offline. | | `ONLINE` | Runner that contacted this instance within the last 2 hours. | -| `PAUSED` **{warning-solid}** | **Deprecated** in 14.6. Use CiRunnerType.active instead. | +| `PAUSED` **{warning-solid}** | **Deprecated** in 14.6. This was renamed. Use: [`CiRunner.paused`](#cirunnerpaused). | | `STALE` | Runner that has not contacted this instance within the last 3 months. Only available if legacyMode is null. Will be a possible return value starting in 15.0. | ### `CiRunnerType` @@ -16511,6 +16968,7 @@ Values for sorting runners. | `INFO` | Code Quality degradation has a status of info. | | `MAJOR` | Code Quality degradation has a status of major. | | `MINOR` | Code Quality degradation has a status of minor. | +| `UNKNOWN` | Code Quality degradation has a status of unknown. | ### `CommitActionMode` @@ -16776,12 +17234,16 @@ Roadmap sort values. | Value | Description | | ----- | ----------- | +| `CREATED_AT_ASC` | Sort by created_at by ascending order. | +| `CREATED_AT_DESC` | Sort by created_at by descending order. | | `END_DATE_ASC` | Sort by end date in ascending order. | | `END_DATE_DESC` | Sort by end date in descending order. | | `START_DATE_ASC` | Sort by start date in ascending order. | | `START_DATE_DESC` | Sort by start date in descending order. | | `TITLE_ASC` | Sort by title in ascending order. | | `TITLE_DESC` | Sort by title in descending order. | +| `UPDATED_AT_ASC` | Sort by updated_at by ascending order. | +| `UPDATED_AT_DESC` | Sort by updated_at by descending order. | | `end_date_asc` **{warning-solid}** | **Deprecated** in 13.11. Use END_DATE_ASC. | | `end_date_desc` **{warning-solid}** | **Deprecated** in 13.11. Use END_DATE_DESC. | | `start_date_asc` **{warning-solid}** | **Deprecated** in 13.11. Use START_DATE_ASC. | @@ -16992,6 +17454,23 @@ Issue type. | `REQUIREMENT` | Requirement issue type. | | `TEST_CASE` | Test Case issue type. | +### `IterationSearchableField` + +Fields to perform the search in. + +| Value | Description | +| ----- | ----------- | +| `CADENCE_TITLE` | Search in cadence_title field. | +| `TITLE` | Search in title field. | + +### `IterationSort` + +Iteration sort values. + +| Value | Description | +| ----- | ----------- | +| `CADENCE_AND_DUE_DATE_ASC` | Sort by cadence id and due date in ascending order. | + ### `IterationState` State of a GitLab iteration. @@ -17111,6 +17590,8 @@ Values for sorting merge requests. | `MILESTONE_DUE_DESC` | Milestone due date by descending order. | | `PRIORITY_ASC` | Priority by ascending order. | | `PRIORITY_DESC` | Priority by descending order. | +| `TITLE_ASC` | Title by ascending order. | +| `TITLE_DESC` | Title by descending order. | | `UPDATED_ASC` | Updated at ascending order. | | `UPDATED_DESC` | Updated at descending order. | | `created_asc` **{warning-solid}** | **Deprecated** in 13.5. This was renamed. Use: `CREATED_ASC`. | @@ -17663,6 +18144,7 @@ Name of the feature that the callout is for. | `SECURITY_CONFIGURATION_DEVOPS_ALERT` | Callout feature name for security_configuration_devops_alert. | | `SECURITY_CONFIGURATION_UPGRADE_BANNER` | Callout feature name for security_configuration_upgrade_banner. | | `SECURITY_NEWSLETTER_CALLOUT` | Callout feature name for security_newsletter_callout. | +| `SECURITY_TRAINING_FEATURE_PROMOTION` | Callout feature name for security_training_feature_promotion. | | `SUGGEST_PIPELINE` | Callout feature name for suggest_pipeline. | | `SUGGEST_POPOVER_DISMISSED` | Callout feature name for suggest_popover_dismissed. | | `TABS_POSITION_HIGHLIGHT` | Callout feature name for tabs_position_highlight. | @@ -17832,6 +18314,24 @@ Weight ID wildcard values. | `ANY` | Weight is assigned. | | `NONE` | No weight is assigned. | +### `WorkItemState` + +State of a GitLab work item. + +| Value | Description | +| ----- | ----------- | +| `CLOSED` | In closed state. | +| `OPEN` | In open state. | + +### `WorkItemStateEvent` + +Values for work item state events. + +| Value | Description | +| ----- | ----------- | +| `CLOSE` | Closes the work item. | +| `REOPEN` | Reopens the work item. | + ## Scalar types Scalar values are atomic values, and do not have fields of their own. @@ -18308,6 +18808,12 @@ A `ReleasesLinkID` is a global ID. It is encoded as a string. An example `ReleasesLinkID` is: `"gid://gitlab/Releases::Link/1"`. +### `SecurityTrainingProviderID` + +A `SecurityTrainingProviderID` is a global ID. It is encoded as a string. + +An example `SecurityTrainingProviderID` is: `"gid://gitlab/Security::TrainingProvider/1"`. + ### `SnippetID` A `SnippetID` is a global ID. It is encoded as a string. @@ -18426,6 +18932,7 @@ One of: - [`Epic`](#epic) - [`Issue`](#issue) - [`MergeRequest`](#mergerequest) +- [`WorkItem`](#workitem) #### `JobNeedUnion` @@ -18614,6 +19121,20 @@ Implementations: | `updatedAt` | [`Time`](#time) | Date and time the membership was last updated. | | `user` | [`UserCore`](#usercore) | User that is associated with the member object. | +##### Fields with arguments + +###### `MemberInterface.mergeRequestInteraction` + +Find a merge request. + +Returns [`UserMergeRequestInteraction`](#usermergerequestinteraction). + +####### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `id` | [`MergeRequestID!`](#mergerequestid) | Global ID of the merge request. | + #### `NoteableInterface` Implementations: @@ -18733,7 +19254,7 @@ Implementations: | `groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | `id` | [`ID!`](#id) | ID of the user. | | `location` | [`String`](#string) | Location of the user. | -| `name` | [`String!`](#string) | Human-readable name of the user. Will return `****` if the user is a project bot and the requester does not have permission to read resource access tokens. | +| `name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | | `namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | | `projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | `publicEmail` | [`String`](#string) | User's public email. | @@ -18777,6 +19298,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ###### `User.authoredMergeRequests` @@ -18809,6 +19332,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ###### `User.groups` @@ -18858,6 +19383,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | | `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| `updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| `updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | ###### `User.snippets` diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md index 37471b9d89d..45366885c5c 100644 --- a/doc/api/group_access_tokens.md +++ b/doc/api/group_access_tokens.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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 --- @@ -58,7 +58,7 @@ POST groups/:id/access_tokens |-----------|---------|----------|---------------------| | `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `name` | String | yes | The name of the group access token | -| `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#scopes-for-a-project-access-token) | +| `scopes` | `Array[String]` | yes | [List of scopes](../user/group/settings/group_access_tokens.md#scopes-for-a-group-access-token) | | `access_level` | Integer | no | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). | | `expires_at` | Date | no | The token expires at midnight UTC on that date | diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index ecb73aa8a5e..360790daf8c 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/group_clusters.md b/doc/api/group_clusters.md index eaecc74a96e..87829708d5e 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -17,7 +17,7 @@ Similarly to [project-level](../user/project/clusters/index.md) and group-level Kubernetes clusters allow you to connect a Kubernetes cluster to your group, enabling you to use the same cluster across multiple projects. -Users need at least the [Maintainer role](../user/permissions.md) for the group to use these endpoints. +Users need at least the Maintainer role for the group to use these endpoints. ## List group clusters diff --git a/doc/api/groups.md b/doc/api/groups.md index d7b4f0c8b54..2e0f9526e16 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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 --- @@ -808,7 +808,7 @@ Parameters: ### Options for `default_branch_protection` -The `default_branch_protection` attribute determines whether users with the Developer or [Maintainer role](../user/permissions.md) can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table: +The `default_branch_protection` attribute determines whether users with the Developer or Maintainer role can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table: | Value | Description | |-------|-------------------------------------------------------------------------------------------------------------| @@ -832,7 +832,8 @@ curl --request POST --header "PRIVATE-TOKEN: " \ ## Transfer project to group -Transfer a project to the Group namespace. Available only to instance administrators, although an [alternative API endpoint](projects.md#transfer-a-project-to-a-new-namespace) is available which does not require instance administrator role. Transferring projects may fail when tagged packages exist in the project's repository. +Transfer a project to the Group namespace. Available only to instance administrators, although an [alternative API endpoint](projects.md#transfer-a-project-to-a-new-namespace) +is available which does not require administrator access on the instance. Transferring projects may fail when tagged packages exist in the project's repository. ```plaintext POST /groups/:id/projects/:project_id @@ -1089,6 +1090,79 @@ GET /groups?search=foobar ] ``` +## List provisioned users **(PREMIUM)** + +> Introduced in GitLab 14.8. + +Get a list of users provisioned by a given group. Does not include users provisioned by subgroups. + +Requires at least the Maintainer role on the group. + +```plaintext +GET /groups/:id/provisioned_users +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:-----------------|:---------------|:---------|:-------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `username` | string | no | Return single user with a specific username | +| `search` | string | no | Search users by name, email, username | +| `active` | boolean | no | Return only active users | +| `blocked` | boolean | no | Return only blocked users | +| `created_after` | datetime | no | Return users created after the specified time | +| `created_before` | datetime | no | Return users created before the specified time | + +Example response: + +```json +[ + { + id: 66, + username: "user22", + name: "John Doe22", + state: "active", + avatar_url: "https://www.gravatar.com/avatar/xxx?s=80&d=identicon", + web_url: "http://my.gitlab.com/user22", + created_at: "2021-09-10T12:48:22.381Z", + bio: "", + location: null, + public_email: "", + skype: "", + linkedin: "", + twitter: "", + website_url: "", + organization: null, + job_title: "", + pronouns: null, + bot: false, + work_information: null, + followers: 0, + following: 0, + local_time: null, + last_sign_in_at: null, + confirmed_at: "2021-09-10T12:48:22.330Z", + last_activity_on: null, + email: "user22@example.org", + theme_id: 1, + color_scheme_id: 1, + projects_limit: 100000, + current_sign_in_at: null, + identities: [ ], + can_create_group: true, + can_create_project: true, + two_factor_enabled: false, + external: false, + private_profile: false, + commit_email: "user22@example.org", + shared_runners_minutes_limit: null, + extra_shared_runners_minutes_limit: null + }, + ... +] +``` + ## Hooks **(PREMIUM)** Also called Group Hooks and Webhooks. diff --git a/doc/api/index.md b/doc/api/index.md index 69db971f58c..589bc0416a1 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -12,6 +12,9 @@ Use the GitLab APIs to automate GitLab. A REST API is available in GitLab. Usage instructions are below. + +For examples, see [How to use the API](#how-to-use-the-api). + For a list of the available resources and their endpoints, see [REST API resources](api_resources.md). @@ -31,7 +34,9 @@ GitLab provides an [SCIM API](scim.md) that both implements ## GraphQL API -A [GraphQL API](graphql/index.md) is available in GitLab. +A GraphQL API is available in GitLab. +For a list of the available resources and their endpoints, see +[GraphQL API resources](graphql/reference/index.md). With GraphQL, you can make an API request for only what you need, and it's versioned by default. @@ -60,7 +65,7 @@ month. Major API version changes, and removal of entire API versions, are done i with major GitLab releases. All deprecations and changes between versions are in the documentation. -For the changes between v3 and v4, see the [v3 to v4 documentation](v3_to_v4.md). +For the changes between v3 and v4, see the [v3 to v4 documentation](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md). ### Current status @@ -74,7 +79,7 @@ For example, the root of the v4 API is at `/api/v4`. ### Valid API request -If you have a GitLab instance at `gitlab.example.com`: +The following is a basic example of a request to the fictional `gitlab.example.com` endpoint: ```shell curl "https://gitlab.example.com/api/v4/projects" @@ -83,6 +88,10 @@ curl "https://gitlab.example.com/api/v4/projects" The API uses JSON to serialize data. You don't need to specify `.json` at the end of the API URL. +NOTE: +In the example above, replace `gitlab.example.com` with `gitlab.com` to query GitLab.com (GitLab SaaS). +Access can be denied due to authentication. For more information, see [Authentication](#authentication). + ### API request to expose HTTP response headers If you want to expose HTTP response headers, use the `--include` option: diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index f29ac5cd7f2..ab631757eab 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -16,8 +16,7 @@ With [instance-level Kubernetes clusters](../user/instance/clusters/index.md), you can connect a Kubernetes cluster to the GitLab instance and use the same cluster across all of the projects within your instance. -NOTE: -Users need the Administrator role to use these endpoints. +Users need administrator access to use these endpoints. ## List instance clusters diff --git a/doc/api/integrations.md b/doc/api/integrations.md index 4719fe69c7b..90bb26ffd3d 100644 --- a/doc/api/integrations.md +++ b/doc/api/integrations.md @@ -13,7 +13,7 @@ In GitLab 14.4, the `services` endpoint was [renamed](https://gitlab.com/gitlab- Calls to the Integrations API can be made to both `/projects/:id/services` and `/projects/:id/integrations`. The examples in this document refer to the endpoint at `/projects/:id/integrations`. -This API requires an access token with the [Maintainer or Owner role](../user/permissions.md). +This API requires an access token with the Maintainer or Owner role. ## List all active integrations @@ -319,11 +319,12 @@ Parameters: | ---------------------- | ------- | -------- | ----------- | | `api_key` | string | true | API key used for authentication with Datadog | | `api_url` | string | false | (Advanced) The full URL for your Datadog site | - - | `datadog_env` | string | false | For self-managed deployments, set the env% tag for all the data sent to Datadog. | | `datadog_service` | string | false | Tag all data from this GitLab instance in Datadog. Useful when managing several self-managed deployments | | `datadog_site` | string | false | The Datadog site to send data to. To send data to the EU site, use `datadoghq.eu` | +| `datadog_tags` | string | false | Custom tags in Datadog. Specify one tag per line in the format: `key:value\nkey2:value2` ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79665) in GitLab 14.8.) | + + ### Disable Datadog integration diff --git a/doc/api/issues.md b/doc/api/issues.md index 5d22952a876..5801f072062 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -29,7 +29,9 @@ When requested across groups or projects, it's expected to be the same as the `f ## List issues +> The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. > The `weight` property moved to GitLab Premium in 13.9. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get all issues the authenticated user has access to. By default it returns only issues created by the current user. To get all issues, @@ -61,7 +63,7 @@ GET /issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | +| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | | `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | @@ -231,7 +233,9 @@ Please use `iid` of the `epic` attribute instead. ## List group issues +> The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. > The `weight` property moved to GitLab Premium in 13.9. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get a list of a group's issues. @@ -264,7 +268,7 @@ GET /groups/:id/issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | +| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | | `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | @@ -431,7 +435,9 @@ Please use `iid` of the `epic` attribute instead. ## List project issues +> The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. > The `weight` property moved to GitLab Premium in 13.9. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get a list of a project's issues. @@ -464,7 +470,7 @@ GET /projects/:id/issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | +| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | | `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | @@ -2422,10 +2428,11 @@ POST /projects/:id/issues/:issue_iid/metric_images | `issue_iid` | integer | yes | The internal ID of a project's issue | | `file` | file | yes | The image file to be uploaded | | `url` | string | no | The URL to view more metric information | +| `url_text` | string | no | A description of the image or URL | ```shell curl --header "PRIVATE-TOKEN: " --form 'file=@/path/to/file.png' \ ---form 'url=http://example.com' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +--form 'url=http://example.com' --form 'url_text=Example website' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" ``` Example response: @@ -2436,7 +2443,8 @@ Example response: "created_at": "2020-11-13T00:06:18.084Z", "filename": "file.png", "file_path": "/uploads/-/system/issuable_metric_image/file/23/file.png", - "url": "http://example.com" + "url": "http://example.com", + "url_text": "Example website" } ``` @@ -2478,6 +2486,39 @@ Example response: ] ``` +## Update metric image + +Available only for Incident issues. + +```plaintext +PUT /projects/:id/issues/:issue_iid/metric_images/:image_id +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `image_id` | integer | yes | The ID of the image | +| `url` | string | no | The URL to view more metric information | +| `url_text` | string | no | A description of the image or URL | + +```shell +curl --header "PRIVATE-TOKEN: " --request PUT --form 'url=http://example.com' --form 'url_text=Example website' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" +``` + +Example response: + +```json +{ + "id": 23, + "created_at": "2020-11-13T00:06:18.084Z", + "filename": "file.png", + "file_path": "/uploads/-/system/issuable_metric_image/file/23/file.png", + "url": "http://example.com", + "url_text": "Example website" +} +``` + ## Delete metric image Available only for Incident issues. diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index a874379506f..d272f259ddf 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Testing +group: Pipeline Insights 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 --- @@ -293,7 +293,9 @@ FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the `bulk_expire_project_artifacts` flag](../administration/feature_flags.md). On GitLab.com, this feature is available. -[Expire artifacts of a project that can be deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/223793) but that don't have an expiry time. +Delete artifacts of a project that can be deleted. + +By default, [artifacts from the most recent successful pipeline of each ref are kept](../ci/pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). ```plaintext DELETE /projects/:id/artifacts diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 8dcd898b8c3..89018548f5f 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -10,14 +10,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w Get a list of jobs in a project. Jobs are sorted in descending order of their IDs. +By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination) + ```plaintext GET /projects/:id/jobs ``` -| Attribute | Type | Required | Description | -|-----------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | +| Attribute | Type | Required | Description | +|-----------|--------------------------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | ```shell curl --globoff --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running" @@ -155,16 +157,18 @@ Example of response Get a list of jobs for a pipeline. +By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination) + ```plaintext GET /projects/:id/pipelines/:pipeline_id/jobs ``` -| Attribute | Type | Required | Description | -|-------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `pipeline_id` | integer | yes | ID of a pipeline. Can also be obtained in CI jobs via the [predefined CI variable](../ci/variables/predefined_variables.md) `CI_PIPELINE_ID`. | -| `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | -| `include_retried` | boolean | no | Include retried jobs in the response. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/272627) in GitLab 13.9. | +| Attribute | Type | Required | Description | +|-------------------|--------------------------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `pipeline_id` | integer | **{check-circle}** Yes | ID of a pipeline. Can also be obtained in CI jobs via the [predefined CI variable](../ci/variables/predefined_variables.md) `CI_PIPELINE_ID`. | +| `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | +| `include_retried` | boolean | **{dotted-circle}** No | Include retried jobs in the response. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/272627) in GitLab 13.9. | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running" @@ -316,11 +320,11 @@ Get a list of bridge jobs for a pipeline. GET /projects/:id/pipelines/:pipeline_id/bridges ``` -| Attribute | Type | Required | Description | -|---------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `pipeline_id` | integer | yes | ID of a pipeline. | -| `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | +| Attribute | Type | Required | Description | +|---------------|--------------------------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `pipeline_id` | integer | **{check-circle}** Yes | ID of a pipeline. | +| `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/pipelines/6/bridges?scope[]=pending&scope[]=running" @@ -483,9 +487,9 @@ GET /job/allowed_agents Supported attributes: -| Attribute | Type | Required | Description | -|:------------ |:---------|:---------|:----------------------| -| `CI_JOB_TOKEN` | string | yes | Token value associated with the GitLab-provided `CI_JOB_TOKEN` variable. | +| Attribute | Type | Required | Description | +|----------------|----------|------------------------|-------------| +| `CI_JOB_TOKEN` | string | **{check-circle}** Yes | Token value associated with the GitLab-provided `CI_JOB_TOKEN` variable. | Example request: @@ -558,10 +562,10 @@ Get a single job of a project GET /projects/:id/jobs/:job_id ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/jobs/8" @@ -635,10 +639,10 @@ Get a log (trace) of a specific job of a project: GET /projects/:id/jobs/:job_id/trace ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell curl --location --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace" @@ -659,10 +663,10 @@ Cancel a single job of a project POST /projects/:id/jobs/:job_id/cancel ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/jobs/1/cancel" @@ -709,10 +713,10 @@ Retry a single job of a project POST /projects/:id/jobs/:job_id/retry ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/jobs/1/retry" @@ -761,10 +765,10 @@ POST /projects/:id/jobs/:job_id/erase Parameters -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | **{check-circle}** Yes | ID of a job. | Example of request @@ -818,10 +822,10 @@ Triggers a manual action to start a job. POST /projects/:id/jobs/:job_id/play ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/jobs/1/play" diff --git a/doc/api/lint.md b/doc/api/lint.md index e5b5e0e2be8..a271b75c035 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -89,7 +89,7 @@ Example responses: The CI lint returns an expanded version of the configuration. The expansion does not work for CI configuration added with [`include: local`](../ci/yaml/index.md#includelocal), -or with [`extends:`](../ci/yaml/index.md#extends). +and the [`extends:`](../ci/yaml/index.md#extends) keyword is [not fully supported](https://gitlab.com/gitlab-org/gitlab/-/issues/258843). Example contents of a `.gitlab-ci.yml` passed to the CI Lint API with `include_merged_yaml` and `include_jobs` set as true: @@ -169,8 +169,9 @@ POST /projects/:id/ci/lint | Attribute | Type | Required | Description | | ---------- | ------- | -------- | -------- | | `content` | string | yes | The CI/CD configuration content. | -| `dry_run` | boolean | no | Run [pipeline creation simulation](../ci/lint.md#pipeline-simulation), or only do static check. This is false by default. | +| `dry_run` | boolean | no | Run [pipeline creation simulation](../ci/lint.md#simulate-a-pipeline), or only do static check. This is false by default. | | `include_jobs` | boolean | no | If the list of jobs that would exist in a static check or pipeline simulation should be included in the response. This is false by default. | +| `ref` | string | no | When `dry_run` is `true`, sets the branch or tag to use. Defaults to the project's default branch when not set. | Example request: @@ -220,6 +221,7 @@ GET /projects/:id/ci/lint | ---------- | ------- | -------- | -------- | | `dry_run` | boolean | no | Run pipeline creation simulation, or only do static check. | | `include_jobs` | boolean | no | If the list of jobs that would exist in a static check or pipeline simulation should be included in the response. This is false by default. | +| `ref` | string | no | When `dry_run` is `true`, sets the branch or tag to use. Defaults to the project's default branch when not set. | Example request: diff --git a/doc/api/members.md b/doc/api/members.md index 95565d40897..10072baf2ff 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/merge_request_approvals.md b/doc/api/merge_request_approvals.md index b6021d494fd..6a0b66ac5dc 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -278,6 +278,12 @@ GET /projects/:id/approval_rules/:approval_rule_id > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. > - Moved to GitLab Premium in 13.9. +WARNING: +The Vulnerability-Check feature, including the Vulnerability-Check attributes listed here, is in its +end-of-life process. It is [deprecated](../update/deprecations.md#vulnerability-check) +for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new +[Security Approval Policies](../user/application_security/policies/#scan-result-policy-editor). + You can create project approval rules using the following endpoint: ```plaintext @@ -295,11 +301,11 @@ POST /projects/:id/approval_rules | `user_ids` | Array | no | The ids of users as approvers | | `group_ids` | Array | no | The ids of groups as approvers | | `protected_branch_ids` | Array | no | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | -| `report_type` | string | no | The report type required when the rule type is `report_approver`. The supported report types are: `vulnerability`, `license_scanning`, `code_coverage`. | -| `scanners` | Array | no | The security scanners the `Vulnerability-Check` approval rule considers. The supported scanners are: `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing`. Defaults to all supported scanners. | -| `severity_levels` | Array | no | The severity levels the `Vulnerability-Check` approval rule considers. The supported severity levels are: `info`, `unknown`, `low`, `medium`, `high`, `critical`. Defaults to `unknown`, `high`, and `critical`. | -| `vulnerabilities_allowed` | integer | no | The number of vulnerabilities allowed for the `Vulnerability-Check` approval rule. Defaults to `0`. | -| `vulnerability_states` | Array | no | The vulnerability states the `Vulnerability-Check` approval rule considers. The supported vulnerability states are: `newly_detected` (default), `detected`, `confirmed`, `resolved`, `dismissed`. | +| `report_type` | string | no | The report type required when the rule type is `report_approver`. The supported report types are: `vulnerability`, `license_scanning`, `code_coverage`. The `vulnerability` report type is part of the Vulnerability-Check feature, which deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | +| `scanners` | Array | no | The security scanners the Vulnerability-Check approval rule considers. The supported scanners are: `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing`. Defaults to all supported scanners. Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | +| `severity_levels` | Array | no | The severity levels the Vulnerability-Check approval rule considers. The supported severity levels are: `info`, `unknown`, `low`, `medium`, `high`, `critical`. Defaults to `unknown`, `high`, and `critical`. Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | +| `vulnerabilities_allowed` | integer | no | The number of vulnerabilities allowed for the Vulnerability-Check approval rule. Defaults to `0`. Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | +| `vulnerability_states` | Array | no | The vulnerability states the Vulnerability-Check approval rule considers. The supported vulnerability states are: `newly_detected` (default), `detected`, `confirmed`, `resolved`, `dismissed`. Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | ```json { @@ -404,6 +410,12 @@ curl --request POST --header "PRIVATE-TOKEN: " \ > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. > - Moved to GitLab Premium in 13.9. +WARNING: +The Vulnerability-Check feature, including the Vulnerability-Check attributes listed here, is in its +end-of-life process. It is [deprecated](../update/deprecations.md#vulnerability-check) +for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new +[Security Approval Policies](../user/application_security/policies/#scan-result-policy-editor). + You can update project approval rules using the following endpoint: ```plaintext @@ -423,10 +435,10 @@ PUT /projects/:id/approval_rules/:approval_rule_id | `user_ids` | Array | no | The ids of users as approvers | | `group_ids` | Array | no | The ids of groups as approvers | | `protected_branch_ids` | Array | no | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | -| `scanners` | Array | no | The security scanners the `Vulnerability-Check` approval rule considers. The supported scanners are: `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing`. Defaults to all supported scanners. | -| `severity_levels` | Array | no | The severity levels the `Vulnerability-Check` approval rule considers. The supported severity levels are: `info`, `unknown`, `low`, `medium`, `high`, `critical`. Defaults to `unknown`, `high`, and `critical`. | -| `vulnerabilities_allowed` | integer | no | The number of vulnerabilities allowed for the `Vulnerability-Check` approval rule. Defaults to `0`. | -| `vulnerability_states` | Array | no | The vulnerability states the `Vulnerability-Check` approval rule considers. The supported vulnerability states are: `newly_detected` (default), `detected`, `confirmed`, `resolved`, `dismissed`. | +| `scanners` | Array | no | The security scanners the Vulnerability-Check approval rule considers. The supported scanners are: `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing`. Defaults to all supported scanners. Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | +| `severity_levels` | Array | no | The severity levels the Vulnerability-Check approval rule considers. The supported severity levels are: `info`, `unknown`, `low`, `medium`, `high`, `critical`. Defaults to `unknown`, `high`, and `critical`. Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | +| `vulnerabilities_allowed` | integer | no | The number of vulnerabilities allowed for the Vulnerability-Check approval rule. Defaults to `0`. Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | +| `vulnerability_states` | Array | no | The vulnerability states the Vulnerability-Check approval rule considers. The supported vulnerability states are: `newly_detected` (default), `detected`, `confirmed`, `resolved`, `dismissed`. Deprecated in GitLab 14.8, and planned for removal in GitLab 15.0. | ```json { @@ -527,9 +539,9 @@ DELETE /projects/:id/approval_rules/:approval_rule_id | `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `approval_rule_id` | integer | yes | The ID of a approval rule -## Merge Request-level MR approvals +## Merge request-level MR approvals -Configuration for approvals on a specific Merge Request. Must be authenticated for all endpoints. +Configuration for approvals on a specific merge request. Must be authenticated for all endpoints. ### Get Configuration @@ -957,7 +969,7 @@ These are system generated rules. | `merge_request_iid` | integer | yes | The IID of the merge request | | `approval_rule_id` | integer | yes | The ID of an approval rule | -## Approve Merge Request +## Approve merge request > Moved to GitLab Premium in 13.9. @@ -978,7 +990,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve | `approval_password` | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. | The `sha` parameter works in the same way as -when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must +when [accepting a merge request](merge_requests.md#merge-a-merge-request): if it is passed, then it must match the current HEAD of the merge request for the approval to be added. If it does not match, the response code is `409`. @@ -1020,7 +1032,7 @@ does not match, the response code is `409`. } ``` -## Unapprove Merge Request +## Unapprove merge request > Moved to GitLab Premium in 13.9. diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 905ecd05d52..a54ea33aca8 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -13,41 +13,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to merge requests must be authenticated. -**Important notes:** - -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29984) in GitLab 12.8, the mergeability (`merge_status`) -of each merge request is checked asynchronously when a request is made to this endpoint. Poll this API endpoint -to get updated status. This affects the `has_conflicts` property as it is dependent on the `merge_status`. It returns -`false` unless `merge_status` is `cannot_be_merged`. -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0, listing merge requests may -not proactively update `merge_status` (which also affects the `has_conflicts`), as this can be an expensive operation. -If you need the value of these fields from this endpoint, set the `with_merge_status_recheck` parameter to -`true` in the query. -- `references.relative` is relative to the group or project that the merge request is being requested. When the merge request -is fetched from its project, `relative` format would be the same as `short` format, and when requested across groups or projects, it is expected to be the same as `full` format. -- If `approvals_before_merge` is not provided, it inherits the value from the target project. If provided, the following conditions must hold for it to take effect: - - - The target project's `approvals_before_merge` must be greater than zero. A - value of zero disables approvals for that project. - - The provided value of `approvals_before_merge` must be greater than the - target project's `approvals_before_merge`. - - This API returns `HTTP 201 Created` for a successful response. - -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46190) in GitLab 13.6, -diffs associated with the set of changes have the same size limitations applied as other diffs -returned by the API or viewed via the UI. When these limits impact the results, the `overflow` -field contains a value of `true`. Diff data without these limits applied can be retrieved by -adding the `access_raw_diffs` parameter, accessing diffs not from the database but from Gitaly directly. -This approach is generally slower and more resource-intensive, but isn't subject to size limits -placed on database-backed diffs. [Limits inherent to Gitaly](../development/diffs.md#diff-limits) -still apply. - -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) in GitLab 14.7, -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. - ## List merge requests Get all merge requests the authenticated user has access to. By @@ -78,7 +43,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. | +| `order_by` | string | no | Return requests ordered by `created_at`, `title`, or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8.| | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | @@ -241,6 +206,14 @@ the `approvals_before_merge` parameter: ] ``` +### Merge requests list response notes + +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0, listing merge requests may + not proactively update `merge_status` (which also affects the `has_conflicts`), as this can be an expensive operation. + If you need the value of these fields from this endpoint, set the `with_merge_status_recheck` parameter to + `true` in the query. +- For notes on merge request object fields, read [Single merge request response notes](#single-merge-request-response-notes). + ## List project merge requests Get all merge requests for this project. @@ -273,7 +246,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `iids[]` | integer array | no | Return the request having the given `iid`. | | `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. | +| `order_by` | string | no | Return requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | @@ -421,16 +394,6 @@ Parameters: ] ``` -The `merge_status` field may hold one of the following values: - -| Value | Interpretation | -|----------------------------|-----------------------------------------------------------------------| -| `unchecked` | We have not checked this yet | -| `checking` | We are currently checking if the merge request can be merged | -| `can_be_merged` | This merge request can be merged without conflict | -| `cannot_be_merged` | There are merge conflicts between the source and target branches | -| `cannot_be_merged_recheck` | Currently unchecked. Before the current changes, there were conflicts | - Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: @@ -445,6 +408,8 @@ the `approvals_before_merge` parameter: ] ``` +For important notes on response data, read [Merge requests list response notes](#merge-requests-list-response-notes). + ## List group merge requests Get all merge requests for this group and its subgroups. @@ -468,7 +433,7 @@ Parameters: | ------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | -| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. | +| `order_by` | string | no | Return merge requests ordered by `created_at`, `title` or `updated_at` fields. Default is `created_at`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.8. | | `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | @@ -627,6 +592,8 @@ the `approvals_before_merge` parameter: ] ``` +For important notes on response data, read [Merge requests list response notes](#merge-requests-list-response-notes). + ## Get single MR Shows information about a single merge request. @@ -805,7 +772,26 @@ the `approvals_before_merge` parameter: } ``` -The `diff_refs` in the response correspond to the latest diff version of the merge request. +### Single merge request response notes + +- The `merge_status` field may hold one of the following values: + - `unchecked`: We have not checked this yet. + - `checking`: We are currently checking if the merge request can be merged. + - `can_be_merged`: This merge request can be merged without conflict. + - `cannot_be_merged`: There are merge conflicts between the source and target branches. + - `cannot_be_merged_recheck`: Currently unchecked. Before the current changes, there were conflicts. +- The `diff_refs` in the response correspond to the latest diff version of the merge request. +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29984) in GitLab 12.8, the mergeability (`merge_status`) + of each merge request is checked asynchronously when a request is made to this endpoint. Poll this API endpoint + to get updated status. This affects the `has_conflicts` property as it is dependent on the `merge_status`. It returns + `false` unless `merge_status` is `cannot_be_merged`. +- `references.relative` is relative to the group or project that the merge request is being requested. When the merge + request is fetched from its project, `relative` format would be the same as `short` format, and when requested across + groups or projects, it is expected to be the same as `full` format. +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) in GitLab 14.7, + 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. ## Get single MR participants @@ -885,6 +871,15 @@ Parameters: Shows information about the merge request including its files and changes. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46190) in GitLab 13.6, +diffs associated with the set of changes have the same size limitations applied as other diffs +returned by the API or viewed via the UI. When these limits impact the results, the `overflow` +field contains a value of `true`. Diff data without these limits applied can be retrieved by +adding the `access_raw_diffs` parameter, accessing diffs not from the database but from Gitaly directly. +This approach is generally slower and more resource-intensive, but isn't subject to size limits +placed on database-backed diffs. [Limits inherent to Gitaly](../development/diffs.md#diff-limits) +still apply. + ```plaintext GET /projects/:id/merge_requests/:merge_request_iid/changes ``` @@ -1040,8 +1035,8 @@ It requires `.gitlab-ci.yml` to be configured with `only: [merge_requests]` to c The new pipeline can be: - A detached merge request pipeline. -- A [pipeline for merged results](../ci/pipelines/pipelines_for_merged_results.md) - if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results). **(PREMIUM)** +- A [merged results pipeline](../ci/pipelines/merged_results_pipelines.md) + if the [project setting is enabled](../ci/pipelines/merged_results_pipelines.md#enable-merged-results-pipelines). ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/pipelines @@ -1116,9 +1111,17 @@ POST /projects/:id/merge_requests | `milestone_id` | integer | no | The global ID of a milestone. | | `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging. | | `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch. | -| `allow_maintainer_to_push` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/22665), see `allow_collaboration`. | +| `allow_maintainer_to_push` | boolean | no | Alias of `allow_collaboration`. | +| `approvals_before_merge` **(PREMIUM)** | integer | no | Number of approvals required before this can be merged (see below). | | `squash` | boolean | no | Squash commits into a single commit when merging. | +If `approvals_before_merge` is not provided, it inherits the value from the target project. If provided, the following conditions must hold for it to take effect: + +- The target project's `approvals_before_merge` must be greater than zero. A + value of zero disables approvals for that project. +- The provided value of `approvals_before_merge` must be greater than the + target project's `approvals_before_merge`. + ```json { "id": 1, @@ -1251,6 +1254,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Update MR Updates an existing merge request. You can change the target branch, title, or even close the MR. @@ -1278,7 +1283,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `squash` | boolean | no | Squash commits into a single commit when merging. | | `discussion_locked` | boolean | no | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. | | `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch. | -| `allow_maintainer_to_push` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/22665), see `allow_collaboration`. | +| `allow_maintainer_to_push` | boolean | no | Alias of `allow_collaboration`. | Must include at least one non-required attribute from above. @@ -1430,6 +1435,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Delete a merge request Only for administrators and project owners. Deletes the merge request in question. @@ -1447,17 +1454,9 @@ DELETE /projects/:id/merge_requests/:merge_request_iid curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/4/merge_requests/85" ``` -## Accept MR - -Merge changes submitted with MR using this API. - -If a merge request is unable to be accepted (such as Draft, Closed, Pipeline Pending Completion, or Failed while requiring Success) - you receive a `405` and the error message 'Method Not Allowed' - -If it has some conflicts and can not be merged - you receive a `406` and the error message 'Branch cannot be merged' - -If the `sha` parameter is passed and does not match the HEAD of the source - you receive a `409` and the error message 'SHA does not match HEAD of source branch' +## Merge a merge request -If you don't have permissions to accept this merge request - you receive a `401` +Accept and merge changes submitted with MR using this API. ```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/merge @@ -1624,6 +1623,17 @@ the `approvals_before_merge` parameter: } ``` +This API returns specific HTTP status codes on failure: + +| HTTP Status | Message | Reason | +| :---: | ------- | ------ | +| `401` | `Unauthorized` | This user does not have permission to accept this merge request. | +| `405` | `Method Not Allowed` | The merge request cannot be accepted because it is `Draft`, `Closed`, `Pipeline Pending Completion`, or `Failed`. `Success` is required. | +| `406` | `Branch cannot be merged` | The branch has conflicts and cannot be merged. | +| `409` | `SHA does not match HEAD of source branch` | The provided `sha` parameter does not match the HEAD of the source. | + +For additional important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Merge to default merge ref path Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` @@ -1821,6 +1831,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Rebase a merge request Automatically rebase the `source_branch` of the merge request against its @@ -2130,6 +2142,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Unsubscribe from a merge request Unsubscribes the authenticated user from a merge request to not receive @@ -2298,6 +2312,8 @@ the `approvals_before_merge` parameter: } ``` +For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). + ## Create a to-do item Manually creates a to-do item for the current user on a merge request. @@ -2686,7 +2702,7 @@ Example response: ## Approvals -For approvals, see [Merge Request Approvals](merge_request_approvals.md) +For approvals, see [Merge request approvals](merge_request_approvals.md) ## List merge request state events diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index feba57a7ced..7732bf61d77 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index f615ddaaa71..3e54ec74b24 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index a02d44136d1..3972a46d7fc 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/notes.md b/doc/api/notes.md index 879ffaca191..445940e02fc 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -320,7 +320,7 @@ Parameters: curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659" ``` -## Merge Requests +## Merge requests ### List all merge request notes diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index ef7d133e907..59a929e30f4 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Manage -group: Authentication & Authorization -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/#designated-technical-writers +group: Authentication and Authorization +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/#designated-technical-writers --- # OAuth 2.0 identity provider API **(FREE)** @@ -32,7 +32,7 @@ GitLab supports the following authorization flows: hosted, first-party services. GitLab recommends against use of this flow. The draft specification for [OAuth 2.1](https://oauth.net/2.1/) specifically omits both the -Implicit grant and Resource Owner Password Credentials flows. It will be deprecated in the next OAuth specification version. +Implicit grant and Resource Owner Password Credentials flows. Refer to the [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out how all those flows work and pick the right one for your use case. @@ -41,7 +41,9 @@ Both **authorization code** (with or without PKCE) and **implicit grant** flows registered first via the `/profile/applications` page in your user's account. During registration, by enabling proper scopes, you can limit the range of resources which the `application` can access. Upon creation, you obtain the -`application` credentials: _Application ID_ and _Client Secret_ - **keep them secure**. +`application` credentials: _Application ID_ and _Client Secret_. The _Client Secret_ +**must be kept secure**. It is also advantageous to keep the _Application ID_ +secret when your application architecture allows. For a list of scopes in GitLab, see [the provider documentation](../integration/oauth_provider.md#authorized-applications). @@ -74,7 +76,10 @@ detailed flow description, from authorization request through access token. The following steps describe our implementation of the flow. The Authorization code with PKCE flow, PKCE for short, makes it possible to securely perform -the OAuth exchange of client credentials for access tokens on public clients. +the OAuth exchange of client credentials for access tokens on public clients without +requiring access to the _Client Secret_ at all. This makes the PKCE flow advantageous +for single page JavaScript applications or other client side apps where keeping secrets +from the user is a technical impossibility. Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `CODE_CHALLENGE`. @@ -113,7 +118,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD any HTTP client. The following example uses Ruby's `rest-client`: ```ruby - parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER' + parameters = 'client_id=APP_ID&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER' RestClient.post 'https://gitlab.example.com/oauth/token', parameters ``` @@ -135,7 +140,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD - Sends new tokens in the response. ```ruby - parameters = 'client_id=APP_ID&client_secret=APP_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER' + parameters = 'client_id=APP_ID&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER' RestClient.post 'https://gitlab.example.com/oauth/token', parameters ``` @@ -239,19 +244,13 @@ You can now make requests to the API with the access token returned. ### Implicit grant flow -NOTE: -For a detailed flow diagram, see the [RFC specification](https://tools.ietf.org/html/rfc6749#section-4.2). - WARNING: Implicit grant flow is inherently insecure and the IETF has removed it in [OAuth 2.1](https://oauth.net/2.1/). -For this reason, [support for it is deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/288516). -In GitLab 14.0, new applications can't be created using it. In GitLab 14.4, support for it is -scheduled to be removed for existing applications. +It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/288516) for use in GitLab 14.0, and is planned for +[removal](https://gitlab.com/gitlab-org/gitlab/-/issues/344609) in GitLab 15.0. -We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce) instead. If you choose to use Implicit flow, be sure to verify the -`application id` (or `client_id`) associated with the access token before granting -access to the data. To learn more, read -[Retrieving the token information](#retrieve-the-token-information)). +We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce) +instead. Unlike the authorization code flow, the client receives an `access token` immediately as a result of the authorization request. The flow does not use the @@ -415,7 +414,7 @@ The following is an example response: The fields `scopes` and `expires_in_seconds` are included in the response. -These are aliases for `scope` and `expires_in` respectively, and have been included to +These fields are aliases for `scope` and `expires_in` respectively, and have been included to prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doorkeeper-gem/doorkeeper/wiki/Migration-from-old-versions#from-4x-to-5x). Don't rely on these fields as they are slated for removal in a later release. diff --git a/doc/api/pages.md b/doc/api/pages.md index a115f0b0a0f..7316d225dbc 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -12,7 +12,7 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a ## Unpublish pages -Remove pages. The user must have the Administrator role. +Remove pages. The user must have administrator access. ```plaintext DELETE /projects/:id/pages diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 624bdf29e5d..c1f81ffa361 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -12,7 +12,7 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a ## List all Pages domains -Get a list of all Pages domains. The user must have the administrator role. +Get a list of all Pages domains. The user must have administrator access. ```plaintext GET /pages/domains diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md index 8d37189ef2a..75c8d241513 100644 --- a/doc/api/plan_limits.md +++ b/doc/api/plan_limits.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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 --- @@ -13,8 +13,7 @@ The plan limits API allows you to maintain the application limits for the existi The existing plans depend on the GitLab edition. In the Community Edition, only the plan `default` is available. In the Enterprise Edition, additional plans are available as well. -NOTE: -The Administrator role is required to use this API. +Administrator access is required to use this API. ## Get current plan limits diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md index 125797a802f..f6eced4f08a 100644 --- a/doc/api/project_access_tokens.md +++ b/doc/api/project_access_tokens.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/project_clusters.md b/doc/api/project_clusters.md index 129b064c650..c1f59520bd7 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -Users need at least the [Maintainer](../user/permissions.md) role to use these endpoints. +Users need at least the Maintainer role to use these endpoints. ## List project clusters diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index e7609d34998..218036b1ee0 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -188,9 +188,9 @@ As an administrator, you can modify the maximum import file size. To do so, use ## Import a file from a remote object storage -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282503) in GitLab 13.12 in [Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282503) in GitLab 13.12 in [Beta](../policy/alpha-beta-support.md#beta-features). -This endpoint is behind a feature flag that is disabled by default. +This endpoint is behind a feature flag that is enabled by default. To enable this endpoint: @@ -243,8 +243,8 @@ curl --request POST \ } ``` -The `ContentType` header must return a valid number. The maximum file size is 10 gigabytes. -The `ContentLength` header must be `application/gzip`. +The `Content-Length` header must return a valid number. The maximum file size is 10 gigabytes. +The `Content-Type` header must be `application/gzip`. ## Import status diff --git a/doc/api/project_relations_export.md b/doc/api/project_relations_export.md index 2016dcbd141..74fdc91e420 100644 --- a/doc/api/project_relations_export.md +++ b/doc/api/project_relations_export.md @@ -18,7 +18,7 @@ With the Project Relations Export API, you can partially export project structur similar to [project export](project_import_export.md), but it exports each top-level relation (for example, milestones/boards/labels) as a separate file instead of one archive. The project relations export API is primarily used in -[group migration](../user/group/import/index.md#enable-or-disable-gitlab-group-migration) +[group migration](../user/group/import/index.md) to support group project import. ## Schedule new export diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index c5f317f7540..efbd8bf9431 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -246,7 +246,7 @@ curl "https://gitlab.com/api/v4/projects/1/snippets/2/files/master/snippet%2Erb/ ## Get user agent details -Available only for users with the Administrator [role](../user/permissions.md). +Available only for users with administrator access. ```plaintext GET /projects/:id/snippets/:snippet_id/user_agent_detail diff --git a/doc/api/projects.md b/doc/api/projects.md index 791be613c71..db8d2361439 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -10,8 +10,8 @@ Interact with [projects](../user/project/index.md) using the REST API. ## Project visibility level -Project in GitLab can be either private, internal or public. -This is determined by the `visibility` field in the project. +A project in GitLab can be private, internal, or public. +The visibility level is determined by the `visibility` field in the project. Values for the project visibility level are: @@ -55,7 +55,7 @@ GET /projects | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `last_activity_at`, or `similarity` fields. `repository_size`, `storage_size`, `packages_size` or `wiki_size` fields are only allowed for administrators. `similarity` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332890) in GitLab 14.1) is only available when searching and is limited to projects that the current user is a member of. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | -| `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in GitLab 11.2). | +| `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed. | | `repository_storage` | string | **{dotted-circle}** No | Limit results to projects stored on `repository_storage`. _(administrators only)_ | | `search_namespaces` | boolean | **{dotted-circle}** No | Include ancestor namespaces when matching search criteria. Default is `false`. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | @@ -65,7 +65,7 @@ GET /projects | `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. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | -| `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in GitLab 11.2). | +| `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)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | @@ -383,6 +383,7 @@ GET /users/:user_id/projects | Attribute | Type | Required | Description | |-------------------------------|---------|------------------------|-------------| +| `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `id_after` | integer | **{dotted-circle}** No | Limit results to projects with IDs greater than the specified ID. | | `id_before` | integer | **{dotted-circle}** No | Limit results to projects with IDs less than the specified ID. | @@ -395,7 +396,6 @@ GET /users/:user_id/projects | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | -| `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | @@ -628,17 +628,17 @@ GET /users/:user_id/starred_projects | Attribute | Type | Required | Description | |-------------------------------|---------|------------------------|-------------| +| `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | -| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned.. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | -| `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | @@ -1045,10 +1045,6 @@ can also see the `approvals_before_merge` parameter: } ``` -The `web_url` and `avatar_url` attributes on `namespace` were -[introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27427) -in GitLab 11.11. - If the project is a fork, the `forked_from_project` field appears in the response. For this field, if the upstream project is private, a valid token for authentication must be provided. The field `mr_default_target_self` appears as well. If this value is `false`, then all merge requests @@ -1164,12 +1160,12 @@ GET /projects/:id/groups | Attribute | Type | Required | Description | |-----------------------------|-------------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific groups. | -| `skip_groups` | array of integers | **{dotted-circle}** No | Skip the group IDs passed. | -| `with_shared` | boolean | **{dotted-circle}** No | Include projects shared with this group. Default is `false`. | | `shared_min_access_level` | integer | **{dotted-circle}** No | Limit to shared groups with at least this [access level](members.md#valid-access-levels). | | `shared_visible_only` | boolean | **{dotted-circle}** No | Limit to shared groups user has access to. | +| `skip_groups` | array of integers | **{dotted-circle}** No | Skip the group IDs passed. | +| `with_shared` | boolean | **{dotted-circle}** No | Include projects shared with this group. Default is `false`. | ```json [ @@ -1226,8 +1222,8 @@ POST /projects | `builds_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | | `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). Valid values for `cadence` are: `1d` (every day), `7d` (every week), `14d` (every two weeks), `1month` (every month), or `3month` (every quarter). | -| `container_registry_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `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. | | `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. Requires `initialize_with_readme` to be `true`. | | `description` | string | **{dotted-circle}** No | Short project description. | | `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | @@ -1248,21 +1244,20 @@ POST /projects | `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | | `mirror` **(PREMIUM)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | | `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | -| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | | `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful pipelines. This setting is named [**Pipelines must succeed**](../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds) in the project settings. | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | -| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | | `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | | `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrator only)_ | | `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | +| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | -| `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | @@ -1304,10 +1299,10 @@ POST /projects/user/:user_id | `build_timeout` | integer | **{dotted-circle}** No | The maximum amount of time, in seconds, that a job can run. | | `builds_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | -| `container_registry_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `container_registry_access_level` | string | **{dotted-circle}** No | Set visibility of container registry, for this project, to one of `disabled`, `private` or `enabled`. | -| `description` | string | **{dotted-circle}** No | Short project description. | +| `container_registry_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. Requires `initialize_with_readme` to be `true`. | +| `description` | string | **{dotted-circle}** No | Short project description. | | `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | @@ -1319,19 +1314,17 @@ POST /projects/user/:user_id | `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. | | `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. | | `merge_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create merge commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.)_ | -| `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ | | `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | | `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | | `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | | `mirror` **(PREMIUM)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | | `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | -| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | | `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful jobs. | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | -| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | | `path` | string | **{dotted-circle}** No | Custom repository name for new project. By default generated based on name. | | `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project-members. | @@ -1339,11 +1332,12 @@ POST /projects/user/:user_id | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrators only)_ | | `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | +| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | -| `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | +| `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | | `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request [suggestions](../user/project/merge_requests/reviews/suggestions.md). | | `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | @@ -1379,6 +1373,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-------------------------------------------------------------|----------------|------------------------|-------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | | `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge request by default. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). | @@ -1395,38 +1390,39 @@ Supported attributes: | `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 | | `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_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `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. | | `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. | | `description` | string | **{dotted-circle}** No | Short project description. | | `emails_disabled` | boolean | **{dotted-circle}** No | Disable email notifications. | | `external_authorization_classification_label` **(PREMIUM)** | string | **{dotted-circle}** No | The classification label for the project. | | `forking_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `import_url` | string | **{dotted-circle}** No | URL to import repository from. | | `issues_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `issues_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable issues for this project. Use `issues_access_level` instead. | +| `issues_template` **(PREMIUM)** | string | **{dotted-circle}** No | Default description for Issues. Description is parsed with GitLab Flavored Markdown. See [Templates for issues and merge requests](#templates-for-issues-and-merge-requests). | | `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. | +| `keep_latest_artifact` | boolean | **{dotted-circle}** No | Disable or enable the ability to keep the latest artifact for this project. | | `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. | | `merge_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create merge commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.)_ | | `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | | `merge_pipelines_enabled` | boolean | **{dotted-circle}** No | Enable or disable merge pipelines. | | `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | +| `merge_requests_template` **(PREMIUM)** | string | **{dotted-circle}** No | Default description for merge requests. Description is parsed with GitLab Flavored Markdown. See [Templates for issues and merge requests](#templates-for-issues-and-merge-requests). | | `merge_trains_enabled` | boolean | **{dotted-circle}** No | Enable or disable merge trains. | | `mirror_overwrites_diverged_branches` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirror overwrites diverged branches. | | `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | | `mirror_user_id` **(PREMIUM)** | integer | **{dotted-circle}** No | User responsible for all the activity surrounding a pull mirror event. _(administrators only)_ | | `mirror` **(PREMIUM)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | +| `mr_default_target_self` | boolean | **{dotted-circle}** No | For forked projects, target merge requests to this project. If `false`, the target will be the upstream project. | | `name` | string | **{dotted-circle}** No | The name of the project. | -| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged when all the discussions are resolved. | | `only_allow_merge_if_pipeline_succeeds` | boolean | **{dotted-circle}** No | Set whether merge requests can only be merged with successful jobs. | | `only_mirror_protected_branches` **(PREMIUM)** | boolean | **{dotted-circle}** No | Only mirror protected branches. | +| `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | -| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | -| `restrict_user_defined_variables` | boolean | **{dotted-circle}** No | Allow only users with the [Maintainer role](../user/permissions.md) to pass user-defined variables when triggering a pipeline. For example when the pipeline is triggered in the UI, with the API, or by a trigger token. | | `path` | string | **{dotted-circle}** No | Custom repository name for the project. By default generated based on name. | | `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | @@ -1434,10 +1430,11 @@ Supported attributes: | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrators only)_ | | `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | +| `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | +| `restrict_user_defined_variables` | boolean | **{dotted-circle}** No | Allow only users with the Maintainer role to pass user-defined variables when triggering a pipeline. For example when the pipeline is triggered in the UI, with the API, or by a trigger token. | | `service_desk_enabled` | boolean | **{dotted-circle}** No | Enable or disable Service Desk feature. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | -| `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ | @@ -1448,10 +1445,6 @@ Supported attributes: | `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | | `wiki_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `wiki_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable wiki for this project. Use `wiki_access_level` instead. | -| `issues_template` **(PREMIUM)** | string | **{dotted-circle}** No | Default description for Issues. Description is parsed with GitLab Flavored Markdown. See [Templates for issues and merge requests](#templates-for-issues-and-merge-requests). | -| `merge_requests_template` **(PREMIUM)** | string | **{dotted-circle}** No | Default description for Merge Requests. Description is parsed with GitLab Flavored Markdown. See [Templates for issues and merge requests](#templates-for-issues-and-merge-requests). | -| `keep_latest_artifact` | boolean | **{dotted-circle}** No | Disable or enable the ability to keep the latest artifact for this project. | -| `mr_default_target_self` | boolean | **{dotted-circle}** No | For forked projects, target merge requests to this project. If `false`, the target will be the upstream project. | ## Fork project @@ -1468,18 +1461,16 @@ POST /projects/:id/fork | Attribute | Type | Required | Description | |------------------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `description` | string | **{dotted-circle}** No | The description assigned to the resultant project after forking. | +| `mr_default_target_self` | boolean | **{dotted-circle}** No | For forked projects, target merge requests to this project. If `false`, the target will be the upstream project. | | `name` | string | **{dotted-circle}** No | The name assigned to the resultant project after forking. | | `namespace_id` | integer | **{dotted-circle}** No | The ID of the namespace that the project is forked to. | | `namespace_path` | string | **{dotted-circle}** No | The path of the namespace that the project is forked to. | | `namespace` | integer or string | **{dotted-circle}** No | _(Deprecated)_ The ID or path of the namespace that the project is forked to. | | `path` | string | **{dotted-circle}** No | The path assigned to the resultant project after forking. | -| `description` | string | **{dotted-circle}** No | The description assigned to the resultant project after forking. | | `visibility` | string | **{dotted-circle}** No | The [visibility level](#project-visibility-level) assigned to the resultant project after forking. | -| `mr_default_target_self` | boolean | **{dotted-circle}** No | For forked projects, target merge requests to this project. If `false`, the target will be the upstream project. | - -## List Forks of a project -> Introduced in GitLab 10.1. +## List forks of a project List the projects accessible to the calling user that have an established, forked relationship with the specified project @@ -1490,8 +1481,8 @@ GET /projects/:id/forks | Attribute | Type | Required | Description | |-------------------------------|----------------|------------------------|-------------| -| `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | @@ -1789,7 +1780,7 @@ Example response: } ``` -## List Starrers of a project +## List starrers of a project List the users who starred the specified project. @@ -2267,10 +2258,10 @@ POST /projects/:id/share | Attribute | Type | Required | Description | |----------------|----------------|------------------------|-------------| -| `expires_at` | string | **{dotted-circle}** No | Share expiration date in ISO 8601 format: 2016-09-26 | | `group_access` | integer | **{check-circle}** Yes | The [access level](members.md#valid-access-levels) to grant the group. | | `group_id` | integer | **{check-circle}** Yes | The ID of the group to share with. | | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `expires_at` | string | **{dotted-circle}** No | Share expiration date in ISO 8601 format: 2016-09-26 | ## Delete a shared project link within a group @@ -2375,11 +2366,12 @@ POST /projects/:id/hooks | Attribute | Type | Required | Description | |------------------------------|----------------|------------------------|-------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `url` | string | **{check-circle}** Yes | The hook URL. | | `confidential_issues_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential issues events. | | `confidential_note_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential note events. | | `deployment_events` | boolean | **{dotted-circle}** No | Trigger hook on deployment events. | | `enable_ssl_verification` | boolean | **{dotted-circle}** No | Do SSL verification when triggering the hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issues_events` | boolean | **{dotted-circle}** No | Trigger hook on issues events. | | `job_events` | boolean | **{dotted-circle}** No | Trigger hook on job events. | | `merge_requests_events` | boolean | **{dotted-circle}** No | Trigger hook on merge requests events. | @@ -2387,11 +2379,10 @@ POST /projects/:id/hooks | `pipeline_events` | boolean | **{dotted-circle}** No | Trigger hook on pipeline events. | | `push_events_branch_filter` | string | **{dotted-circle}** No | Trigger hook on push events for matching branches only. | | `push_events` | boolean | **{dotted-circle}** No | Trigger hook on push events. | +| `releases_events` | boolean | **{dotted-circle}** No | Trigger hook on release events. | | `tag_push_events` | boolean | **{dotted-circle}** No | Trigger hook on tag push events. | | `token` | string | **{dotted-circle}** No | Secret token to validate received payloads; this isn't returned in the response. | -| `url` | string | **{check-circle}** Yes | The hook URL. | | `wiki_page_events` | boolean | **{dotted-circle}** No | Trigger hook on wiki events. | -| `releases_events` | boolean | **{dotted-circle}** No | Trigger hook on release events. | ### Edit project hook @@ -2403,12 +2394,13 @@ PUT /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |------------------------------|----------------|------------------------|-------------| +| `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `url` | string | **{check-circle}** Yes | The hook URL. | | `confidential_issues_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential issues events. | | `confidential_note_events` | boolean | **{dotted-circle}** No | Trigger hook on confidential note events. | | `deployment_events` | boolean | **{dotted-circle}** No | Trigger hook on deployment events. | | `enable_ssl_verification` | boolean | **{dotted-circle}** No | Do SSL verification when triggering the hook. | -| `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `issues_events` | boolean | **{dotted-circle}** No | Trigger hook on issues events. | | `job_events` | boolean | **{dotted-circle}** No | Trigger hook on job events. | | `merge_requests_events` | boolean | **{dotted-circle}** No | Trigger hook on merge requests events. | @@ -2416,11 +2408,10 @@ PUT /projects/:id/hooks/:hook_id | `pipeline_events` | boolean | **{dotted-circle}** No | Trigger hook on pipeline events. | | `push_events_branch_filter` | string | **{dotted-circle}** No | Trigger hook on push events for matching branches only. | | `push_events` | boolean | **{dotted-circle}** No | Trigger hook on push events. | +| `releases_events` | boolean | **{dotted-circle}** No | Trigger hook on release events. | | `tag_push_events` | boolean | **{dotted-circle}** No | Trigger hook on tag push events. | | `token` | string | **{dotted-circle}** No | Secret token to validate received payloads; this isn't returned in the response. | -| `url` | string | **{check-circle}** Yes | The hook URL. | | `wiki_page_events` | boolean | **{dotted-circle}** No | Trigger hook on wiki page events. | -| `releases_events` | boolean | **{dotted-circle}** No | Trigger hook on release events. | ### Delete project hook @@ -2478,8 +2469,8 @@ GET /projects | Attribute | Type | Required | Description | |------------|--------|------------------------|-------------| -| `order_by` | string | **{dotted-circle}** No | Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields. | | `search` | string | **{check-circle}** Yes | A string contained in the project name. | +| `order_by` | string | **{dotted-circle}** No | Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields. | | `sort` | string | **{dotted-circle}** No | Return requests sorted in `asc` or `desc` order. | ```shell @@ -2496,11 +2487,11 @@ POST /projects/:id/housekeeping |-----------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | -## Push Rules **(PREMIUM)** +## Push rules **(PREMIUM)** ### Get project push rules -Get the [push rules](../push_rules/push_rules.md#enabling-push-rules) of a +Get the [push rules](../user/project/repository/push_rules.md#enabling-push-rules) of a project. ```plaintext @@ -2554,6 +2545,7 @@ POST /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------------------------------------|----------------|------------------------|-------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `author_email_regex` | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | | `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | @@ -2561,7 +2553,6 @@ POST /projects/:id/push_rule | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | | `file_name_regex` | string | **{dotted-circle}** No | All committed filenames must **not** match this, for example `(jar|exe)$`. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding), | | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | @@ -2577,6 +2568,7 @@ PUT /projects/:id/push_rule | Attribute | Type | Required | Description | |-----------------------------------------|----------------|------------------------|-------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `author_email_regex` | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | | `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | @@ -2584,7 +2576,6 @@ PUT /projects/:id/push_rule | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | | `file_name_regex` | string | **{dotted-circle}** No | All committed filenames must **not** match this, for example `(jar|exe)$`. | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | @@ -2607,7 +2598,8 @@ DELETE /projects/:id/push_rule ## Transfer a project to a new namespace -> Introduced in GitLab 11.1. +See the [Project documentation](../user/project/settings/index.md#transferring-an-existing-project-into-another-namespace) +for prerequisites to transfer a project. ```plaintext PUT /projects/:id/transfer @@ -2736,7 +2728,7 @@ Example response: Read more in the [Branches](branches.md) documentation. -## Project Import/Export +## Project import/export Read more in the [Project import/export](project_import_export.md) documentation. @@ -2750,8 +2742,7 @@ Read more in the [Project vulnerabilities](project_vulnerabilities.md) documenta ## Configure pull mirroring for a project **(PREMIUM)** -> - Introduced in GitLab 11. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. Configure pull mirroring while [creating a new project](#create-project) or [updating an existing project](#edit-project) using the API @@ -2791,8 +2782,6 @@ Read more in the [Project Badges](project_badges.md) documentation. ## Download snapshot of a Git repository -> Introduced in GitLab 10.7 - This endpoint may only be accessed by an administrative user. Download a snapshot of the project (or wiki, if requested) Git repository. This diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index fd024240e90..23acebf5aab 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -185,17 +185,17 @@ This allows you to create a single file. For creating multiple files with a sing POST /projects/:id/repository/files/:file_path ``` -| Attribute | Type | Required | Description | -|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | -| `branch` | string | yes | Name of the branch | -| `start_branch` | string | no | Name of the branch to start the new commit from | -| `encoding` | string | no | Change encoding to `base64`. Default is `text`. | -| `author_email` | string | no | Specify the commit author's email address | -| `author_name` | string | no | Specify the commit author's name | -| `content` | string | yes | File content | -| `commit_message` | string | yes | Commit message | +| Attribute | Type | Required | Description | +| ---------------- | -------------- | -------- | ----------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | +| `branch` | string | yes | Name of the new branch to create. The commit is added to this branch. | +| `start_branch` | string | no | Name of the base branch to create the new branch from. | +| `encoding` | string | no | Change encoding to `base64`. Default is `text`. | +| `author_email` | string | no | The commit author's email address. | +| `author_name` | string | no | The commit author's name. | +| `content` | string | yes | The file's content. | +| `commit_message` | string | yes | The commit message. | ```shell curl --request POST --header 'PRIVATE-TOKEN: ' \ @@ -222,18 +222,18 @@ This allows you to update a single file. For updating multiple files with a sing PUT /projects/:id/repository/files/:file_path ``` -| Attribute | Type | Required | Description | -|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +| ---------------- | -------------- | -------- | ----------- | | `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | -| `branch` | string | yes | Name of the branch | -| `start_branch` | string | no | Name of the branch to start the new commit from | -| `encoding` | string | no | Change encoding to `base64`. Default is `text`. | -| `author_email` | string | no | Specify the commit author's email address | -| `author_name` | string | no | Specify the commit author's name | -| `content` | string | yes | File content | -| `commit_message` | string | yes | Commit message | -| `last_commit_id` | string | no | Last known file commit ID | +| `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | +| `branch` | string | yes | Name of the new branch to create. The commit is added to this branch. | +| `start_branch` | string | no | Name of the base branch to create the new branch from. | +| `encoding` | string | no | Change encoding to `base64`. Default is `text`. | +| `author_email` | string | no | The commit author's email address. | +| `author_name` | string | no | The commit author's name. | +| `content` | string | yes | The file's content. | +| `commit_message` | string | yes | The commit message. | +| `last_commit_id` | string | no | Last known file commit ID. | ```shell curl --request PUT --header 'PRIVATE-TOKEN: ' \ @@ -270,16 +270,16 @@ This allows you to delete a single file. For deleting multiple files with a sing DELETE /projects/:id/repository/files/:file_path ``` -| Attribute | Type | Required | Description | -|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | -| `branch` | string | yes | Name of the branch | -| `start_branch` | string | no | Name of the branch to start the new commit from | -| `author_email` | string | no | Specify the commit author's email address. | -| `author_name` | string | no | Specify the commit author's name. | -| `commit_message` | string | yes | Commit message. | -| `last_commit_id` | string | no | Last known file commit ID. | +| Attribute | Type | Required | Description | +| ---------------- | -------------- | -------- | ----------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | +| `branch` | string | yes | Name of the new branch to create. The commit is added to this branch. | +| `start_branch` | string | no | Name of the base branch to create the new branch from. | +| `author_email` | string | no | The commit author's email address. | +| `author_name` | string | no | The commit author's name. | +| `commit_message` | string | yes | The commit message. | +| `last_commit_id` | string | no | Last known file commit ID. | ```shell curl --request DELETE --header 'PRIVATE-TOKEN: ' \ diff --git a/doc/api/runners.md b/doc/api/runners.md index e53062ce074..3423a02c078 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -39,27 +39,38 @@ Get a list of specific runners available to the user. GET /runners GET /runners?scope=active GET /runners?type=project_type -GET /runners?status=active +GET /runners?status=online +GET /runners?paused=true GET /runners?tag_list=tag1,tag2 ``` -| Attribute | Type | Required | Description | -|-------------|----------------|----------|---------------------| -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | -| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | -| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | -| `tag_list` | string array | no | List of the runner's tags | +| Attribute | Type | Required | Description | +|------------|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 15.0 | +| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | +| `tag_list` | string array | no | List of the runner's tags | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/runners" ``` +NOTE: +The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter. + +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json [ { "active": true, + "paused": false, "description": "test-1-20150125", "id": 6, "ip_address": "127.0.0.1", @@ -71,6 +82,7 @@ Example response: }, { "active": true, + "paused": false, "description": "test-2-20150125", "id": 8, "ip_address": "127.0.0.1", @@ -86,33 +98,44 @@ Example response: ## List all runners **(FREE SELF)** Get a list of all runners in the GitLab instance (specific and shared). Access -is restricted to users with the administrator role. +is restricted to users with administrator access. ```plaintext GET /runners/all GET /runners/all?scope=online GET /runners/all?type=project_type -GET /runners/all?status=active +GET /runners/all?status=online +GET /runners/all?paused=true GET /runners/all?tag_list=tag1,tag2 ``` -| Attribute | Type | Required | Description | -|-------------|----------------|----------|---------------------| -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`, `offline`; showing all runners if none provided | -| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | -| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | -| `tag_list` | string array | no | List of the runner's tags | +| Attribute | Type | Required | Description | +|------------|--------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 15.0 | +| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | +| `tag_list` | string array | no | List of the runner's tags | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/runners/all" ``` +NOTE: +The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter. + +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json [ { "active": true, + "paused": false, "description": "shared-runner-1", "id": 1, "ip_address": "127.0.0.1", @@ -124,6 +147,7 @@ Example response: }, { "active": true, + "paused": false, "description": "shared-runner-2", "id": 3, "ip_address": "127.0.0.1", @@ -135,6 +159,7 @@ Example response: }, { "active": true, + "paused": false, "description": "test-1-20150125", "id": 6, "ip_address": "127.0.0.1", @@ -146,6 +171,7 @@ Example response: }, { "active": true, + "paused": false, "description": "test-2-20150125", "id": 8, "ip_address": "127.0.0.1", @@ -164,7 +190,7 @@ To view more than the first 20 runners, use [pagination](index.md#pagination). Get details of a runner. -At least the [Maintainer role](../user/permissions.md) is required to get runner details at the +At least the Maintainer role is required to get runner details at the project and group level. Instance-level runner details via this endpoint are available to all signed in users. @@ -185,11 +211,16 @@ NOTE: The `token` attribute in the response was deprecated [in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320). and removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/214322). +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json { "active": true, + "paused": false, "architecture": null, "description": "test-1-20150125", "id": 6, @@ -229,16 +260,17 @@ Update details of a runner. PUT /runners/:id ``` -| Attribute | Type | Required | Description | -|---------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a runner | -| `description` | string | no | The description of a runner | -| `active` | boolean | no | The state of a runner; can be set to `true` or `false` | -| `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner | -| `run_untagged`| boolean | no | Flag indicating the runner can execute untagged jobs | -| `locked` | boolean | no | Flag indicating the runner is locked | -| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | -| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job | +| Attribute | Type | Required | Description | +|-------------------|---------|----------|--------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a runner | +| `description` | string | no | The description of a runner | +| `active` | boolean | no | Deprecated: Use `:paused` instead. Flag indicating whether the runner is allowed to receive jobs | +| `paused` | boolean | no | Flag indicating whether the runner should ignore new jobs | +| `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner | +| `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs | +| `locked` | boolean | no | Flag indicating the runner is locked | +| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | +| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job | ```shell curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/runners/6" \ @@ -249,6 +281,10 @@ NOTE: The `token` attribute in the response was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/214320) in GitLab 12.10. and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/214322) in GitLab 13.0. +NOTE: +The `active` query parameter was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json @@ -292,7 +328,12 @@ Example response: Pause a specific runner. ```plaintext -PUT --form "active=false" /runners/:runner_id +PUT --form "paused=true" /runners/:runner_id + +# --or-- + +# Deprecated: removal planned in 15.0 +PUT --form "active=false" /runners/:runner_id ``` | Attribute | Type | Required | Description | @@ -300,10 +341,20 @@ PUT --form "active=false" /runners/:runner_id | `runner_id` | integer | yes | The ID of a runner | ```shell +curl --request PUT --header "PRIVATE-TOKEN: " \ + --form "paused=true" "https://gitlab.example.com/api/v4/runners/6" + +# --or-- + +# Deprecated: removal planned in 15.0 curl --request PUT --header "PRIVATE-TOKEN: " \ --form "active=false" "https://gitlab.example.com/api/v4/runners/6" ``` +NOTE: +The `active` form attribute was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + ## List runner's jobs > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) in GitLab 10.3. @@ -397,35 +448,45 @@ Example response: ## List project's runners -List all runners (specific and shared) available in the project. Shared runners -are listed if at least one shared runner is defined. +List all runners available in the project, including from ancestor groups and [any allowed shared runners](../ci/runners/runners_scope.md#enable-shared-runners). ```plaintext GET /projects/:id/runners GET /projects/:id/runners?scope=active GET /projects/:id/runners?type=project_type -GET /projects/:id/runners?status=active +GET /projects/:id/runners/all?status=online +GET /projects/:id/runners/all?paused=true GET /projects/:id/runners?tag_list=tag1,tag2 ``` -| Attribute | Type | Required | Description | -|------------|----------------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | -| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | -| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | -| `tag_list` | string array | no | List of the runner's tags | +| Attribute | Type | Required | Description | +|------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 15.0 | +| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | +| `tag_list` | string array | no | List of the runner's tags | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/9/runners" ``` +NOTE: +The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter. + +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json [ { "active": true, + "paused": false, "description": "test-2-20150125", "id": 8, "ip_address": "127.0.0.1", @@ -437,6 +498,7 @@ Example response: }, { "active": true, + "paused": false, "description": "development_runner", "id": 5, "ip_address": "127.0.0.1", @@ -444,7 +506,7 @@ Example response: "runner_type": "instance_type", "name": null, "online": true, - "status": "paused" + "status": "online" } ] ``` @@ -504,27 +566,36 @@ curl --request DELETE --header "PRIVATE-TOKEN: " "https://git ## List group's runners -List all runners (specific and shared) available in the group as well it's ancestor groups. -Shared runners are listed if at least one shared runner is defined. +List all runners available in the group as well as its ancestor groups, including [any allowed shared runners](../ci/runners/runners_scope.md#enable-shared-runners). ```plaintext GET /groups/:id/runners GET /groups/:id/runners?type=group_type -GET /groups/:id/runners?status=active +GET /groups/:id/runners/all?status=online +GET /groups/:id/runners/all?paused=true GET /groups/:id/runners?tag_list=tag1,tag2 ``` -| Attribute | Type | Required | Description | -|------------|----------------|----------|---------------------| -| `id` | integer | yes | The ID of the group owned by the authenticated user | -| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | -| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | -| `tag_list` | string array | no | List of the runner's tags | +| Attribute | Type | Required | Description | +|------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of the group owned by the authenticated user | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type`. The `project_type` value is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351466) and will be removed in GitLab 15.0 | +| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 15.0 | +| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | +| `tag_list` | string array | no | List of the runner's tags | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/9/runners" ``` +NOTE: +The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter. + +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json @@ -534,6 +605,7 @@ Example response: "description": "Shared", "ip_address": "127.0.0.1", "active": true, + "paused": false, "is_shared": true, "runner_type": "instance_type", "name": "gitlab-runner", @@ -545,6 +617,7 @@ Example response: "description": "Test", "ip_address": "127.0.0.1", "active": true, + "paused": false, "is_shared": true, "runner_type": "instance_type", "name": "gitlab-runner", @@ -556,6 +629,7 @@ Example response: "description": "Test 2", "ip_address": "127.0.0.1", "active": true, + "paused": false, "is_shared": false, "runner_type": "group_type", "name": "gitlab-runner", @@ -573,18 +647,20 @@ Register a new runner for the instance. POST /runners ``` -| Attribute | Type | Required | Description | -|-------------------|----------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | -| `description` | string | no | Runner's description | -| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI. | -| `active` | boolean | no | Whether the runner is active | -| `locked` | boolean | no | Whether the runner should be locked for current project | -| `run_untagged` | boolean | no | Whether the runner should handle untagged jobs | -| `tag_list` | string array | no | List of runner's tags | -| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | -| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job | -| `maintainer_note` | string | no | Free-form maintainer notes for the runner (255 characters) | +| Attribute | Type | Required | Description | +|--------------------|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `token` | string | yes | [Registration token](#registration-and-authentication-tokens) | +| `description` | string | no | Runner's description | +| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI | +| `active` | boolean | no | Deprecated: Use `:paused` instead. Whether the runner is allowed to receive jobs | +| `paused` | boolean | no | Whether the runner should ignore new jobs | +| `locked` | boolean | no | Whether the runner should be locked for current project | +| `run_untagged` | boolean | no | Whether the runner should handle untagged jobs | +| `tag_list` | string array | no | List of runner's tags | +| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | +| `maximum_timeout` | integer | no | Maximum timeout set when this runner handles the job | +| `maintainer_note` | string | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350730), see `maintenance_note` | +| `maintenance_note` | string | no | Free-form maintenance notes for the runner (255 characters) | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners" \ @@ -603,7 +679,8 @@ Example response: ```json { "id": 12345, - "token": "6337ff461c94fd3fa32ba3b1ff4125" + "token": "6337ff461c94fd3fa32ba3b1ff4125", + "token_expires_at": "2021-09-27T21:05:03.203Z" } ``` @@ -743,6 +820,7 @@ Example response: ```json { - "token": "6337ff461c94fd3fa32ba3b1ff4125" + "token": "6337ff461c94fd3fa32ba3b1ff4125", + "token_expires_at": "2021-09-27T21:05:03.203Z" } ``` diff --git a/doc/api/scim.md b/doc/api/scim.md index acc6a6ae686..ab3a181f5be 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/settings.md b/doc/api/settings.md index 2ed841b885c..4246c7a46f1 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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 --- @@ -65,6 +65,8 @@ Example response: "dsa_key_restriction": 0, "ecdsa_key_restriction": 0, "ed25519_key_restriction": 0, + "ecdsa_sk_key_restriction": 0, + "ed25519_sk_key_restriction": 0, "first_day_of_week": 0, "enforce_terms": true, "terms": "Hello world!", @@ -166,6 +168,8 @@ Example response: "dsa_key_restriction": 0, "ecdsa_key_restriction": 0, "ed25519_key_restriction": 0, + "ecdsa_sk_key_restriction": 0, + "ed25519_sk_key_restriction": 0, "first_day_of_week": 0, "enforce_terms": true, "terms": "Hello world!", @@ -268,7 +272,9 @@ listed in the descriptions of the relevant settings. | `domain_allowlist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is `null`, meaning there is no restriction. | | `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. | | `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. | +| `ecdsa_sk_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA_SK key. Default is `0` (no restriction). `-1` disables ECDSA_SK keys. | | `ed25519_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. | +| `ed25519_sk_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519_SK key. Default is `0` (no restriction). `-1` disables ED25519_SK keys. | | `eks_access_key_id` | string | no | AWS IAM access key ID. | | `eks_account_id` | string | no | Amazon account ID. | | `eks_integration_enabled` | boolean | no | Enable integration with Amazon EKS. | @@ -370,6 +376,7 @@ listed in the descriptions of the relevant settings. | `push_event_hooks_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether webhooks and services fire or not. Webhooks and services aren't submitted if it surpasses that value. | | `rate_limiting_response_text` | string | no | When rate limiting is enabled via the `throttle_*` settings, send this plain text response when a rate limit is exceeded. 'Retry later' is sent if this is blank. | | `raw_blob_request_limit` | integer | no | Max number of requests per minute for each raw path. Default: 300. To disable throttling set to 0.| +| `user_email_lookup_limit` | integer | no | Max number of requests per minute for email lookup. Default: 60. To disable throttling set to 0.| | `recaptcha_enabled` | boolean | no | (**If enabled, requires:** `recaptcha_private_key` and `recaptcha_site_key`) Enable reCAPTCHA. | | `recaptcha_private_key` | string | required by: `recaptcha_enabled` | Private key for reCAPTCHA. | | `recaptcha_site_key` | string | required by: `recaptcha_enabled` | Site key for reCAPTCHA. | diff --git a/doc/api/statistics.md b/doc/api/statistics.md index 59197260988..17daf2fc71f 100644 --- a/doc/api/statistics.md +++ b/doc/api/statistics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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/status_checks.md b/doc/api/status_checks.md index 7de188ad185..a3a342854dd 100644 --- a/doc/api/status_checks.md +++ b/doc/api/status_checks.md @@ -31,7 +31,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/status_checks "id": 2, "name": "Rule 1", "external_url": "https://gitlab.com/test-endpoint", - "status": "approved" + "status": "pass" }, { "id": 1, @@ -47,6 +47,8 @@ GET /projects/:id/merge_requests/:merge_request_iid/status_checks For a single merge request, use the API to inform GitLab that a merge request has passed a check by an external service. To set the status of an external check, the personal access token used must belong to a user with at least the developer role on the target project of the merge request. +Execute this API call as any user with rights to approve the merge request itself. + ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses ``` @@ -59,6 +61,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses | `merge_request_iid` | integer | yes | IID of a merge request | | `sha` | string | yes | SHA at `HEAD` of the source branch | | `external_status_check_id` | integer | yes | ID of an external status check | +| `status` | string | no | Set to `pass` to pass the check | NOTE: `sha` must be the SHA at the `HEAD` of the merge request's source branch. diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md index ea9baa79b4a..0a3e7d54f88 100644 --- a/doc/api/suggestions.md +++ b/doc/api/suggestions.md @@ -13,8 +13,8 @@ Every API call to suggestions must be authenticated. ## Applying suggestions -Applies a suggested patch in a merge request. Users must be -at least [Developer](../user/permissions.md) to perform such action. +Applies a suggested patch in a merge request. Users must have +at least the Developer role to perform such action. ```plaintext PUT /suggestions/:id/apply diff --git a/doc/api/tags.md b/doc/api/tags.md index 6aa40cf476d..903cb361587 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -22,7 +22,7 @@ Parameters: | `id` | integer/string| yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user| | `order_by` | string | no | Return tags ordered by `name` or `updated` fields. Default is `updated` | | `sort` | string | no | Return tags sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Return list of tags matching the search criteria. You can use `^term` and `term$` to find tags that begin and end with `term` respectively. | +| `search` | string | no | Return list of tags matching the search criteria. You can use `^term` and `term$` to find tags that begin and end with `term` respectively. No other regular expressions are supported. | ```json [ diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md index 4809166f357..c7064ebf65b 100644 --- a/doc/api/usage_data.md +++ b/doc/api/usage_data.md @@ -13,7 +13,7 @@ The Service Data API is associated with [Service Ping](../development/service_pi > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57270) in GitLab 13.11. -Export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](https://metrics.gitlab.com/index.html), for easier importing. +Export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](https://metrics.gitlab.com/), for easier importing. ```plaintext GET /usage_data/metric_definitions diff --git a/doc/api/users.md b/doc/api/users.md index 9b79a249220..925563aeb1f 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization 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 --- @@ -78,13 +78,14 @@ GET /users?external=true GitLab supports bot users such as the [alert bot](../operations/incident_management/integrations.md) or the [support bot](../user/project/service_desk.md#support-bot-user). You can exclude the following types of [internal users](../development/internal_users.md#internal-users) -from the users' list, with the `exclude_internal=true` parameter, -([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241144) in GitLab 13.4). +from the users' list with the `exclude_internal=true` parameter +([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241144) in GitLab 13.4): - Alert bot - Support bot -However, this action does not exclude [project bot users](../user/project/settings/project_access_tokens.md#project-bot-users). +However, this action does not exclude [bot users for projects](../user/project/settings/project_access_tokens.md#bot-users-for-projects) +or [bot users for groups](../user/group/settings/group_access_tokens.md#bot-users-for-groups). ```plaintext GET /users?exclude_internal=true @@ -108,7 +109,7 @@ GET /users | `sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc` | | `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users | | `without_projects` | boolean | no | Filter users without projects. Default is `false`, which means that all users are returned, with and without projects. | -| `admins` | boolean | no | Return only admin users. Default is `false` | +| `admins` | boolean | no | Return only administrators. Default is `false` | | `saml_provider_id` **(PREMIUM)** | number | no | Return only users created by the specified SAML provider ID. If not included, it returns all users. | ```json @@ -532,7 +533,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------|---------|----------|----------------------------------------------| | `id` | integer | yes | The ID of a user | -| `hard_delete` | boolean | no | If true, contributions that would usually be [moved to the ghost user](../user/profile/account/delete_account.md#associated-records) are deleted instead, as well as groups owned solely by this 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) @@ -696,6 +697,38 @@ Example response: } ``` +## Set user status + +Set the status of the current user. + +```plaintext +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. | +| `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. + +```shell +curl --request PUT --header "PRIVATE-TOKEN: " --data "clear_status_after=1_day" --data "emoji=coffee" \ + --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status" +``` + +Example responses + +```json +{ + "emoji":"coffee", + "message":"I crave coffee", + "message_html": "I crave coffee", + "clear_status_at":"2021-02-15T10:49:01.311Z" +} +``` + ## Get user preferences Get a list of currently authenticated user's preferences. @@ -743,38 +776,6 @@ 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. | -## Set user status - -Set the status of the current user. - -```plaintext -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. | -| `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. - -```shell -curl --request PUT --header "PRIVATE-TOKEN: " --data "clear_status_after=1_day" --data "emoji=coffee" \ - --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status" -``` - -Example responses - -```json -{ - "emoji":"coffee", - "message":"I crave coffee", - "message_html": "I crave coffee", - "clear_status_at":"2021-02-15T10:49:01.311Z" -} -``` - ## User Follow ### Follow and unfollow users @@ -1545,7 +1546,7 @@ Please refer to the [Events API documentation](events.md#get-user-contribution-e ## Get all impersonation tokens of a user -> Requires administrator permissions. +Requires administrator access. It retrieves every impersonation token of the user. Use the pagination parameters `page` and `per_page` to restrict the list of impersonation tokens. @@ -1719,8 +1720,8 @@ Example response: ## Create an impersonation token -> Requires administrator permissions. -> Token values are returned once. Make sure you save it - you can't access it again. +Requires administrator access. Token values are returned once. Make sure you save it because you can't access +it again. It creates a new impersonation token. Only administrators can do this. You are only able to create impersonation tokens to impersonate the user and perform @@ -1764,7 +1765,7 @@ Example response: ## Revoke an impersonation token -> Requires administrator permissions. +Requires administrator access. It revokes an impersonation token. @@ -1837,7 +1838,7 @@ The activities that update the timestamp are: - Git HTTP/SSH activities (such as clone, push) - User logging in to GitLab -- User visiting pages related to Dashboards, Projects, Issues, and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54947) in GitLab 11.8) +- User visiting pages related to dashboards, projects, issues, and merge requests ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54947) in GitLab 11.8) - User using the API - User using the GraphQL API diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index da269073905..9c2170e0709 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -1,18 +1,9 @@ --- -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 +redirect_to: 'https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md' +remove_date: '2023-01-31' --- -# API V3 to API V4 +This document was moved to [another location](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md). -WARNING: -The GitLab API v3 was [removed](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819) in GitLab 11.0. - -For information about the current version of the GitLab API, read the [API documentation](index.md). - -## Related topics - -- [GitLab v3 API documentation](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-16-stable/doc/api/index.md) -- [Migration guide](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md) from - v3 to v4 + + diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index 8457f63fd38..7f91b829061 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights 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 --- # Visual Review discussions API **(PREMIUM)** @@ -10,7 +9,7 @@ type: reference, api > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18710) in GitLab 12.5. > - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. -Visual Review discussions are notes on Merge Requests sent as +Visual Review discussions are notes on merge requests sent as feedback from [Visual Reviews](../ci/review_apps/index.md#visual-reviews). ## Create new merge request thread -- cgit v1.2.1