diff options
Diffstat (limited to 'doc/api')
124 files changed, 3238 insertions, 2157 deletions
diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 9eab35a32d8..8f8f6881162 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -30,7 +30,7 @@ GET /projects/:id/access_requests | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -73,7 +73,7 @@ POST /projects/:id/access_requests | Attribute | Type | Required | Description | | --------- | -------------- | -------- |-----------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group or project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group or project](rest/index.md#namespaced-path-encoding) | Example request: @@ -106,7 +106,7 @@ PUT /projects/:id/access_requests/:user_id/approve | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the access requester | | `access_level` | integer | no | A valid access level (defaults: `30`, the Developer role) | @@ -141,7 +141,7 @@ DELETE /projects/:id/access_requests/:user_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the access requester | Example request: diff --git a/doc/api/alert_management_alerts.md b/doc/api/alert_management_alerts.md index 702d453e140..c4293cc76f1 100644 --- a/doc/api/alert_management_alerts.md +++ b/doc/api/alert_management_alerts.md @@ -17,7 +17,7 @@ POST /projects/:id/alert_management_alerts/:alert_iid/metric_images | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `alert_iid` | integer | yes | The internal ID of a project's alert. | ```shell @@ -46,7 +46,7 @@ GET /projects/:id/alert_management_alerts/:alert_iid/metric_images | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `alert_iid` | integer | yes | The internal ID of a project's alert. | ```shell @@ -84,7 +84,7 @@ PUT /projects/:id/alert_management_alerts/:alert_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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `alert_iid` | integer | yes | The internal ID of a project's alert. | | `image_id` | integer | yes | The ID of the image. | | `url` | string | no | The URL to view more metrics information. | @@ -115,7 +115,7 @@ DELETE /projects/:id/alert_management_alerts/:alert_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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `alert_iid` | integer | yes | The internal ID of a project's alert. | | `image_id` | integer | yes | The ID of the image. | diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 531d679a34d..b7c1def0ba4 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -40,6 +40,7 @@ The following API resources are available in the project context: | [Deploy tokens](deploy_tokens.md) | `/projects/:id/deploy_tokens` (also available for groups and standalone) | | [Deployments](deployments.md) | `/projects/:id/deployments` | | [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) | +| [Draft Notes](draft_notes.md) (comments) | `/projects/:id/merge_requests/.../draft_notes` | [Environments](environments.md) | `/projects/:id/environments` | | [Error Tracking](error_tracking.md) | `/projects/:id/error_tracking/settings` | | [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | @@ -134,6 +135,7 @@ The following API resources are available in the group context: | [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | | [Issues Statistics](issues_statistics.md) | `/groups/:id/issues_statistics` (also available for projects and standalone) | | [Linked epics](linked_epics.md) | `/groups/:id/epics/.../related_epics` | +| [Member Roles](member_roles.md) | `/groups/:id/member_roles` | | [Members](members.md) | `/groups/:id/members` (also available for projects) | | [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | | [Notes](notes.md) (comments) | `/groups/:id/epics/.../notes` (also available for projects) | diff --git a/doc/api/appearance.md b/doc/api/appearance.md index eb88ec5e1b3..94fb092c739 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -29,8 +29,10 @@ Example response: ```json { "title": "GitLab Test Instance", - "pwa_short_name": "GitLab", "description": "gitlab-test.example.com", + "pwa_name": "GitLab PWA", + "pwa_short_name": "GitLab", + "pwa_description": "GitLab as PWA", "pwa_icon": "/uploads/-/system/appearance/pwa_icon/1/pwa_logo.png", "logo": "/uploads/-/system/appearance/logo/1/logo.png", "header_logo": "/uploads/-/system/appearance/header_logo/1/header.png", @@ -56,8 +58,10 @@ PUT /application/appearance | Attribute | Type | Required | Description | | --------------------------------- | ------- | -------- | ----------- | | `title` | string | no | Instance title on the sign in / sign up page -| `pwa_short_name` | string | no | Optional, short name for Progressive Web App | `description` | string | no | Markdown text shown on the sign in / sign up page +| `pwa_name` | string | no | Full name of the Progressive Web App. Used for the attribute `name` in `manifest.json`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. +| `pwa_short_name` | string | no | Short name for Progressive Web App. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. +| `pwa_description` | string | no | An explanation of what the Progressive Web App does. Used for the attribute `description` in `manifest.json`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. | `pwa_icon` | mixed | no | Icon used for Progressive Web App. See [Change logo](#change-logo). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375708) in GitLab 15.8. | `logo` | mixed | no | Instance image used on the sign in / sign up page. See [Change logo](#change-logo) | `header_logo` | mixed | no | Instance image used for the main navigation bar @@ -79,8 +83,10 @@ Example response: ```json { "title": "GitLab Test Instance", - "pwa_short_name": "GitLab", "description": "gitlab-test.example.com", + "pwa_name": "GitLab PWA", + "pwa_short_name": "GitLab", + "pwa_description": "GitLab as PWA", "pwa_icon": "/uploads/-/system/appearance/pwa_icon/1/pwa_logo.png", "logo": "/uploads/-/system/appearance/logo/1/logo.png", "header_logo": "/uploads/-/system/appearance/header_logo/1/header.png", diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index db89262c84f..fec719b189c 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -6,14 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Audit Events API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121) in GitLab 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/121) in GitLab 12.4. +> - [Author Email added to the response body](https://gitlab.com/gitlab-org/gitlab/-/issues/386322) in GitLab 15.9. ## Instance Audit Events **(PREMIUM SELF)** The Audit Events API allows you to retrieve [instance audit events](../administration/audit_events.md#instance-events). This API cannot retrieve group or project audit events. -To retrieve audit events using the API, you must [authenticate yourself](index.md#authentication) as an Administrator. +To retrieve audit events using the API, you must [authenticate yourself](rest/index.md#authentication) as an Administrator. ### Retrieve all instance audit events @@ -31,7 +32,7 @@ GET /audit_events By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/audit_events" @@ -49,6 +50,7 @@ Example response: "details": { "custom_message": "Project archived", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs/flight", "target_type": "Project", "target_details": "flightjs/flight", @@ -65,6 +67,7 @@ Example response: "details": { "add": "group", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs", "target_type": "Group", "target_details": "flightjs", @@ -83,6 +86,7 @@ Example response: "from": "hello@flightjs.com", "to": "maintainer@flightjs.com", "author_name": "Andreas", + "author_email": "admin@example.com", "target_id": 51, "target_type": "User", "target_details": "Andreas", @@ -119,6 +123,7 @@ Example response: "details": { "custom_message": "Project archived", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs/flight", "target_type": "Project", "target_details": "flightjs/flight", @@ -142,7 +147,7 @@ A user with: - The Owner role can retrieve group audit events of all users. - The Developer or Maintainer role is limited to group audit events based on their individual actions. -This endpoint supports both offset-based and [keyset-based](index.md#keyset-based-pagination) pagination. Keyset-based +This endpoint supports both offset-based and [keyset-based](rest/index.md#keyset-based-pagination) pagination. Keyset-based pagination is recommended when requesting consecutive pages of results. ### Retrieve all group audit events @@ -153,14 +158,14 @@ GET /groups/:id/audit_events | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `created_after` | string | no | Return group audit events created on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ)` | | `created_before` | string | no | Return group audit events created on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/groups/60/audit_events" @@ -178,6 +183,7 @@ Example response: "details": { "custom_message": "Group marked for deletion", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs", "target_type": "Group", "target_details": "flightjs", @@ -194,6 +200,7 @@ Example response: "details": { "add": "group", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs", "target_type": "Group", "target_details": "flightjs", @@ -215,7 +222,7 @@ GET /groups/:id/audit_events/:audit_event_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `audit_event_id` | integer | yes | The ID of the audit event | ```shell @@ -233,6 +240,7 @@ Example response: "details": { "custom_message": "Group marked for deletion", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": "flightjs", "target_type": "Group", "target_details": "flightjs", @@ -260,14 +268,14 @@ GET /projects/:id/audit_events | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `created_after` | string | no | Return project audit events created on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | | `created_before` | string | no | Return project audit events created on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/projects/7/audit_events" @@ -287,6 +295,7 @@ Example response: "from": "", "to": "true", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": 7, "target_type": "Project", "target_details": "twitter/typeahead-js", @@ -305,6 +314,7 @@ Example response: "from": "false", "to": "true", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": 7, "target_type": "Project", "target_details": "twitter/typeahead-js", @@ -326,7 +336,7 @@ GET /projects/:id/audit_events/:audit_event_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `audit_event_id` | integer | yes | The ID of the audit event | ```shell @@ -346,6 +356,7 @@ Example response: "from": "", "to": "true", "author_name": "Administrator", + "author_email": "admin@example.com", "target_id": 7, "target_type": "Project", "target_details": "twitter/typeahead-js", diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 9d0b8945c53..a669c6d00c3 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -38,7 +38,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | Example request: @@ -103,7 +103,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `award_id` | integer | yes | ID of the award emoji. | @@ -148,7 +148,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `name` | string | yes | Name of the emoji without colons. | @@ -193,7 +193,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `award_id` | integer | yes | ID of an award emoji. | @@ -225,7 +225,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | @@ -273,7 +273,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `award_id` | integer | yes | ID of the award emoji. | @@ -317,7 +317,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `name` | string | yes | Name of the emoji without colons. | @@ -363,7 +363,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | Internal ID of an issue. | | `note_id` | integer | yes | ID of a comment (note). | | `award_id` | integer | yes | ID of an award emoji. | diff --git a/doc/api/boards.md b/doc/api/boards.md index 79f5cca4a0d..00ab9a7b9cb 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -21,7 +21,7 @@ GET /projects/:id/boards | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/boards" @@ -105,7 +105,7 @@ GET /projects/:id/boards/:board_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -182,7 +182,7 @@ POST /projects/:id/boards | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the new board | ```shell @@ -225,7 +225,7 @@ PUT /projects/:id/boards/:board_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `name` | string | no | The new name of the board | | `assignee_id` **(PREMIUM)** | integer | no | The assignee the board should be scoped to | @@ -305,7 +305,7 @@ DELETE /projects/:id/boards/:board_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -323,7 +323,7 @@ GET /projects/:id/boards/:board_id/lists | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -383,7 +383,7 @@ GET /projects/:id/boards/:board_id/lists/:list_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id`| integer | yes | The ID of a board's list | @@ -418,7 +418,7 @@ POST /projects/:id/boards/:board_id/lists | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `label_id` | integer | no | The ID of a label | | `assignee_id` **(PREMIUM)** | integer | no | The ID of a user | @@ -461,7 +461,7 @@ PUT /projects/:id/boards/:board_id/lists/:list_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | | `position` | integer | yes | The position of the list | @@ -497,7 +497,7 @@ DELETE /projects/:id/boards/:board_id/lists/:list_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | diff --git a/doc/api/branches.md b/doc/api/branches.md index 0c9df88cf85..f99c4443ac8 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -26,8 +26,9 @@ 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.| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user.| | `search` | string | no | Return list of branches containing the search string. You can use `^term` and `term$` to find branches that begin and end with `term` respectively. | +| `regex` | string | no | Return list of branches with names matching a [re2](https://github.com/google/re2/wiki/Syntax) regular expression. | Example request: @@ -83,8 +84,8 @@ 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. | -| `branch` | string | yes | [URL-encoded name](index.md#namespaced-path-encoding) of the branch. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `branch` | string | yes | [URL-encoded name](rest/index.md#namespaced-path-encoding) of the branch. | Example request: @@ -144,7 +145,7 @@ Parameters: | Attribute | Type | Required | Description | |:----------|:--------|:---------|:-------------------------------------------------------------------------------------------------------------| -| `id` | integer | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `branch` | string | yes | Name of the branch. | | `ref` | string | yes | Branch name or commit SHA to create branch from. | @@ -199,7 +200,7 @@ 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. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `branch` | string | yes | Name of the branch. | Example request: @@ -223,7 +224,7 @@ 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. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | Example request: diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md index a438bc13818..6a33bd1bc95 100644 --- a/doc/api/bulk_imports.md +++ b/doc/api/bulk_imports.md @@ -4,14 +4,14 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Migrations (Bulk Imports) API **(FREE)** +# Group migration by direct transfer API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64335) in GitLab 14.1. -With the GitLab Migrations API, you can view the progress of migrations initiated with -[GitLab Group Migration](../user/group/import/index.md). +With the group migration by direct transfer API, you can start and view the progress of migrations initiated with +[group migration by direct transfer](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended). -## Start a new GitLab migration +## Start a new group migration > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66353) in GitLab 14.2. @@ -54,7 +54,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla { "id": 1, "status": "created", "source_type": "gitlab", "created_at": "2021-06-18T09:45:55.358Z", "updated_at": "2021-06-18T09:46:27.003Z" } ``` -## List all GitLab migrations +## List all group migrations ```plaintext GET /bulk_imports @@ -97,7 +97,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ] ``` -## List all GitLab migrations' entities +## List all group migrations' entities ```plaintext GET /bulk_imports/entities @@ -165,7 +165,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ] ``` -## Get GitLab migration details +## Get group migration details ```plaintext GET /bulk_imports/:id @@ -185,7 +185,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab } ``` -## List GitLab migration entities +## List group migration entities ```plaintext GET /bulk_imports/:id/entities @@ -221,7 +221,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab ] ``` -## Get GitLab migration entity details +## Get group migration entity details ```plaintext GET /bulk_imports/:id/entities/:entity_id diff --git a/doc/api/cluster_agents.md b/doc/api/cluster_agents.md index 718871884fb..2622d6782aa 100644 --- a/doc/api/cluster_agents.md +++ b/doc/api/cluster_agents.md @@ -25,7 +25,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|-------------------|-----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user | Response: @@ -103,7 +103,7 @@ Parameters: | Attribute | Type | Required | Description | |------------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user | | `agent_id` | integer | yes | ID of the agent | Response: @@ -165,7 +165,7 @@ Parameters: | Attribute | Type | Required | Description | |-----------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user | | `name` | string | yes | Name for the agent | Response: @@ -229,7 +229,7 @@ Parameters: | Attribute | Type | Required | Description | |------------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user | | `agent_id` | integer | yes | ID of the agent | Example request: @@ -254,7 +254,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------|-------------------|-----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `agent_id` | integer or string | yes | ID of the agent. | Response: @@ -321,7 +321,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------|-------------------|----------|-------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `agent_id` | integer | yes | ID of the agent. | | `token_id` | integer | yes | ID of the token. | @@ -377,7 +377,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------|-------------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `agent_id` | integer | yes | ID of the agent. | | `name` | string | yes | Name for the token. | | `description` | string | no | Description for the token. | @@ -441,7 +441,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------|-------------------|----------|---------------------------------------------------------------------------------------------------------------- -| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `agent_id` | integer | yes | ID of the agent. | | `token_id` | integer | yes | ID of the token. | diff --git a/doc/api/commits.md b/doc/api/commits.md index 83fa54231ee..5a3481ee086 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -10,9 +10,13 @@ This API operates on [repository commits](https://git-scm.com/book/en/v2/Git-Bas ## 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. +Some date fields in responses from this API are, or can appear to be, duplicated +information: + +- The `created_at` field exists solely for consistency with other GitLab APIs. It + is always identical to the `committed_date` field. +- The `committed_date` and `authored_date` fields are generated from different sources, + and may not be identical. ## List repository commits @@ -24,7 +28,7 @@ GET /projects/:id/repository/commits | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `ref_name` | string | no | The name of a repository branch, tag or revision range, or if not given the default branch | | `since` | string | no | Only commits after or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ` | | `until` | string | no | Only commits before or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ` | @@ -88,12 +92,12 @@ POST /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `branch` | string | yes | Name of the branch to commit into. To create a new branch, also provide either `start_branch` or `start_sha`, and optionally `start_project`. | | `commit_message` | string | yes | Commit message | | `start_branch` | string | no | Name of the branch to start the new branch from | | `start_sha` | string | no | SHA of the commit to start the new branch from | -| `start_project` | integer/string | no | The project ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) to start the new branch from. Defaults to the value of `id`. | +| `start_project` | integer/string | no | The project ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) to start the new branch from. Defaults to the value of `id`. | | `actions[]` | array | yes | An array of action hashes to commit as a batch. See the next table for what attributes it can take. | | `author_email` | string | no | Specify the commit author's email address | | `author_name` | string | no | Specify the commit author's name | @@ -177,7 +181,7 @@ Example response: } ``` -GitLab supports [form encoding](index.md#encoding-api-parameters-of-array-and-hash-types). The following is an example using Commit API with form encoding: +GitLab supports [form encoding](rest/index.md#encoding-api-parameters-of-array-and-hash-types). The following is an example using Commit API with form encoding: ```shell curl --request POST \ @@ -215,7 +219,7 @@ Parameters: | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | | `stats` | boolean | no | Include commit stats. Default is true | @@ -270,7 +274,7 @@ Parameters: | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash | | `type` | string | no | The scope of commits. Possible values `branch`, `tag`, `all`. Default is `all`. | @@ -302,7 +306,7 @@ Parameters: | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `sha` | string | yes | The commit hash | | `branch` | string | yes | The name of the branch | | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced in GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) | @@ -375,7 +379,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `sha` | string | yes | Commit SHA to revert | | `branch` | string | yes | Target branch name | | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) in GitLab 13.3 | @@ -443,7 +447,7 @@ Parameters: | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -479,7 +483,7 @@ Parameters: | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -527,7 +531,7 @@ POST /projects/:id/repository/commits/:sha/comments | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA or name of a repository branch or tag | | `note` | string | yes | The text of the comment | | `path` | string | no | The file path relative to the repository | @@ -572,7 +576,7 @@ Parameters: | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell @@ -631,7 +635,7 @@ GET /projects/:id/repository/commits/:sha/statuses | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA | `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch | `stage` | string | no | Filter by [build stage](../ci/yaml/index.md#stages), for example, `test` @@ -706,7 +710,7 @@ POST /projects/:id/statuses/:sha | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA | `state` | string | yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled` | `ref` | string | no | The `ref` (branch or tag) to which the status refers @@ -749,7 +753,7 @@ Example response: ## List merge requests associated with a commit -Get a list of merge requests related to the specified commit. +Returns information about the merge request that originally introduced a specific commit. ```plaintext GET /projects/:id/repository/commits/:sha/merge_requests @@ -757,7 +761,7 @@ GET /projects/:id/repository/commits/:sha/merge_requests | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA ```shell @@ -829,7 +833,7 @@ Parameters: | 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 +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index b94bee210e4..5fc4cb138a1 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -12,7 +12,7 @@ This is the API documentation of the [GitLab Container Registry](../user/package When the `ci_job_token_scope` feature flag is enabled (it is **disabled by default**), you can use the below endpoints from a CI/CD job, by passing the `$CI_JOB_TOKEN` variable as the `JOB-TOKEN` header. -The job token will only have access to its own project. +The job token only has access to its own project. [GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) can opt to enable it. @@ -41,7 +41,7 @@ PUT /projects/:id/ | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | | `container_registry_access_level` | string | no | The desired visibility of the Container Registry. One of `enabled` (default), `private`, or `disabled`. | Descriptions of the possible values for `container_registry_access_level`: @@ -83,7 +83,7 @@ Example response: ## Container Registry pagination By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). ## List registry repositories @@ -97,7 +97,7 @@ GET /projects/:id/registry/repositories | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | | `tags` | boolean | no | If the parameter is included as true, each repository includes an array of `"tags"` in the response. | | `tags_count` | boolean | no | If the parameter is included as true, each repository includes `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | @@ -142,7 +142,7 @@ GET /groups/:id/registry/repositories | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -231,7 +231,7 @@ DELETE /projects/:id/registry/repositories/:repository_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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | ```shell @@ -251,7 +251,7 @@ GET /projects/:id/registry/repositories/:repository_id/tags | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | ```shell @@ -286,7 +286,7 @@ GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) accessible by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `tag_name` | string | yes | The name of tag. | @@ -320,7 +320,7 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `tag_name` | string | yes | The name of tag. | @@ -345,7 +345,7 @@ DELETE /projects/:id/registry/repositories/:repository_id/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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `repository_id` | integer | yes | The ID of registry repository. | | `name_regex` | string | no | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to delete. To delete all tags specify `.*`. **Note:** `name_regex` is deprecated in favor of `name_regex_delete`. This field is validated. | | `name_regex_delete` | string | yes | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to delete. To delete all tags specify `.*`. This field is validated. | @@ -375,7 +375,7 @@ WARNING: The number of tags deleted by this API is limited on GitLab.com because of the scale of the Container Registry there. 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. +only some of them are 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. Examples: diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index dce928046bc..b99d9e2d91d 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -33,7 +33,7 @@ GET /projects/:id/dependencies?package_manager=yarn,bundler | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `package_manager` | string array | no | Returns dependencies belonging to specified package manager. Valid values: `bundler`, `composer`, `conan`, `go`, `gradle`, `maven`, `npm`, `nuget`, `pip`, `pipenv`, `yarn`, `sbt`, or `setuptools`. | ```shell @@ -85,4 +85,4 @@ Example response: By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index b7eade83bb8..53b4b0db0d7 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -20,7 +20,7 @@ DELETE /groups/:id/dependency_proxy/cache | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | Example request: diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index bc5852db457..684df9fdfdc 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -86,7 +86,7 @@ GET /projects/:id/deploy_keys | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys" @@ -188,7 +188,7 @@ Parameters: | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```shell @@ -222,7 +222,7 @@ POST /projects/:id/deploy_keys | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | New deploy key's title | | `key` | string | yes | New deploy key | | `can_push` | boolean | no | Can deploy key push to the project's repository | @@ -255,7 +255,7 @@ PUT /projects/:id/deploy_keys/:key_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | no | New deploy key's title | | `can_push` | boolean | no | Can deploy key push to the project's repository | @@ -286,7 +286,7 @@ DELETE /projects/:id/deploy_keys/:key_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```shell @@ -303,7 +303,7 @@ POST /projects/:id/deploy_keys/:key_id/enable | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```shell diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index dff3ef05bb0..2cfb58c25e1 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -66,7 +66,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:-----------------------|:------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `active` | boolean | **{dotted-circle}** No | Limit by active status. | Example request: @@ -108,7 +108,7 @@ Parameters: | 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 | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | ID of the deploy token | Example request: @@ -148,7 +148,7 @@ Parameters: | 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 | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | **{check-circle}** Yes | New deploy token's name | | `expires_at` | datetime | **{dotted-circle}** No | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `username` | string | **{dotted-circle}** No | Username for deploy token. Default is `gitlab+deploy-token-{n}` | @@ -193,7 +193,7 @@ Parameters: | 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 | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | ID of the deploy token | Example request: @@ -222,7 +222,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:-----------------------|:------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `active` | boolean | **{dotted-circle}** No | Limit by active status. | Example request: @@ -264,7 +264,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------- | -------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | ID of the deploy token | Example request: @@ -304,7 +304,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | ---- | --------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | **{check-circle}** Yes | New deploy token's name | | `expires_at` | datetime | **{dotted-circle}** No | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `username` | string | **{dotted-circle}** No | Username for deploy token. Default is `gitlab+deploy-token-{n}` | @@ -349,7 +349,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------- | -------------- | ---------------------- | ----------- | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `token_id` | integer | **{check-circle}** Yes | ID of the deploy token | Example request: diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 688806e9b22..c6537493eab 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -17,7 +17,7 @@ GET /projects/:id/deployments | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return deployments ordered by either one of `id`, `iid`, `created_at`, `updated_at`, `finished_at` or `ref` fields. Default is `id`. | | `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc`. | | `updated_after` | datetime | no | Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -195,7 +195,7 @@ GET /projects/:id/deployments/:deployment_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `deployment_id` | integer | yes | The ID of the deployment | ```shell @@ -354,7 +354,7 @@ POST /projects/:id/deployments | 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.| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user.| | `environment` | string | yes | The [name of the environment](../ci/environments/index.md) to create the deployment for. | | `sha` | string | yes | The SHA of the commit that is deployed. | | `ref` | string | yes | The name of the branch or tag that is deployed. | @@ -412,7 +412,7 @@ PUT /projects/:id/deployments/:deployment_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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `deployment_id` | integer | yes | The ID of the deployment to update. | | `status` | string | yes | The new status of the deployment. One of `running`, `success`, `failed`, or `canceled`. | @@ -482,7 +482,7 @@ DELETE /projects/:id/deployments/:deployment_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `deployment_id` | integer | yes | The ID of the deployment | ```shell @@ -541,7 +541,7 @@ POST /projects/:id/deployments/:deployment_id/approval | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `deployment_id` | integer | yes | The ID of the deployment. | | `status` | string | yes | The status of the approval (either `approved` or `rejected`). | | `comment` | string | no | A comment to go with the approval | diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 67fca84e449..ccef57dab7f 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -24,7 +24,7 @@ Label notes are not part of this API, but recorded as separate events in By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## Issues @@ -38,7 +38,7 @@ GET /projects/:id/issues/:issue_iid/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | ```json @@ -137,7 +137,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -158,7 +158,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -183,7 +183,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -207,7 +207,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -230,7 +230,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `discussion_id` | integer | yes | The ID of a discussion | | `note_id` | integer | yes | The ID of a discussion note | @@ -252,7 +252,7 @@ GET /projects/:id/snippets/:snippet_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | ```json @@ -351,7 +351,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -373,7 +373,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `body` | string | yes | The content of a discussion | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -395,7 +395,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -419,7 +419,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -442,7 +442,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of an snippet | | `discussion_id` | integer | yes | The ID of a discussion | | `note_id` | integer | yes | The ID of a discussion note | @@ -464,7 +464,7 @@ GET /groups/:id/epics/:epic_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | ```json @@ -564,7 +564,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -586,7 +586,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -609,7 +609,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -633,7 +633,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -656,7 +656,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -678,7 +678,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | ```json @@ -842,7 +842,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a discussion item | @@ -866,7 +866,7 @@ Parameters for all comments: | Attribute | Type | Required | Description | | ---------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | | `commit_id` | string | no | SHA referencing commit to start this thread on | @@ -1008,7 +1008,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `resolved` | boolean | yes | Resolve/unresolve the discussion | @@ -1031,7 +1031,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1055,7 +1055,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1086,7 +1086,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `discussion_id` | integer | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1108,7 +1108,7 @@ GET /projects/:id/repository/commits/:commit_id/discussions | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | ```json @@ -1252,7 +1252,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `discussion_id` | string | yes | The ID of a discussion item | @@ -1274,7 +1274,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `body` | string | yes | The content of the thread | | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -1313,7 +1313,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `discussion_id` | string | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1337,7 +1337,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `discussion_id` | string | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | @@ -1367,7 +1367,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `commit_id` | string | yes | The SHA of a commit | | `discussion_id` | string | yes | The ID of a thread | | `note_id` | integer | yes | The ID of a thread note | diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 4374d1dde95..f0e90234ff4 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -23,10 +23,10 @@ GET /projects/:id/dora/metrics | Attribute | Type | Required | Description | |:---------------------|:-----------------|:---------|:------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) can be accessed by the authenticated user. | | `metric` | string | yes | One of `deployment_frequency`, `lead_time_for_changes`, `time_to_restore_service` or `change_failure_rate`. | | `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | -| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, please use `environment_tiers`. | +| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, use `environment_tiers`. | | `environment_tiers` | array of strings | no | The [tiers of the environments](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | | `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | | `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | @@ -64,10 +64,10 @@ GET /groups/:id/dora/metrics | Attribute | Type | Required | Description | |:--------------------|:-----------------|:---------|:------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) can be accessed by the authenticated user. | | `metric` | string | yes | One of `deployment_frequency`, `lead_time_for_changes`, `time_to_restore_service` or `change_failure_rate`. | | `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | -| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, please use `environment_tiers`. | +| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. Deprecated, use `environment_tiers`. | | `environment_tiers` | array of strings | no | The [tiers of the environments](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | | `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | | `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | diff --git a/doc/api/draft_notes.md b/doc/api/draft_notes.md new file mode 100644 index 00000000000..a168c41092c --- /dev/null +++ b/doc/api/draft_notes.md @@ -0,0 +1,131 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Draft Notes API **(FREE)** + +Draft notes are pending, unpublished comments on merge requests. They can be either start a discussion, or be associated with an existing discussion as a reply. They are viewable only by the author until they are published. + +## List all merge request draft notes + +Gets a list of all draft notes for a single merge request. + +```plaintext +GET /projects/:id/merge_requests/:merge_request_iid/draft_notes +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) +| `merge_request_iid` | integer | yes | The IID of a project merge request + +```json +[{ + id: 5, + author_id: 23, + merge_request_id: 11, + resolve_discussion: false, + discussion_id: nil, + note: "Example title", + commit_id: nil, + line_code: nil, + position: + { + base_sha: nil, + start_sha: nil, + head_sha: nil, + old_path: nil, + new_path: nil, + position_type: "text", + old_line: nil, + new_line: nil, + line_range: nil + } +}] +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes" +``` + +## Get a single draft note + +Returns a single draft note for a given merge request. + +```plaintext +GET /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `draft_note_id` | integer | yes | The ID of a draft note. +| `merge_request_iid` | integer | yes | The IID of a project merge request. + +```json +{ + id: 5, + author_id: 23, + merge_request_id: 11, + resolve_discussion: false, + discussion_id: nil, + note: "Example title", + commit_id: nil, + line_code: nil, + position: + { + base_sha: nil, + start_sha: nil, + head_sha: nil, + old_path: nil, + new_path: nil, + position_type: "text", + old_line: nil, + new_line: nil, + line_range: nil + } +} +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5" +``` + +## Delete a draft note + +Deletes an existing draft note for a given merge request. + +```plaintext +DELETE /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ----------- | --------------------- | +| `draft_note_id` | integer | yes | The ID of a draft note. +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `merge_request_iid` | integer | yes | The IID of a project merge request. + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5" +``` + +## Publish a draft note + +Publishes an existing draft note for a given merge request. + +```plaintext +PUT /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id/publish +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ----------- | --------------------- | +| `draft_note_id` | integer | yes | The ID of a draft note. +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). +| `merge_request_iid` | integer | yes | The IID of a project merge request. + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5/publish" +``` diff --git a/doc/api/environments.md b/doc/api/environments.md index 2b67c59ae35..bbf6c5fee99 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -15,12 +15,12 @@ Get all environments for a given project. GET /projects/:id/environments ``` -| 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 | -| `name` | string | no | Return the environment with this name. Mutually exclusive with `search` | -| `search` | string | no | Return list of environments matching the search criteria. Mutually exclusive with `name`. Must be at least 3 characters long. | -| `states` | string | no | List all environments that match a specific state. Accepted values: `available`, `stopping`, or `stopped`. If no state value given, returns all environments. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded](rest/index.md#namespaced-path-encoding) path of the project. | +| `name` | string | no | Return the environment with this name. Mutually exclusive with `search`. | +| `search` | string | no | Return list of environments matching the search criteria. Mutually exclusive with `name`. Must be at least 3 characters long. | +| `states` | string | no | List all environments that match a specific state. Accepted values: `available`, `stopping`, or `stopped`. If no state value given, returns all environments. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments?name=review%2Ffix-foo" @@ -133,10 +133,10 @@ Example response: GET /projects/:id/environments/:environment_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 | -| `environment_id` | integer | yes | The ID of the environment | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|--------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `environment_id` | integer | yes | The ID of the environment. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" @@ -252,12 +252,12 @@ It returns `201` if the environment was successfully created, `400` for wrong pa POST /projects/:id/environments ``` -| 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 | -| `name` | string | yes | The name of the environment | -| `external_url` | string | no | Place to link to for this environment | -| `tier` | string | no | The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other` | +| Attribute | Type | Required | Description | +|----------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `name` | string | yes | The name of the environment. | +| `external_url` | string | no | Place to link to for this environment. | +| `tier` | string | no | The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other`. | ```shell curl --data "name=deploy&external_url=https://deploy.gitlab.example.com" \ @@ -289,13 +289,13 @@ It returns `200` if the environment was successfully updated. In case of an erro PUT /projects/:id/environments/:environments_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 | -| `environment_id` | integer | yes | The ID of the environment | -| `name` | string | no | [Deprecated and will be removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) | -| `external_url` | string | no | The new `external_url` | -| `tier` | string | no | The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other` | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `environment_id` | integer | yes | The ID of the environment. | +| `name` | string | no | [Deprecated and will be removed in GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338897). | +| `external_url` | string | no | The new `external_url`. | +| `tier` | string | no | The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other`. | ```shell curl --request PUT --data "name=staging&external_url=https://staging.gitlab.example.com" \ @@ -325,10 +325,10 @@ It returns `204` if the environment was successfully deleted, and `404` if the e DELETE /projects/:id/environments/:environment_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 | -| `environment_id` | integer | yes | The ID of the environment | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|--------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `environment_id` | integer | yes | The ID of the environment. | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" @@ -348,12 +348,12 @@ By default, it only deletes environments 30 days or older. You can change this d DELETE /projects/:id/environments/review_apps ``` -| 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. | -| `before` | datetime | no | The date before which environments can be deleted. Defaults to 30 days ago. Expected in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | -| `limit` | integer | no | Maximum number of environments to delete. Defaults to 100. | -| `dry_run` | boolean | no | Defaults to `true` for safety reasons. It performs a dry run where no actual deletion will be performed. Set to `false` to actually delete the environment. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `before` | datetime | no | The date before which environments can be deleted. Defaults to 30 days ago. Expected in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | +| `limit` | integer | no | Maximum number of environments to delete. Defaults to 100. | +| `dry_run` | boolean | no | Defaults to `true` for safety reasons. It performs a dry run where no actual deletion is performed. Set to `false` to actually delete the environment. | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/review_apps" @@ -389,11 +389,11 @@ It returns `200` if the environment was successfully stopped, and `404` if the e POST /projects/:id/environments/:environment_id/stop ``` -| 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 | -| `environment_id` | integer | yes | The ID of the environment | -| `force` | boolean | no | Force environment to stop without executing `on_stop` actions | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|--------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | +| `environment_id` | integer | yes | The ID of the environment. | +| `force` | boolean | no | Force environment to stop without executing `on_stop` actions. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1/stop" @@ -423,7 +423,7 @@ POST /projects/:id/environments/stop_stale | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project. | | `before` | date | yes | Stop environments that have been modified or deployed to before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Valid inputs are between 10 years ago and 1 week ago | ```shell diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index 28c74a0a418..9d3a32beb07 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -16,7 +16,7 @@ If the Epics feature is not available, a `403` status code is returned. ## Epic Issues pagination -API results [are paginated](index.md#pagination). Requests that return +API results [are paginated](rest/index.md#pagination). Requests that return multiple issues default to returning 20 results at a time. ## List issues for an epic @@ -29,7 +29,7 @@ GET /groups/:id/epics/:epic_iid/issues | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -124,7 +124,7 @@ POST /groups/:id/epics/:epic_iid/issues/:issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `issue_id` | integer/string | yes | The ID of the issue. | @@ -230,7 +230,7 @@ DELETE /groups/:id/epics/:epic_iid/issues/:epic_issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | -----------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `epic_issue_id` | integer/string | yes | The ID of the issue - epic association. | @@ -336,7 +336,7 @@ PUT /groups/:id/epics/:epic_iid/issues/:epic_issue_id | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | -----------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | | `epic_issue_id` | integer/string | yes | The ID of the issue - epic association. | | `move_before_id` | integer/string | no | The ID of the issue - epic association that should be placed before the link in the question. | diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index 91560512ffc..f46fa8e0989 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -28,7 +28,7 @@ GET /groups/:id/epics/:epic_iid/epics | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the epic. | ```shell @@ -82,7 +82,7 @@ POST /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | @@ -135,7 +135,7 @@ POST /groups/:id/epics/:epic_iid/epics | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of the (future parent) epic. | | `title` | string | yes | The title of a newly created epic. | | `confidential` | boolean | no | Whether the epic should be confidential. Parameter is ignored if `confidential_epics` feature flag is disabled. Defaults to the confidentiality state of the parent epic. | @@ -169,7 +169,7 @@ PUT /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | ---------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | | `move_before_id` | integer | no | The global ID of a sibling epic that should be placed before the child epic. | @@ -226,7 +226,7 @@ DELETE /groups/:id/epics/:epic_iid/epics/:child_epic_id | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `epic_iid` | integer | yes | The internal ID of the epic. | | `child_epic_id` | integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. | diff --git a/doc/api/epics.md b/doc/api/epics.md index 85a127696f6..3d8e19a6e99 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -37,7 +37,7 @@ fields `start_date_is_fixed` and `due_date_is_fixed`, and four date fields `star By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). WARNING: In [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) and later, @@ -63,7 +63,7 @@ GET /groups/:id/epics?state=opened | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `author_id` | integer | no | Return epics created by the given user `id` | | `author_username` | string | no | Return epics created by the user with the given `username`. Available in [GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/348257) and later | | `labels` | string | no | Return epics matching a comma-separated list of labels names. Label names from the epic group or a parent group can be used | @@ -203,7 +203,7 @@ GET /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -282,7 +282,7 @@ POST /groups/:id/epics | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of the epic | | `labels` | string | no | The comma-separated list of labels | | `description` | string | no | The description of the epic. Limited to 1,048,576 characters. | @@ -371,7 +371,7 @@ PUT /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic | | `add_labels` | string | no | Comma-separated label names to add to an issue. | | `confidential` | boolean | no | Whether the epic should be confidential | @@ -451,7 +451,7 @@ DELETE /groups/:id/epics/:epic_iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic. | ```shell @@ -470,7 +470,7 @@ POST /groups/:id/epics/:epic_iid/todo | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer | yes | The internal ID of a group's epic | ```shell diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 4d6d5e50245..36bcbb30d4b 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -21,7 +21,7 @@ GET /projects/:id/error_tracking/settings | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/error_tracking/settings" @@ -50,7 +50,7 @@ PATCH /projects/:id/error_tracking/settings | Attribute | Type | Required | Description | | ------------ | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `active` | boolean | yes | Pass `true` to enable the already configured error tracking settings or `false` to disable it. | | `integrated` | boolean | no | Pass `true` to enable the integrated error tracking backend. [Available in](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68260) GitLab 14.2 and later. | @@ -85,7 +85,7 @@ GET /projects/:id/error_tracking/client_keys | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/error_tracking/client_keys" @@ -120,7 +120,7 @@ POST /projects/:id/error_tracking/client_keys | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ @@ -148,7 +148,7 @@ DELETE /projects/:id/error_tracking/client_keys/:key_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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `key_id` | integer | yes | The ID of the client key. | ```shell diff --git a/doc/api/events.md b/doc/api/events.md index 320c7a531e8..493f8f43bfd 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -264,7 +264,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `action` | string | no | Include only events of a particular [action type](#actions) | | `target_type` | string | no | Include only events of a particular [target type](#target-types) | | `before` | date | no | Include only events created before a particular date. [View how to format dates](#date-formatting). | diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index ca4ca755d08..27e2e925506 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -15,7 +15,7 @@ Users with Developer or higher [permissions](../user/permissions.md) can access NOTE: `GET` requests return twenty results at a time because the API results -are [paginated](index.md#pagination). You can change this value. +are [paginated](rest/index.md#pagination). You can change this value. ## List all feature flag user lists for a project @@ -27,7 +27,7 @@ GET /projects/:id/feature_flags_user_lists | Attribute | Type | Required | Description | | --------- | -------------- | -------- | -------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `search` | string | no | Return user lists matching the search criteria. | ```shell @@ -69,7 +69,7 @@ POST /projects/:id/feature_flags_user_lists | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the list. | | `user_xids` | string | yes | A comma-separated list of external user IDs. | @@ -109,7 +109,7 @@ GET /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list. | ```shell @@ -140,7 +140,7 @@ PUT /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list. | | `name` | string | no | The name of the list. | | `user_xids` | string | no | A comma-separated list of external user IDs. | @@ -181,7 +181,7 @@ DELETE /projects/:id/feature_flags_user_lists/:iid | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list | ```shell diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index 4b385a35405..cd9907c8032 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -16,7 +16,7 @@ Users with Developer or higher [permissions](../user/permissions.md) can access ## Feature flags pagination By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). ## List feature flags for a project @@ -28,7 +28,7 @@ GET /projects/:id/feature_flags | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `scope` | string | no | The condition of feature flags, one of: `enabled`, `disabled`. | ```shell @@ -98,7 +98,7 @@ GET /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The name of the feature flag. | ```shell @@ -142,13 +142,13 @@ POST /projects/:id/feature_flags | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the feature flag. | | `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit to create a Legacy feature flag. | | `description` | string | no | The description of the feature flag. | | `active` | boolean | no | The active state of the flag. Defaults to true. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | | `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). | -| `strategies:name` | JSON | no | The strategy name. Can be `default`, `gradualRolloutUserId`, `userWithId`, or `gitlabUserList`. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/36380) and later, can be [`flexibleRollout`](https://docs.getunleash.io/user_guide/activation_strategy#gradual-rollout). | +| `strategies:name` | JSON | no | The strategy name. Can be `default`, `gradualRolloutUserId`, `userWithId`, or `gitlabUserList`. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/36380) and later, can be [`flexibleRollout`](https://docs.getunleash.io/user_guide/activation_strategy/#gradual-rollout). | | `strategies:parameters` | JSON | no | The strategy parameters. | | `strategies:scopes` | JSON | no | The scopes for the strategy. | | `strategies:scopes:environment_scope` | string | no | The environment scope of the scope. | @@ -203,7 +203,7 @@ PUT /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The current name of the feature flag. | | `description` | string | no | The description of the feature flag. | | `active` | boolean | no | The active state of the flag. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | @@ -280,7 +280,7 @@ DELETE /projects/:id/feature_flags/:feature_flag_name | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `feature_flag_name` | string | yes | The name of the feature flag. | ```shell diff --git a/doc/api/features.md b/doc/api/features.md index 819405bea77..c3db1e53f68 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -116,7 +116,7 @@ POST /features/:name | `name` | string | yes | Name of the feature to create or update | | `value` | integer/string | yes | `true` or `false` to enable/disable, or an integer for percentage of time | | `key` | string | no | `percentage_of_actors` or `percentage_of_time` (default) | -| `feature_group` | string | no | A Feature group name | +| `feature_group` | string | no | A [Feature group](../development/feature_flags/index.md#feature-groups) name | | `user` | string | no | A GitLab username or comma-separated multiple usernames | | `group` | string | no | A GitLab group's path, for example `gitlab-org`, or comma-separated multiple group paths | | `namespace` | string | no | A GitLab group or user namespace's path, for example `john-doe`, or comma-separated multiple namespace paths. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353117) in GitLab 15.0. | diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index 9d2989229ae..ce7377e1e35 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -13,8 +13,9 @@ You can use the Freeze Periods API to manipulate GitLab [Freeze Period](../user/ ## Permissions and security -Only users with Maintainer [permissions](../user/permissions.md) can -interact with the Freeze Period API endpoints. +Users with Reporter [permissions](../user/permissions.md) or greater can read +Freeze Period API endpoints. Only users with the Maintainer role can modify +Freeze Periods. ## List freeze periods @@ -26,7 +27,7 @@ GET /projects/:id/freeze_periods | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | Example request: @@ -59,7 +60,7 @@ GET /projects/:id/freeze_periods/:freeze_period_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `freeze_period_id` | integer | yes | The ID of the freeze period. | Example request: @@ -91,7 +92,7 @@ POST /projects/:id/freeze_periods | Attribute | Type | Required | Description | | -------------------| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `freeze_start` | string | yes | Start of the freeze period in [cron](https://crontab.guru/) format. | | `freeze_end` | string | yes | End of the freeze period in [cron](https://crontab.guru/) format. | | `cron_timezone` | string | no | The time zone for the cron fields, defaults to UTC if not provided. | @@ -127,7 +128,7 @@ PUT /projects/:id/freeze_periods/:freeze_period_id | Attribute | Type | Required | Description | | ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `freeze_period_id` | integer | yes | The ID of the freeze period. | | `freeze_start` | string | no | Start of the freeze period in [cron](https://crontab.guru/) format. | | `freeze_end` | string | no | End of the freeze period in [cron](https://crontab.guru/) format. | @@ -164,7 +165,7 @@ DELETE /projects/:id/freeze_periods/:freeze_period_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `freeze_period_id` | integer | yes | The ID of the freeze period. | Example request: diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 5f9323016c0..0b0dd543503 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -953,7 +953,7 @@ GET /geo_nodes/current/failures | `type` | string | no | Type of failed objects (`repository`/`wiki`) | | `failure_type` | string | no | Type of failures (`sync`/`checksum_mismatch`/`verification`) | -This endpoint uses [Pagination](index.md#pagination). +This endpoint uses [Pagination](rest/index.md#pagination). ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/geo_nodes/current/failures" diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md index e2e8bce4290..9c794a080c9 100644 --- a/doc/api/graphql/custom_emoji.md +++ b/doc/api/graphql/custom_emoji.md @@ -20,7 +20,7 @@ Parameters: | Attribute | Type | Required | Description | | :----------- | :------------- | :--------------------- | :------------------------------------------------------------------------ | -| `group_path` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) | +| `group_path` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) | | `name` | string | **{check-circle}** Yes | Name of the custom emoji. | | `file` | string | **{check-circle}** Yes | URL of the custom emoji image. | diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 9f423d68d3b..57d7880988b 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -173,7 +173,7 @@ More about queries: Authorization uses the same engine as the GitLab application (and GitLab.com). If you've signed in to GitLab and use GraphiQL, all queries are performed as you, the authenticated user. For more information, read the -[GitLab API documentation](../index.md#authentication). +[GitLab API documentation](../rest/index.md#authentication). ### Mutations diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 320e7cbcfc1..4286d459e54 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -75,7 +75,7 @@ frequently [verify your API calls against the future breaking-change schema](#ve Fields behind a feature flag and disabled by default do not follow the deprecation and removal process, and can be removed at any time without notice. -Learn more about [breaking changes](../../development/deprecation_guidelines/index.md). +For more information, see [Deprecating GitLab features](../../development/deprecation_guidelines/index.md). WARNING: GitLab makes all attempts to follow the [deprecation and removal process](#deprecation-and-removal-process). @@ -172,7 +172,7 @@ Limit | Default Max page size | 100 records (nodes) per page. Applies to most connections in the API. Particular connections may have different max page size limits that are higher or lower. [Max query complexity](#max-query-complexity) | `200` for unauthenticated requests and `250` for authenticated requests. Request timeout | 30 seconds. -Max query size | 10,000 characters per query. If this limit is reached, use [variables](https://graphql.org/learn/queries/#variables) and [fragments](https://graphql.org/learn/queries/#fragments) to reduce the query size. Remove white spaces as last resort. +Max query size | 10,000 characters per query or mutation. If this limit is reached, use [variables](https://graphql.org/learn/queries/#variables) and [fragments](https://graphql.org/learn/queries/#fragments) to reduce the query or mutation size. Remove white spaces as last resort. ### Max query complexity diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 4bd7702474f..7dc5b557d33 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -97,6 +97,12 @@ This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): `before: String`, `after: String`, `first: Int`, `last: Int`. +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querycivariablessort"></a>`sort` | [`CiVariableSort`](#civariablesort) | Sort order of results. | + ### `Query.containerRepository` Find a container repository. @@ -196,6 +202,22 @@ Returns [`Group`](#group). | ---- | ---- | ----------- | | <a id="querygroupfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the project, group, or namespace. For example, `gitlab-org/gitlab-foss`. | +### `Query.groups` + +Find groups. + +Returns [`GroupConnection`](#groupconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querygroupssearch"></a>`search` | [`String`](#string) | Search query for group name or group full path. | + ### `Query.instanceSecurityDashboard` Fields related to Instance Security Dashboard. @@ -216,7 +238,7 @@ Returns [`Issue`](#issue). ### `Query.issues` -Find issues visible to the current user. At least one filter must be provided. Returns `null` if the `root_level_issues_query` feature flag is disabled. +Find issues visible to the current user. At least one filter must be provided. WARNING: **Introduced** in 15.6. @@ -345,6 +367,22 @@ Returns [`Namespace`](#namespace). | ---- | ---- | ----------- | | <a id="querynamespacefullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the project, group, or namespace. For example, `gitlab-org/gitlab-foss`. | +### `Query.note` + +Find a note. + +WARNING: +**Introduced** in 15.9. +This feature is in Alpha. It can be changed or removed at any time. + +Returns [`Note`](#note). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querynoteid"></a>`id` | [`NoteID!`](#noteid) | Global ID of the note. | + ### `Query.package` Find a package. This field can only be resolved for one query in any single request. Returns `null` if a package has no `default` status. @@ -389,6 +427,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="queryprojectssearchnamespaces"></a>`searchNamespaces` | [`Boolean`](#boolean) | Include namespace in project search. | | <a id="queryprojectssort"></a>`sort` | [`String`](#string) | Sort order of results. Format: `<field_name>_<sort_direction>`, for example: `id_desc` or `name_asc`. | | <a id="queryprojectstopics"></a>`topics` | [`[String!]`](#string) | Filter projects by topics. | +| <a id="queryprojectswithissuesenabled"></a>`withIssuesEnabled` | [`Boolean`](#boolean) | Return only projects with issues enabled. | +| <a id="queryprojectswithmergerequestsenabled"></a>`withMergeRequestsEnabled` | [`Boolean`](#boolean) | Return only projects with merge requests enabled. | ### `Query.queryComplexity` @@ -412,6 +452,10 @@ Returns [`CiRunner`](#cirunner). Supported runner platforms. +WARNING: +**Deprecated** in 15.9. +No longer used, use gitlab-runner documentation to learn about supported platforms. + Returns [`RunnerPlatformConnection`](#runnerplatformconnection). This field returns a [connection](#connections). It accepts the @@ -422,6 +466,10 @@ four standard [pagination arguments](#connection-pagination-arguments): Runner setup instructions. +WARNING: +**Deprecated** in 15.9. +No longer used, use gitlab-runner documentation to learn about runner registration commands. + Returns [`RunnerSetup`](#runnersetup). #### Arguments @@ -487,6 +535,23 @@ This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): `before: String`, `after: String`, `first: Int`, `last: Int`. +### `Query.syntheticNote` + +Find a synthetic note. + +WARNING: +**Introduced** in 15.9. +This feature is in Alpha. It can be changed or removed at any time. + +Returns [`Note`](#note). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querysyntheticnotenoteableid"></a>`noteableId` | [`NoteableID!`](#noteableid) | Global ID of the resource to search synthetic note on. | +| <a id="querysyntheticnotesha"></a>`sha` | [`String!`](#string) | Global ID of the note. | + ### `Query.timelogs` Find timelogs visible to the current user. @@ -693,7 +758,6 @@ Input type: `AchievementsCreateInput` | <a id="mutationachievementscreatedescription"></a>`description` | [`String`](#string) | Description of or notes for the achievement. | | <a id="mutationachievementscreatename"></a>`name` | [`String!`](#string) | Name for the achievement. | | <a id="mutationachievementscreatenamespaceid"></a>`namespaceId` | [`NamespaceID!`](#namespaceid) | Namespace for the achievement. | -| <a id="mutationachievementscreaterevokeable"></a>`revokeable` | [`Boolean!`](#boolean) | Revokeability for the achievement. | #### Fields @@ -835,6 +899,28 @@ Input type: `ApiFuzzingCiConfigurationCreateInput` | <a id="mutationapifuzzingciconfigurationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationapifuzzingciconfigurationcreategitlabciyamleditpath"></a>`gitlabCiYamlEditPath` **{warning-solid}** | [`String`](#string) | **Deprecated:** The configuration snippet is now generated client-side. Deprecated in 14.6. | +### `Mutation.approveDeployment` + +Input type: `ApproveDeploymentInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationapprovedeploymentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationapprovedeploymentcomment"></a>`comment` | [`String`](#string) | Comment to go with the approval. | +| <a id="mutationapprovedeploymentid"></a>`id` | [`DeploymentID!`](#deploymentid) | ID of the deployment. | +| <a id="mutationapprovedeploymentrepresentedas"></a>`representedAs` | [`String`](#string) | Name of the User/Group/Role to use for the approval, when the user belongs to multiple approval rules. | +| <a id="mutationapprovedeploymentstatus"></a>`status` | [`DeploymentsApprovalStatus!`](#deploymentsapprovalstatus) | Status of the approval (either `APPROVED` or `REJECTED`). | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationapprovedeploymentclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationapprovedeploymentdeploymentapproval"></a>`deploymentApproval` | [`DeploymentApproval!`](#deploymentapproval) | DeploymentApproval after mutation. | +| <a id="mutationapprovedeploymenterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.artifactDestroy` Input type: `ArtifactDestroyInput` @@ -1148,6 +1234,7 @@ Input type: `CiCdSettingsUpdateInput` | <a id="mutationcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for the project. | | <a id="mutationcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | +| <a id="mutationcicdsettingsupdateoptinjwt"></a>`optInJwt` | [`Boolean`](#boolean) | When disabled, the JSON Web Token is always available in all jobs in the pipeline. | #### Fields @@ -1166,6 +1253,7 @@ Input type: `CiJobTokenScopeAddProjectInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcijobtokenscopeaddprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcijobtokenscopeaddprojectdirection"></a>`direction` | [`CiJobTokenScopeDirection`](#cijobtokenscopedirection) | Direction of access, which defaults to outbound. | | <a id="mutationcijobtokenscopeaddprojectprojectpath"></a>`projectPath` | [`ID!`](#id) | Project that the CI job token scope belongs to. | | <a id="mutationcijobtokenscopeaddprojecttargetprojectpath"></a>`targetProjectPath` | [`ID!`](#id) | Project to be added to the CI job token scope. | @@ -1173,7 +1261,7 @@ Input type: `CiJobTokenScopeAddProjectInput` | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationcijobtokenscopeaddprojectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | CI job token's scope of access. | +| <a id="mutationcijobtokenscopeaddprojectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | CI job token's access scope. | | <a id="mutationcijobtokenscopeaddprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcijobtokenscopeaddprojecterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | @@ -1186,6 +1274,7 @@ Input type: `CiJobTokenScopeRemoveProjectInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcijobtokenscoperemoveprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcijobtokenscoperemoveprojectdirection"></a>`direction` | [`CiJobTokenScopeDirection`](#cijobtokenscopedirection) | Direction of access, which defaults to outbound. | | <a id="mutationcijobtokenscoperemoveprojectprojectpath"></a>`projectPath` | [`ID!`](#id) | Project that the CI job token scope belongs to. | | <a id="mutationcijobtokenscoperemoveprojecttargetprojectpath"></a>`targetProjectPath` | [`ID!`](#id) | Project to be removed from the CI job token scope. | @@ -1960,6 +2049,7 @@ Input type: `DastProfileCreateInput` | <a id="mutationdastprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the profile belongs to. | | <a id="mutationdastprofilecreatename"></a>`name` | [`String!`](#string) | Name of the profile. | | <a id="mutationdastprofilecreaterunaftercreate"></a>`runAfterCreate` | [`Boolean`](#boolean) | Run scan using profile after creation. Defaults to false. | +| <a id="mutationdastprofilecreatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the profile. | #### Fields @@ -2026,6 +2116,7 @@ Input type: `DastProfileUpdateInput` | <a id="mutationdastprofileupdateid"></a>`id` | [`DastProfileID!`](#dastprofileid) | ID of the profile to be deleted. | | <a id="mutationdastprofileupdatename"></a>`name` | [`String`](#string) | Name of the profile. | | <a id="mutationdastprofileupdaterunafterupdate"></a>`runAfterUpdate` | [`Boolean`](#boolean) | Run scan using profile after update. Defaults to false. | +| <a id="mutationdastprofileupdatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the profile. | #### Fields @@ -2050,7 +2141,7 @@ Input type: `DastScannerProfileCreateInput` | <a id="mutationdastscannerprofilecreatescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="mutationdastscannerprofilecreateshowdebugmessages"></a>`showDebugMessages` | [`Boolean`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="mutationdastscannerprofilecreatespidertimeout"></a>`spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | -| <a id="mutationdastscannerprofilecreatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the scanner profile. | +| <a id="mutationdastscannerprofilecreatetaglist"></a>`tagList` **{warning-solid}** | [`[String!]`](#string) | **Deprecated:** Moved to DastProfile. Deprecated in 15.8. | | <a id="mutationdastscannerprofilecreatetargettimeout"></a>`targetTimeout` | [`Int`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | <a id="mutationdastscannerprofilecreateuseajaxspider"></a>`useAjaxSpider` | [`Boolean`](#boolean) | Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider. | @@ -2097,7 +2188,7 @@ Input type: `DastScannerProfileUpdateInput` | <a id="mutationdastscannerprofileupdatescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="mutationdastscannerprofileupdateshowdebugmessages"></a>`showDebugMessages` | [`Boolean`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="mutationdastscannerprofileupdatespidertimeout"></a>`spiderTimeout` | [`Int!`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | -| <a id="mutationdastscannerprofileupdatetaglist"></a>`tagList` | [`[String!]`](#string) | Indicates the runner tags associated with the scanner profile. | +| <a id="mutationdastscannerprofileupdatetaglist"></a>`tagList` **{warning-solid}** | [`[String!]`](#string) | **Deprecated:** Moved to DastProfile. Deprecated in 15.8. | | <a id="mutationdastscannerprofileupdatetargettimeout"></a>`targetTimeout` | [`Int!`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | <a id="mutationdastscannerprofileupdateuseajaxspider"></a>`useAjaxSpider` | [`Boolean`](#boolean) | Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider. | @@ -2817,6 +2908,7 @@ Input type: `EpicMoveListInput` | <a id="mutationepicmovelistfromlistid"></a>`fromListId` | [`BoardsEpicListID`](#boardsepiclistid) | ID of the board list that the epic will be moved from. Required if moving between lists. | | <a id="mutationepicmovelistmoveafterid"></a>`moveAfterId` | [`EpicID`](#epicid) | ID of epic that should be placed after the current epic. | | <a id="mutationepicmovelistmovebeforeid"></a>`moveBeforeId` | [`EpicID`](#epicid) | ID of epic that should be placed before the current epic. | +| <a id="mutationepicmovelistpositioninlist"></a>`positionInList` | [`Int`](#int) | Position of epics within the board list. Positions start at 0. Use -1 to move to the end of the list. | | <a id="mutationepicmovelisttolistid"></a>`toListId` | [`BoardsEpicListID!`](#boardsepiclistid) | ID of the list the epic will be in after mutation. | #### Fields @@ -3543,6 +3635,35 @@ Input type: `IssueUnlinkAlertInput` | <a id="mutationissueunlinkalerterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationissueunlinkalertissue"></a>`issue` | [`Issue`](#issue) | Issue after mutation. | +### `Mutation.issuesBulkUpdate` + +Allows updating several properties for a set of issues. Does nothing if the `bulk_update_issues_mutation` feature flag is disabled. + +WARNING: +**Introduced** in 15.9. +This feature is in Alpha. It can be changed or removed at any time. + +Input type: `IssuesBulkUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuesbulkupdateassigneeids"></a>`assigneeIds` | [`[UserID!]`](#userid) | Global ID array of the users that will be assigned to the given issues. Existing assignees will be replaced with the ones on this list. | +| <a id="mutationissuesbulkupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuesbulkupdateids"></a>`ids` | [`[IssueID!]!`](#issueid) | Global ID array of the issues that will be updated. IDs that the user can't update will be ignored. A max of 100 can be provided. | +| <a id="mutationissuesbulkupdateiterationid"></a>`iterationId` | [`IterationID`](#iterationid) | Global ID of the iteration that will be assigned to the issues. | +| <a id="mutationissuesbulkupdatemilestoneid"></a>`milestoneId` | [`MilestoneID`](#milestoneid) | Global ID of the milestone that will be assigned to the issues. | +| <a id="mutationissuesbulkupdateparentid"></a>`parentId` | [`IssueParentID!`](#issueparentid) | Global ID of the parent that the bulk update will be scoped to . Example `IssueParentID` are `"gid://gitlab/Project/1"` and `"gid://gitlab/Group/1"`. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuesbulkupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuesbulkupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationissuesbulkupdateupdatedissuecount"></a>`updatedIssueCount` | [`Int`](#int) | Number of issues that were successfully updated. | + ### `Mutation.iterationCadenceCreate` Input type: `IterationCadenceCreateInput` @@ -4083,6 +4204,7 @@ Input type: `MergeRequestUpdateInput` | <a id="mutationmergerequestupdateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the merge request to mutate is in. | | <a id="mutationmergerequestupdatestate"></a>`state` | [`MergeRequestNewState`](#mergerequestnewstate) | Action to perform to change the state. | | <a id="mutationmergerequestupdatetargetbranch"></a>`targetBranch` | [`String`](#string) | Target branch of the merge request. | +| <a id="mutationmergerequestupdatetimeestimate"></a>`timeEstimate` | [`String`](#string) | Estimated time to complete the merge request, or `0` to remove the current estimate. | | <a id="mutationmergerequestupdatetitle"></a>`title` | [`String`](#string) | Title of the merge request. | #### Fields @@ -4443,6 +4565,31 @@ Input type: `PipelineScheduleTakeOwnershipInput` | <a id="mutationpipelinescheduletakeownershiperrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationpipelinescheduletakeownershippipelineschedule"></a>`pipelineSchedule` | [`PipelineSchedule`](#pipelineschedule) | Updated pipeline schedule ownership. | +### `Mutation.pipelineScheduleUpdate` + +Input type: `PipelineScheduleUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinescheduleupdateactive"></a>`active` | [`Boolean`](#boolean) | Indicates if the pipeline schedule should be active or not. | +| <a id="mutationpipelinescheduleupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinescheduleupdatecron"></a>`cron` | [`String`](#string) | Cron expression of the pipeline schedule. | +| <a id="mutationpipelinescheduleupdatecrontimezone"></a>`cronTimezone` | [`String`](#string) | Cron time zone supported by ActiveSupport::TimeZone. For example: "Pacific Time (US & Canada)" (default: "UTC"). | +| <a id="mutationpipelinescheduleupdatedescription"></a>`description` | [`String`](#string) | Description of the pipeline schedule. | +| <a id="mutationpipelinescheduleupdateid"></a>`id` | [`CiPipelineScheduleID!`](#cipipelinescheduleid) | ID of the pipeline schedule to mutate. | +| <a id="mutationpipelinescheduleupdateref"></a>`ref` | [`String`](#string) | Ref of the pipeline schedule. | +| <a id="mutationpipelinescheduleupdatevariables"></a>`variables` | [`[PipelineScheduleVariableInput!]`](#pipelineschedulevariableinput) | Variables for the pipeline schedule. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinescheduleupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinescheduleupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationpipelinescheduleupdatepipelineschedule"></a>`pipelineSchedule` | [`PipelineSchedule`](#pipelineschedule) | Updated pipeline schedule. | + ### `Mutation.projectCiCdSettingsUpdate` Input type: `ProjectCiCdSettingsUpdateInput` @@ -4458,6 +4605,7 @@ Input type: `ProjectCiCdSettingsUpdateInput` | <a id="mutationprojectcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for the project. | | <a id="mutationprojectcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationprojectcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | +| <a id="mutationprojectcicdsettingsupdateoptinjwt"></a>`optInJwt` | [`Boolean`](#boolean) | When disabled, the JSON Web Token is always available in all jobs in the pipeline. | #### Fields @@ -4984,6 +5132,25 @@ Input type: `SecurityFindingDismissInput` | <a id="mutationsecurityfindingdismisserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationsecurityfindingdismissuuid"></a>`uuid` | [`String`](#string) | UUID of dismissed finding. | +### `Mutation.securityFindingRevertToDetected` + +Input type: `SecurityFindingRevertToDetectedInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsecurityfindingreverttodetectedclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecurityfindingreverttodetecteduuid"></a>`uuid` | [`String!`](#string) | UUID of the finding to be dismissed. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsecurityfindingreverttodetectedclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecurityfindingreverttodetectederrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationsecurityfindingreverttodetectedsecurityfinding"></a>`securityFinding` | [`PipelineSecurityReportFinding`](#pipelinesecurityreportfinding) | Finding reverted to detected. | + ### `Mutation.securityPolicyProjectAssign` Assigns the specified project(`security_policy_project_id`) as security policy project for the given project(`full_path`). If the project already has a security policy project, this reassigns the project's security policy project with the given `security_policy_project_id`. @@ -5651,6 +5818,7 @@ Input type: `UpdateIssueInput` | <a id="mutationupdateissueprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | | <a id="mutationupdateissueremovelabelids"></a>`removeLabelIds` | [`[ID!]`](#id) | IDs of labels to be removed from the issue. | | <a id="mutationupdateissuestateevent"></a>`stateEvent` | [`IssueStateEvent`](#issuestateevent) | Close or reopen an issue. | +| <a id="mutationupdateissuetimeestimate"></a>`timeEstimate` | [`String`](#string) | Estimated time to complete the issue, or `0` to remove the current estimate. | | <a id="mutationupdateissuetitle"></a>`title` | [`String`](#string) | Title of the issue. | | <a id="mutationupdateissuetype"></a>`type` | [`IssueType`](#issuetype) | Type of the issue. | | <a id="mutationupdateissueweight"></a>`weight` | [`Int`](#int) | Weight of the issue. | @@ -7715,6 +7883,29 @@ The edge type for [`Discussion`](#discussion). | <a id="discussionedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="discussionedgenode"></a>`node` | [`Discussion`](#discussion) | The item at the end of the edge. | +#### `EgressNodeConnection` + +The connection type for [`EgressNode`](#egressnode). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="egressnodeconnectionedges"></a>`edges` | [`[EgressNodeEdge]`](#egressnodeedge) | A list of edges. | +| <a id="egressnodeconnectionnodes"></a>`nodes` | [`[EgressNode]`](#egressnode) | A list of nodes. | +| <a id="egressnodeconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `EgressNodeEdge` + +The edge type for [`EgressNode`](#egressnode). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="egressnodeedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="egressnodeedgenode"></a>`node` | [`EgressNode`](#egressnode) | The item at the end of the edge. | + #### `EmailConnection` The connection type for [`Email`](#email). @@ -9015,28 +9206,28 @@ The edge type for [`ProductAnalyticsDashboard`](#productanalyticsdashboard). | <a id="productanalyticsdashboardedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="productanalyticsdashboardedgenode"></a>`node` | [`ProductAnalyticsDashboard`](#productanalyticsdashboard) | The item at the end of the edge. | -#### `ProductAnalyticsDashboardWidgetConnection` +#### `ProductAnalyticsDashboardPanelConnection` -The connection type for [`ProductAnalyticsDashboardWidget`](#productanalyticsdashboardwidget). +The connection type for [`ProductAnalyticsDashboardPanel`](#productanalyticsdashboardpanel). ##### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="productanalyticsdashboardwidgetconnectionedges"></a>`edges` | [`[ProductAnalyticsDashboardWidgetEdge]`](#productanalyticsdashboardwidgetedge) | A list of edges. | -| <a id="productanalyticsdashboardwidgetconnectionnodes"></a>`nodes` | [`[ProductAnalyticsDashboardWidget]`](#productanalyticsdashboardwidget) | A list of nodes. | -| <a id="productanalyticsdashboardwidgetconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | +| <a id="productanalyticsdashboardpanelconnectionedges"></a>`edges` | [`[ProductAnalyticsDashboardPanelEdge]`](#productanalyticsdashboardpaneledge) | A list of edges. | +| <a id="productanalyticsdashboardpanelconnectionnodes"></a>`nodes` | [`[ProductAnalyticsDashboardPanel]`](#productanalyticsdashboardpanel) | A list of nodes. | +| <a id="productanalyticsdashboardpanelconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | -#### `ProductAnalyticsDashboardWidgetEdge` +#### `ProductAnalyticsDashboardPanelEdge` -The edge type for [`ProductAnalyticsDashboardWidget`](#productanalyticsdashboardwidget). +The edge type for [`ProductAnalyticsDashboardPanel`](#productanalyticsdashboardpanel). ##### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="productanalyticsdashboardwidgetedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | -| <a id="productanalyticsdashboardwidgetedgenode"></a>`node` | [`ProductAnalyticsDashboardWidget`](#productanalyticsdashboardwidget) | The item at the end of the edge. | +| <a id="productanalyticsdashboardpaneledgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="productanalyticsdashboardpaneledgenode"></a>`node` | [`ProductAnalyticsDashboardPanel`](#productanalyticsdashboardpanel) | The item at the end of the edge. | #### `ProjectConnection` @@ -9439,6 +9630,7 @@ The connection type for [`SavedReply`](#savedreply). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="savedreplyconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="savedreplyconnectionedges"></a>`edges` | [`[SavedReplyEdge]`](#savedreplyedge) | A list of edges. | | <a id="savedreplyconnectionnodes"></a>`nodes` | [`[SavedReply]`](#savedreply) | A list of nodes. | | <a id="savedreplyconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -10377,7 +10569,6 @@ Representation of a GitLab user. | <a id="achievementid"></a>`id` | [`AchievementsAchievementID!`](#achievementsachievementid) | ID of the achievement. | | <a id="achievementname"></a>`name` | [`String!`](#string) | Name of the achievement. | | <a id="achievementnamespace"></a>`namespace` | [`Namespace!`](#namespace) | Namespace of the achievement. | -| <a id="achievementrevokeable"></a>`revokeable` | [`Boolean!`](#boolean) | Revokeability of the achievement. | | <a id="achievementupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the achievement was last updated. | ### `AgentConfiguration` @@ -10585,6 +10776,7 @@ Describes a rule for who can approve merge requests. | <a id="approvalruleapprovalsrequired"></a>`approvalsRequired` | [`Int`](#int) | Number of required approvals. | | <a id="approvalruleapproved"></a>`approved` | [`Boolean`](#boolean) | Indicates if the rule is satisfied. | | <a id="approvalruleapprovedby"></a>`approvedBy` | [`UserCoreConnection`](#usercoreconnection) | List of users defined in the rule that approved the merge request. (see [Connections](#connections)) | +| <a id="approvalrulecommentedby"></a>`commentedBy` | [`UserCoreConnection`](#usercoreconnection) | List of users, defined in the rule, who commented on the merge request. (see [Connections](#connections)) | | <a id="approvalrulecontainshiddengroups"></a>`containsHiddenGroups` | [`Boolean`](#boolean) | Indicates if the rule contains approvers from a hidden group. | | <a id="approvalruleeligibleapprovers"></a>`eligibleApprovers` | [`[UserCore!]`](#usercore) | List of all users eligible to approve the merge request (defined explicitly and from associated groups). | | <a id="approvalrulegroups"></a>`groups` | [`GroupConnection`](#groupconnection) | List of groups added as approvers for the rule. (see [Connections](#connections)) | @@ -10759,7 +10951,7 @@ Represents an epic on an issue board. | <a id="boardepicdescendantcounts"></a>`descendantCounts` | [`EpicDescendantCount`](#epicdescendantcount) | Number of open and closed descendant epics and issues. | | <a id="boardepicdescendantweightsum"></a>`descendantWeightSum` | [`EpicDescendantWeights`](#epicdescendantweights) | Total weight of open and closed issues in the epic and its descendants. | | <a id="boardepicdescription"></a>`description` | [`String`](#string) | Description of the epic. | -| <a id="boardepicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="boardepicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="boardepicdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="boardepicdownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the epic has received. | | <a id="boardepicduedate"></a>`dueDate` | [`Time`](#time) | Due date of the epic. | @@ -10791,7 +10983,7 @@ Represents an epic on an issue board. | <a id="boardepicsubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Indicates the currently logged in user is subscribed to the epic. | | <a id="boardepictextcolor"></a>`textColor` | [`String`](#string) | Text color generated for the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | | <a id="boardepictitle"></a>`title` | [`String`](#string) | Title of the epic. | -| <a id="boardepictitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="boardepictitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="boardepicupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the epic was updated. | | <a id="boardepicupvotes"></a>`upvotes` | [`Int!`](#int) | Number of upvotes the epic has received. | | <a id="boardepicuserdiscussionscount"></a>`userDiscussionsCount` | [`Int!`](#int) | Number of user discussions in the epic. | @@ -10832,6 +11024,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicancestorsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="boardepicancestorsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="boardepicancestorsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="boardepicancestorsor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="boardepicancestorssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="boardepicancestorssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="boardepicancestorsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -10870,6 +11063,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicchildrenmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="boardepicchildrenmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="boardepicchildrennot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="boardepicchildrenor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="boardepicchildrensearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="boardepicchildrensort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="boardepicchildrenstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -11204,6 +11398,7 @@ CI/CD variables for a GitLab instance. | <a id="cijobdetailedstatus"></a>`detailedStatus` | [`DetailedStatus`](#detailedstatus) | Detailed status of the job. | | <a id="cijobdownstreampipeline"></a>`downstreamPipeline` | [`Pipeline`](#pipeline) | Downstream pipeline for a bridge. | | <a id="cijobduration"></a>`duration` | [`Int`](#int) | Duration of the job in seconds. | +| <a id="cijoberasedat"></a>`erasedAt` | [`Time`](#time) | When the job was erased. | | <a id="cijobfinishedat"></a>`finishedAt` | [`Time`](#time) | When a job has finished running. | | <a id="cijobid"></a>`id` | [`JobID`](#jobid) | ID of the job. | | <a id="cijobkind"></a>`kind` | [`CiJobKind!`](#cijobkind) | Indicates the type of job. | @@ -11214,6 +11409,7 @@ CI/CD variables for a GitLab instance. | <a id="cijobpipeline"></a>`pipeline` | [`Pipeline`](#pipeline) | Pipeline the job belongs to. | | <a id="cijobplayable"></a>`playable` | [`Boolean!`](#boolean) | Indicates the job can be played. | | <a id="cijobpreviousstagejobsorneeds"></a>`previousStageJobsOrNeeds` | [`JobNeedUnionConnection`](#jobneedunionconnection) | Jobs that must complete before the job runs. Returns `BuildNeed`, which is the needed jobs if the job uses the `needs` keyword, or the previous stage jobs otherwise. (see [Connections](#connections)) | +| <a id="cijobproject"></a>`project` | [`Project`](#project) | Project that the job belongs to. | | <a id="cijobqueuedat"></a>`queuedAt` | [`Time`](#time) | When the job was enqueued and marked as pending. | | <a id="cijobqueuedduration"></a>`queuedDuration` | [`Duration`](#duration) | How long the job was enqueued before starting. | | <a id="cijobrefname"></a>`refName` | [`String`](#string) | Ref name of the job. | @@ -11251,7 +11447,9 @@ CI/CD variables for a GitLab instance. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="cijobtokenscopetypeprojects"></a>`projects` | [`ProjectConnection!`](#projectconnection) | Allow list of projects that can be accessed by CI Job tokens created by this project. (see [Connections](#connections)) | +| <a id="cijobtokenscopetypeinboundallowlist"></a>`inboundAllowlist` | [`ProjectConnection!`](#projectconnection) | Allow list of projects that can access the current project through its CI Job tokens. (see [Connections](#connections)) | +| <a id="cijobtokenscopetypeoutboundallowlist"></a>`outboundAllowlist` | [`ProjectConnection!`](#projectconnection) | Allow list of projects that are accessible using the current project's CI Job tokens. (see [Connections](#connections)) | +| <a id="cijobtokenscopetypeprojects"></a>`projects` **{warning-solid}** | [`ProjectConnection!`](#projectconnection) | **Deprecated** in 15.9. The `projects` attribute is being deprecated. Use `outbound_allowlist`. | ### `CiJobsDurationStatistics` @@ -11346,6 +11544,7 @@ CI/CD variables for a project. | <a id="cirunnercreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of creation of this runner. | | <a id="cirunnerdescription"></a>`description` | [`String`](#string) | Description of the runner. | | <a id="cirunnereditadminurl"></a>`editAdminUrl` | [`String`](#string) | Admin form URL of the runner. Only available for administrators. | +| <a id="cirunnerephemeralauthenticationtoken"></a>`ephemeralAuthenticationToken` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. Ephemeral authentication token used for runner machine registration. | | <a id="cirunnerexecutorname"></a>`executorName` | [`String`](#string) | Executor last advertised by the runner. | | <a id="cirunnergroups"></a>`groups` | [`GroupConnection`](#groupconnection) | Groups the runner is associated with. For group runners only. (see [Connections](#connections)) | | <a id="cirunnerid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner. | @@ -11354,7 +11553,7 @@ CI/CD variables for a project. | <a id="cirunnerjobexecutionstatus"></a>`jobExecutionStatus` **{warning-solid}** | [`CiRunnerJobExecutionStatus`](#cirunnerjobexecutionstatus) | **Introduced** in 15.7. This feature is in Alpha. It can be changed or removed at any time. Job execution status of the runner. | | <a id="cirunnerlocked"></a>`locked` | [`Boolean`](#boolean) | Indicates the runner is locked. | | <a id="cirunnermaintenancenote"></a>`maintenanceNote` | [`String`](#string) | Runner's maintenance notes. | -| <a id="cirunnermaintenancenotehtml"></a>`maintenanceNoteHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `maintenance_note`. | +| <a id="cirunnermaintenancenotehtml"></a>`maintenanceNoteHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `maintenance_note`. | | <a id="cirunnermaximumtimeout"></a>`maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. | | <a id="cirunnerownerproject"></a>`ownerProject` | [`Project`](#project) | Project that owns the runner. For project runners only. | | <a id="cirunnerpaused"></a>`paused` | [`Boolean!`](#boolean) | Indicates the runner is paused and not available to run jobs. | @@ -11561,12 +11760,29 @@ Represents a code quality degradation on the pipeline. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="codequalitydegradationdescription"></a>`description` | [`String!`](#string) | Description of the code quality degradation. | +| <a id="codequalitydegradationenginename"></a>`engineName` | [`String!`](#string) | Code Quality plugin that reported the finding. | | <a id="codequalitydegradationfingerprint"></a>`fingerprint` | [`String!`](#string) | Unique fingerprint to identify the code quality degradation. For example, an MD5 hash. | | <a id="codequalitydegradationline"></a>`line` | [`Int!`](#int) | Line on which the code quality degradation occurred. | | <a id="codequalitydegradationpath"></a>`path` | [`String!`](#string) | Relative path to the file containing the code quality degradation. | | <a id="codequalitydegradationseverity"></a>`severity` | [`CodeQualityDegradationSeverity!`](#codequalitydegradationseverity) | Status of the degradation (BLOCKER, CRITICAL, MAJOR, MINOR, INFO, UNKNOWN). | | <a id="codequalitydegradationweburl"></a>`webUrl` | [`String`](#string) | URL to the file along with line number. | +### `CodeQualityReportSummary` + +Code Quality report for a pipeline. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="codequalityreportsummaryblocker"></a>`blocker` | [`Int`](#int) | Total number of blocker status. | +| <a id="codequalityreportsummarycount"></a>`count` | [`Int`](#int) | Total number of Code Quality reports. | +| <a id="codequalityreportsummarycritical"></a>`critical` | [`Int`](#int) | Total number of critical status. | +| <a id="codequalityreportsummaryinfo"></a>`info` | [`Int`](#int) | Total number of info status. | +| <a id="codequalityreportsummarymajor"></a>`major` | [`Int`](#int) | Total number of major status. | +| <a id="codequalityreportsummaryminor"></a>`minor` | [`Int`](#int) | Total number of minor status. | +| <a id="codequalityreportsummaryunknown"></a>`unknown` | [`Int`](#int) | Total number of unknown status. | + ### `Commit` #### Fields @@ -11579,9 +11795,9 @@ Represents a code quality degradation on the pipeline. | <a id="commitauthorname"></a>`authorName` | [`String`](#string) | Commit authors name. | | <a id="commitauthoreddate"></a>`authoredDate` | [`Time`](#time) | Timestamp of when the commit was authored. | | <a id="commitdescription"></a>`description` | [`String`](#string) | Description of the commit message. | -| <a id="commitdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="commitdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="commitfulltitle"></a>`fullTitle` | [`String`](#string) | Full title of the commit message. | -| <a id="commitfulltitlehtml"></a>`fullTitleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `full_title`. | +| <a id="commitfulltitlehtml"></a>`fullTitleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `full_title`. | | <a id="commitid"></a>`id` | [`ID!`](#id) | ID (global ID) of the commit. | | <a id="commitmessage"></a>`message` | [`String`](#string) | Raw commit message. | | <a id="commitsha"></a>`sha` | [`String!`](#string) | SHA1 ID of the commit. | @@ -11589,7 +11805,7 @@ Represents a code quality degradation on the pipeline. | <a id="commitsignature"></a>`signature` | [`CommitSignature`](#commitsignature) | Signature of the commit. | | <a id="commitsignaturehtml"></a>`signatureHtml` | [`String`](#string) | Rendered HTML of the commit signature. | | <a id="committitle"></a>`title` | [`String`](#string) | Title of the commit message. | -| <a id="committitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="committitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="commitwebpath"></a>`webPath` | [`String!`](#string) | Web path of the commit. | | <a id="commitweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the commit. | @@ -11974,6 +12190,7 @@ Represents a DAST Profile. | <a id="dastprofileeditpath"></a>`editPath` | [`String`](#string) | Relative web path to the edit page of a profile. | | <a id="dastprofileid"></a>`id` | [`DastProfileID!`](#dastprofileid) | ID of the profile. | | <a id="dastprofilename"></a>`name` | [`String`](#string) | Name of the profile. | +| <a id="dastprofiletaglist"></a>`tagList` | [`[String!]`](#string) | Runner tags associated with the profile. | ### `DastProfileBranch` @@ -12028,7 +12245,7 @@ Represents a DAST scanner profile. | <a id="dastscannerprofilescantype"></a>`scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | <a id="dastscannerprofileshowdebugmessages"></a>`showDebugMessages` | [`Boolean!`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | <a id="dastscannerprofilespidertimeout"></a>`spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | -| <a id="dastscannerprofiletaglist"></a>`tagList` | [`[String!]`](#string) | Runner tags associated with the scanner profile. | +| <a id="dastscannerprofiletaglist"></a>`tagList` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 15.8. Moved to DastProfile. | | <a id="dastscannerprofiletargettimeout"></a>`targetTimeout` | [`Int`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | <a id="dastscannerprofileuseajaxspider"></a>`useAjaxSpider` | [`Boolean!`](#boolean) | Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider. | @@ -12107,6 +12324,16 @@ The response from the AdminSidekiqQueuesDeleteJobs mutation. | <a id="deletejobsresponsedeletedjobs"></a>`deletedJobs` | [`Int`](#int) | Number of matching jobs deleted. | | <a id="deletejobsresponsequeuesize"></a>`queueSize` | [`Int`](#int) | Queue size after processing. | +### `DeletedNote` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="deletednotediscussionid"></a>`discussionId` | [`DiscussionID`](#discussionid) | ID of the discussion for the deleted note. | +| <a id="deletednoteid"></a>`id` | [`NoteID!`](#noteid) | ID of the deleted note. | +| <a id="deletednotelastdiscussionnote"></a>`lastDiscussionNote` | [`Boolean`](#boolean) | Whether deleted note is the last note in the discussion. | + ### `DependencyProxyBlob` Dependency proxy blob. @@ -12217,7 +12444,7 @@ The deployment of an environment. | <a id="deploymentsha"></a>`sha` | [`String`](#string) | Git-SHA that the deployment ran on. | | <a id="deploymentstatus"></a>`status` | [`DeploymentStatus`](#deploymentstatus) | Status of the deployment. | | <a id="deploymenttag"></a>`tag` | [`Boolean`](#boolean) | True or false if the deployment ran on a Git-tag. | -| <a id="deploymenttags"></a>`tags` | [`[DeploymentTag!]`](#deploymenttag) | Git tags that contain this deployment. This field can only be resolved for one deployment in any single request. | +| <a id="deploymenttags"></a>`tags` | [`[DeploymentTag!]`](#deploymenttag) | Git tags that contain this deployment. This field can only be resolved for two deployments in any single request. | | <a id="deploymenttriggerer"></a>`triggerer` | [`UserCore`](#usercore) | User who executed the deployment. | | <a id="deploymentupdatedat"></a>`updatedAt` | [`Time`](#time) | When the deployment record was updated. | | <a id="deploymentuserpermissions"></a>`userPermissions` | [`DeploymentPermissions!`](#deploymentpermissions) | Permissions for the current user on the resource. | @@ -12713,6 +12940,19 @@ Returns [`[DoraMetric!]`](#dorametric). | <a id="dorametricdate"></a>`date` | [`String`](#string) | Date of the data point. | | <a id="dorametricvalue"></a>`value` | [`Float`](#float) | Value of the data point. | +### `EgressNode` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="egressnodeartifactsegress"></a>`artifactsEgress` | [`BigInt!`](#bigint) | Artifacts egress for that project in that period of time. | +| <a id="egressnodedate"></a>`date` | [`String!`](#string) | First day of the node range. There is one node per month. | +| <a id="egressnodepackagesegress"></a>`packagesEgress` | [`BigInt!`](#bigint) | Packages egress for that project in that period of time. | +| <a id="egressnoderegistryegress"></a>`registryEgress` | [`BigInt!`](#bigint) | Registery egress for that project in that period of time. | +| <a id="egressnoderepositoryegress"></a>`repositoryEgress` | [`BigInt!`](#bigint) | Repository egress for that project in that period of time. | +| <a id="egressnodetotalegress"></a>`totalEgress` | [`BigInt!`](#bigint) | Total egress for that project in that period of time. | + ### `Email` #### Fields @@ -12826,7 +13066,7 @@ Represents an epic. | <a id="epicdescendantcounts"></a>`descendantCounts` | [`EpicDescendantCount`](#epicdescendantcount) | Number of open and closed descendant epics and issues. | | <a id="epicdescendantweightsum"></a>`descendantWeightSum` | [`EpicDescendantWeights`](#epicdescendantweights) | Total weight of open and closed issues in the epic and its descendants. | | <a id="epicdescription"></a>`description` | [`String`](#string) | Description of the epic. | -| <a id="epicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="epicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="epicdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="epicdownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the epic has received. | | <a id="epicduedate"></a>`dueDate` | [`Time`](#time) | Due date of the epic. | @@ -12858,7 +13098,7 @@ Represents an epic. | <a id="epicsubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Indicates the currently logged in user is subscribed to the epic. | | <a id="epictextcolor"></a>`textColor` | [`String`](#string) | Text color generated for the epic. Returns `null` if `epic_color_highlight` feature flag is disabled. | | <a id="epictitle"></a>`title` | [`String`](#string) | Title of the epic. | -| <a id="epictitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="epictitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="epicupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the epic was updated. | | <a id="epicupvotes"></a>`upvotes` | [`Int!`](#int) | Number of upvotes the epic has received. | | <a id="epicuserdiscussionscount"></a>`userDiscussionsCount` | [`Int!`](#int) | Number of user discussions in the epic. | @@ -12898,6 +13138,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicancestorsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="epicancestorsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="epicancestorsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="epicancestorsor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="epicancestorssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="epicancestorssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="epicancestorsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -12936,6 +13177,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicchildrenmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="epicchildrenmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="epicchildrennot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="epicchildrenor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="epicchildrensearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="epicchildrensort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="epicchildrenstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -13067,7 +13309,7 @@ Relationship between an epic and an issue. | <a id="epicissuecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the issue was created. | | <a id="epicissuecustomerrelationscontacts"></a>`customerRelationsContacts` | [`CustomerRelationsContactConnection`](#customerrelationscontactconnection) | Customer relations contacts of the issue. (see [Connections](#connections)) | | <a id="epicissuedescription"></a>`description` | [`String`](#string) | Description of the issue. | -| <a id="epicissuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="epicissuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="epicissuedesigncollection"></a>`designCollection` | [`DesignCollection`](#designcollection) | Collection of design images associated with this issue. | | <a id="epicissuediscussionlocked"></a>`discussionLocked` | [`Boolean!`](#boolean) | Indicates discussion is locked on the issue. | | <a id="epicissuediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | @@ -13080,7 +13322,7 @@ Relationship between an epic and an issue. | <a id="epicissueescalationstatus"></a>`escalationStatus` | [`IssueEscalationStatus`](#issueescalationstatus) | Escalation status of the issue. | | <a id="epicissuehasepic"></a>`hasEpic` | [`Boolean!`](#boolean) | Indicates if the issue belongs to an epic. Can return true and not show an associated epic when the user has no access to the epic. | | <a id="epicissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Current health status. | -| <a id="epicissuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. Will always return `null` if `ban_user_feature_flag` feature flag is disabled. | +| <a id="epicissuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. | | <a id="epicissuehumantimeestimate"></a>`humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the issue. | | <a id="epicissuehumantotaltimespent"></a>`humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the issue. | | <a id="epicissueid"></a>`id` | [`ID`](#id) | Global ID of the epic-issue relation. | @@ -13095,6 +13337,7 @@ Relationship between an epic and an issue. | <a id="epicissuenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="epicissueparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants in the issue. (see [Connections](#connections)) | | <a id="epicissueprojectid"></a>`projectId` | [`Int!`](#int) | ID of the issue project. | +| <a id="epicissuerelatedmergerequests"></a>`relatedMergeRequests` | [`MergeRequestConnection`](#mergerequestconnection) | Merge requests related to the issue. This field can only be resolved for one issue in any single request. (see [Connections](#connections)) | | <a id="epicissuerelatedvulnerabilities"></a>`relatedVulnerabilities` | [`VulnerabilityConnection`](#vulnerabilityconnection) | Related vulnerabilities of the issue. (see [Connections](#connections)) | | <a id="epicissuerelationpath"></a>`relationPath` | [`String`](#string) | URI path of the epic-issue relation. | | <a id="epicissuerelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the issue (used for positioning in epic tree and issue boards). | @@ -13107,7 +13350,7 @@ Relationship between an epic and an issue. | <a id="epicissuetimeestimate"></a>`timeEstimate` | [`Int!`](#int) | Time estimate of the issue. | | <a id="epicissuetimelogs"></a>`timelogs` | [`TimelogConnection!`](#timelogconnection) | Timelogs on the issue. (see [Connections](#connections)) | | <a id="epicissuetitle"></a>`title` | [`String!`](#string) | Title of the issue. | -| <a id="epicissuetitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="epicissuetitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="epicissuetotaltimespent"></a>`totalTimeSpent` | [`Int!`](#int) | Total time reported as spent on the issue. | | <a id="epicissuetype"></a>`type` | [`IssueType`](#issuetype) | Type of the issue. | | <a id="epicissueupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the issue was last updated. | @@ -13689,7 +13932,6 @@ GPG signature for a signed commit. | <a id="groupallowstalerunnerpruning"></a>`allowStaleRunnerPruning` | [`Boolean!`](#boolean) | Indicates whether to regularly prune stale group runners. Defaults to false. | | <a id="groupautodevopsenabled"></a>`autoDevopsEnabled` | [`Boolean`](#boolean) | Indicates whether Auto DevOps is enabled for all projects within this group. | | <a id="groupavatarurl"></a>`avatarUrl` | [`String`](#string) | Avatar URL of the group. | -| <a id="groupcivariables"></a>`ciVariables` | [`CiGroupVariableConnection`](#cigroupvariableconnection) | List of the group's CI/CD variables. (see [Connections](#connections)) | | <a id="groupcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the group. | | <a id="groupcontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. | | <a id="groupcrossprojectpipelineavailable"></a>`crossProjectPipelineAvailable` | [`Boolean!`](#boolean) | Indicates if the cross_project_pipeline feature is available for the namespace. | @@ -13703,7 +13945,7 @@ GPG signature for a signed commit. | <a id="groupdependencyproxysetting"></a>`dependencyProxySetting` | [`DependencyProxySetting`](#dependencyproxysetting) | Dependency Proxy settings for the group. | | <a id="groupdependencyproxytotalsize"></a>`dependencyProxyTotalSize` | [`String!`](#string) | Total size of the dependency proxy cached images. | | <a id="groupdescription"></a>`description` | [`String`](#string) | Description of the namespace. | -| <a id="groupdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="groupdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="groupdora"></a>`dora` | [`Dora`](#dora) | Group's DORA metrics. | | <a id="groupemailsdisabled"></a>`emailsDisabled` | [`Boolean`](#boolean) | Indicates if a group has email notifications disabled. | | <a id="groupenforcefreeusercap"></a>`enforceFreeUserCap` | [`Boolean`](#boolean) | Indicates whether the group has limited users for a free plan. | @@ -13783,6 +14025,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="groupboardsid"></a>`id` | [`BoardID`](#boardid) | Find a board by its ID. | +##### `Group.ciVariables` + +List of the group's CI/CD variables. + +Returns [`CiGroupVariableConnection`](#cigroupvariableconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupcivariablessort"></a>`sort` | [`CiVariableSort`](#civariablesort) | Sort order of results. | + ##### `Group.clusterAgents` Cluster agents associated with projects in the group and its subgroups. @@ -13897,6 +14155,19 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupcontributionsfrom"></a>`from` | [`ISO8601Date!`](#iso8601date) | Start date of the reporting time range. | | <a id="groupcontributionsto"></a>`to` | [`ISO8601Date!`](#iso8601date) | End date of the reporting time range. The end date must be within 31 days after the start date. | +##### `Group.dataTransfer` + +Data transfer data point for a specific period. This is mocked data under a development feature flag. + +Returns [`GroupDataTransfer`](#groupdatatransfer). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupdatatransferfrom"></a>`from` | [`Date`](#date) | Retain egress data for 1 year. Current month will increase dynamically as egress occurs. | +| <a id="groupdatatransferto"></a>`to` | [`Date`](#date) | End date for the data. | + ##### `Group.descendantGroups` List of descendant groups of this group. @@ -13940,6 +14211,7 @@ Returns [`Epic`](#epic). | <a id="groupepicmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="groupepicmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="groupepicnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="groupepicor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="groupepicsearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="groupepicsort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="groupepicstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -13990,6 +14262,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupepicsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="groupepicsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="groupepicsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | +| <a id="groupepicsor"></a>`or` **{warning-solid}** | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="groupepicssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="groupepicssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="groupepicsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | @@ -14311,6 +14584,24 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupprojectsincludesubgroups"></a>`includeSubgroups` | [`Boolean`](#boolean) | Include also subgroup projects. | | <a id="groupprojectssearch"></a>`search` | [`String`](#string) | Search project with most similar names or paths. | | <a id="groupprojectssort"></a>`sort` | [`NamespaceProjectSort`](#namespaceprojectsort) | Sort projects by this criteria. | +| <a id="groupprojectswithissuesenabled"></a>`withIssuesEnabled` | [`Boolean`](#boolean) | Return only projects with issues enabled. | +| <a id="groupprojectswithmergerequestsenabled"></a>`withMergeRequestsEnabled` | [`Boolean`](#boolean) | Return only projects with merge requests enabled. | + +##### `Group.releases` + +Releases belonging to projects in the group. + +Returns [`ReleaseConnection`](#releaseconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupreleasessort"></a>`sort` | [`GroupReleaseSort`](#groupreleasesort) | Sort group releases by given criteria. | ##### `Group.runners` @@ -14486,6 +14777,14 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="groupworkitemtypestaskable"></a>`taskable` | [`Boolean`](#boolean) | If `true`, only taskable work item types will be returned. Argument is experimental and can be removed in the future without notice. | +### `GroupDataTransfer` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupdatatransferegressnodes"></a>`egressNodes` | [`EgressNodeConnection`](#egressnodeconnection) | Data nodes. (see [Connections](#connections)) | + ### `GroupMember` Represents a Group Membership. @@ -14779,7 +15078,7 @@ Describes an issuable resource link for incident issues. | <a id="issuecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the issue was created. | | <a id="issuecustomerrelationscontacts"></a>`customerRelationsContacts` | [`CustomerRelationsContactConnection`](#customerrelationscontactconnection) | Customer relations contacts of the issue. (see [Connections](#connections)) | | <a id="issuedescription"></a>`description` | [`String`](#string) | Description of the issue. | -| <a id="issuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="issuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="issuedesigncollection"></a>`designCollection` | [`DesignCollection`](#designcollection) | Collection of design images associated with this issue. | | <a id="issuediscussionlocked"></a>`discussionLocked` | [`Boolean!`](#boolean) | Indicates discussion is locked on the issue. | | <a id="issuediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | @@ -14791,7 +15090,7 @@ Describes an issuable resource link for incident issues. | <a id="issueescalationstatus"></a>`escalationStatus` | [`IssueEscalationStatus`](#issueescalationstatus) | Escalation status of the issue. | | <a id="issuehasepic"></a>`hasEpic` | [`Boolean!`](#boolean) | Indicates if the issue belongs to an epic. Can return true and not show an associated epic when the user has no access to the epic. | | <a id="issuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Current health status. | -| <a id="issuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. Will always return `null` if `ban_user_feature_flag` feature flag is disabled. | +| <a id="issuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. | | <a id="issuehumantimeestimate"></a>`humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the issue. | | <a id="issuehumantotaltimespent"></a>`humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the issue. | | <a id="issueid"></a>`id` | [`ID!`](#id) | ID of the issue. | @@ -14806,6 +15105,7 @@ Describes an issuable resource link for incident issues. | <a id="issuenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="issueparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants in the issue. (see [Connections](#connections)) | | <a id="issueprojectid"></a>`projectId` | [`Int!`](#int) | ID of the issue project. | +| <a id="issuerelatedmergerequests"></a>`relatedMergeRequests` | [`MergeRequestConnection`](#mergerequestconnection) | Merge requests related to the issue. This field can only be resolved for one issue in any single request. (see [Connections](#connections)) | | <a id="issuerelatedvulnerabilities"></a>`relatedVulnerabilities` | [`VulnerabilityConnection`](#vulnerabilityconnection) | Related vulnerabilities of the issue. (see [Connections](#connections)) | | <a id="issuerelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the issue (used for positioning in epic tree and issue boards). | | <a id="issueseverity"></a>`severity` | [`IssuableSeverity`](#issuableseverity) | Severity level of the incident. | @@ -14817,7 +15117,7 @@ Describes an issuable resource link for incident issues. | <a id="issuetimeestimate"></a>`timeEstimate` | [`Int!`](#int) | Time estimate of the issue. | | <a id="issuetimelogs"></a>`timelogs` | [`TimelogConnection!`](#timelogconnection) | Timelogs on the issue. (see [Connections](#connections)) | | <a id="issuetitle"></a>`title` | [`String!`](#string) | Title of the issue. | -| <a id="issuetitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="issuetitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="issuetotaltimespent"></a>`totalTimeSpent` | [`Int!`](#int) | Total time reported as spent on the issue. | | <a id="issuetype"></a>`type` | [`IssueType`](#issuetype) | Type of the issue. | | <a id="issueupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the issue was last updated. | @@ -14936,7 +15236,7 @@ Represents an iteration object. | ---- | ---- | ----------- | | <a id="iterationcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of iteration creation. | | <a id="iterationdescription"></a>`description` | [`String`](#string) | Description of the iteration. | -| <a id="iterationdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="iterationdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="iterationduedate"></a>`dueDate` | [`Time`](#time) | Timestamp of the iteration due date. | | <a id="iterationid"></a>`id` | [`ID!`](#id) | ID of the iteration. | | <a id="iterationiid"></a>`iid` | [`ID!`](#id) | Internal ID of the iteration. | @@ -15110,7 +15410,7 @@ Represents an SSH key. | <a id="labelcolor"></a>`color` | [`String!`](#string) | Background color of the label. | | <a id="labelcreatedat"></a>`createdAt` | [`Time!`](#time) | When this label was created. | | <a id="labeldescription"></a>`description` | [`String`](#string) | Description of the label (Markdown rendered as HTML for caching). | -| <a id="labeldescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="labeldescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="labelid"></a>`id` | [`ID!`](#id) | Label ID. | | <a id="labeltextcolor"></a>`textColor` | [`String!`](#string) | Text color of the label. | | <a id="labeltitle"></a>`title` | [`String!`](#string) | Content of the label. | @@ -15212,7 +15512,7 @@ Defines which user roles, users, or groups can merge into a protected branch. | <a id="mergerequestdefaultmergecommitmessage"></a>`defaultMergeCommitMessage` | [`String`](#string) | Default merge commit message of the merge request. | | <a id="mergerequestdefaultsquashcommitmessage"></a>`defaultSquashCommitMessage` | [`String`](#string) | Default squash commit message of the merge request. | | <a id="mergerequestdescription"></a>`description` | [`String`](#string) | Description of the merge request (Markdown rendered as HTML for caching). | -| <a id="mergerequestdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="mergerequestdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="mergerequestdetailedmergestatus"></a>`detailedMergeStatus` | [`DetailedMergeStatus`](#detailedmergestatus) | Detailed merge status of the merge request. | | <a id="mergerequestdiffheadsha"></a>`diffHeadSha` | [`String`](#string) | Diff head SHA of the merge request. | | <a id="mergerequestdiffrefs"></a>`diffRefs` | [`DiffRefs`](#diffrefs) | References of the base SHA, the head SHA, and the start SHA for this merge request. | @@ -15260,8 +15560,8 @@ Defines which user roles, users, or groups can merge into a protected branch. | <a id="mergerequestsourcebranchprotected"></a>`sourceBranchProtected` | [`Boolean!`](#boolean) | Indicates if the source branch is protected. | | <a id="mergerequestsourceproject"></a>`sourceProject` | [`Project`](#project) | Source project of the merge request. | | <a id="mergerequestsourceprojectid"></a>`sourceProjectId` | [`Int`](#int) | ID of the merge request source project. | -| <a id="mergerequestsquash"></a>`squash` | [`Boolean!`](#boolean) | Indicates if squash on merge is enabled. | -| <a id="mergerequestsquashonmerge"></a>`squashOnMerge` | [`Boolean!`](#boolean) | Indicates if squash on merge is enabled. | +| <a id="mergerequestsquash"></a>`squash` | [`Boolean!`](#boolean) | Indicates if the merge request is set to be squashed when merged. [Project settings](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html#configure-squash-options-for-a-project) may override this value. Use `squash_on_merge` instead to take project squash options into account. | +| <a id="mergerequestsquashonmerge"></a>`squashOnMerge` | [`Boolean!`](#boolean) | Indicates if the merge request will be squashed when merged. | | <a id="mergerequeststate"></a>`state` | [`MergeRequestState!`](#mergerequeststate) | State of the merge request. | | <a id="mergerequestsubscribed"></a>`subscribed` | [`Boolean!`](#boolean) | Indicates if the currently logged in user is subscribed to this merge request. | | <a id="mergerequestsuggestedreviewers"></a>`suggestedReviewers` **{warning-solid}** | [`SuggestedReviewersType`](#suggestedreviewerstype) | **Introduced** in 15.4. This feature is in Alpha. It can be changed or removed at any time. Suggested reviewers for merge request. Returns `null` if `suggested_reviewers` feature flag is disabled. This flag is disabled by default and only available on GitLab.com because the feature is experimental and is subject to change without notice. | @@ -15273,7 +15573,7 @@ Defines which user roles, users, or groups can merge into a protected branch. | <a id="mergerequesttimeestimate"></a>`timeEstimate` | [`Int!`](#int) | Time estimate of the merge request. | | <a id="mergerequesttimelogs"></a>`timelogs` | [`TimelogConnection!`](#timelogconnection) | Timelogs on the merge request. (see [Connections](#connections)) | | <a id="mergerequesttitle"></a>`title` | [`String!`](#string) | Title of the merge request. | -| <a id="mergerequesttitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="mergerequesttitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="mergerequesttotaltimespent"></a>`totalTimeSpent` | [`Int!`](#int) | Total time reported as spent on the merge request. | | <a id="mergerequestupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the merge request was last updated. | | <a id="mergerequestupvotes"></a>`upvotes` | [`Int!`](#int) | Number of upvotes for the merge request. | @@ -15356,7 +15656,9 @@ Information relating to rules that must be satisfied to merge this merge request | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mergerequestapprovalstateapprovalrulesoverwritten"></a>`approvalRulesOverwritten` | [`Boolean`](#boolean) | Indicates if the merge request approval rules are overwritten for the merge request. | +| <a id="mergerequestapprovalstateinvalidapproversrules"></a>`invalidApproversRules` | [`[ApprovalRule!]`](#approvalrule) | List of approval rules that are associated with the merge request, but invalid. | | <a id="mergerequestapprovalstaterules"></a>`rules` | [`[ApprovalRule!]`](#approvalrule) | List of approval rules associated with the merge request. | +| <a id="mergerequestapprovalstatesuggestedapprovers"></a>`suggestedApprovers` | [`UserCoreConnection`](#usercoreconnection) | List of suggested approvers. (see [Connections](#connections)) | ### `MergeRequestAssignee` @@ -15514,6 +15816,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneereviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="mergerequestassigneereviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `MergeRequestAssignee.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mergerequestassigneesavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `MergeRequestAssignee.snippets` Snippets authored by the user. @@ -15748,6 +16062,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestauthorreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="mergerequestauthorreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `MergeRequestAuthor.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mergerequestauthorsavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `MergeRequestAuthor.snippets` Snippets authored by the user. @@ -16001,6 +16327,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestparticipantreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="mergerequestparticipantreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `MergeRequestParticipant.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mergerequestparticipantsavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `MergeRequestParticipant.snippets` Snippets authored by the user. @@ -16088,6 +16426,7 @@ Check permissions for the current user on a merge request. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mergerequestpermissionsadminmergerequest"></a>`adminMergeRequest` | [`Boolean!`](#boolean) | Indicates the user can perform `admin_merge_request` on this resource. | +| <a id="mergerequestpermissionscanapprove"></a>`canApprove` | [`Boolean!`](#boolean) | Indicates the user can perform `can_approve` on this resource. | | <a id="mergerequestpermissionscanmerge"></a>`canMerge` | [`Boolean!`](#boolean) | Indicates the user can perform `can_merge` on this resource. | | <a id="mergerequestpermissionscherrypickoncurrentmergerequest"></a>`cherryPickOnCurrentMergeRequest` | [`Boolean!`](#boolean) | Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource. | | <a id="mergerequestpermissionscreatenote"></a>`createNote` | [`Boolean!`](#boolean) | Indicates the user can perform `create_note` on this resource. | @@ -16253,6 +16592,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewerreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="mergerequestreviewerreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `MergeRequestReviewer.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mergerequestreviewersavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `MergeRequestReviewer.snippets` Snippets authored by the user. @@ -16458,7 +16809,7 @@ Contains statistics about a milestone. | <a id="namespacecontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. | | <a id="namespacecrossprojectpipelineavailable"></a>`crossProjectPipelineAvailable` | [`Boolean!`](#boolean) | Indicates if the cross_project_pipeline feature is available for the namespace. | | <a id="namespacedescription"></a>`description` | [`String`](#string) | Description of the namespace. | -| <a id="namespacedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="namespacedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="namespacefullname"></a>`fullName` | [`String!`](#string) | Full name of the namespace. | | <a id="namespacefullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the namespace. | | <a id="namespaceid"></a>`id` | [`ID!`](#id) | ID of the namespace. | @@ -16516,6 +16867,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="namespaceprojectsincludesubgroups"></a>`includeSubgroups` | [`Boolean`](#boolean) | Include also subgroup projects. | | <a id="namespaceprojectssearch"></a>`search` | [`String`](#string) | Search project with most similar names or paths. | | <a id="namespaceprojectssort"></a>`sort` | [`NamespaceProjectSort`](#namespaceprojectsort) | Sort projects by this criteria. | +| <a id="namespaceprojectswithissuesenabled"></a>`withIssuesEnabled` | [`Boolean`](#boolean) | Return only projects with issues enabled. | +| <a id="namespaceprojectswithmergerequestsenabled"></a>`withMergeRequestsEnabled` | [`Boolean`](#boolean) | Return only projects with merge requests enabled. | ##### `Namespace.scanExecutionPolicies` @@ -16618,7 +16971,7 @@ Represents the network policy. | ---- | ---- | ----------- | | <a id="noteauthor"></a>`author` | [`UserCore!`](#usercore) | User who wrote this note. | | <a id="notebody"></a>`body` | [`String!`](#string) | Content of the note. | -| <a id="notebodyhtml"></a>`bodyHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `note`. | +| <a id="notebodyhtml"></a>`bodyHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `note`. | | <a id="noteconfidential"></a>`confidential` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.5. This was renamed. Use: `internal`. | | <a id="notecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of the note creation. | | <a id="notediscussion"></a>`discussion` | [`Discussion`](#discussion) | Discussion this note is a part of. | @@ -16819,6 +17172,7 @@ Represents a package details in the Package Registry. | <a id="packagedetailstypepackagetype"></a>`packageType` | [`PackageTypeEnum!`](#packagetypeenum) | Package type. | | <a id="packagedetailstypepipelines"></a>`pipelines` | [`PipelineConnection`](#pipelineconnection) | Pipelines that built the package. Max page size 20. (see [Connections](#connections)) | | <a id="packagedetailstypeproject"></a>`project` | [`Project!`](#project) | Project where the package is stored. | +| <a id="packagedetailstypepublicpackage"></a>`publicPackage` | [`Boolean`](#boolean) | Indicates if there is public access to the package. | | <a id="packagedetailstypepypisetupurl"></a>`pypiSetupUrl` | [`String`](#string) | Url of the PyPi project setup endpoint. | | <a id="packagedetailstypepypiurl"></a>`pypiUrl` | [`String`](#string) | Url of the PyPi project endpoint. | | <a id="packagedetailstypestatus"></a>`status` | [`PackageStatus!`](#packagestatus) | Package status. | @@ -17029,6 +17383,7 @@ Represents a file or directory in the project repository that has been locked. | <a id="pipelineactive"></a>`active` | [`Boolean!`](#boolean) | Indicates if the pipeline is active. | | <a id="pipelinebeforesha"></a>`beforeSha` | [`String`](#string) | Base SHA of the source branch. | | <a id="pipelinecancelable"></a>`cancelable` | [`Boolean!`](#boolean) | Specifies if a pipeline can be canceled. | +| <a id="pipelinecodequalityreportsummary"></a>`codeQualityReportSummary` | [`CodeQualityReportSummary`](#codequalityreportsummary) | Code Quality report summary for a pipeline. | | <a id="pipelinecodequalityreports"></a>`codeQualityReports` | [`CodeQualityDegradationConnection`](#codequalitydegradationconnection) | Code Quality degradations reported on the pipeline. (see [Connections](#connections)) | | <a id="pipelinecommit"></a>`commit` | [`Commit`](#commit) | Git commit of the pipeline. | | <a id="pipelinecommitpath"></a>`commitPath` | [`String`](#string) | Path to the commit that triggered the pipeline. | @@ -17286,8 +17641,11 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="pipelinesecurityreportfindingassets"></a>`assets` | [`[AssetType!]`](#assettype) | List of assets associated with the vulnerability. | | <a id="pipelinesecurityreportfindingconfidence"></a>`confidence` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.4. This field will be removed from the Finding domain model. | | <a id="pipelinesecurityreportfindingdescription"></a>`description` | [`String`](#string) | Description of the vulnerability finding. | -| <a id="pipelinesecurityreportfindingdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="pipelinesecurityreportfindingdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="pipelinesecurityreportfindingdetails"></a>`details` | [`[VulnerabilityDetail!]!`](#vulnerabilitydetail) | Details of the security finding. | +| <a id="pipelinesecurityreportfindingdismissalreason"></a>`dismissalReason` | [`VulnerabilityDismissalReason`](#vulnerabilitydismissalreason) | Reason for the dismissal of the security report finding. | +| <a id="pipelinesecurityreportfindingdismissedat"></a>`dismissedAt` | [`Time`](#time) | Time of the dismissal of the security report finding. | +| <a id="pipelinesecurityreportfindingdismissedby"></a>`dismissedBy` | [`UserCore`](#usercore) | User who dismissed the security report finding. | | <a id="pipelinesecurityreportfindingevidence"></a>`evidence` | [`VulnerabilityEvidence`](#vulnerabilityevidence) | Evidence for the vulnerability. | | <a id="pipelinesecurityreportfindingfalsepositive"></a>`falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. | | <a id="pipelinesecurityreportfindingidentifiers"></a>`identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerability finding. | @@ -17298,11 +17656,13 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="pipelinesecurityreportfindingname"></a>`name` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.1. Use `title`. | | <a id="pipelinesecurityreportfindingproject"></a>`project` | [`Project`](#project) | Project on which the vulnerability finding was found. | | <a id="pipelinesecurityreportfindingprojectfingerprint"></a>`projectFingerprint` **{warning-solid}** | [`String`](#string) | **Deprecated** in 15.1. The `project_fingerprint` attribute is being deprecated. Use `uuid` to identify findings. | +| <a id="pipelinesecurityreportfindingremediations"></a>`remediations` | [`[VulnerabilityRemediationType!]`](#vulnerabilityremediationtype) | Remediations of the security report finding. | | <a id="pipelinesecurityreportfindingreporttype"></a>`reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability finding. | | <a id="pipelinesecurityreportfindingscanner"></a>`scanner` | [`VulnerabilityScanner`](#vulnerabilityscanner) | Scanner metadata for the vulnerability. | | <a id="pipelinesecurityreportfindingseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability finding. | | <a id="pipelinesecurityreportfindingsolution"></a>`solution` | [`String`](#string) | Solution for resolving the security report finding. | | <a id="pipelinesecurityreportfindingstate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | Finding status. | +| <a id="pipelinesecurityreportfindingstatecomment"></a>`stateComment` | [`String`](#string) | Comment for the state of the security report finding. | | <a id="pipelinesecurityreportfindingtitle"></a>`title` | [`String`](#string) | Title of the vulnerability finding. | | <a id="pipelinesecurityreportfindinguuid"></a>`uuid` | [`String`](#string) | UUIDv5 digest based on the vulnerability's report type, primary identifier, location, fingerprint, project identifier. | | <a id="pipelinesecurityreportfindingvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability related to the security report finding. | @@ -17326,32 +17686,32 @@ Represents a product analytics dashboard. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="productanalyticsdashboarddescription"></a>`description` | [`String`](#string) | Description of the dashboard. | +| <a id="productanalyticsdashboardpanels"></a>`panels` | [`ProductAnalyticsDashboardPanelConnection!`](#productanalyticsdashboardpanelconnection) | Panels shown on the dashboard. (see [Connections](#connections)) | | <a id="productanalyticsdashboardtitle"></a>`title` | [`String!`](#string) | Title of the dashboard. | -| <a id="productanalyticsdashboardwidgets"></a>`widgets` | [`ProductAnalyticsDashboardWidgetConnection!`](#productanalyticsdashboardwidgetconnection) | Widgets shown on the dashboard. (see [Connections](#connections)) | -### `ProductAnalyticsDashboardVisualization` +### `ProductAnalyticsDashboardPanel` -Represents a product analytics dashboard visualization. +Represents a product analytics dashboard panel. #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="productanalyticsdashboardvisualizationdata"></a>`data` | [`JSON!`](#json) | Data of the visualization. | -| <a id="productanalyticsdashboardvisualizationoptions"></a>`options` | [`JSON!`](#json) | Options of the visualization. | -| <a id="productanalyticsdashboardvisualizationtype"></a>`type` | [`String!`](#string) | Type of the visualization. | +| <a id="productanalyticsdashboardpanelgridattributes"></a>`gridAttributes` | [`JSON`](#json) | Description of the position and size of the panel. | +| <a id="productanalyticsdashboardpaneltitle"></a>`title` | [`String!`](#string) | Title of the panel. | +| <a id="productanalyticsdashboardpanelvisualization"></a>`visualization` | [`ProductAnalyticsDashboardVisualization!`](#productanalyticsdashboardvisualization) | Visualization of the panel. | -### `ProductAnalyticsDashboardWidget` +### `ProductAnalyticsDashboardVisualization` -Represents a product analytics dashboard widget. +Represents a product analytics dashboard visualization. #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="productanalyticsdashboardwidgetgridattributes"></a>`gridAttributes` | [`JSON`](#json) | Description of the position and size of the widget. | -| <a id="productanalyticsdashboardwidgettitle"></a>`title` | [`String!`](#string) | Title of the widget. | -| <a id="productanalyticsdashboardwidgetvisualization"></a>`visualization` | [`ProductAnalyticsDashboardVisualization!`](#productanalyticsdashboardvisualization) | Visualization of the widget. | +| <a id="productanalyticsdashboardvisualizationdata"></a>`data` | [`JSON!`](#json) | Data of the visualization. | +| <a id="productanalyticsdashboardvisualizationoptions"></a>`options` | [`JSON!`](#json) | Options of the visualization. | +| <a id="productanalyticsdashboardvisualizationtype"></a>`type` | [`String!`](#string) | Type of the visualization. | ### `Project` @@ -17370,7 +17730,6 @@ Represents a product analytics dashboard widget. | <a id="projectcicdsettings"></a>`ciCdSettings` | [`ProjectCiCdSetting`](#projectcicdsetting) | CI/CD settings for the project. | | <a id="projectciconfigpathordefault"></a>`ciConfigPathOrDefault` | [`String!`](#string) | Path of the CI configuration file. | | <a id="projectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | The CI Job Tokens scope of access. | -| <a id="projectcivariables"></a>`ciVariables` | [`CiProjectVariableConnection`](#ciprojectvariableconnection) | List of the project's CI/CD variables. (see [Connections](#connections)) | | <a id="projectcodecoveragesummary"></a>`codeCoverageSummary` | [`CodeCoverageSummary`](#codecoveragesummary) | Code coverage summary associated with the project. | | <a id="projectcomplianceframeworks"></a>`complianceFrameworks` | [`ComplianceFrameworkConnection`](#complianceframeworkconnection) | Compliance frameworks associated with the project. (see [Connections](#connections)) | | <a id="projectcontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy of the project. | @@ -17381,7 +17740,7 @@ Represents a product analytics dashboard widget. | <a id="projectdastscannerprofiles"></a>`dastScannerProfiles` | [`DastScannerProfileConnection`](#dastscannerprofileconnection) | DAST scanner profiles associated with the project. (see [Connections](#connections)) | | <a id="projectdastsiteprofiles"></a>`dastSiteProfiles` | [`DastSiteProfileConnection`](#dastsiteprofileconnection) | DAST Site Profiles associated with the project. (see [Connections](#connections)) | | <a id="projectdescription"></a>`description` | [`String`](#string) | Short description of the project. | -| <a id="projectdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="projectdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="projectdora"></a>`dora` | [`Dora`](#dora) | Project's DORA metrics. | | <a id="projectforkscount"></a>`forksCount` | [`Int!`](#int) | Number of times the project has been forked. | | <a id="projectfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the project. | @@ -17600,6 +17959,22 @@ Returns [`CiTemplate`](#citemplate). | ---- | ---- | ----------- | | <a id="projectcitemplatename"></a>`name` | [`String!`](#string) | Name of the CI/CD template to search for. Template must be formatted as `Name.gitlab-ci.yml`. | +##### `Project.ciVariables` + +List of the project's CI/CD variables. + +Returns [`CiProjectVariableConnection`](#ciprojectvariableconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectcivariablessort"></a>`sort` | [`CiVariableSort`](#civariablesort) | Sort order of results. | + ##### `Project.clusterAgent` Find a single cluster agent by name. @@ -17704,6 +18079,19 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectdastsitevalidationsnormalizedtargeturls"></a>`normalizedTargetUrls` | [`[String!]`](#string) | Normalized URL of the target to be scanned. | | <a id="projectdastsitevalidationsstatus"></a>`status` | [`DastSiteValidationStatusEnum`](#dastsitevalidationstatusenum) | Status of the site validation. | +##### `Project.dataTransfer` + +Data transfer data point for a specific period. This is mocked data under a development feature flag. + +Returns [`ProjectDataTransfer`](#projectdatatransfer). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectdatatransferfrom"></a>`from` | [`Date`](#date) | Retain egress data for 1 year. Current month will increase dynamically as egress occurs. | +| <a id="projectdatatransferto"></a>`to` | [`Date`](#date) | End date for the data. | + ##### `Project.deployment` Details of the deployment of the project. @@ -18286,6 +18674,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="projectpipelineschedulesids"></a>`ids` | [`[ID!]`](#id) | Filter pipeline schedules by IDs. | | <a id="projectpipelineschedulesstatus"></a>`status` | [`PipelineScheduleStatus`](#pipelineschedulestatus) | Filter pipeline schedules by active status. | ##### `Project.pipelines` @@ -18375,7 +18764,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectreleasessort"></a>`sort` | [`ReleaseSort`](#releasesort) | Sort releases by this criteria. | +| <a id="projectreleasessort"></a>`sort` | [`ReleaseSort`](#releasesort) | Sort releases by given criteria. | ##### `Project.requirement` @@ -18518,6 +18907,10 @@ Returns [`SentryDetailedError`](#sentrydetailederror). Project services. +WARNING: +**Deprecated** in 15.9. +This will be renamed to `Project.integrations`. + Returns [`ServiceConnection`](#serviceconnection). This field returns a [connection](#connections). It accepts the @@ -18583,6 +18976,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projecttimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | | <a id="projecttimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | +##### `Project.visibleForks` + +Visible forks of the project. + +WARNING: +**Introduced** in 15.10. +This feature is in Alpha. It can be changed or removed at any time. + +Returns [`ProjectConnection`](#projectconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectvisibleforksminimumaccesslevel"></a>`minimumAccessLevel` | [`AccessLevelEnum`](#accesslevelenum) | Minimum access level. | + ##### `Project.vulnerabilities` Vulnerabilities reported on the project. @@ -18682,9 +19095,11 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="projectworkitemsauthorusername"></a>`authorUsername` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. Filter work items by author username. | | <a id="projectworkitemsiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | | <a id="projectworkitemsiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of work items. For example, `["1", "2"]`. | | <a id="projectworkitemsin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument.'. | +| <a id="projectworkitemsrequirementlegacywidget"></a>`requirementLegacyWidget` **{warning-solid}** | [`RequirementLegacyFilterInput`](#requirementlegacyfilterinput) | **Deprecated** in 15.9. Use work item IID filter instead. | | <a id="projectworkitemssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="projectworkitemssort"></a>`sort` | [`WorkItemSort`](#workitemsort) | Sort work items by this criteria. | | <a id="projectworkitemsstate"></a>`state` | [`IssuableState`](#issuablestate) | Current state of this work item. | @@ -18702,8 +19117,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectcicdsettingkeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Whether to keep the latest builds artifacts. | | <a id="projectcicdsettingmergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Whether merge pipelines are enabled. | | <a id="projectcicdsettingmergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Whether merge trains are enabled. | +| <a id="projectcicdsettingoptinjwt"></a>`optInJwt` | [`Boolean`](#boolean) | When disabled, the JSON Web Token is always available in all jobs in the pipeline. | | <a id="projectcicdsettingproject"></a>`project` | [`Project`](#project) | Project the CI/CD settings belong to. | +### `ProjectDataTransfer` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectdatatransferegressnodes"></a>`egressNodes` | [`EgressNodeConnection`](#egressnodeconnection) | Data nodes. (see [Connections](#connections)) | +| <a id="projectdatatransfertotalegress"></a>`totalEgress` | [`BigInt`](#bigint) | Total egress for that project in that period of time. | + ### `ProjectMember` Represents a Project Membership. @@ -18963,7 +19388,7 @@ Represents a release. | <a id="releasecommit"></a>`commit` | [`Commit`](#commit) | Commit associated with the release. | | <a id="releasecreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of when the release was created. | | <a id="releasedescription"></a>`description` | [`String`](#string) | Description (also known as "release notes") of the release. | -| <a id="releasedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="releasedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="releaseevidences"></a>`evidences` | [`ReleaseEvidenceConnection`](#releaseevidenceconnection) | Evidence for the release. (see [Connections](#connections)) | | <a id="releasehistoricalrelease"></a>`historicalRelease` | [`Boolean`](#boolean) | Indicates the release is an historical release. | | <a id="releaseid"></a>`id` | [`ReleaseID!`](#releaseid) | Global ID of the release. | @@ -18985,7 +19410,7 @@ Represents an asset link associated with a release. | ---- | ---- | ----------- | | <a id="releaseassetlinkdirectassetpath"></a>`directAssetPath` | [`String`](#string) | Relative path for the direct asset link. | | <a id="releaseassetlinkdirectasseturl"></a>`directAssetUrl` | [`String`](#string) | Direct asset URL of the link. | -| <a id="releaseassetlinkexternal"></a>`external` | [`Boolean`](#boolean) | Indicates the link points to an external resource. | +| <a id="releaseassetlinkexternal"></a>`external` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.9. No longer used. | | <a id="releaseassetlinkid"></a>`id` | [`ID!`](#id) | ID of the link. | | <a id="releaseassetlinklinktype"></a>`linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | Type of the link: `other`, `runbook`, `image`, `package`; defaults to `other`. | | <a id="releaseassetlinkname"></a>`name` | [`String`](#string) | Name of the link. | @@ -19661,7 +20086,7 @@ Represents a snippet entry. | <a id="snippetcommenters"></a>`commenters` | [`UserCoreConnection!`](#usercoreconnection) | All commenters on this noteable. (see [Connections](#connections)) | | <a id="snippetcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp this snippet was created. | | <a id="snippetdescription"></a>`description` | [`String`](#string) | Description of the snippet. | -| <a id="snippetdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="snippetdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="snippetdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="snippetfilename"></a>`fileName` | [`String`](#string) | File Name of the snippet. | | <a id="snippethttpurltorepo"></a>`httpUrlToRepo` | [`String`](#string) | HTTP URL to the snippet repository. | @@ -19832,7 +20257,9 @@ Represents a Suggested Reviewers result set. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="suggestedreviewerstypeaccepted"></a>`accepted` | [`[String!]`](#string) | List of accepted reviewer usernames. | +| <a id="suggestedreviewerstypecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the suggestions were created. | | <a id="suggestedreviewerstypesuggested"></a>`suggested` | [`[String!]!`](#string) | List of suggested reviewer usernames. | +| <a id="suggestedreviewerstypeupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the suggestions were updated. | ### `SystemNoteMetadata` @@ -20144,7 +20571,7 @@ Representing a to-do entry. | ---- | ---- | ----------- | | <a id="topicavatarurl"></a>`avatarUrl` | [`String`](#string) | URL to avatar image file of the topic. | | <a id="topicdescription"></a>`description` | [`String`](#string) | Description of the topic. | -| <a id="topicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="topicdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="topicid"></a>`id` | [`ID!`](#id) | ID of the topic. | | <a id="topicname"></a>`name` | [`String!`](#string) | Name of the topic. | | <a id="topictitle"></a>`title` | [`String!`](#string) | Title of the topic. | @@ -20385,6 +20812,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercorereviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="usercorereviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +##### `UserCore.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="usercoresavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ##### `UserCore.snippets` Snippets authored by the user. @@ -20537,7 +20976,7 @@ Represents a vulnerability. | <a id="vulnerabilityconfirmedat"></a>`confirmedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to confirmed. | | <a id="vulnerabilityconfirmedby"></a>`confirmedBy` | [`UserCore`](#usercore) | User that confirmed the vulnerability. | | <a id="vulnerabilitydescription"></a>`description` | [`String`](#string) | Description of the vulnerability. | -| <a id="vulnerabilitydescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="vulnerabilitydescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="vulnerabilitydetails"></a>`details` | [`[VulnerabilityDetail!]!`](#vulnerabilitydetail) | Details of the vulnerability. | | <a id="vulnerabilitydetectedat"></a>`detectedAt` | [`Time!`](#time) | Timestamp of when the vulnerability was first detected. | | <a id="vulnerabilitydiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | @@ -20562,6 +21001,7 @@ Represents a vulnerability. | <a id="vulnerabilityscanner"></a>`scanner` | [`VulnerabilityScanner`](#vulnerabilityscanner) | Scanner metadata for the vulnerability. | | <a id="vulnerabilityseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability (INFO, UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL). | | <a id="vulnerabilitystate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | State of the vulnerability (DETECTED, CONFIRMED, RESOLVED, DISMISSED). | +| <a id="vulnerabilitystatecomment"></a>`stateComment` | [`String`](#string) | Comment given for the vulnerability state change. | | <a id="vulnerabilitytitle"></a>`title` | [`String`](#string) | Title of the vulnerability. | | <a id="vulnerabilityupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp of when the vulnerability was last updated. | | <a id="vulnerabilityusernotescount"></a>`userNotesCount` | [`Int!`](#int) | Number of user notes attached to the vulnerability. | @@ -20984,6 +21424,17 @@ Check permissions for the current user on a vulnerability. | <a id="vulnerabilitypermissionsreadvulnerabilityfeedback"></a>`readVulnerabilityFeedback` | [`Boolean!`](#boolean) | Indicates the user can perform `read_vulnerability_feedback` on this resource. | | <a id="vulnerabilitypermissionsupdatevulnerabilityfeedback"></a>`updateVulnerabilityFeedback` | [`Boolean!`](#boolean) | Indicates the user can perform `update_vulnerability_feedback` on this resource. | +### `VulnerabilityRemediationType` + +Represents a vulnerability remediation type. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerabilityremediationtypediff"></a>`diff` | [`String`](#string) | Diff of the remediation. | +| <a id="vulnerabilityremediationtypesummary"></a>`summary` | [`String`](#string) | Summary of the remediation. | + ### `VulnerabilityRequest` Represents a Vulnerability Request. @@ -21105,18 +21556,19 @@ Represents vulnerability letter grades with associated projects. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="workitemauthor"></a>`author` **{warning-solid}** | [`UserCore`](#usercore) | **Introduced** in 15.9. This feature is in Alpha. It can be changed or removed at any time. User that created the work item. | | <a id="workitemclosedat"></a>`closedAt` | [`Time`](#time) | Timestamp of when the work item was closed. | | <a id="workitemconfidential"></a>`confidential` | [`Boolean!`](#boolean) | Indicates the work item is confidential. | | <a id="workitemcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the work item was created. | | <a id="workitemdescription"></a>`description` | [`String`](#string) | Description of the work item. | -| <a id="workitemdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="workitemdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="workitemid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | | <a id="workitemiid"></a>`iid` | [`ID!`](#id) | Internal ID of the work item. | | <a id="workitemlockversion"></a>`lockVersion` | [`Int!`](#int) | Lock version of the work item. Incremented each time the work item is updated. | | <a id="workitemproject"></a>`project` **{warning-solid}** | [`Project!`](#project) | **Introduced** in 15.3. This feature is in Alpha. It can be changed or removed at any time. Project the work item belongs to. | | <a id="workitemstate"></a>`state` | [`WorkItemState!`](#workitemstate) | State of the work item. | | <a id="workitemtitle"></a>`title` | [`String!`](#string) | Title of the work item. | -| <a id="workitemtitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="workitemtitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="workitemupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the work item was last updated. | | <a id="workitemuserpermissions"></a>`userPermissions` | [`WorkItemPermissions!`](#workitempermissions) | Permissions for the current user on the resource. | | <a id="workitemweburl"></a>`webUrl` | [`String`](#string) | URL of this object. | @@ -21131,6 +21583,7 @@ Check permissions for the current user on a work item. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="workitempermissionsadminworkitem"></a>`adminWorkItem` | [`Boolean!`](#boolean) | Indicates the user can perform `admin_work_item` on this resource. | | <a id="workitempermissionsdeleteworkitem"></a>`deleteWorkItem` | [`Boolean!`](#boolean) | Indicates the user can perform `delete_work_item` on this resource. | | <a id="workitempermissionsreadworkitem"></a>`readWorkItem` | [`Boolean!`](#boolean) | Indicates the user can perform `read_work_item` on this resource. | | <a id="workitempermissionsupdateworkitem"></a>`updateWorkItem` | [`Boolean!`](#boolean) | Indicates the user can perform `update_work_item` on this resource. | @@ -21167,7 +21620,7 @@ Represents a description widget. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="workitemwidgetdescriptiondescription"></a>`description` | [`String`](#string) | Description of the work item. | -| <a id="workitemwidgetdescriptiondescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="workitemwidgetdescriptiondescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="workitemwidgetdescriptionedited"></a>`edited` | [`Boolean!`](#boolean) | Whether the description has been edited since the work item was created. | | <a id="workitemwidgetdescriptionlasteditedat"></a>`lastEditedAt` | [`Time`](#time) | Timestamp of when the work item's description was last edited. | | <a id="workitemwidgetdescriptionlasteditedby"></a>`lastEditedBy` | [`UserCore`](#usercore) | User that made the last edit to the work item's description. | @@ -21304,6 +21757,17 @@ Represents a status widget. | <a id="workitemwidgetstatusstatus"></a>`status` | [`String`](#string) | Status of the work item. | | <a id="workitemwidgetstatustype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | +### `WorkItemWidgetTestReports` + +Represents a test reports widget. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgettestreportstestreports"></a>`testReports` | [`TestReportConnection`](#testreportconnection) | Test reports of the work item. (see [Connections](#connections)) | +| <a id="workitemwidgettestreportstype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | + ### `WorkItemWidgetWeight` Represents a weight widget. @@ -21594,6 +22058,15 @@ Deploy freeze period status. | <a id="cijobstatussuccess"></a>`SUCCESS` | A job that is success. | | <a id="cijobstatuswaiting_for_resource"></a>`WAITING_FOR_RESOURCE` | A job that is waiting for resource. | +### `CiJobTokenScopeDirection` + +Direction of access. + +| Value | Description | +| ----- | ----------- | +| <a id="cijobtokenscopedirectioninbound"></a>`INBOUND` | Target projects in the inbound allowlist can access the scope project through their job tokens. | +| <a id="cijobtokenscopedirectionoutbound"></a>`OUTBOUND` | Job token scope project can access target project in the outbound allowlist. | + ### `CiRunnerAccessLevel` | Value | Description | @@ -21659,6 +22132,15 @@ Values for sorting runners. | <a id="cirunnerupgradestatusnot_available"></a>`NOT_AVAILABLE` | Upgrade is not available for the runner. | | <a id="cirunnerupgradestatusrecommended"></a>`RECOMMENDED` | Upgrade is available and recommended for the runner. | +### `CiVariableSort` + +Values for sorting variables. + +| Value | Description | +| ----- | ----------- | +| <a id="civariablesortkey_asc"></a>`KEY_ASC` | Sorted by key in ascending order. | +| <a id="civariablesortkey_desc"></a>`KEY_DESC` | Sorted by key in descending order. | + ### `CiVariableType` | Value | Description | @@ -22212,6 +22694,15 @@ User permission on groups. | <a id="grouppermissioncreate_projects"></a>`CREATE_PROJECTS` | Groups where the user can create projects. | | <a id="grouppermissiontransfer_projects"></a>`TRANSFER_PROJECTS` | Groups where the user can transfer projects to. | +### `GroupReleaseSort` + +Values for sorting releases belonging to a group. + +| Value | Description | +| ----- | ----------- | +| <a id="groupreleasesortreleased_at_asc"></a>`RELEASED_AT_ASC` | Released at by ascending order. | +| <a id="groupreleasesortreleased_at_desc"></a>`RELEASED_AT_DESC` | Released at by descending order. | + ### `HealthStatus` Health status of an issue or epic. @@ -22648,6 +23139,7 @@ Values for sorting projects. | Value | Description | | ----- | ----------- | +| <a id="namespaceprojectsortactivity_desc"></a>`ACTIVITY_DESC` | Sort by latest activity, in descending order. | | <a id="namespaceprojectsortsimilarity"></a>`SIMILARITY` | Most similar to the search query. | | <a id="namespaceprojectsortstorage"></a>`STORAGE` | Sort by storage size. | @@ -23309,6 +23801,7 @@ Verification status of a GPG or X.509 signature for a commit. | ----- | ----------- | | <a id="verificationstatusmultiple_signatures"></a>`MULTIPLE_SIGNATURES` | multiple_signatures verification status. | | <a id="verificationstatusother_user"></a>`OTHER_USER` | other_user verification status. | +| <a id="verificationstatusrevoked_key"></a>`REVOKED_KEY` | revoked_key verification status. | | <a id="verificationstatussame_user_different_email"></a>`SAME_USER_DIFFERENT_EMAIL` | same_user_different_email verification status. | | <a id="verificationstatusunknown_key"></a>`UNKNOWN_KEY` | unknown_key verification status. | | <a id="verificationstatusunverified"></a>`UNVERIFIED` | unverified verification status. | @@ -23507,6 +24000,7 @@ Type of a work item widget. | <a id="workitemwidgettyperequirement_legacy"></a>`REQUIREMENT_LEGACY` | Requirement Legacy widget. | | <a id="workitemwidgettypestart_and_due_date"></a>`START_AND_DUE_DATE` | Start And Due Date widget. | | <a id="workitemwidgettypestatus"></a>`STATUS` | Status widget. | +| <a id="workitemwidgettypetest_reports"></a>`TEST_REPORTS` | Test Reports widget. | | <a id="workitemwidgettypeweight"></a>`WEIGHT` | Weight widget. | ## Scalar types @@ -23724,6 +24218,12 @@ A `DependencyProxyManifestID` is a global ID. It is encoded as a string. An example `DependencyProxyManifestID` is: `"gid://gitlab/DependencyProxy::Manifest/1"`. +### `DeploymentID` + +A `DeploymentID` is a global ID. It is encoded as a string. + +An example `DeploymentID` is: `"gid://gitlab/Deployment/1"`. + ### `DescriptionVersionID` A `DescriptionVersionID` is a global ID. It is encoded as a string. @@ -23882,6 +24382,12 @@ A `IssueID` is a global ID. It is encoded as a string. An example `IssueID` is: `"gid://gitlab/Issue/1"`. +### `IssueParentID` + +A `IssueParentID` is a global ID. It is encoded as a string. + +An example `IssueParentID` is: `"gid://gitlab/IssueParent/1"`. + ### `IterationID` A `IterationID` is a global ID. It is encoded as a string. @@ -24742,6 +25248,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="userreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | | <a id="userreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | +###### `User.savedReply` + +Saved reply authored by the user. Will not return saved reply if `saved_replies` feature flag is disabled. + +Returns [`SavedReply`](#savedreply). + +####### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="usersavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + ###### `User.snippets` Snippets authored by the user. @@ -24836,6 +25354,7 @@ Implementations: - [`WorkItemWidgetRequirementLegacy`](#workitemwidgetrequirementlegacy) - [`WorkItemWidgetStartAndDueDate`](#workitemwidgetstartandduedate) - [`WorkItemWidgetStatus`](#workitemwidgetstatus) +- [`WorkItemWidgetTestReports`](#workitemwidgettestreports) - [`WorkItemWidgetWeight`](#workitemwidgetweight) ##### Fields @@ -25041,6 +25560,7 @@ Values for ordering deployments by a specific field. | <a id="epicfilterslabelname"></a>`labelName` | [`[String]`](#string) | Filter by label name. | | <a id="epicfiltersmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="epicfiltersnot"></a>`not` | [`NegatedEpicBoardIssueInput`](#negatedepicboardissueinput) | Negated epic arguments. | +| <a id="epicfiltersor"></a>`or` | [`UnionedEpicFilterInput`](#unionedepicfilterinput) | List of arguments with inclusive OR. Ignored unless `or_issuable_queries` flag is enabled. | | <a id="epicfilterssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | ### `EpicTreeNodeFieldsInputType` @@ -25231,6 +25751,14 @@ Fields that are available when modifying release assets. | ---- | ---- | ----------- | | <a id="releaseassetsinputlinks"></a>`links` | [`[ReleaseAssetLinkInput!]`](#releaseassetlinkinput) | List of asset links to associate to the release. | +### `RequirementLegacyFilterInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="requirementlegacyfilterinputlegacyiids"></a>`legacyIids` | [`[String!]!`](#string) | List of legacy requirement IIDs of work items. or example `["1", "2"]`. | + ### `SastCiConfigurationAnalyzersEntityInput` Represents the analyzers entity in SAST CI configuration. @@ -25307,6 +25835,15 @@ A time-frame defined as a closed inclusive range of two dates. | <a id="timeframeend"></a>`end` | [`Date!`](#date) | End of the range. | | <a id="timeframestart"></a>`start` | [`Date!`](#date) | Start of the range. | +### `UnionedEpicFilterInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="unionedepicfilterinputauthorusername"></a>`authorUsername` | [`[String!]`](#string) | Filters epics that are authored by one of the given users. | +| <a id="unionedepicfilterinputlabelname"></a>`labelName` | [`[String!]`](#string) | Filters epics that have at least one of the given labels. | + ### `UnionedIssueFilterInput` #### Arguments diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md index 2f3459a6121..82065590b33 100644 --- a/doc/api/group_access_tokens.md +++ b/doc/api/group_access_tokens.md @@ -20,7 +20,7 @@ GET groups/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens" @@ -56,7 +56,7 @@ GET groups/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | ID of the group access token | ```shell @@ -92,7 +92,7 @@ POST groups/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `name` | String | yes | Name of the group 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 | Access level. Valid values are `10` (Guest), `20` (Reporter), `30` (Developer), `40` (Maintainer), and `50` (Owner). | @@ -135,7 +135,7 @@ DELETE groups/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | ID of the group access token | ```shell diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 46f0a28e945..ede7591c6d1 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -36,7 +36,7 @@ GET /groups/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | no | Name of the badges to return (case-sensitive). | ```shell @@ -69,7 +69,7 @@ GET /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -80,6 +80,7 @@ Example response: ```json { + "name": "Coverage", "id": 1, "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}", "image_url": "https://shields.io/my/badge", @@ -99,13 +100,14 @@ POST /groups/:id/badges | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link | | `image_url` | string | yes | URL of the badge image | +| `name` | string | no | Name of the badge | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ - --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&position=0" \ + --data "link_url=https://gitlab.com/gitlab-org/gitlab-foss/commits/master&image_url=https://shields.io/my/badge1&name=mybadge&position=0" \ "https://gitlab.example.com/api/v4/groups/:id/badges" ``` @@ -114,6 +116,7 @@ Example response: ```json { "id": 1, + "name": "mybadge", "link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", "image_url": "https://shields.io/my/badge1", "rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", @@ -132,10 +135,11 @@ PUT /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | | `link_url` | string | no | URL of the badge link | | `image_url` | string | no | URL of the badge image | +| `name` | string | no | Name of the badge | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -147,6 +151,7 @@ Example response: ```json { "id": 1, + "name": "mybadge", "link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", "image_url": "https://shields.io/my/badge", "rendered_link_url": "https://gitlab.com/gitlab-org/gitlab-foss/commits/master", @@ -165,7 +170,7 @@ DELETE /groups/:id/badges/:badge_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -182,7 +187,7 @@ GET /groups/:id/badges/render | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link| | `image_url` | string | yes | URL of the badge image | diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index d08a84aea61..f01c33607a7 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -21,7 +21,7 @@ GET /groups/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/boards" @@ -138,7 +138,7 @@ GET /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -252,7 +252,7 @@ POST /groups/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the new board | ```shell @@ -291,7 +291,7 @@ PUT /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | ---------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `name` | string | no | The new name of the board | | `hide_backlog_list` | boolean | no | Hide the Open list | @@ -359,7 +359,7 @@ DELETE /groups/:id/boards/:board_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -377,7 +377,7 @@ GET /groups/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```shell @@ -428,7 +428,7 @@ GET /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | @@ -460,7 +460,7 @@ POST /groups/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `label_id` | integer | yes | The ID of a label | @@ -501,7 +501,7 @@ PUT /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | | `position` | integer | yes | The position of the list | @@ -534,7 +534,7 @@ DELETE /groups/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index ed50594c73a..daffda8340c 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -31,7 +31,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | Example request: @@ -100,7 +100,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -169,7 +169,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------------------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `name` | string | yes | The name of the cluster | | `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | @@ -240,7 +240,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | string | no | The name of the cluster | | `domain` | string | no | The [base domain](../user/group/clusters/index.md#base-domain) of the cluster | @@ -325,7 +325,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/group_epic_boards.md b/doc/api/group_epic_boards.md new file mode 100644 index 00000000000..e85147a2868 --- /dev/null +++ b/doc/api/group_epic_boards.md @@ -0,0 +1,273 @@ +--- +stage: Plan +group: Product Planning +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Group epic boards API **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385903) in GitLab 15.9. + +Every API call to [group epic boards](../user/group/epics/epic_boards.md#epic-boards) must be authenticated. + +If a user is not a member of a group and the group is private, a `GET` +request results in `404` status code. + +## List all epic boards in a group + +Lists epic boards in the given group. + +```plaintext +GET /groups/:id/epic_boards +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epic_boards" +``` + +Example response: + +```json +[ + { + "id": 1, + "name": "group epic board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "hide_backlog_list": false, + "hide_closed_list": false, + "labels": [ + { + "id": 1, + "title": "Board Label", + "color": "#c21e56", + "description": "label applied to the epic board", + "group_id": 5, + "project_id": null, + "template": false, + "text_color": "#FFFFFF", + "created_at": "2023-01-27T10:40:59.738Z", + "updated_at": "2023-01-27T10:40:59.738Z" + } + ], + "lists": [ + { + "id": 1, + "label": { + "id": 69, + "name": "Testing", + "color": "#F0AD4E", + "description": null + }, + "position": 1, + "list_type": "label" + }, + { + "id": 2, + "label": { + "id": 70, + "name": "Ready", + "color": "#FF0000", + "description": null + }, + "position": 2, + "list_type": "label" + }, + { + "id": 3, + "label": { + "id": 71, + "name": "Production", + "color": "#FF5F00", + "description": null + }, + "position": 3, + "list_type": "label" + } + ] + } +] +``` + +## Single group epic board + +Gets a single group epic board. + +```plaintext +GET /groups/:id/epic_boards/:board_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user | +| `board_id` | integer | yes | The ID of an epic board | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epic_boards/1" +``` + +Example response: + +```json + { + "id": 1, + "name": "group epic board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "labels": [ + { + "id": 1, + "title": "Board Label", + "color": "#c21e56", + "description": "label applied to the epic board", + "group_id": 5, + "project_id": null, + "template": false, + "text_color": "#FFFFFF", + "created_at": "2023-01-27T10:40:59.738Z", + "updated_at": "2023-01-27T10:40:59.738Z" + } + ], + "lists" : [ + { + "id" : 1, + "label" : { + "id": 69, + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1, + "list_type": "label" + }, + { + "id" : 2, + "label" : { + "id": 70, + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2, + "list_type": "label" + }, + { + "id" : 3, + "label" : { + "id": 71, + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3, + "list_type": "label" + } + ] + } +``` + +## List group epic board lists + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385904) in GitLab 15.9. + +Gets a list of the epic board's lists. +Does not include `open` and `closed` lists. + +```plaintext +GET /groups/:id/epic_boards/:board_id/lists +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user | +| `board_id` | integer | yes | The ID of an epic board | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epic_boards/1/lists" +``` + +Example response: + +```json +[ + { + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1, + "list_type" : "label", + "collapsed" : false + }, + { + "id" : 2, + "label" : { + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2, + "list_type" : "label", + "collapsed" : false + }, + { + "id" : 3, + "label" : { + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3, + "list_type" : "label", + "collapsed" : false + } +] +``` + +## Single group epic board list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385904) in GitLab 15.9. + +Gets a single board list. + +```plaintext +GET /groups/:id/epic_boards/:board_id/lists/:list_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) accessible by the authenticated user | +| `board_id` | integer | yes | The ID of an epic board | +| `list_id` | integer | yes | The ID of an epic board's list | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epic_boards/1/lists/1" +``` + +Example response: + +```json +{ + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1, + "list_type" : "label", + "collapsed" : false +} +``` diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 989b7a66285..c648b6bad37 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -87,7 +87,7 @@ POST /groups/import | `name` | string | yes | The name of the group to be imported | | `path` | string | yes | Name and path for new group | | `file` | string | yes | The file to be uploaded | -| `parent_id` | integer | no | ID of a parent group that the group will be imported into. Defaults to the current user's namespace if not provided. | +| `parent_id` | integer | no | ID of a parent group to import the group into. Defaults to the current user's namespace if not provided. | To upload a file from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index 988986d8965..3c445ee09dd 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -26,7 +26,7 @@ GET /groups/:id/iterations?include_ancestors=false | Attribute | Type | Required | Description | | ------------------- | ------- | -------- | ----------- | -| `state` | string | no | 'Return `opened`, `upcoming`, `current (previously started)`, `closed`, or `all` iterations. Filtering by `started` state is deprecated starting with 14.1, please use `current` instead.' | +| `state` | string | no | 'Return `opened`, `upcoming`, `current (previously started)`, `closed`, or `all` iterations. Filtering by `started` state is deprecated starting with 14.1, use `current` instead.' | | `search` | string | no | Return only iterations with a title matching the provided string. | | `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index f33f181336f..298847f929b 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -25,7 +25,7 @@ GET /groups/:id/labels | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543) in GitLab 12.2)_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -77,7 +77,7 @@ GET /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -114,7 +114,7 @@ POST /groups/:id/labels | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | | `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label, | @@ -152,7 +152,7 @@ PUT /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `new_name` | string | no | The new name of the label | | `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | @@ -193,7 +193,7 @@ DELETE /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -214,7 +214,7 @@ POST /groups/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -250,7 +250,7 @@ POST /groups/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index f6b47118b5f..4037a778d7f 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -18,7 +18,7 @@ GET /groups/:id/variables | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" @@ -57,7 +57,7 @@ GET /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | ```shell @@ -86,13 +86,13 @@ POST /groups/:id/variables | Attribute | Type | required | Description | |-----------------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `raw` | boolean | no | Whether the variable is expandable | +| `raw` | boolean | no | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | | `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell @@ -122,13 +122,13 @@ PUT /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `raw` | boolean | no | Whether the variable is expandable | +| `raw` | boolean | no | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | | `environment_scope` **(PREMIUM)** | string | no | The [environment scope](../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) of a variable | ```shell @@ -158,7 +158,7 @@ DELETE /groups/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | ```shell diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 824c4eb4678..fc95230cbba 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -27,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | | `state` | string | no | Return only `active` or `closed` milestones | | `title` | string | no | Return only the milestones having the given `title` | @@ -71,7 +71,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the group milestone | ## Create new milestone @@ -86,7 +86,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of a milestone | | `description` | string | no | The description of the milestone | | `due_date` | date | no | The due date of the milestone, in ISO 8601 format (`YYYY-MM-DD`) | @@ -104,7 +104,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | | `title` | string | no | The title of a milestone | | `description` | string | no | The description of a milestone | @@ -124,7 +124,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the group's milestone | ## Get all issues assigned to a single milestone @@ -139,7 +139,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | Currently, this API endpoint doesn't return issues from any subgroups. @@ -159,7 +159,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | ## Get all burndown chart events for a single milestone **(PREMIUM)** @@ -177,5 +177,5 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of a group milestone | diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index ecd433bf321..3003b6b840f 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -34,7 +34,7 @@ GET /groups/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/" @@ -70,7 +70,7 @@ GET /groups/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| ```shell @@ -105,7 +105,7 @@ POST /groups/:id/protected_environments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. | | `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | @@ -148,7 +148,7 @@ PUT /groups/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| | `deploy_access_levels` | array | no | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. | | `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | @@ -314,7 +314,7 @@ DELETE /groups/:id/protected_environments/:name | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| ```shell diff --git a/doc/api/group_releases.md b/doc/api/group_releases.md index 1918d0a54b9..9c395adbe04 100644 --- a/doc/api/group_releases.md +++ b/doc/api/group_releases.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Review your groups' [releases](../user/project/releases/index.md) with the REST API. NOTE: -For information about the project releases API, visit the [Releases API](releases/index.md) page. +For more information about the project releases API, see [Releases API](releases/index.md). FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `group_releases_finder_inoperator`. @@ -27,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|----------------|----------|---------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `sort` | string | no | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. | | `simple` | boolean | no | Return only limited fields for each release. | diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index a207775cf45..8d685c75f60 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -32,7 +32,7 @@ push new commits: The repository is temporarily read-only. Please try again later. ``` -This API requires you to [authenticate yourself](index.md#authentication) as an administrator. +This API requires you to [authenticate yourself](rest/index.md#authentication) as an administrator. APIs are also available to move other types of repositories: @@ -46,7 +46,7 @@ GET /group_repository_storage_moves ``` By default, `GET` requests return 20 results at a time, because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Example request: @@ -82,7 +82,7 @@ GET /groups/:group_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time, because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Supported attributes: diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index d5fe7825dc6..6fb74ea00b7 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -25,7 +25,7 @@ GET /groups/:id/wikis | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `with_content` | boolean | no | Include pages' content | ```shell @@ -69,7 +69,7 @@ GET /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | | `render_html` | boolean | no | Return the rendered HTML of the wiki page | | `version` | string | no | Wiki page version SHA | @@ -100,7 +100,7 @@ POST /projects/:id/wikis | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `content` | string | yes | The content of the wiki page | | `title` | string | yes | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -133,7 +133,7 @@ PUT /groups/:id/wikis/:slug | Attribute | Type | Required | Description | |-----------|----------------|----------------------------------|-------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `content` | string | yes if `title` is not provided | The content of the wiki page. | | `title` | string | yes if `content` is not provided | The title of the wiki page. | | `format` | string | no | The format of the wiki page. Available formats are `markdown` (default), `rdoc`, `asciidoc`, and `org`. | @@ -167,7 +167,7 @@ DELETE /groups/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell @@ -187,7 +187,7 @@ POST /groups/:id/wikis/attachments | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `file` | string | yes | The attachment to be uploaded | | `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | diff --git a/doc/api/groups.md b/doc/api/groups.md index 0e093759a80..8b4850fa6de 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -11,9 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Get a list of visible groups for the authenticated user. When accessed without authentication, only public groups are returned. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). -When accessed without authentication, this endpoint also supports [keyset pagination](index.md#keyset-based-pagination): +When accessed without authentication, this endpoint also supports [keyset pagination](rest/index.md#keyset-based-pagination): - When requesting consecutive pages of results, we recommend you use keyset pagination. - Beyond a specific offset limit (specified by [max offset allowed by the REST API for offset-based pagination](../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination)), offset pagination is unavailable. @@ -127,7 +127,7 @@ GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_valu Get a list of visible direct subgroups in this group. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). If you request this list as: @@ -139,7 +139,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | ----------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) of the immediate parent group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) of the immediate parent group | | `skip_groups` | array of integers | no | Skip the group IDs passed | | `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators); Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria. Only subgroup short paths are searched (not full paths) | @@ -191,13 +191,13 @@ GET /groups/:id/subgroups Get a list of visible descendant groups of this group. When accessed without authentication, only public groups are returned. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). Parameters: | Attribute | Type | Required | Description | | ------------------------ | ----------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) of the immediate parent group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) of the immediate parent group | | `skip_groups` | array of integers | no | Skip the group IDs passed | | `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators). Attributes `owned` and `min_access_level` have precedence | | `search` | string | no | Return the list of authorized groups matching the search criteria. Only descendant group short paths are searched (not full paths) | @@ -271,7 +271,7 @@ GET /groups/:id/descendant_groups Get a list of projects in this group. When accessed without authentication, only public projects are returned. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). ```plaintext GET /groups/:id/projects @@ -281,7 +281,7 @@ Parameters: | Attribute | Type | Required | Description | | -------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `archived` | boolean | no | Limit by archived status | | `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity` (1), or `last_activity_at` fields. Default is `created_at` | @@ -354,7 +354,7 @@ To distinguish between a project in the group and a project shared to the group, Get a list of projects shared to this group. When accessed without authentication, only public shared projects are returned. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). ```plaintext GET /groups/:id/projects/shared @@ -364,7 +364,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `archived` | boolean | no | Limit by archived status | | `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | @@ -502,7 +502,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------ | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only). | | `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | @@ -871,8 +871,8 @@ Parameters: | Attribute | Type | Required | Description | | ------------ | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the target group](index.md#namespaced-path-encoding) | -| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the target group](rest/index.md#namespaced-path-encoding) | +| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -891,7 +891,7 @@ GET /groups/:id/transfer_locations | Attribute | Type | Required | Description | |-------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group to be transferred](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group to be transferred](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | The group names to search for. | Example request: @@ -993,6 +993,7 @@ PUT /groups/:id | `unique_project_download_limit` **(ULTIMATE)** | integer | no | Maximum number of unique projects a user can download in the specified time period before they are banned. Available only on top-level groups. Default: 0, Maximum: 10,000. | | `unique_project_download_limit_interval_in_seconds` **(ULTIMATE)** | integer | no | Time period during which a user can download a maximum amount of projects before they are banned. Available only on top-level groups. Default: 0, Maximum: 864,000 seconds (10 days). | | `unique_project_download_limit_allowlist` **(ULTIMATE)** | array of strings | no | List of usernames excluded from the unique project download limit. Available only on top-level groups. Default: `[]`, Maximum: 100 usernames. | +| `unique_project_download_limit_alertlist` **(ULTIMATE)** | array of integers | no | List of user IDs that are emailed when the unique project download limit is exceeded. Available only on top-level groups. Default: `[]`, Maximum: 100 user IDs. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110201) in GitLab 15.9. | | `auto_ban_user_on_excessive_projects_download` **(ULTIMATE)** | boolean | no | When enabled, users are automatically banned from the group when they download more than the maximum number of unique projects specified by `unique_project_download_limit` and `unique_project_download_limit_interval_in_seconds`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94159) in GitLab 15.4. | | `ip_restriction_ranges` **(PREMIUM)** | string | no | Comma-separated list of IP addresses or subnet masks to restrict group access. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351493) in GitLab 15.4. | @@ -1135,6 +1136,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab > - Immediately deleting subgroups was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360008) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `immediate_delete_subgroup_api`. Disabled by default. > - Immediately deleting subgroups was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) in GitLab 15.4. > - Immediately deleting subgroups was [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) by default in GitLab 15.4. +> - The flag `immediate_delete_subgroup_api` for immediately deleting subgroups was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/374069) in GitLab 15.9. Only available to group owners and administrators. @@ -1152,7 +1154,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------------|------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `permanently_remove` **(PREMIUM)** | boolean/string | no | Immediately deletes a subgroup if it is marked for deletion. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) in GitLab 15.4 | | `full_path` **(PREMIUM)** | string | no | Full path of subgroup to use with `permanently_remove`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368276) in GitLab 15.4. To find the subgroup path, see the [group details](groups.md#details-of-a-group) | @@ -1175,7 +1177,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ## Search for group @@ -1200,7 +1202,8 @@ GET /groups?search=foobar > Introduced in GitLab 14.8. -Get a list of users provisioned by a given group. Does not include users provisioned by subgroups. +Get a list of users provisioned by a given group. Does not include subgroups. +Users in this list are considered [enterprise users](../user/enterprise_user/index.md). Requires at least the Maintainer role on the group. @@ -1212,7 +1215,7 @@ Parameters: | Attribute | Type | Required | Description | |:-----------------|:---------------|:---------|:-------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/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 | @@ -1284,7 +1287,7 @@ GET /groups/:id/hooks | Attribute | Type | Required | Description | | --------- | --------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ### Get group hook @@ -1292,7 +1295,7 @@ Get a specific hook for a group. | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of a group hook | ```plaintext @@ -1319,6 +1322,10 @@ GET /groups/:id/hooks/:hook_id "releases_events": true, "subgroup_events": true, "enable_ssl_verification": true, + "repository_update_events": false, + "alert_status": "executable", + "disabled_until": null, + "url_variables": [ ], "created_at": "2012-10-12T17:04:47Z" } ``` @@ -1333,7 +1340,7 @@ POST /groups/:id/hooks | Attribute | Type | Required | Description | | -----------------------------| -------------- |----------| ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | | `push_events_branch_filter` | string | No | Trigger hook on push events for matching branches only. | @@ -1362,7 +1369,7 @@ PUT /groups/:id/hooks/:hook_id | Attribute | Type | Required | Description | | ---------------------------- | -------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `hook_id` | integer | yes | The ID of the group hook. | | `url` | string | yes | The hook URL. | | `push_events` | boolean | no | Trigger hook on push events. | @@ -1393,7 +1400,7 @@ DELETE /groups/:id/hooks/:hook_id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the group hook. | ## Group Audit Events **(PREMIUM)** @@ -1430,7 +1437,7 @@ GET /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ### Add LDAP group link with CN or filter **(PREMIUM SELF)** @@ -1442,7 +1449,7 @@ POST /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cn` | string | no | The CN of an LDAP group | | `filter` | string | no | The LDAP filter for the group | | `group_access` | integer | yes | [Role (`access_level`)](members.md#roles) for members of the LDAP group | @@ -1461,7 +1468,7 @@ DELETE /groups/:id/ldap_group_links/:cn | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | Deletes an LDAP group link for a specific LDAP provider. Deprecated. Scheduled for removal in a future release. @@ -1472,7 +1479,7 @@ DELETE /groups/:id/ldap_group_links/:provider/:cn | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cn` | string | yes | The CN of an LDAP group | | `provider` | string | yes | LDAP provider for the LDAP group link | @@ -1486,7 +1493,7 @@ DELETE /groups/:id/ldap_group_links | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `cn` | string | no | The CN of an LDAP group | | `filter` | string | no | The LDAP filter for the group | | `provider` | string | yes | LDAP provider for the LDAP group link | @@ -1513,9 +1520,9 @@ Supported attributes: | Attribute | Type | Required | Description | |:----------|:---------------|:---------|:-------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | -If successful, returns [`200`](index.md#status-codes) and the following response attributes: +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | |:-------------------|:--------|:-----------------------------------------------------------------------------| @@ -1555,10 +1562,10 @@ Supported attributes: | Attribute | Type | Required | Description | |:-------------------|:---------------|:---------|:-------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `saml_group_name` | string | yes | Name of an SAML group | -If successful, returns [`200`](index.md#status-codes) and the following response attributes: +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | |:---------------|:--------|:-----------------------------------------------------------------------------| @@ -1592,11 +1599,11 @@ Supported attributes: | Attribute | Type | Required | Description | |:-------------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `saml_group_name` | string | yes | Name of a SAML group | | `access_level` | integer | yes | [Role (`access_level`)](members.md#roles) for members of the SAML group | -If successful, returns [`201`](index.md#status-codes) and the following response attributes: +If successful, returns [`201`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | |:---------------|:--------|:-----------------------------------------------------------------------------| @@ -1630,10 +1637,10 @@ Supported attributes: | Attribute | Type | Required | Description | |:-------------------|:---------------|:---------|:-------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `saml_group_name` | string | yes | Name of a SAML group | -If successful, returns [`204`](index.md#status-codes) status code without any response body. +If successful, returns [`204`](rest/index.md#status-codes) status code without any response body. Example request: @@ -1681,7 +1688,7 @@ POST /groups/:id/share | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | | `group_access` | integer | yes | The [role (`access_level`)](members.md#roles) to grant the group | | `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | @@ -1696,7 +1703,7 @@ DELETE /groups/:id/share/:group_id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | ## Push Rules **(PREMIUM)** @@ -1715,7 +1722,7 @@ GET /groups/:id/push_rule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the group or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID of the group or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | ```json { @@ -1758,7 +1765,7 @@ POST /groups/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `deny_delete_tag` | boolean | no | Deny deleting a tag | | `member_check` | boolean | no | Allows only GitLab users to author commits | | `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | @@ -1805,7 +1812,7 @@ PUT /groups/:id/push_rule | Attribute | Type | Required | Description | | --------------------------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `deny_delete_tag` | boolean | no | Deny deleting a tag | | `member_check` | boolean | no | Restricts commits to be authored by existing GitLab users only | | `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | @@ -1852,4 +1859,4 @@ DELETE /groups/:id/push_rule | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | diff --git a/doc/api/import.md b/doc/api/import.md index 67ee7bc60a1..5e9fbf30226 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -12,7 +12,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import your projects from GitHub to GitLab using the API. -The namespace set in `target_namespace` must exist. The namespace can be your user namespace or an existing group that you have at least the Developer role for. +The namespace set in `target_namespace` must exist. The namespace can be your user namespace or an existing group that +you have at least the Maintainer role for. Using the Developer role for this purpose was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. ```plaintext POST /import/github diff --git a/doc/api/index.md b/doc/api/index.md index 8075b667a67..110534ceced 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -4,812 +4,14 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# API Docs **(FREE)** +# Develop with GitLab **(FREE)** -Use the GitLab APIs to automate GitLab. +Automate and interact with GitLab, and integrate with external applications. -## REST API - -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). - -You can also use a partial [OpenAPI definition](openapi/openapi_interactive.md), -to test the API directly from the GitLab user interface. -Contributions are welcome. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an introduction and basic steps, see -[How to make GitLab API calls](https://www.youtube.com/watch?v=0LsMC3ZiXkA). - -## GraphQL API - -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. - -GraphQL co-exists with the current v4 REST API. If we have a v5 API, this should -be a compatibility layer on top of GraphQL. - -There were some patenting and licensing concerns with GraphQL. However, these -have been resolved to our satisfaction. The reference implementations -were re-licensed under MIT, and the OWF license used for the GraphQL specification. - -## Compatibility guidelines - -The HTTP API is versioned with a single number, which is currently `4`. This number -symbolizes the major version number, as described by [SemVer](https://semver.org/). -Because of this, backward-incompatible changes require this version number to -change. - -The minor version isn't explicit, which allows for a stable API -endpoint. New features can be added to the API in the same -version number. - -New features and bug fixes are released in tandem with GitLab. Apart -from incidental patch and security releases, GitLab is released on the 22nd of each -month. Major API version changes, and removal of entire API versions, are done in tandem -with major GitLab releases. - -All deprecations and changes between versions are in the documentation. - -### Current status - -Only API version v4 is available. - -## How to use the API - -API requests must include both `api` and the API version. The API -version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/api.rb). -For example, the root of the v4 API is at `/api/v4`. - -### Valid API request - -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" -``` - -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: - -```shell -curl --include "https://gitlab.example.com/api/v4/projects" -HTTP/2 200 -... -``` - -This request can help you investigate an unexpected response. - -### API request that includes the exit code - -If you want to expose the HTTP exit code, include the `--fail` option: - -```shell -curl --fail "https://gitlab.example.com/api/v4/does-not-exist" -curl: (22) The requested URL returned error: 404 -``` - -The HTTP exit code can help you diagnose the success or failure of your REST request. - -## Authentication - -Most API requests require authentication, or only return public data when -authentication isn't provided. When authentication is not required, the documentation -for each endpoint specifies this. For example, the -[`/projects/:id` endpoint](projects.md#get-single-project) does not require authentication. - -There are several ways you can authenticate with the GitLab API: - -- [OAuth2 tokens](#oauth2-tokens) -- [Personal access tokens](../user/profile/personal_access_tokens.md) -- [Project access tokens](../user/project/settings/project_access_tokens.md) -- [Group access tokens](../user/group/settings/group_access_tokens.md) -- [Session cookie](#session-cookie) -- [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) **(Specific endpoints only)** - -Project access tokens are supported by: - -- Self-managed GitLab Free and higher. -- GitLab SaaS Premium and higher. - -If you are an administrator, you or your application can authenticate as a specific user. -To do so, use: - -- [Impersonation tokens](#impersonation-tokens) -- [Sudo](#sudo) - -If authentication information is not valid or is missing, GitLab returns an error -message with a status code of `401`: - -```json -{ - "message": "401 Unauthorized" -} -``` - -NOTE: -Deploy tokens can't be used with the GitLab public API. For details, see -[Deploy Tokens](../user/project/deploy_tokens/index.md). - -### OAuth2 tokens - -You can use an [OAuth2 token](oauth2.md) to authenticate with the API by passing -it in either the `access_token` parameter or the `Authorization` header. - -Example of using the OAuth2 token in a parameter: - -```shell -curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN" -``` - -Example of using the OAuth2 token in a header: - -```shell -curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects" -``` - -Read more about [GitLab as an OAuth2 provider](oauth2.md). - -NOTE: -We recommend OAuth access tokens have an expiration. You can use the `refresh_token` parameter -to refresh tokens. Integrations may need to be updated to use refresh tokens prior to -expiration, which is based on the [`expires_in`](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14) -property in the token endpoint response. See [OAuth2 token](oauth2.md) documentation -for examples requesting a new access token using a refresh token. - -A default refresh setting of two hours is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336598). - -### Personal/project/group access tokens - -You can use access tokens to authenticate with the API by passing it in either -the `private_token` parameter or the `PRIVATE-TOKEN` header. - -Example of using the personal, project, or group access token in a parameter: - -```shell -curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>" -``` - -Example of using the personal, project, or group access token in a header: - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" -``` - -You can also use personal, project, or group access tokens with OAuth-compliant headers: - -```shell -curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects" -``` - -### Session cookie - -Signing in to the main GitLab application sets a `_gitlab_session` cookie. The -API uses this cookie for authentication if it's present. Using the API to -generate a new session cookie isn't supported. - -The primary user of this authentication method is the web frontend of GitLab -itself. The web frontend can use the API as the authenticated user to get a -list of projects without explicitly passing an access token. - -### Impersonation tokens - -Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md). -They can be created only by an administrator, and are used to authenticate with the -API as a specific user. - -Use impersonation tokens as an alternative to: - -- The user's password or one of their personal access tokens. -- The [Sudo](#sudo) feature. The user's or administrator's password or token - may not be known, or may change over time. - -For more information, see the [users API](users.md#create-an-impersonation-token) -documentation. - -Impersonation tokens are used exactly like regular personal access tokens, and -can be passed in either the `private_token` parameter or the `PRIVATE-TOKEN` -header. - -#### Disable impersonation - -By default, impersonation is enabled. To disable impersonation: - -**For Omnibus installations** - -1. Edit the `/etc/gitlab/gitlab.rb` file: - - ```ruby - gitlab_rails['impersonation_enabled'] = false - ``` - -1. Save the file, and then [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - GitLab for the changes to take effect. - -To re-enable impersonation, remove this configuration, and then reconfigure -GitLab. - -**For installations from source** - -1. Edit the `config/gitlab.yml` file: - - ```yaml - gitlab: - impersonation_enabled: false - ``` - -1. Save the file, and then [restart](../administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. - -To re-enable impersonation, remove this configuration, and then restart GitLab. - -### Sudo - -All API requests support performing an API request as if you were another user, -provided you're authenticated as an administrator with an OAuth or personal -access token that has the `sudo` scope. The API requests are executed with the -permissions of the impersonated user. - -As an [administrator](../user/permissions.md), pass the `sudo` parameter either -by using query string or a header with an ID or username (case insensitive) of -the user you want to perform the operation as. If passed as a header, the header -name must be `Sudo`. - -If a non administrative access token is provided, GitLab returns an error -message with a status code of `403`: - -```json -{ - "message": "403 Forbidden - Must be admin to use sudo" -} -``` - -If an access token without the `sudo` scope is provided, an error message is -returned with a status code of `403`: - -```json -{ - "error": "insufficient_scope", - "error_description": "The request requires higher privileges than provided by the access token.", - "scope": "sudo" -} -``` - -If the sudo user ID or username cannot be found, an error message is -returned with a status code of `404`: - -```json -{ - "message": "404 User with ID or username '123' Not Found" -} -``` - -Example of a valid API request and a request using cURL with sudo request, -providing a username: - -```plaintext -GET /projects?private_token=<your_access_token>&sudo=username -``` - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" -``` - -Example of a valid API request and a request using cURL with sudo request, -providing an ID: - -```plaintext -GET /projects?private_token=<your_access_token>&sudo=23 -``` - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" -``` - -## Status codes - -The API is designed to return different status codes according to context and -action. This way, if a request results in an error, you can get -insight into what went wrong. - -The following table gives an overview of how the API functions generally behave. - -| Request type | Description | -|---------------|-------------| -| `GET` | Access one or more resources and return the result as JSON. | -| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | -| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. | -| `DELETE` | Returns `204 No Content` if the resource was deleted successfully or `202 Accepted` if the resource is scheduled to be deleted. | - -The following table shows the possible return codes for API requests. - -| Return values | Description | -|--------------------------|-------------| -| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, and the resource itself is returned as JSON. | -| `202 Accepted` | The `GET`, `PUT` or `DELETE` request was successful, and the resource is scheduled for processing. | -| `204 No Content` | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. | -| `201 Created` | The `POST` request was successful, and the resource is returned as JSON. | -| `304 Not Modified` | The resource hasn't been modified since the last request. | -| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | -| `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | -| `403 Forbidden` | The request isn't allowed. For example, the user isn't allowed to delete a project. | -| `404 Not Found` | A resource couldn't be accessed. For example, an ID for a resource couldn't be found. | -| `405 Method Not Allowed` | The request isn't supported. | -| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | -| `412` | The request was denied. This can happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | -| `422 Unprocessable` | The entity couldn't be processed. | -| `429 Too Many Requests` | The user exceeded the [application rate limits](../administration/instance_limits.md#rate-limits). | -| `500 Server Error` | While handling the request, something went wrong on the server. | - -## Pagination - -GitLab supports the following pagination methods: - -- Offset-based pagination. This is the default method and is available on all endpoints. -- Keyset-based pagination. Added to selected endpoints but being - [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). - -For large collections, for performance reasons we recommend keyset pagination -(when available) instead of offset pagination. - -### Offset-based pagination - -Sometimes, the returned result spans many pages. When listing resources, you can -pass the following parameters: - -| Parameter | Description | -|------------|-------------| -| `page` | Page number (default: `1`). | -| `per_page` | Number of items to list per page (default: `20`, max: `100`). | - -In the following example, we list 50 [namespaces](namespaces.md) per page: - -```shell -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50" -``` - -NOTE: -There is a [max offset allowed limit](../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination) for offset pagination. You can change the limit in self-managed instances. - -#### Pagination `Link` header - -[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each -response. They have `rel` set to `prev`, `next`, `first`, or `last` and contain -the relevant URL. Be sure to use these links instead of generating your own URLs. - -For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). - -In the following cURL example, we limit the output to three items per page -(`per_page=3`) and we request the second page (`page=2`) of [comments](notes.md) -of the issue with ID `8` which belongs to the project with ID `9`: - -```shell -curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" -``` - -The response is: - -```http -HTTP/2 200 OK -cache-control: no-cache -content-length: 1103 -content-type: application/json -date: Mon, 18 Jan 2016 09:43:18 GMT -link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last" -status: 200 OK -vary: Origin -x-next-page: 3 -x-page: 2 -x-per-page: 3 -x-prev-page: 1 -x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86 -x-runtime: 0.108688 -x-total: 8 -x-total-pages: 3 -``` - -#### Other pagination headers - -GitLab also returns the following additional pagination headers: - -| Header | Description | -|-----------------|-------------| -| `x-next-page` | The index of the next page. | -| `x-page` | The index of the current page (starting at 1). | -| `x-per-page` | The number of items per page. | -| `x-prev-page` | The index of the previous page. | -| `x-total` | The total number of items. | -| `x-total-pages` | The total number of pages. | - -For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). - -### Keyset-based pagination - -Keyset-pagination allows for more efficient retrieval of pages and - in contrast -to offset-based pagination - runtime is independent of the size of the -collection. - -This method is controlled by the following parameters. `order_by` and `sort` are both mandatory. - -| Parameter | Required | Description | -|--------------| ------------ | --------- | -| `pagination` | yes | `keyset` (to enable keyset pagination). | -| `per_page` | no | Number of items to list per page (default: `20`, max: `100`). | -| `order_by` | yes | Column by which to order by. | -| `sort` | yes | Sort order (`asc` or `desc`) | - -In the following example, we list 50 [projects](projects.md) per page, ordered -by `id` ascending. - -```shell -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" -``` - -The response header includes a link to the next page. For example: - -```http -HTTP/1.1 200 OK -... -Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" -Status: 200 OK -... -``` - -The link to the next page contains an additional filter `id_after=42` that -excludes already-retrieved records. - -As another example, the following request lists 50 [groups](groups.md) per page ordered -by `name` ascending using keyset pagination: - -```shell -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc" -``` - -The response header includes a link to the next page: - -```http -HTTP/1.1 200 OK -... -Link: <https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc&cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9>; rel="next" -Status: 200 OK -... -``` - -The link to the next page contains an additional filter `cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9` that -excludes already-retrieved records. - -The type of filter depends on the -`order_by` option used, and we can have more than one additional filter. - -WARNING: -The `Links` header was removed in GitLab 14.0 to be aligned with the -[W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` -header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) -and should be used instead. - -When the end of the collection is reached and there are no additional -records to retrieve, the `Link` header is absent and the resulting array is -empty. - -We recommend using only the given link to retrieve the next page instead of -building your own URL. Apart from the headers shown, we don't expose additional -pagination headers. - -Keyset-based pagination is supported only for selected resources and ordering -options: - -| Resource | Options | Availability | -|:---------------------------------------------------------|:---------------------------------|:-------------------------------------------------------------------------------------------------------------| -| [Projects](projects.md) | `order_by=id` only | Authenticated and unauthenticated users | -| [Groups](groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | -| [Group audit events](audit_events.md#group-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2) | - -### Pagination response headers - -For performance reasons, if a query returns more than 10,000 records, GitLab -doesn't return the following headers: - -- `x-total`. -- `x-total-pages`. -- `rel="last"` `link` - -## Path parameters - -If an endpoint has path parameters, the documentation displays them with a -preceding colon. - -For example: - -```plaintext -DELETE /projects/:id/share/:group_id -``` - -The `:id` path parameter needs to be replaced with the project ID, and the -`:group_id` needs to be replaced with the ID of the group. The colons `:` -shouldn't be included. - -The resulting cURL request for a project with ID `5` and a group ID of `17` is then: - -```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" -``` - -Path parameters that are required to be URL-encoded must be followed. If not, -it doesn't match an API endpoint and responds with a 404. If there's -something in front of the API (for example, Apache), ensure that it doesn't decode -the URL-encoded path parameters. - -## Namespaced path encoding - -If using namespaced API requests, make sure that the `NAMESPACE/PROJECT_PATH` is -URL-encoded. - -For example, `/` is represented by `%2F`: - -```plaintext -GET /api/v4/projects/diaspora%2Fdiaspora -``` - -A project's _path_ isn't necessarily the same as its _name_. A project's path is -found in the project's URL or in the project's settings, under -**General > Advanced > Change path**. - -## File path, branches, and tags name encoding - -If a file path, branch or tag contains a `/`, make sure it is URL-encoded. - -For example, `/` is represented by `%2F`: - -```plaintext -GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master -GET /api/v4/projects/1/branches/my%2Fbranch/commits -GET /api/v4/projects/1/repository/tags/my%2Ftag -``` - -## Request Payload - -API Requests can use parameters sent as [query strings](https://en.wikipedia.org/wiki/Query_string) -or as a [payload body](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-p3-payload-14#section-3.2). -GET requests usually send a query string, while PUT or POST requests usually -send the payload body: - -- Query string: - - ```shell - curl --request POST "https://gitlab/api/v4/projects?name=<example-name>&description=<example-description>" - ``` - -- Request payload (JSON): - - ```shell - curl --request POST --header "Content-Type: application/json" \ - --data '{"name":"<example-name>", "description":"<example-description>"}' "https://gitlab/api/v4/projects" - ``` - -URL encoded query strings have a length limitation. Requests that are too large -result in a `414 Request-URI Too Large` error message. This can be resolved by -using a payload body instead. - -## Encoding API parameters of `array` and `hash` types - -You can request the API with `array` and `hash` types parameters: - -### `array` - -`import_sources` is a parameter of type `array`: - -```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ --d "import_sources[]=github" \ --d "import_sources[]=bitbucket" \ -"https://gitlab.example.com/api/v4/some_endpoint" -``` - -### `hash` - -`override_params` is a parameter of type `hash`: - -```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ---form "namespace=email" \ ---form "path=impapi" \ ---form "file=@/path/to/somefile.txt" \ ---form "override_params[visibility]=private" \ ---form "override_params[some_other_param]=some_value" \ -"https://gitlab.example.com/api/v4/projects/import" -``` - -### Array of hashes - -`variables` is a parameter of type `array` containing hash key/value pairs -`[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: - -```shell -curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ -"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world" - -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ---header "Content-Type: application/json" \ ---data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \ -"https://gitlab.example.com/api/v4/projects/169/pipeline" -``` - -## `id` vs `iid` - -Some resources have two similarly-named fields. For example, [issues](issues.md), -[merge requests](merge_requests.md), and [project milestones](merge_requests.md). -The fields are: - -- `id`: ID that is unique across all projects. -- `iid`: Additional, internal ID (displayed in the web UI) that's unique in the - scope of a single project. - -If a resource has both the `iid` field and the `id` field, the `iid` field is -usually used instead of `id` to fetch the resource. - -For example, suppose a project with `id: 42` has an issue with `id: 46` and -`iid: 5`. In this case: - -- A valid API request to retrieve the issue is `GET /projects/42/issues/5`. -- An invalid API request to retrieve the issue is `GET /projects/42/issues/46`. - -Not all resources with the `iid` field are fetched by `iid`. For guidance -regarding which field to use, see the documentation for the specific resource. - -## Data validation and error reporting - -When working with the API you may encounter validation errors, in which case -the API returns an HTTP `400` error. - -Such errors appear in the following cases: - -- A required attribute of the API request is missing (for example, the title of - an issue isn't given). -- An attribute did not pass the validation (for example, the user bio is too - long). - -When an attribute is missing, you receive something like: - -```http -HTTP/1.1 400 Bad Request -Content-Type: application/json -{ - "message":"400 (Bad request) \"title\" not given" -} -``` - -When a validation error occurs, error messages are different. They hold -all details of validation errors: - -```http -HTTP/1.1 400 Bad Request -Content-Type: application/json -{ - "message": { - "bio": [ - "is too long (maximum is 255 characters)" - ] - } -} -``` - -This makes error messages more machine-readable. The format can be described as -follows: - -```json -{ - "message": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - "<embed-entity>": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - } - } -} -``` - -## Unknown route - -When you attempt to access an API URL that doesn't exist, you receive a -404 Not Found message. - -```http -HTTP/1.1 404 Not Found -Content-Type: application/json -{ - "error": "404 Not Found" -} -``` - -## Encoding `+` in ISO 8601 dates - -If you need to include a `+` in a query parameter, you may need to use `%2B` -instead, due to a [W3 recommendation](https://www.w3.org/Addressing/URL/4_URI_Recommentations.html) -that causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, -you may want to include a specific time in ISO 8601 format, such as: - -```plaintext -2017-10-17T23:11:13.000+05:30 -``` - -The correct encoding for the query parameter would be: - -```plaintext -2017-10-17T23:11:13.000%2B05:30 -``` - -## Clients - -There are many unofficial GitLab API Clients for most of the popular programming -languages. For a complete list, visit the [GitLab website](https://about.gitlab.com/partners/technology-partners/#api-clients). - -## Rate limits - -For administrator documentation on rate limit settings, see -[Rate limits](../security/rate_limits.md). To find the settings that are -specifically used by GitLab.com, see -[GitLab.com-specific rate limits](../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). - -## Content type - -The GitLab API supports the `application/json` content type by default, though -some API endpoints also support `text/plain`. - -In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/250342), -API endpoints do not support `text/plain` by default, unless it's explicitly documented. - -## Resolve requests detected as spam - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352913) in GitLab 14.9. - -REST API requests can be detected as spam. If a request is detected as spam and: - -- A CAPTCHA service is not configured, an error response is returned. For example: - - ```json - {"message":{"error":"Your snippet has been recognized as spam and has been discarded."}} - ``` - -- A CAPTCHA service is configured, you receive a response with: - - `needs_captcha_response` set to `true`. - - The `spam_log_id` and `captcha_site_key` fields set. - - For example: - - ```json - {"needs_captcha_response":true,"spam_log_id":42,"captcha_site_key":"6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","message":{"error":"Your snippet has been recognized as spam. Please, change the content or solve the reCAPTCHA to proceed."}} - ``` - -- Use the `captcha_site_key` to obtain a CAPTCHA response value using the appropriate CAPTCHA API. - Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported. -- Resubmit the request with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set. - -```shell -export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>" -export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>" -curl --request POST --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" "https://gitlab.example.com/api/v4/snippets?title=Title&file_name=FileName&content=Content&visibility=public" -``` +- [Integrations](../integration/index.md) +- [Webhooks](../user/project/integrations/webhooks.md) +- [Visual Studio Code extension](../user/project/repository/vscode.md) +- [REST API](rest/index.md) +- [GraphQL API](graphql/index.md) +- [Lint `.gitlab-ci.yml`](lint.md) +- [GitLab as an OAuth2 provider](oauth2.md) diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 908fa0ce890..2484cfe1728 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -37,7 +37,7 @@ POST /projects/:id/invitations | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `email` | string | yes (if `user_id` isn't provided) | The email of the new member or multiple emails separated by commas. | | `user_id` | integer/string | yes (if `email` isn't provided) | The ID of the new member or multiple IDs separated by commas. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350999) in GitLab 14.10. | | `access_level` | integer | yes | A valid access level | @@ -88,7 +88,7 @@ GET /projects/:id/invitations | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `page` | integer | no | Page to retrieve | | `per_page`| integer | no | Number of member invitations to return per page | | `query` | string | no | A query string to search for invited members by invite email. Query text must match email address exactly. When empty, returns all invitations. | @@ -125,7 +125,7 @@ PUT /projects/:id/invitations/:email | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `email` | string | yes | The email address the invitation was previously sent to. | | `access_level` | integer | no | A valid access level (defaults: `30`, the Developer role). | | `expires_at` | string | no | A date string in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). | @@ -155,7 +155,7 @@ DELETE /projects/:id/invitations/:email | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `email` | string | yes | The email address to which the invitation was previously sent | ```shell diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index ce3d26f1c08..46cf8e9b2b6 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -22,7 +22,7 @@ Parameters: | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```json @@ -77,7 +77,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------------|----------------|------------------------|-----------------------------------------------------------------------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | **{check-circle}** Yes | Internal ID of a project's issue. | | `issue_link_id` | integer/string | **{check-circle}** Yes | ID of an issue relationship. | @@ -174,9 +174,9 @@ POST /projects/:id/issues/:issue_iid/links | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | -| `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) of a target project | +| `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) of a target project | | `target_issue_iid` | integer/string | yes | The internal ID of a target project's issue | | `link_type` | string | no | The type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to`). | @@ -262,7 +262,7 @@ DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `issue_link_id` | integer/string | yes | The ID of an issue relationship | | `link_type` | string | no | The type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to` | diff --git a/doc/api/issues.md b/doc/api/issues.md index 94547d69064..e252655f781 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -16,7 +16,7 @@ request on that project results in a `404` status code. By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). WARNING: The `reference` attribute in responses is deprecated in favor of `references`. @@ -295,7 +295,7 @@ GET /groups/:id/issues?state=opened | `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), `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 global ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | @@ -499,7 +499,7 @@ GET /projects/:id/issues?state=opened | `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), `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 global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | @@ -846,7 +846,7 @@ GET /projects/:id/issues/:issue_iid | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1012,7 +1012,7 @@ POST /projects/:id/issues | `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | | `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | | `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | | `labels` | string | no | Comma-separated label names for an issue | @@ -1180,7 +1180,7 @@ PUT /projects/:id/issues/:issue_iid | `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | | `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | | `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `issue_type` | string | no | Updates the type of issue. One of `issue`, `incident`, or `test_case`. | | `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | @@ -1326,7 +1326,7 @@ DELETE /projects/:id/issues/:issue_iid | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1345,7 +1345,7 @@ PUT /projects/:id/issues/:issue_iid/reorder | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of the project's issue | | `move_after_id` | integer | no | The global ID of a project's issue that should be placed after this issue | | `move_before_id` | integer | no | The global ID of a project's issue that should be placed before this issue | @@ -1369,7 +1369,7 @@ POST /projects/:id/issues/:issue_iid/move | Attribute | Type | Required | Description | |-----------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `to_project_id` | integer | yes | The ID of the new project | @@ -1515,7 +1515,7 @@ POST /projects/:id/issues/:issue_iid/clone | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `issue_iid` | integer | **{check-circle}** Yes | Internal ID of a project's issue. | | `to_project_id` | integer | **{check-circle}** Yes | ID of the new project. | | `with_notes` | boolean | **{dotted-circle}** No | Clone the issue with [notes](notes.md). Default is `false`. | @@ -1622,7 +1622,7 @@ POST /projects/:id/issues/:issue_iid/subscribe | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1765,7 +1765,7 @@ POST /projects/:id/issues/:issue_iid/unsubscribe | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1839,7 +1839,7 @@ POST /projects/:id/issues/:issue_iid/todo | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -1950,7 +1950,7 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass Promotes an issue to an epic by adding a comment with the `/promote` [quick action](../user/project/quick_actions.md). -To learn more about promoting issues to epics, visit [Manage epics](../user/group/epics/manage_epics.md#promote-an-issue-to-an-epic). +For more information about promoting issues to epics, see [Manage epics](../user/group/epics/manage_epics.md#promote-an-issue-to-an-epic). ```plaintext POST /projects/:id/issues/:issue_iid/notes @@ -1960,7 +1960,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `body` | String | yes | The content of a note. Must contain `/promote` at the start of a new line. | @@ -2011,7 +2011,7 @@ POST /projects/:id/issues/:issue_iid/time_estimate | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| | `duration` | string | yes | The duration in human format. e.g: `3h30m` | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2039,7 +2039,7 @@ POST /projects/:id/issues/:issue_iid/reset_time_estimate | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2068,7 +2068,7 @@ POST /projects/:id/issues/:issue_iid/add_spent_time | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| | `duration` | string | yes | The duration in human format. e.g: `3h30m` | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `summary` | string | no | A summary of how the time was spent | @@ -2097,7 +2097,7 @@ POST /projects/:id/issues/:issue_iid/reset_spent_time | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2126,7 +2126,7 @@ GET /projects/:id/issues/:issue_iid/time_stats | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2157,7 +2157,7 @@ GET /projects/:id/issues/:issue_iid/related_merge_requests | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2317,7 +2317,7 @@ GET /projects/:id/issues/:issue_iid/closed_by | Attribute | Type | Required | Description | | ----------- | ---------------| -------- | ---------------------------------- | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project issue | ```shell @@ -2394,7 +2394,7 @@ GET /projects/:id/issues/:issue_iid/participants | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2438,7 +2438,7 @@ GET /projects/:id/issues/:issue_iid/user_agent_detail | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2470,7 +2470,7 @@ POST /projects/:id/issues/:issue_iid/metric_images | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `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 | @@ -2504,7 +2504,7 @@ GET /projects/:id/issues/:issue_iid/metric_images | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | ```shell @@ -2542,7 +2542,7 @@ PUT /projects/:id/issues/:issue_iid/metric_images/:image_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/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 | @@ -2575,7 +2575,7 @@ DELETE /projects/:id/issues/:issue_iid/metric_images/:image_id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/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 | diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index cb08dc26b64..3910594f086 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -91,7 +91,7 @@ GET /groups/:id/issues_statistics?confidential=true | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | @@ -147,7 +147,7 @@ GET /projects/:id/issues_statistics?confidential=true | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the milestone having the given `iid` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 3e5f49377cb..b73eafea3c4 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -18,7 +18,7 @@ GET /projects/:id/jobs/:job_id/artifacts | 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. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | | `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | @@ -82,7 +82,7 @@ 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. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | | `job` | string | yes | The name of the job. | | `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | @@ -143,7 +143,7 @@ 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. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | The unique job identifier. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | | `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. | @@ -187,7 +187,7 @@ 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. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `ref_name` | string | yes | Branch or tag name in repository. `HEAD` or `SHA` references are not supported. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | | `job` | string | yes | The name of the job. | @@ -219,7 +219,7 @@ 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. | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | Example request: @@ -274,7 +274,7 @@ DELETE /projects/:id/jobs/:job_id/artifacts | Attribute | Type | Required | Description | |-----------|----------------|----------|-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `job_id` | integer | yes | ID of a job. | Example request: @@ -303,7 +303,7 @@ DELETE /projects/:id/artifacts | Attribute | Type | Required | Description | |-----------|----------------|----------|-----------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | Example request: diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 992cb70c45d..2d65ea82edd 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -10,7 +10,10 @@ 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) +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination) + +This endpoint supports both offset-based and [keyset-based](rest/index.md#keyset-based-pagination) pagination. Keyset-based +pagination is recommended when requesting consecutive pages of results. ```plaintext GET /projects/:id/jobs @@ -18,7 +21,7 @@ GET /projects/:id/jobs | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/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`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | ```shell @@ -44,6 +47,7 @@ Example of response "created_at": "2015-12-24T15:51:21.802Z", "started_at": "2015-12-24T17:54:27.722Z", "finished_at": "2015-12-24T17:54:27.895Z", + "erased_at": null, "duration": 0.173, "queued_duration": 0.010, "artifacts_file": { @@ -112,6 +116,7 @@ Example of response "created_at": "2015-12-24T15:51:21.727Z", "started_at": "2015-12-24T17:54:24.729Z", "finished_at": "2015-12-24T17:54:24.921Z", + "erased_at": null, "duration": 0.192, "queued_duration": 0.023, "artifacts_expire_at": "2016-01-23T17:54:24.921Z", @@ -163,7 +168,7 @@ 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) +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination) ```plaintext GET /projects/:id/pipelines/:pipeline_id/jobs @@ -171,7 +176,7 @@ GET /projects/:id/pipelines/:pipeline_id/jobs | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/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`, `waiting_for_resource`, 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. | @@ -199,6 +204,7 @@ Example of response "created_at": "2015-12-24T15:51:21.727Z", "started_at": "2015-12-24T17:54:24.729Z", "finished_at": "2015-12-24T17:54:24.921Z", + "erased_at": null, "duration": 0.192, "queued_duration": 0.023, "artifacts_expire_at": "2016-01-23T17:54:24.921Z", @@ -258,6 +264,7 @@ Example of response "created_at": "2015-12-24T15:51:21.802Z", "started_at": "2015-12-24T17:54:27.722Z", "finished_at": "2015-12-24T17:54:27.895Z", + "erased_at": null, "duration": 0.173, "queued_duration": 0.023, "artifacts_file": { @@ -334,7 +341,7 @@ GET /projects/:id/pipelines/:pipeline_id/bridges | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/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`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | @@ -361,6 +368,7 @@ Example of response "created_at": "2015-12-24T15:51:21.802Z", "started_at": "2015-12-24T17:54:27.722Z", "finished_at": "2015-12-24T17:58:27.895Z", + "erased_at": null, "duration": 240, "queued_duration": 0.123, "id": 7, @@ -449,6 +457,7 @@ Example of response "created_at": "2015-12-24T15:51:21.880Z", "started_at": "2015-12-24T17:54:30.733Z", "finished_at": "2015-12-24T17:54:31.198Z", + "erased_at": null, "duration": 0.465, "queued_duration": 0.123, "artifacts_expire_at": "2016-01-23T17:54:31.198Z", @@ -575,7 +584,7 @@ GET /projects/:id/jobs/:job_id | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell @@ -600,6 +609,7 @@ Example of response "created_at": "2015-12-24T15:51:21.880Z", "started_at": "2015-12-24T17:54:30.733Z", "finished_at": "2015-12-24T17:54:31.198Z", + "erased_at": null, "duration": 0.465, "queued_duration": 0.010, "artifacts_expire_at": "2016-01-23T17:54:31.198Z", @@ -655,7 +665,7 @@ GET /projects/:id/jobs/:job_id/trace | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell @@ -679,7 +689,7 @@ POST /projects/:id/jobs/:job_id/cancel | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell @@ -704,6 +714,7 @@ Example of response "created_at": "2016-01-11T10:13:33.506Z", "started_at": "2016-01-11T10:14:09.526Z", "finished_at": null, + "erased_at": null, "duration": 8, "queued_duration": 0.010, "id": 1, @@ -732,7 +743,7 @@ POST /projects/:id/jobs/:job_id/retry | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | ```shell @@ -757,6 +768,7 @@ Example of response "created_at": "2016-01-11T10:13:33.506Z", "started_at": null, "finished_at": null, + "erased_at": null, "duration": null, "queued_duration": 0.010, "id": 1, @@ -787,7 +799,7 @@ Parameters | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | Example of request @@ -821,6 +833,7 @@ Example of response "created_at": "2016-01-11T10:13:33.506Z", "started_at": "2016-01-11T10:13:33.506Z", "finished_at": "2016-01-11T10:15:10.506Z", + "erased_at": "2016-01-11T11:30:19.914Z", "duration": 97.0, "queued_duration": 0.010, "status": "failed", @@ -847,7 +860,7 @@ POST /projects/:id/jobs/:job_id/play | 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. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. | | `job_variables_attributes` | array of hashes | **{dotted-circle}** No | An array containing the custom variables available to the job. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/37267) GitLab 14.9. | @@ -894,6 +907,7 @@ Example response: "created_at": "2016-01-11T10:13:33.506Z", "started_at": null, "finished_at": null, + "erased_at": null, "duration": null, "queued_duration": 0.010, "id": 1, diff --git a/doc/api/labels.md b/doc/api/labels.md index 5851138a3a3..a5d5461c1ac 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -15,7 +15,7 @@ The `description_html` - was [added](https://gitlab.com/gitlab-org/gitlab/-/merg Get all labels for a given project. -By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination). ```plaintext GET /projects/:id/labels @@ -23,7 +23,7 @@ GET /projects/:id/labels | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543) in GitLab 12.2)_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `search` | string | no | Keyword to filter labels by. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -119,7 +119,7 @@ GET /projects/:id/labels/:label_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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | @@ -156,7 +156,7 @@ POST /projects/:id/labels | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | | `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label | @@ -195,7 +195,7 @@ DELETE /projects/:id/labels/:label_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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -216,7 +216,7 @@ PUT /projects/:id/labels/:label_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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `new_name` | string | yes if `color` is not provided | The new name of the label | | `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | @@ -265,7 +265,7 @@ PUT /projects/:id/labels/:label_id/promote | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -303,7 +303,7 @@ POST /projects/:id/labels/:label_id/subscribe | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```shell @@ -341,7 +341,7 @@ POST /projects/:id/labels/:label_id/unsubscribe | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```shell diff --git a/doc/api/linked_epics.md b/doc/api/linked_epics.md index c240b3255c6..434e6080ffb 100644 --- a/doc/api/linked_epics.md +++ b/doc/api/linked_epics.md @@ -11,7 +11,129 @@ info: To determine the technical writer assigned to the Stage/Group associated w If the Related Epics feature is not available in your GitLab plan, a `403` status code is returned. -## List linked epics +## List related epic links from a group + +Get a list of a given group's related epic links within group and sub-groups, filtered according to the user authorizations. +The user needs to have access to the `source_epic` and `target_epic` to access the related epic link. + +```plaintext +GET /groups/:id/epics/related_epic_links +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| ---------- | -------------- | ---------------------- | ------------------------------------------------------------------------- | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | +| `created_after` | string | no | Return related epic links created on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | +| `created_before` | string | no | Return related epic links created on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | +| `updated_after` | string | no | Return related epic links updated on or after the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | +| `updated_before` | string | no | Return related epic links updated on or before the given time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/related_epic_links" +``` + +Example response: + +```json +[ + { + "id": 1, + "created_at": "2022-01-31T15:10:44.988Z", + "updated_at": "2022-01-31T15:10:44.988Z", + "link_type": "relates_to", + "source_epic": { + "id": 21, + "iid": 1, + "color": "#1068bf", + "text_color": "#FFFFFF", + "group_id": 26, + "parent_id": null, + "parent_iid": null, + "title": "Aspernatur recusandae distinctio omnis et qui est iste.", + "description": "some description", + "confidential": false, + "author": { + "id": 15, + "username": "trina", + "name": "Theresia Robel", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/085e28df717e16484cbf6ceca75e9a93?s=80&d=identicon", + "web_url": "http://gitlab.example.com/trina" + }, + "start_date": null, + "end_date": null, + "due_date": null, + "state": "opened", + "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/1", + "references": { + "short": "&1", + "relative": "&1", + "full": "flightjs&1" + }, + "created_at": "2022-01-31T15:10:44.988Z", + "updated_at": "2022-03-16T09:32:35.712Z", + "closed_at": null, + "labels": [], + "upvotes": 0, + "downvotes": 0, + "_links": { + "self": "http://gitlab.example.com/api/v4/groups/26/epics/1", + "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/1/issues", + "group": "http://gitlab.example.com/api/v4/groups/26", + "parent": null + } + }, + "target_epic": { + "id": 25, + "iid": 5, + "color": "#1068bf", + "text_color": "#FFFFFF", + "group_id": 26, + "parent_id": null, + "parent_iid": null, + "title": "Aut assumenda id nihil distinctio fugiat vel numquam est.", + "description": "some description", + "confidential": false, + "author": { + "id": 3, + "username": "valerie", + "name": "Erika Wolf", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/9ef7666abb101418a4716a8ed4dded80?s=80&d=identicon", + "web_url": "http://gitlab.example.com/valerie" + }, + "start_date": null, + "end_date": null, + "due_date": null, + "state": "opened", + "web_url": "http://gitlab.example.com/groups/flightjs/-/epics/5", + "references": { + "short": "&5", + "relative": "&5", + "full": "flightjs&5" + }, + "created_at": "2022-01-31T15:10:45.080Z", + "updated_at": "2022-03-16T09:32:35.842Z", + "closed_at": null, + "labels": [], + "upvotes": 0, + "downvotes": 0, + "_links": { + "self": "http://gitlab.example.com/api/v4/groups/26/epics/5", + "epic_issues": "http://gitlab.example.com/api/v4/groups/26/epics/5/issues", + "group": "http://gitlab.example.com/api/v4/groups/26", + "parent": null + } + }, + } +] +``` + +## List linked epics from an epic Get a list of a given epic's linked epics filtered according to the user authorizations. @@ -24,7 +146,7 @@ Supported attributes: | Attribute | Type | Required | Description | | ---------- | -------------- | ---------------------- | ------------------------------------------------------------------------- | | `epic_iid` | integer | **{check-circle}** Yes | Internal ID of a group's epic | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | Example request: @@ -103,9 +225,9 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|----------------|-----------------------------|---------------------------------------| | `epic_iid` | integer | **{check-circle}** Yes | Internal ID of a group's epic. | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `target_epic_iid` | integer/string | **{check-circle}** Yes | Internal ID of a target group's epic. | -| `target_group_id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the target group](index.md#namespaced-path-encoding). | +| `target_group_id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the target group](rest/index.md#namespaced-path-encoding). | | `link_type` | string | **{dotted-circle}** No | Type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to`. | Example request: @@ -118,6 +240,10 @@ Example response: ```json { + "id": 1, + "created_at": "2022-01-31T15:10:44.988Z", + "updated_at": "2022-01-31T15:10:44.988Z", + "link_type": "relates_to", "source_epic": { "id": 21, "iid": 1, @@ -202,7 +328,6 @@ Example response: "parent": null } }, - "link_type": "relates_to" } ``` @@ -222,7 +347,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------------|----------------|-----------------------------|---------------------------------------| | `epic_iid` | integer | **{check-circle}** Yes | Internal ID of a group's epic. | -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `related_epic_link_id` | integer/string | **{check-circle}** Yes | Internal ID of a related epic link. | Example request: @@ -235,6 +360,10 @@ Example response: ```json { + "id": 1, + "created_at": "2022-01-31T15:10:44.988Z", + "updated_at": "2022-01-31T15:10:44.988Z", + "link_type": "relates_to", "source_epic": { "id": 21, "iid": 1, @@ -319,6 +448,5 @@ Example response: "parent": null } }, - "link_type": "relates_to" } ``` diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index e9cab7f878a..6aee60c57e0 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -19,7 +19,7 @@ GET /projects/:id/managed_licenses | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses" @@ -52,7 +52,7 @@ GET /projects/:id/managed_licenses/:managed_license_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | ```shell @@ -79,7 +79,7 @@ POST /projects/:id/managed_licenses | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the managed license | | `approval_status` | string | yes | The approval status of the license. "allowed" or "denied". | @@ -107,7 +107,7 @@ DELETE /projects/:id/managed_licenses/:managed_license_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | ```shell @@ -126,7 +126,7 @@ PATCH /projects/:id/managed_licenses/:managed_license_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | | `approval_status` | string | yes | The approval status of the license. "allowed" or "denied". | diff --git a/doc/api/markdown.md b/doc/api/markdown.md index b4b700d24d6..e79b05ac012 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -20,7 +20,7 @@ To remove the requirement to authenticate, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `authenticate_markdown_api`. On GitLab.com, this feature is available. -All API calls to the Markdown API must be [authenticated](index.md#authentication). +All API calls to the Markdown API must be [authenticated](rest/index.md#authentication). ## Render an arbitrary Markdown document diff --git a/doc/api/member_roles.md b/doc/api/member_roles.md new file mode 100644 index 00000000000..a7fc93e0df5 --- /dev/null +++ b/doc/api/member_roles.md @@ -0,0 +1,117 @@ +--- +stage: Manage +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/product/ux/technical-writing/#assignments +--- + +# Member roles API **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96996) in GitLab 15.4. [Deployed behind the `customizable_roles` flag](../administration/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9. + +## List all member roles of a group + +Gets a list of group member roles viewable by the authenticated user. + +```plaintext +GET /groups/:id/member_roles +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | + +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: + +| Attribute | Type | Description | +|:-------------------------|:---------|:----------------------| +| `[].id` | integer | The ID of the member role. | +| `[].group_id` | integer | The ID of the group that the member role belongs to. | +| `[].base_access_level` | integer | Base access level for member role. | +| `[].read_code` | boolean | Permission to read code. | + +Example request: + +```shell +curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/member_roles" +``` + +Example response: + +```json +[ + { + "id": 2, + "group_id": 84, + "base_access_level": 10, + "read_code": true + }, + { + "id": 3, + "group_id": 84, + "base_access_level": 10, + "read_code": false + } +] +``` + +## Add a member role to a group + +Adds a member role to a group. + +```plaintext +POST /groups/:id/member_roles +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `base_access_level` | integer | yes | Base access level for configured role. | +| `read_code` | boolean | no | Permission to read code. | + +If successful, returns [`201`](rest/index.md#status-codes) and the following attributes: + +| Attribute | Type | Description | +|:-------------------------|:---------|:----------------------| +| `id` | integer | The ID of the member role. | +| `group_id` | integer | The ID of the group that the member role belongs to. | +| `base_access_level` | integer | Base access level for member role. | +| `read_code` | boolean | Permission to read code. | + +Example request: + +```shell + curl --request POST --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"base_access_level" : 10, "read_code" : true}' "https://example.gitlab.com/api/v4/groups/:id/member_roles" +``` + +Example response: + +```json +{ + "id": 3, + "group_id": 84, + "base_access_level": 10, + "read_code": true +} +``` + +### Remove member role of a group + +Deletes a member role of a group. + +```plaintext +DELETE /groups/:id/member_roles/:member_role_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `member_role_id` | integer | yes | The ID of the member role. | + +If successful, returns [`204`](rest/index.md#status-codes) and an empty response. + +Example request: + +```shell +curl --request DELETE --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" "https://example.gitlab.com/api/v4/groups/:group_id/member_roles/:member_role_id" +``` diff --git a/doc/api/members.md b/doc/api/members.md index 0d6fd6aabc4..950289effd2 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -29,8 +29,7 @@ In GitLab 14.8 and earlier, projects in personal namespaces have an `access_leve The `group_saml_identity` attribute is only visible to a group owner for [SSO enabled groups](../user/group/saml_sso/index.md). -The `email` attribute is only visible to group owners when the user was provisioned by the group. -Users are provisioned by the group when the account was created via [SCIM](../user/group/saml_sso/scim_setup.md) or by first sign-in with [SAML SSO for GitLab.com groups](../user/group/saml_sso/index.md). +The `email` attribute is only visible to group Owners for any [enterprise user](../user/enterprise_user/index.md). ## List all members of a group or project @@ -46,7 +45,7 @@ GET /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | | `skip_users` | array of integers | no | Filter skipped users out of the results | @@ -132,7 +131,7 @@ GET /projects/:id/members/all | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | | `show_seat_info` | boolean | no | Show seat information for users | @@ -226,7 +225,7 @@ GET /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -273,7 +272,7 @@ GET /projects/:id/members/all/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -315,7 +314,7 @@ Gets a list of group members that count as billable. The list includes members i This API endpoint works on top-level groups only. It does not work on subgroups. -This function takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of users. +This function takes [pagination](rest/index.md#pagination) parameters `page` and `per_page` to restrict the list of users. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262875) in GitLab 13.7, the `search` and `sort` parameters allow you to search for billable group members by name and sort the results, @@ -327,7 +326,7 @@ GET /groups/:id/billable_members | Attribute | Type | Required | Description | | ----------------------------- | --------------- | --------- |-------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `search` | string | no | A query string to search for group members by name, username, or public email. | | `sort` | string | no | A query string containing parameters that specify the sort attribute and order. See supported values below. | @@ -412,7 +411,7 @@ This API endpoint works on top-level groups only. It does not work on subgroups. This API endpoint requires permission to administer memberships for the group. -This API endpoint takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of memberships. +This API endpoint takes [pagination](rest/index.md#pagination) parameters `page` and `per_page` to restrict the list of memberships. ```plaintext GET /groups/:id/billable_members/:user_id/memberships @@ -420,7 +419,7 @@ GET /groups/:id/billable_members/:user_id/memberships | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the billable member | ```shell @@ -472,7 +471,7 @@ DELETE /groups/:id/billable_members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -492,7 +491,7 @@ PUT /groups/:id/members/:user_id/state | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `user_id` | integer | yes | The user ID of the member. | | `state` | string | yes | The new state for the user. State is either `awaiting` or `active`. | @@ -519,7 +518,7 @@ POST /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer/string | yes | The user ID of the new member or multiple IDs separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | @@ -571,10 +570,11 @@ PUT /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format `YEAR-MONTH-DAY` | +| `member_role_id` | integer | no | The ID of a member role **(ULTIMATE)** | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id?access_level=40" @@ -620,11 +620,11 @@ POST /groups/:id/members/:user_id/override | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id/override" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id/override" ``` Example response: @@ -666,7 +666,7 @@ DELETE /groups/:id/members/:user_id/override | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```shell @@ -715,7 +715,7 @@ DELETE /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `skip_subresources` | boolean | false | Whether the deletion of direct memberships of the removed member in subgroups and projects should be skipped. Default is `false`. | | `unassign_issuables` | boolean | false | Whether the removed member should be unassigned from any issues or merge requests inside a given group or project. Default is `false`. | @@ -737,7 +737,7 @@ PUT /groups/:id/members/:member_id/approve | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the root group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the root group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `member_id` | integer | yes | The ID of the member | Example request: @@ -756,7 +756,7 @@ POST /groups/:id/members/approve_all | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the root group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the root group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -778,7 +778,7 @@ This API endpoint works on top-level groups only. It does not work on subgroups. This API endpoint requires permission to administer members for the group. -This API endpoint takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of members. +This API endpoint takes [pagination](rest/index.md#pagination) parameters `page` and `per_page` to restrict the list of members. ```plaintext GET /groups/:id/pending_members @@ -786,7 +786,7 @@ GET /groups/:id/pending_members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/pending_members" diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 12f6ab318c9..0df2b90e64d 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -30,7 +30,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | ```json { @@ -61,7 +61,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_before_merge` (deprecated) | integer | **{dotted-circle}** No | How many approvals are required before a merge request can be merged. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/11132) in GitLab 12.3. | | `disable_overriding_approvers_per_merge_request` | boolean | **{dotted-circle}** No | Allow or prevent overriding approvers per merge request. | | `merge_requests_author_approval` | boolean | **{dotted-circle}** No | Allow or prevent authors from self approving merge requests; `true` means authors can self approve. | @@ -96,13 +96,13 @@ You can request information about a project's approval rules using the following GET /projects/:id/approval_rules ``` -Use the `page` and `per_page` [pagination](index.md#offset-based-pagination) parameters to restrict the list of approval rules. +Use the `page` and `per_page` [pagination](rest/index.md#offset-based-pagination) parameters to restrict the list of approval rules. Supported attributes: | Attribute | Type | Required | Description | |-----------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | ```json [ @@ -204,7 +204,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | ```json @@ -306,7 +306,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | | `name` | string | **{check-circle}** Yes | The name of the approval rule. | | `applies_to_all_protected_branches` | boolean | **{dotted-circle}** No | Whether the rule is applied to all protected branches. If set to `true`, the value of `protected_branch_ids` is ignored. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335316) in GitLab 15.3. | @@ -435,7 +435,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-------------------------------------|-------------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | | `name` | string | **{check-circle}** Yes | The name of the approval rule. | @@ -542,7 +542,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of a approval rule. | ## Merge request-level MR approvals @@ -564,7 +564,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json @@ -617,7 +617,7 @@ Supported attributes: | Attribute | Type | Required | Description | |----------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_required` | integer | **{check-circle}** Yes | Approvals required before MR can be merged. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | @@ -658,7 +658,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json @@ -722,13 +722,13 @@ You can request information about a merge request's approval rules using the fol GET /projects/:id/merge_requests/:merge_request_iid/approval_rules ``` -Use the `page` and `per_page` [pagination](index.md#offset-based-pagination) parameters to restrict the list of approval rules. +Use the `page` and `per_page` [pagination](rest/index.md#offset-based-pagination) parameters to restrict the list of approval rules. Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | ```json @@ -805,7 +805,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | @@ -881,7 +881,7 @@ Supported attributes: | Attribute | Type | Required | Description | |----------------------------|-------------------|------------------------|------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding) | | `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | | `name` | string | **{check-circle}** Yes | The name of the approval rule. | @@ -971,7 +971,7 @@ Supported attributes: | Attribute | Type | Required | Description | |------------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approvals_required` | integer | **{check-circle}** Yes | The number of required approvals for this rule. | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | @@ -1056,7 +1056,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_rule_id` | integer | **{check-circle}** Yes | The ID of an approval rule. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | @@ -1075,7 +1075,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `approval_password` | string | **{dotted-circle}** 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. | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of the merge request. | | `sha` | string | **{dotted-circle}** No | The `HEAD` of the merge request. | @@ -1138,5 +1138,5 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|-------------------------------------------------------------------------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | **{check-circle}** Yes | The IID of a merge request. | diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index f5e22c469a3..756f54586db 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -19,7 +19,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------| -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -53,7 +53,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|---------|----------|-------------| -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```plaintext @@ -95,5 +95,5 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|--------------|----------|--------------| | `commits` | string array | **{check-circle}** Yes | The context commits' SHA. | -| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 3ef5d3420c1..024593b2c6b 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -59,8 +59,8 @@ Supported attributes: | `my_reaction_emoji` | string | **{dotted-circle}** No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | | `order_by` | string | **{dotted-circle}** No | Returns 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.| -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | | `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | | `sort` | string | **{dotted-circle}** No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | @@ -245,7 +245,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `approved_by_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `id`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `approver_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have specified all the users with the given `id` as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `assignee_id` | integer | **{dotted-circle}** No | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | @@ -260,8 +260,8 @@ Supported attributes: | `my_reaction_emoji` | string | **{dotted-circle}** No | Returns merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | | `order_by` | string | **{dotted-circle}** No | Returns 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. | -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me`, or `all`. | | `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | | `sort` | string | **{dotted-circle}** No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | @@ -434,7 +434,7 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------------------- | -------------- | -------- | ----------- | -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `approved_by_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `id`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `approved_by_usernames` **(PREMIUM)** | string array | **{dotted-circle}** No | Returns merge requests which have been approved by all the users with the given `username`, with a maximum of 5. `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `approver_ids` **(PREMIUM)** | integer array | **{dotted-circle}** No | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | @@ -449,8 +449,8 @@ Supported attributes: | `non_archived` | boolean | **{dotted-circle}** No | Returns merge requests from non archived projects only. Default is `true`. | | `not` | Hash | **{dotted-circle}** No | Returns merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | | `order_by` | string | **{dotted-circle}** No | Returns 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. | -| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `reviewer_id` | integer | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | +| `reviewer_username` | string | **{dotted-circle}** No | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/reviews/index.md) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `scope` | string | **{dotted-circle}** No | Returns merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. | | `search` | string | **{dotted-circle}** No | Search merge requests against their `title` and `description`. | | `source_branch` | string | **{dotted-circle}** No | Returns merge requests with the given source branch. | @@ -616,7 +616,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `include_diverged_commits_count` | boolean | **{dotted-circle}** No | If `true`, response includes the commits behind the target branch. | | `include_rebase_in_progress` | boolean | **{dotted-circle}** No | If `true`, response includes whether a rebase operation is in progress. | @@ -866,7 +866,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -902,7 +902,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -946,7 +946,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -997,7 +997,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `access_raw_diffs` | boolean | **{dotted-circle}** No | Retrieve change diffs via Gitaly. | @@ -1120,12 +1120,12 @@ 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `page` | integer | **{dotted-circle}** no | The page of results to return. Defaults to 1. | | `per_page` | integer | **{dotted-circle}** no | The number of results per page. Defaults to 20. | -If successful, returns [`200 OK`](index.md#status-codes) and the +If successful, returns [`200 OK`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | @@ -1184,7 +1184,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -1218,7 +1218,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -1270,7 +1270,7 @@ POST /projects/:id/merge_requests | 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) owned by the authenticated user | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `source_branch` | string | **{check-circle}** Yes | The source branch. | | `target_branch` | string | **{check-circle}** Yes | The target branch. | | `title` | string | **{check-circle}** Yes | Title of MR. | @@ -1284,7 +1284,8 @@ POST /projects/:id/merge_requests | `milestone_id` | integer | **{dotted-circle}** No | The global ID of a milestone. | | `remove_source_branch` | boolean | **{dotted-circle}** No | Flag indicating if a merge request should remove the source branch when merging. | | `reviewer_ids` | integer array | **{dotted-circle}** No | The ID of the users added as a reviewer to the merge request. If set to `0` or left empty, no reviewers are added. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `squash` | boolean | **{dotted-circle}** No | Squash commits into a single commit when merging. | +| `squash` | boolean | no | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. Use `squash_on_merge` instead to take project squash options into account. | +| `squash_on_merge` | boolean | no | Indicates if the merge request will be squashed when merged. | | `target_project_id` | integer | **{dotted-circle}** No | Numeric ID of the target project. | 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: @@ -1439,7 +1440,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The ID of a merge request. | | `add_labels` | string | **{dotted-circle}** No | Comma-separated label names to add to a merge request. | | `allow_collaboration` | boolean | **{dotted-circle}** No | Allow commits from members who can merge to the target branch. | @@ -1453,7 +1454,8 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `remove_labels` | string | **{dotted-circle}** No | Comma-separated label names to remove from a merge request. | | `remove_source_branch` | boolean | **{dotted-circle}** No | Flag indicating if a merge request should remove the source branch when merging. | | `reviewer_ids` | integer array | **{dotted-circle}** No | The ID of the users set as a reviewer to the merge request. Set the value to `0` or provide an empty value to unset all reviewers. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `squash` | boolean | **{dotted-circle}** No | Squash commits into a single commit when merging. | +| `squash` | boolean | no | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. Use `squash_on_merge` instead to take project squash options into account. | +| `squash_on_merge` | boolean | no | Indicates if the merge request will be squashed when merged. | | `state_event` | string | **{dotted-circle}** No | New state (close/reopen). | | `target_branch` | string | **{dotted-circle}** No | The target branch. | | `title` | string | **{dotted-circle}** No | Title of MR. | @@ -1621,7 +1623,7 @@ DELETE /projects/:id/merge_requests/:merge_request_iid | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -1640,7 +1642,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `merge_commit_message` | string | **{dotted-circle}** No | Custom merge commit message. | | `merge_when_pipeline_succeeds` | boolean | **{dotted-circle}** No | If `true`, the merge request is merged when the pipeline succeeds. | @@ -1832,7 +1834,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -1859,7 +1861,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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```json @@ -2027,7 +2029,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `skip_ci` | boolean | **{dotted-circle}** No | Set to `true` to skip creating a CI pipeline. | @@ -2089,7 +2091,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/reset_approvals | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2110,7 +2112,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2186,7 +2188,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2357,7 +2359,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2528,7 +2530,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell @@ -2774,7 +2776,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `duration` | string | **{check-circle}** Yes | The duration in human format, such as `3h30m`. | @@ -2803,7 +2805,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of a project's merge request. | ```shell @@ -2831,7 +2833,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | | `duration` | string | **{check-circle}** Yes | The duration in human format, such as `3h30m` | | `summary` | string | **{dotted-circle}** No | A summary of how the time was spent. | @@ -2861,7 +2863,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of a project's merge request. | ```shell @@ -2887,7 +2889,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/time_stats | 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) owned by the authenticated user. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | **{check-circle}** Yes | The internal ID of the merge request. | ```shell diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index e8912aac759..6d5d12a618c 100644 --- a/doc/api/merge_trains.md +++ b/doc/api/merge_trains.md @@ -20,7 +20,7 @@ If Merge Trains is not available for the project, a `403` status code is returne By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## List Merge Trains for a project @@ -33,7 +33,7 @@ GET /projects/:id/merge_trains?scope=complete | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `scope` | string | no | Return Merge Trains filtered by the given scope. Available scopes are `active` (to be merged) and `complete` (have been merged). | | `sort` | string | no | Return Merge Trains sorted in `asc` or `desc` order. Default is `desc`. | @@ -97,7 +97,7 @@ Supported attributes: | Attribute | Type | Required | Description | | --------------- | ---------------| -------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `target_branch` | string | yes | The target branch of the merge train. | | `scope` | string | no | Return Merge Trains filtered by the given scope. Available scopes are `active` (to be merged) and `complete` (have been merged). | | `sort` | string | no | Return Merge Trains sorted in `asc` or `desc` order. Default is `desc`. | @@ -167,7 +167,7 @@ Supported attributes: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | Example request: diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index dbc6f64044f..80d47da94e0 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -22,7 +22,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `dashboard_path` | string | yes | URL-encoded path to file defining the dashboard which should be marked as favorite. | ```shell @@ -53,7 +53,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied, all dashboards within given projects are removed from favorites. | ```shell diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 22746d4ceed..998beeb9b3b 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -27,7 +27,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | optional | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | | `state` | string | optional | Return only `active` or `closed` milestones | | `title` | string | optional | Return only the milestones having the given `title` | @@ -70,7 +70,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Create new milestone @@ -85,7 +85,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of a milestone | | `description` | string | no | The description of the milestone | | `due_date` | string | no | The due date of the milestone (`YYYYMMDD`) | @@ -103,7 +103,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | | `title` | string | no | The title of a milestone | | `description` | string | no | The description of the milestone | @@ -125,7 +125,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all issues assigned to a single milestone @@ -140,7 +140,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all merge requests assigned to a single milestone @@ -155,7 +155,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Promote project milestone to a group milestone @@ -172,7 +172,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all burndown chart events for a single milestone **(PREMIUM)** @@ -190,5 +190,5 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `milestone_id` | integer | yes | The ID of the project's milestone | diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index f75ebe5a881..cbf7ea079bc 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -12,7 +12,7 @@ Usernames and group names fall under a special category called For users and groups supported API calls see the [users](users.md) and [groups](groups.md) documentation respectively. -[Pagination](index.md#pagination) is used. +[Pagination](rest/index.md#pagination) is used. ## List namespaces @@ -133,7 +133,7 @@ GET /namespaces/:id | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the namespace](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the namespace](rest/index.md#namespaced-path-encoding) | Example request: diff --git a/doc/api/notes.md b/doc/api/notes.md index 44bd7624022..9c453c6390f 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -34,7 +34,7 @@ Some system notes are not part of this API, but are recorded as separate events: By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## Rate limits @@ -54,7 +54,7 @@ GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | `issue_iid` | integer | yes | The IID of an issue | `sort` | string | no | Return issue notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return issue notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -124,7 +124,7 @@ Parameters: | Attribute | Type | Required | Description | |-------------|----------------|----------|---------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of a project issue | | `note_id` | integer | yes | The ID of an issue note | @@ -144,7 +144,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | The IID of an issue. | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0 and renamed to `internal`. The confidential flag of a note. Default is false. | @@ -167,7 +167,7 @@ Parameters: | Attribute | Type | Required | Description | |----------------|----------------|-------------|----------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `issue_iid` | integer | yes | The IID of an issue. | | `note_id` | integer | yes | The ID of a note. | | `body` | string | no | The content of a note. Limited to 1,000,000 characters. | @@ -189,7 +189,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `note_id` | integer | yes | The ID of a note | @@ -212,7 +212,7 @@ GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | `snippet_id` | integer | yes | The ID of a project snippet | `sort` | string | no | Return snippet notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -233,7 +233,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------|----------------|----------|---------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a project snippet | | `note_id` | integer | yes | The ID of a snippet note | @@ -273,7 +273,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a snippet | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -294,7 +294,7 @@ Parameters: | Attribute | Type | Required | Description | |--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a snippet | | `note_id` | integer | yes | The ID of a snippet note | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | @@ -315,7 +315,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a snippet | | `note_id` | integer | yes | The ID of a note | @@ -336,7 +336,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=upda | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | `merge_request_iid` | integer | yes | The IID of a project merge request | `sort` | string | no | Return merge request notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -357,7 +357,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|----------------|----------|---------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a project merge request | | `note_id` | integer | yes | The ID of a merge request note | @@ -403,7 +403,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a project merge request | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -421,7 +421,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------|-------------------|----------|----------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a project merge request | | `note_id` | integer | no | The ID of a note | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | @@ -443,7 +443,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `note_id` | integer | yes | The ID of a note | @@ -469,7 +469,7 @@ GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of a group epic | | `sort` | string | no | Return epic notes sorted in `asc` or `desc` order. Default is `desc` | | `order_by` | string | no | Return epic notes ordered by `created_at` or `updated_at` fields. Default is `created_at` | @@ -490,7 +490,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | @@ -534,7 +534,7 @@ Parameters: | --------- | -------------- | -------- | ----------- | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | | `epic_id` | integer | yes | The ID of an epic | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0 and is renamed to `internal`. The confidential flag of a note. Default is `false`. | | `internal` | boolean | no | The internal flag of a note. Overrides `confidential` when both parameters are submitted. Default is `false`. | @@ -554,7 +554,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------| ----------------- | -------- | ---------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | | `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | @@ -576,7 +576,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `note_id` | integer | yes | The ID of a note | diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index d3e4a058b11..aa8e47d6141 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -121,7 +121,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/index.md#namespaced-path-encoding). | Example response: @@ -147,7 +147,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID, or [URL-encoded path, of the group or project](rest/index.md#namespaced-path-encoding) | | `level` | string | no | The global notification level | | `new_note` | boolean | no | Enable/disable this notification | | `new_issue` | boolean | no | Enable/disable this notification | diff --git a/doc/api/packages.md b/doc/api/packages.md index 6c5cf6bee1e..32b21ce354d 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -25,7 +25,7 @@ GET /projects/:id/packages | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, or `type`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | | `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, `helm`, `terraform_module`, or `golang`. (_Introduced in GitLab 12.9_) @@ -71,7 +71,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](rest/index.md#pagination). Although you can filter packages by status, working with packages that have a `processing` status can result in malformed data or broken packages. @@ -91,7 +91,7 @@ GET /groups/:id/packages | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `exclude_subgroups` | boolean | false | If the parameter is included as true, packages from projects from subgroups are not listed. Default is `false`. | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, `type`, or `project_path`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | @@ -168,7 +168,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](rest/index.md#pagination). The `_links` object contains the following properties: @@ -188,7 +188,7 @@ GET /projects/:id/packages/:package_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `package_id` | integer | yes | ID of a package. | ```shell @@ -269,7 +269,7 @@ GET /projects/:id/packages/:package_id/package_files | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `package_id` | integer | yes | ID of a package. | ```shell @@ -328,7 +328,7 @@ Example response: ] ``` -By default, the `GET` request returns 20 results, because the API is [paginated](index.md#pagination). +By default, the `GET` request returns 20 results, because the API is [paginated](rest/index.md#pagination). ## Delete a project package @@ -340,7 +340,7 @@ DELETE /projects/:id/packages/:package_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `package_id` | integer | yes | ID of a package. | ```shell @@ -368,7 +368,7 @@ DELETE /projects/:id/packages/:package_id/package_files/:package_file_id | Attribute | Type | Required | Description | | ----------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `package_id` | integer | yes | ID of a package. | | `package_file_id` | integer | yes | ID of a package file. | diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md index bfed66a6579..87b583de5e6 100644 --- a/doc/api/packages/debian.md +++ b/doc/api/packages/debian.md @@ -22,10 +22,6 @@ For instructions on how to upload and install Debian packages from the GitLab package registry, see the [Debian registry documentation](../../user/packages/debian_repository/index.md). NOTE: -The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. -These endpoints will all return `404 Not Found`. - -NOTE: These endpoints do not adhere to the standard API authentication methods. See the [Debian registry documentation](../../user/packages/debian_repository/index.md) for details on which headers and token types are supported. @@ -44,6 +40,10 @@ The Debian group API is behind a feature flag that is disabled by default. can opt to enable it. To enable it, follow the instructions in [Enable the Debian group API](../../user/packages/debian_repository/index.md#enable-the-debian-group-api). +### Authenticate to the Debian Package Repositories + +See [Authenticate to the Debian Package Repositories](../../user/packages/debian_repository/index.md#authenticate-to-the-debian-package-repositories). + ## Upload a package file > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62028) in GitLab 14.0. diff --git a/doc/api/packages/debian_group_distributions.md b/doc/api/packages/debian_group_distributions.md index 95f3bae2c1d..23bc85bf0a0 100644 --- a/doc/api/packages/debian_group_distributions.md +++ b/doc/api/packages/debian_group_distributions.md @@ -18,10 +18,6 @@ This API is under development and is not meant for production use. For more information about working with Debian packages, see the [Debian package registry documentation](../../user/packages/debian_repository/index.md). -NOTE: -The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. -These endpoints will all return `404 Not Found`. - ## Enable the Debian group API Debian group repository support is still a work in progress. It's gated behind a feature flag that's @@ -30,17 +26,21 @@ Debian group repository support is still a work in progress. It's gated behind a can opt to enable it. To enable it, follow the instructions in [Enable the Debian group API](../../user/packages/debian_repository/index.md#enable-the-debian-group-api). +## Authenticate to the Debian distributions APIs + +See [Authenticate to the Debian distributions APIs](../../user/packages/debian_repository/index.md#authenticate-to-the-debian-distributions-apis). + ## List all Debian distributions in a group Lists Debian distributions in the given group. ```plaintext -GET /groups/:id/debian_distributions +GET /groups/:id/-/debian_distributions ``` | Attribute | Type | Required | Description | | ---------- | --------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding). | | `codename` | string | no | Filter with specific `codename`. | | `suite` | string | no | Filter with specific `suite`. | @@ -54,7 +54,7 @@ Example response: [ { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -77,12 +77,12 @@ Example response: Gets a single Debian group distribution. ```plaintext -GET /groups/:id/debian_distributions/:codename +GET /groups/:id/-/debian_distributions/:codename ``` | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The `codename` of a distribution. | ```shell @@ -94,7 +94,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -116,12 +116,12 @@ Example response: Gets a single Debian group distribution key. ```plaintext -GET /groups/:id/debian_distributions/:codename/key.asc +GET /groups/:id/-/debian_distributions/:codename/key.asc ``` | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The `codename` of a distribution. | ```shell @@ -153,12 +153,12 @@ DAAKCRDyMVUMT0fjjlnQAQDFHUs6TIcxrNTtEZFjUFm1M0PJ1Dng/cDW4xN80fsn Creates a Debian group distribution. ```plaintext -POST /groups/:id/debian_distributions +POST /groups/:id/-/debian_distributions ``` | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | string | yes | The codename of a Debian distribution. | | `suite` | string | no | The suite of the new Debian distribution. | | `origin` | string | no | The origin of the new Debian distribution. | @@ -170,7 +170,7 @@ POST /groups/:id/debian_distributions | `architectures` | architectures | no | The new Debian distribution's list of architectures. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions?codename=unstable" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/debian_distributions?codename=sid" ``` Example response: @@ -178,7 +178,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -200,12 +200,12 @@ Example response: Updates a Debian group distribution. ```plaintext -PUT /groups/:id/debian_distributions/:codename +PUT /groups/:id/-/debian_distributions/:codename ``` | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | string | yes | The Debian distribution's new codename. | | `suite` | string | no | The Debian distribution's new suite. | | `origin` | string | no | The Debian distribution's new origin. | @@ -225,7 +225,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": "new-suite", "origin": null, "label": null, @@ -247,12 +247,12 @@ Example response: Deletes a Debian group distribution. ```plaintext -DELETE /groups/:id/debian_distributions/:codename +DELETE /groups/:id/-/debian_distributions/:codename ``` | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The codename of the Debian distribution. | ```shell diff --git a/doc/api/packages/debian_project_distributions.md b/doc/api/packages/debian_project_distributions.md index 573f1bffd1a..0a43546e2e1 100644 --- a/doc/api/packages/debian_project_distributions.md +++ b/doc/api/packages/debian_project_distributions.md @@ -18,10 +18,6 @@ This API is under development and is not meant for production use. For more information about working with Debian packages, see the [Debian package registry documentation](../../user/packages/debian_repository/index.md). -NOTE: -The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. -These endpoints will all return `404 Not Found`. - ## Enable the Debian API The Debian API is behind a feature flag that is disabled by default. @@ -29,6 +25,10 @@ The Debian API is behind a feature flag that is disabled by default. can opt to enable it. To enable it, follow the instructions in [Enable the Debian API](../../user/packages/debian_repository/index.md#enable-the-debian-api). +## Authenticate to the Debian distributions APIs + +See [Authenticate to the Debian distributions APIs](../../user/packages/debian_repository/index.md#authenticate-to-the-debian-distributions-apis). + ## List all Debian distributions in a project Lists Debian distributions in the given project. @@ -39,7 +39,7 @@ GET /projects/:id/debian_distributions | Attribute | Type | Required | Description | | ---------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `codename` | string | no | Filter with a specific `codename`. | | `suite` | string | no | Filter with a specific `suite`. | @@ -53,7 +53,7 @@ Example response: [ { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -81,7 +81,7 @@ GET /projects/:id/debian_distributions/:codename | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The `codename` of a distribution. | ```shell @@ -93,7 +93,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -120,7 +120,7 @@ GET /projects/:id/debian_distributions/:codename/key.asc | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The `codename` of a distribution. | ```shell @@ -157,7 +157,7 @@ POST /projects/:id/debian_distributions | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | string | yes | The Debian distribution's codename. | | `suite` | string | no | The new Debian distribution's suite. | | `origin` | string | no | The new Debian distribution's origin. | @@ -169,7 +169,7 @@ POST /projects/:id/debian_distributions | `architectures` | architectures | no | The new Debian distribution's list of architectures. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions?codename=unstable" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/debian_distributions?codename=sid" ``` Example response: @@ -177,7 +177,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -204,7 +204,7 @@ PUT /projects/:id/debian_distributions/:codename | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | string | yes | The Debian distribution's codename. | | `suite` | string | no | The Debian distribution's new suite. | | `origin` | string | no | The Debian distribution's new origin. | @@ -224,7 +224,7 @@ Example response: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": "new-suite", "origin": null, "label": null, @@ -251,7 +251,7 @@ DELETE /projects/:id/debian_distributions/:codename | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `codename` | integer | yes | The Debian distribution's codename. | ```shell diff --git a/doc/api/pages.md b/doc/api/pages.md index 1855eaf153f..dbe7416b939 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -20,7 +20,7 @@ DELETE /projects/:id/pages | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --request 'DELETE' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/2/pages" diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 511098fa380..815cea7cc63 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -47,7 +47,7 @@ GET /projects/:id/pages/domains | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/pages/domains" @@ -83,7 +83,7 @@ GET /projects/:id/pages/domains/:domain | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | ```shell @@ -125,7 +125,7 @@ POST /projects/:id/pages/domains | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | | `auto_ssl_enabled` | boolean | no | Enables [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates issued by Let's Encrypt for custom domains. | | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| @@ -178,7 +178,7 @@ PUT /projects/:id/pages/domains/:domain | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | | `auto_ssl_enabled` | boolean | no | Enables [automatic generation](../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) of SSL certificates issued by Let's Encrypt for custom domains. | | `certificate` | file/string | no | The certificate in PEM format with intermediates following in most specific to least specific order.| @@ -256,7 +256,7 @@ DELETE /projects/:id/pages/domains/:domain | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `domain` | string | yes | The custom domain indicated by the user | ```shell diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index edab87f3478..5dc0dead683 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -18,7 +18,7 @@ GET /projects/:id/pipeline_schedules | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | no | The scope of pipeline schedules, one of: `active`, `inactive` | ```shell @@ -59,7 +59,7 @@ GET /projects/:id/pipeline_schedules/:pipeline_schedule_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -115,7 +115,7 @@ Supported attributes: | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID. | Example request: @@ -165,7 +165,7 @@ POST /projects/:id/pipeline_schedules | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `description` | string | yes | The description of the pipeline schedule. | | `ref` | string | yes | The branch or tag name that is triggered. | | `cron` | string | yes | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | @@ -211,7 +211,7 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID. | | `description` | string | no | The description of the pipeline schedule. | | `ref` | string | no | The branch or tag name that is triggered. | @@ -262,7 +262,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -307,7 +307,7 @@ DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | ```shell @@ -355,7 +355,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | Example request: @@ -384,7 +384,7 @@ POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `value` | string | yes | The `value` of a variable | @@ -413,7 +413,7 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | @@ -443,7 +443,7 @@ DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_schedule_id` | integer | yes | The pipeline schedule ID | | `key` | string | yes | The `key` of a variable | diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index 999b223a934..1ffda1c0d79 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -18,7 +18,7 @@ GET /projects/:id/triggers | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers" @@ -51,7 +51,7 @@ GET /projects/:id/triggers/:trigger_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | ```shell @@ -80,7 +80,7 @@ POST /projects/:id/triggers | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | yes | The trigger name | ```shell @@ -110,7 +110,7 @@ PUT /projects/:id/triggers/:trigger_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | | `description` | string | no | The trigger name | @@ -141,7 +141,7 @@ DELETE /projects/:id/triggers/:trigger_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger ID | ```shell @@ -167,7 +167,7 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------------|:-----------------------|:---------------------| -| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `ref` | string | **{check-circle}** Yes | The branch or tag to run the pipeline on. | | `token` | string | **{check-circle}** Yes | The trigger token or CI/CD job token. | | `variables` | hash | **{dotted-circle}** No | A map of key-valued strings containing the pipeline variables. For example: `{ VAR1: "value1", VAR2: "value2" }`. | @@ -175,7 +175,7 @@ Supported attributes: Example request: ```shell -curl --request POST "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline?token=2cb1840fb9dfc9fb0b7b1609cd29cb&ref=main" +curl --request POST --form "variables[VAR1]=value1" --form "variables[VAR2]=value2" "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline?token=2cb1840fb9dfc9fb0b7b1609cd29cb&ref=main" ``` Example response: @@ -184,7 +184,7 @@ Example response: { "id": 257, "iid": 118, - "project_id": 21, + "project_id": 123, "sha": "91e2711a93e5d9e8dddfeb6d003b636b25bf6fc9", "ref": "main", "status": "created", diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 669161049d5..7049d3c3927 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## List project pipelines @@ -26,7 +26,7 @@ GET /projects/:id/pipelines | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | no | The scope of pipelines, one of: `running`, `pending`, `finished`, `branches`, `tags` | | `status` | string | no | The status of pipelines, one of: `created`, `waiting_for_resource`, `preparing`, `pending`, `running`, `success`, `failed`, `canceled`, `skipped`, `manual`, `scheduled` | | `source` | string | no | In [GitLab 14.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/325439), how the pipeline was triggered, one of: `push`, `web`, `trigger`, `schedule`, `api`, `external`, `pipeline`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, `ondemand_dast_scan`, or `ondemand_dast_validation`. | @@ -89,7 +89,7 @@ GET /projects/:id/pipelines/:pipeline_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -137,7 +137,7 @@ GET /projects/:id/pipelines/:pipeline_id/variables | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -173,7 +173,7 @@ GET /projects/:id/pipelines/:pipeline_id/test_report | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | Sample request: @@ -229,7 +229,7 @@ GET /projects/:id/pipelines/:pipeline_id/test_report_summary | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | Sample request: @@ -340,9 +340,9 @@ POST /projects/:id/pipeline | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `ref` | string | yes | The branch or tag to run the pipeline on. | -| `variables` | array | no | An [array of hashes](index.md#array-of-hashes) containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. | +| `variables` | array | no | An [array of hashes](rest/index.md#array-of-hashes) containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=main" @@ -391,7 +391,7 @@ POST /projects/:id/pipelines/:pipeline_id/retry | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -439,7 +439,7 @@ POST /projects/:id/pipelines/:pipeline_id/cancel | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell @@ -498,7 +498,7 @@ DELETE /projects/:id/pipelines/:pipeline_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ```shell diff --git a/doc/api/product_analytics.md b/doc/api/product_analytics.md index 90df1090f62..c687acdb5db 100644 --- a/doc/api/product_analytics.md +++ b/doc/api/product_analytics.md @@ -25,42 +25,48 @@ POST /projects/:id/product_analytics/request/load POST /projects/:id/product_analytics/request/dry-run ``` -| Attribute | Type | Required | Description | -| --------- |------------------| -------- |---------------------------------------------------------------| -| `id` | integer | yes | The ID of a project that the current user has read access to. | +| Attribute | Type | Required | Description | +|-----------------|------------------| -------- |---------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a project that the current user has read access to. | +| `include_token` | boolean | no | Whether to include the access token in the response. (Only required for funnel generation.) | ### Request body The body of the load request must be a valid Cube query. +NOTE: +When measuring `TrackedEvents`, you must use `TrackedEvents.*` for `dimensions` and `timeDimensions`. The same rule applies when measuring `Sessions`. + +#### Tracked events example + ```json { "query": { "measures": [ - "Jitsu.count" + "TrackedEvents.count" ], "timeDimensions": [ { - "dimension": "Jitsu.utcTime", + "dimension": "TrackedEvents.utcTime", "dateRange": "This week" } ], "order": [ [ - "Jitsu.count", + "TrackedEvents.count", "desc" ], [ - "Jitsu.docPath", + "TrackedEvents.docPath", "desc" ], [ - "Jitsu.utcTime", + "TrackedEvents.utcTime", "asc" ] ], "dimensions": [ - "Jitsu.docPath" + "TrackedEvents.docPath" ], "limit": 23 }, @@ -68,6 +74,29 @@ The body of the load request must be a valid Cube query. } ``` +#### Sessions example + +```json +{ + "query": { + "measures": [ + "Sessions.count" + ], + "timeDimensions": [ + { + "dimension": "Sessions.startAt", + "granularity": "day" + } + ], + "order": { + "Sessions.startAt": "asc" + }, + "limit": 100 + }, + "queryType": "multi" +} +``` + ## Send metadata request to Cube Return Cube Metadata for the Analytics data. For example: @@ -79,3 +108,15 @@ GET /projects/:id/product_analytics/request/meta | Attribute | Type | Required | Description | | --------- |------------------| -------- |---------------------------------------------------------------| | `id` | integer | yes | The ID of a project that the current user has read access to. | + +## List a project's funnels + +List all funnels for a project. For example: + +```plaintext +GET /projects/:id/product_analytics/funnels +``` + +| Attribute | Type | Required | Description | +| --------- |------------------| -------- |--------------------------------------------------------------------| +| `id` | integer | yes | The ID of a project that the current user has the Developer role for. | diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md index 4b74dacb996..6711d1b0261 100644 --- a/doc/api/project_access_tokens.md +++ b/doc/api/project_access_tokens.md @@ -20,7 +20,7 @@ GET projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" @@ -56,7 +56,7 @@ GET projects/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | ID of the project access token | ```shell @@ -101,7 +101,7 @@ POST projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `name` | String | yes | Name of the project access token | | `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#scopes-for-a-project-access-token) | | `access_level` | Integer | no | Access level. Valid values are `10` (Guest), `20` (Reporter), `30` (Developer), `40` (Maintainer), and `50` (Owner). Defaults to `40`. | @@ -144,7 +144,7 @@ DELETE projects/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `token_id` | integer or string | yes | ID of the project access token | ```shell diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index 52d32ab17b9..3dad40a3f96 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -31,11 +31,11 @@ GET /projects/:id/badges | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | no | Name of the badges to return (case-sensitive). | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/badges" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/badges?name=Coverage" ``` Example response: @@ -73,7 +73,7 @@ GET /projects/:id/badges/:badge_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -84,6 +84,7 @@ Example response: ```json { + "name": "Coverage", "id": 1, "link_url": "http://example.com/ci_status.svg?project=%{project_path}&ref=%{default_branch}", "image_url": "https://shields.io/my/badge", @@ -103,7 +104,7 @@ POST /projects/:id/badges | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link | | `image_url` | string | yes | URL of the badge image | | `name` | string | no | Name of the badge | @@ -138,7 +139,7 @@ PUT /projects/:id/badges/:badge_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | | `link_url` | string | no | URL of the badge link | | `image_url` | string | no | URL of the badge image | @@ -172,7 +173,7 @@ DELETE /projects/:id/badges/:badge_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `badge_id` | integer | yes | The badge ID | ```shell @@ -189,7 +190,7 @@ GET /projects/:id/badges/render | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `link_url` | string | yes | URL of the badge link| | `image_url` | string | yes | URL of the badge image | diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 48fc669fe59..01081bdd6d9 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -26,7 +26,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | Example request: @@ -96,7 +96,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -190,7 +190,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the cluster | | `domain` | string | no | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster | | `management_project_id` | integer | no | The ID of the [management project](../user/clusters/management_project.md) for the cluster | @@ -287,7 +287,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | string | no | The name of the cluster | | `domain` | string | no | The [base domain](../user/project/clusters/gitlab_managed_clusters.md#base-domain) of the cluster | @@ -398,7 +398,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | Example request: diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index fe3b2e2a3fb..00e73d41b46 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -39,7 +39,7 @@ POST /projects/:id/export | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | no | Overrides the project description | | `upload` | hash | no | Hash that contains the information to upload the exported project to a web server | | `upload[url]` | string | yes | The URL to upload the project | @@ -67,7 +67,7 @@ GET /projects/:id/export | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/export" @@ -115,7 +115,7 @@ GET /projects/:id/export/download | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ @@ -135,8 +135,7 @@ POST /projects/import | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------- | -| `namespace` | integer/string | no | The ID or path of the namespace to import the project to. Defaults to the current user's namespace. Requires at least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was -[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. | +| `namespace` | integer/string | no | The ID or path of the namespace to import the project to. Defaults to the current user's namespace.<br/><br/>Requires at least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. | | `name` | string | no | The name of the project to be imported. Defaults to the path of the project if not provided | | `file` | string | yes | The file to be uploaded | | `path` | string | yes | Name and path for new project | @@ -341,7 +340,7 @@ GET /projects/:id/import | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/import" diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index c6b56c53413..92ca2849e8e 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -17,7 +17,7 @@ GET /projects/:id/variables | Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" @@ -57,7 +57,7 @@ GET /projects/:id/variables/:key | Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | @@ -89,13 +89,13 @@ POST /projects/:id/variables | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected. Default: `false` | | `masked` | boolean | no | Whether the variable is masked. Default: `false` | -| `raw` | boolean | no | Whether the variable is expandable. Default: `false` | +| `raw` | boolean | no | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | | `environment_scope` | string | no | The `environment_scope` of the variable. Default: `*` | ```shell @@ -126,13 +126,13 @@ PUT /projects/:id/variables/:key | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | | `protected` | boolean | no | Whether the variable is protected | | `masked` | boolean | no | Whether the variable is masked | -| `raw` | boolean | no | Whether the variable is expandable. Default: `false` | +| `raw` | boolean | no | Whether the variable is treated as a raw string. Default: `false`. When `true`, variables in the value are not [expanded](../ci/variables/index.md#prevent-cicd-variable-expansion). | | `environment_scope` | string | no | The `environment_scope` of the variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | @@ -164,7 +164,7 @@ DELETE /projects/:id/variables/:key | Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index bed4d4c9d88..925d3a46f45 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -26,7 +26,7 @@ To ensure data integrity, projects are put in a temporary read-only state for th duration of the move. During this time, users receive a `The repository is temporarily read-only. Please try again later.` message if they try to push new commits. -This API requires you to [authenticate yourself](index.md#authentication) as an administrator. +This API requires you to [authenticate yourself](rest/index.md#authentication) as an administrator. For other repository types see: @@ -40,7 +40,7 @@ GET /project_repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Example request: @@ -78,7 +78,7 @@ GET /projects/:project_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Parameters: diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 95477cdc765..242edf7d768 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -8,16 +8,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Snippet visibility level -Snippets in GitLab can be either private, internal or public. +[Snippets](../api/project_snippets.md) in GitLab can be either private, internal or public. You can set it with the `visibility` field in the snippet. Constants for snippet visibility levels are: | visibility | Description | | ---------- | ----------- | -| `private` | The snippet is visible only to project members | -| `internal` | The snippet is visible for any authenticated user except [external users](../user/admin_area/external_users.md) | -| `public` | The snippet can be accessed without any authentication | +| `private` | The snippet is visible only to project members. | +| `internal` | The snippet is visible for any authenticated user except [external users](../user/admin_area/external_users.md). | +| `public` | The snippet can be accessed without any authentication. | NOTE: From July 2019, the `Internal` visibility setting is disabled for new projects, groups, @@ -37,7 +37,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ## Single snippet @@ -51,8 +51,8 @@ Parameters: | 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 | -| `snippet_id` | integer | yes | The ID of a project's snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | integer | yes | The ID of a project's snippet. | ```json { @@ -88,15 +88,15 @@ Parameters: | 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 | -| `title` | string | yes | Title of a snippet | -| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | -| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | -| `description` | string | no | Description of a snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `title` | string | yes | Title of a snippet. | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file. | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet. | +| `description` | string | no | Description of a snippet. | | `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | -| `files` | array of hashes | no | An array of snippet files | -| `files:file_path` | string | yes | File path of the snippet file | -| `files:content` | string | yes | Content of the snippet file | +| `files` | array of hashes | no | An array of snippet files. | +| `files:file_path` | string | yes | File path of the snippet file. | +| `files:content` | string | yes | Content of the snippet file. | Example request: @@ -127,6 +127,8 @@ curl --request POST "https://gitlab.com/api/v4/projects/:id/snippets" \ Updates an existing project snippet. The user must have permission to change an existing snippet. +Updates to snippets with multiple files *must* use the `files` attribute. + ```plaintext PUT /projects/:id/snippets/:snippet_id ``` @@ -135,20 +137,18 @@ Parameters: | 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 | -| `snippet_id` | integer | yes | The ID of a project's snippet | -| `title` | string | no | Title of a snippet | -| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | -| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | -| `description` | string | no | Description of a snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | integer | yes | The ID of a project's snippet. | +| `title` | string | no | Title of a snippet. | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file. | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet. | +| `description` | string | no | Description of a snippet. | | `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | -| `files` | array of hashes | no | An array of snippet files | +| `files` | array of hashes | no | An array of snippet files. | | `files:action` | string | yes | Type of action to perform on the file, one of: `create`, `update`, `delete`, `move` | -| `files:file_path` | string | no | File path of the snippet file | -| `files:previous_path` | string | no | Previous path of the snippet file | -| `files:content` | string | no | Content of the snippet file | - -Updates to snippets with multiple files *must* use the `files` attribute. +| `files:file_path` | string | no | File path of the snippet file. | +| `files:previous_path` | string | no | Previous path of the snippet file. | +| `files:content` | string | no | Content of the snippet file. | Example request: @@ -188,8 +188,8 @@ Parameters: | 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 | -| `snippet_id` | integer | yes | The ID of a project's snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | integer | yes | The ID of a project's snippet. | Example request: @@ -210,8 +210,8 @@ Parameters: | 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 | -| `snippet_id` | integer | yes | The ID of a project's snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | integer | yes | The ID of a project's snippet. | Example request: @@ -232,10 +232,10 @@ Parameters: | 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 | -| `snippet_id` | integer | yes | The ID of a project's snippet | -| `ref` | string | yes | The name of a branch, tag or commit, for example, main | -| `file_path` | string | yes | The URL-encoded path to the file, for example, snippet%2Erb | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | +| `snippet_id` | integer | yes | The ID of a project's snippet. | +| `ref` | string | yes | The name of a branch, tag or commit, for example, main. | +| `file_path` | string | yes | The URL-encoded path to the file, for example, snippet%2Erb. | Example request: @@ -254,8 +254,8 @@ GET /projects/:id/snippets/:snippet_id/user_agent_detail | 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 | -| `snippet_id` | Integer | yes | The ID of a snippet | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `snippet_id` | Integer | yes | The ID of a snippet. | Example request: diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index 7d8cc19457a..2bf8a908116 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -21,7 +21,7 @@ GET /projects/:id/statistics | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | Example response: diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index ae366e35f91..dfcfa3d7254 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -30,7 +30,7 @@ GET /projects/:id/templates/:type | 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](rest/index.md#namespaced-path-encoding). | | `type` | string | **{check-circle}** Yes | The type of the template. Accepted values are: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, or `merge_requests`. | Example response (licenses): @@ -96,7 +96,7 @@ GET /projects/:id/templates/:type/:name | 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](rest/index.md#namespaced-path-encoding). | | `name` | string | **{check-circle}** Yes | The key of the template, as obtained from the collection endpoint. | | `type` | string | **{check-circle}** Yes | The type of the template. One of: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, or `merge_requests`. | | `fullname` | string | **{dotted-circle}** No | The full name of the copyright holder to use when expanding placeholders in the template. Affects only licenses. | diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index b1eb1b958ee..9effe54b8e2 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -16,7 +16,7 @@ across GitLab releases. Please use the [GraphQL API](graphql/reference/index.md#queryvulnerabilities) instead. -Every API call to vulnerabilities must be [authenticated](index.md#authentication). +Every API call to vulnerabilities must be [authenticated](rest/index.md#authentication). Vulnerability permissions inherit permissions from their project. If a project is private, and a user isn't a member of the project to which the vulnerability @@ -26,7 +26,7 @@ belongs, requests to that project returns a `404 Not Found` status code. API results are paginated, and `GET` requests return 20 results at a time by default. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## List project vulnerabilities @@ -42,7 +42,7 @@ GET /projects/:id/vulnerabilities | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/vulnerabilities" @@ -119,7 +119,7 @@ POST /projects/:id/vulnerabilities?finding_id=<your_finding_id> | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) which the authenticated user is a member of | | `finding_id` | integer or string | yes | The ID of a Vulnerability Finding to create the new Vulnerability from | The other attributes of a newly created Vulnerability are populated from diff --git a/doc/api/projects.md b/doc/api/projects.md index d14ed007dca..b502d547ddc 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -6,20 +6,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Projects API **(FREE)** -Interact with [projects](../user/project/index.md) using the REST API. +Interact with [projects](../user/project/index.md) by using the REST API. ## Project visibility level 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: - -- `private`: project access must be granted explicitly to each user. -- `internal`: the project can be cloned by any authenticated user except [external users](../user/admin_area/external_users.md). -- `public`: the project can be accessed without any authentication. - -For more, read [Project visibility](../user/public_access.md). +For details, see [Project visibility](../user/public_access.md). ## Project merge method @@ -74,7 +68,7 @@ GET /projects | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | | `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | -This endpoint supports [keyset pagination](index.md#keyset-based-pagination) +This endpoint supports [keyset pagination](rest/index.md#keyset-based-pagination) for selected `order_by` options. When `simple=true` or the user is unauthenticated this returns something like: @@ -213,9 +207,13 @@ When the user is authenticated and `simple` is not set this returns something li "security_and_compliance_access_level": "private", "emails_disabled": null, "shared_runners_enabled": true, + "group_runners_enabled": true, "lfs_enabled": true, "creator_id": 1, + "import_url": null, + "import_type": null, "import_status": "none", + "import_error": null, "open_issues_count": 0, "ci_default_git_depth": 20, "ci_forward_deployment_enabled": true, @@ -299,9 +297,9 @@ curl --globoff --request GET "https://gitlab.example.com/api/v4/projects?custom_ ### Pagination limits -In GitLab 13.0 and later, [offset-based pagination](index.md#offset-based-pagination) +In GitLab 13.0 and later, [offset-based pagination](rest/index.md#offset-based-pagination) is [limited to 50,000 records](https://gitlab.com/gitlab-org/gitlab/-/issues/34565). -[Keyset pagination](index.md#keyset-based-pagination) is required to retrieve +[Keyset pagination](rest/index.md#keyset-based-pagination) is required to retrieve projects beyond this limit. Keyset pagination supports only `order_by=id`. Other sorting options aren't available. @@ -316,7 +314,7 @@ authentication, only public projects are returned. NOTE: Only the projects in the user's (specified in `user_id`) namespace are returned. Projects owned by the user in any group or subgroups are not returned. An empty list is returned if a profile is set to private. -This endpoint supports [keyset pagination](index.md#keyset-based-pagination) +This endpoint supports [keyset pagination](rest/index.md#keyset-based-pagination) for selected `order_by` options. ```plaintext @@ -386,6 +384,10 @@ GET /users/:user_id/projects "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", "creator_id": 3, + "import_url": null, + "import_type": null, + "import_status": "none", + "import_error": null, "namespace": { "id": 3, "name": "Diaspora", @@ -397,6 +399,7 @@ GET /users/:user_id/projects "archived": false, "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", @@ -486,6 +489,10 @@ GET /users/:user_id/projects "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", "creator_id": 3, + "import_url": null, + "import_type": null, + "import_status": "none", + "import_error": null, "namespace": { "id": 4, "name": "Brightbox", @@ -508,6 +515,7 @@ GET /users/:user_id/projects "archived": false, "avatar_url": null, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", @@ -659,6 +667,7 @@ Example response: "archived": false, "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", @@ -763,6 +772,7 @@ Example response: "archived": false, "avatar_url": null, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", @@ -834,7 +844,7 @@ GET /projects/:id | 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](rest/index.md#namespaced-path-encoding). | | `license` | boolean | **{dotted-circle}** No | Include project license data. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrators only)_ | @@ -899,6 +909,8 @@ GET /projects/:id "avatar_url": "http://localhost:3000/uploads/group/avatar/3/foo.jpg", "web_url": "http://localhost:3000/groups/diaspora" }, + "import_url": null, + "import_type": null, "import_status": "none", "import_error": null, "permissions": { @@ -922,6 +934,7 @@ GET /projects/:id "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", @@ -1110,7 +1123,7 @@ GET /projects/:id/users | 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](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | | `skip_users` | integer array | **{dotted-circle}** No | Filter out users with the specified IDs. | @@ -1145,7 +1158,7 @@ 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](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific groups. | | `shared_min_access_level` | integer | **{dotted-circle}** No | Limit to shared groups with at least this [role (`access_level`)](members.md#roles). | | `shared_visible_only` | boolean | **{dotted-circle}** No | Limit to shared groups user has access to. | @@ -1160,7 +1173,7 @@ GET /projects/:id/groups "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg", "web_url": "http://localhost:3000/groups/foo-bar", "full_name": "Foobar Group", - "full_path": "foo-bar", + "full_path": "foo-bar" }, { "id": 2, @@ -1168,7 +1181,41 @@ GET /projects/:id/groups "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg", "web_url": "http://gitlab.example.com/groups/foo/bar", "full_name": "Shared Group", - "full_path": "foo/shared", + "full_path": "foo/shared" + } +] +``` + +## List a project's shareable groups + +Get a list of groups that can be shared with a project + +```plaintext +GET /projects/:id/share_locations +``` + +| Attribute | Type | Required | Description | +|-----------------------------|-------------------|------------------------|-------------| +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `search` | string | **{dotted-circle}** No | Search for specific groups. | + +```json +[ + { + "id": 22, + "web_url": "http://127.0.0.1:3000/groups/gitlab-org", + "name": "Gitlab Org", + "avatar_url": null, + "full_name": "Gitlab Org", + "full_path": "gitlab-org" + }, + { + "id": 25, + "web_url": "http://127.0.0.1:3000/groups/gnuwget", + "name": "Gnuwget", + "avatar_url": null, + "full_name": "Gnuwget", + "full_path": "gnuwget" } ] ``` @@ -1201,8 +1248,8 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | Attribute | Type | Required | Description | |-------------------------------------------------------------|---------|------------------------|-------------| -| `name` | string | **{check-circle}** Yes (if path isn't provided) | The name of the new project. Equals path if not provided. | -| `path` | string | **{check-circle}** Yes (if name isn't provided) | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). Starting with GitLab 14.9, path must not start or end with a special character and must not contain consecutive special characters. | +| `name` | string | **{check-circle}** Yes (if `path` isn't provided) | The name of the new project. Equals path if not provided. | +| `path` | string | **{check-circle}** Yes (if `name` isn't provided) | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). Starting with GitLab 14.9, path must not start or end with a special character and must not contain consecutive special characters. | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | | `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | @@ -1259,6 +1306,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `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`. | @@ -1343,6 +1391,7 @@ POST /projects/user/:user_id | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `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. | | `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/merge_requests/creating_merge_requests.md#from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | @@ -1382,9 +1431,9 @@ 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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/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. | -| `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. | +| `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false.<br/><br/>[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. The feature flag was enabled by default in GitLab 15.9. | | `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). | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | @@ -1453,6 +1502,7 @@ Supported attributes: | `security_and_compliance_access_level` | string | **{dotted-circle}** No | (GitLab 14.9 and later) Security and compliance access level. One of `disabled`, `private`, or `enabled`. | | `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. | +| `group_runners_enabled` | boolean | **{dotted-circle}** No | Enable group runners for this project. | | `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. | | `issue_branch_template` | string | **{dotted-circle}** No | Template used to suggest names for [branches created from issues](../user/project/merge_requests/creating_merge_requests.md#from-an-issue). _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21243) in GitLab 15.6.)_ | @@ -1479,7 +1529,7 @@ 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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/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. | @@ -1502,7 +1552,7 @@ GET /projects/:id/forks | 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](rest/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 [role (`access_level`)](members.md#roles). | @@ -1572,6 +1622,7 @@ Example responses: "archived": true, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 1, "public_jobs": true, @@ -1616,7 +1667,7 @@ POST /projects/:id/star | 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](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star" @@ -1679,6 +1730,7 @@ Example response: "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 1, "public_jobs": true, @@ -1721,7 +1773,7 @@ POST /projects/:id/unstar | 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](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar" @@ -1784,6 +1836,7 @@ Example response: "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "public_jobs": true, @@ -1824,7 +1877,7 @@ GET /projects/:id/starrers | 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](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | Search for specific users. | ```shell @@ -1870,7 +1923,7 @@ GET /projects/:id/languages | 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](rest/index.md#namespaced-path-encoding). | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages" @@ -1901,7 +1954,7 @@ POST /projects/:id/archive | 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](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive" @@ -1980,6 +2033,7 @@ Example response: "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", @@ -2029,7 +2083,7 @@ POST /projects/:id/unarchive | 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](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive" @@ -2108,6 +2162,7 @@ Example response: "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" }, "shared_runners_enabled": true, + "group_runners_enabled": true, "forks_count": 0, "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", @@ -2171,7 +2226,7 @@ DELETE /projects/:id | 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](rest/index.md#namespaced-path-encoding). | ## Restore project marked for deletion **(PREMIUM)** @@ -2185,7 +2240,7 @@ POST /projects/:id/restore | 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](rest/index.md#namespaced-path-encoding). | ## Upload a file @@ -2200,7 +2255,7 @@ POST /projects/:id/uploads | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `file` | string | **{check-circle}** Yes | The file to be uploaded. | -| `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](rest/index.md#namespaced-path-encoding). | To upload a file from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The @@ -2274,7 +2329,7 @@ PUT /projects/:id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `avatar` | string | **{check-circle}** Yes | The file to be uploaded. | -| `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](rest/index.md#namespaced-path-encoding). | To upload an avatar from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The @@ -2321,7 +2376,7 @@ POST /projects/:id/share |----------------|----------------|------------------------|-------------| | `group_access` | integer | **{check-circle}** Yes | The [role (`access_level`)](members.md#roles) 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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/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 @@ -2335,7 +2390,7 @@ DELETE /projects/:id/share/:group_id | Attribute | Type | Required | Description | |------------|----------------|------------------------|-------------| | `group_id` | integer | **{check-circle}** Yes | The ID of the group. | -| `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](rest/index.md#namespaced-path-encoding). | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" @@ -2351,8 +2406,8 @@ POST /projects/:id/import_project_members/:project_id | Attribute | Type | Required | Description | |--------------|-------------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the target project to receive the members. | -| `project_id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the source project to import the members from. | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the target project to receive the members. | +| `project_id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the source project to import the members from. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/import_project_members/32" @@ -2379,7 +2434,7 @@ GET /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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ### Get project hook @@ -2392,7 +2447,7 @@ GET /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|---------------------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of a project hook. | -| `id` | integer 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](rest/index.md#namespaced-path-encoding). | ```json { @@ -2413,6 +2468,10 @@ GET /projects/:id/hooks/:hook_id "deployment_events": true, "releases_events": true, "enable_ssl_verification": true, + "repository_update_events": false, + "alert_status": "executable", + "disabled_until": null, + "url_variables": [ ], "created_at": "2012-10-12T17:04:47Z" } ``` @@ -2427,7 +2486,7 @@ 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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/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. | @@ -2456,7 +2515,7 @@ 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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/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. | @@ -2486,7 +2545,7 @@ DELETE /projects/:id/hooks/:hook_id | Attribute | Type | Required | Description | |-----------|----------------|------------------------|-------------| | `hook_id` | integer | **{check-circle}** Yes | The ID of the project hook. | -| `id` | integer 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](rest/index.md#namespaced-path-encoding). | Note the JSON response differs if the hook is available or not. If the project hook is available before it's returned in the JSON response or an empty response @@ -2506,7 +2565,7 @@ POST /projects/:id/fork/:forked_from_id | Attribute | Type | Required | Description | |------------------|----------------|------------------------|-------------| | `forked_from_id` | ID | **{check-circle}** Yes | The ID of the project that was forked from. | -| `id` | integer 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](rest/index.md#namespaced-path-encoding). | ### Delete an existing forked from relationship @@ -2516,7 +2575,7 @@ DELETE /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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ## Search for projects by name @@ -2546,7 +2605,8 @@ POST /projects/:id/housekeeping | 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](rest/index.md#namespaced-path-encoding). | +| `task` | string | **{dotted-circle}** No | `prune` to trigger manual prune of unreachable objects or `eager` to trigger eager housekeeping. | ## Push rules **(PREMIUM)** @@ -2561,7 +2621,7 @@ GET /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) | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | ```json { @@ -2582,20 +2642,6 @@ GET /projects/:id/push_rule } ``` -Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) -can also see the `commit_committer_check` and `reject_unsigned_commits` -parameters: - -```json -{ - "id": 1, - "project_id": 3, - "commit_committer_check": false, - "reject_unsigned_commits": false - ... -} -``` - ### Add project push rule Adds a push rule to a specified project. @@ -2606,7 +2652,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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/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 if the committer email is one of their own verified emails. | @@ -2629,7 +2675,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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/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 if the committer email is one of their own verified emails. | @@ -2655,7 +2701,7 @@ DELETE /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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ## Get groups to which a user can transfer a project @@ -2669,7 +2715,7 @@ GET /projects/:id/transfer_locations | 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](rest/index.md#namespaced-path-encoding). | | `search` | string | **{dotted-circle}** No | The group names to search for. | Example request: @@ -2714,7 +2760,7 @@ PUT /projects/:id/transfer | 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](rest/index.md#namespaced-path-encoding). | | `namespace` | integer or string | **{check-circle}** Yes | The ID or path of the namespace to transfer to project to. | Example request: @@ -2801,6 +2847,7 @@ Example response: "security_and_compliance_access_level": "enabled", "emails_disabled": null, "shared_runners_enabled": true, + "group_runners_enabled": true, "lfs_enabled": true, "creator_id": 2, "import_status": "none", @@ -2849,7 +2896,7 @@ Read more in the [Project vulnerabilities](project_vulnerabilities.md) documenta ## Get a project's pull mirror details **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354506) in GitLab 15.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354506) in GitLab 15.6. Returns the details of the project's pull mirror. @@ -2861,7 +2908,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). | +| `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | Example request: @@ -2922,7 +2969,7 @@ POST /projects/:id/mirror/pull | 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](rest/index.md#namespaced-path-encoding). | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/mirror/pull" @@ -2949,14 +2996,17 @@ GET /projects/:id/snapshot | 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](rest/index.md#namespaced-path-encoding). | | `wiki` | boolean | **{dotted-circle}** No | Whether to download the wiki, rather than project, repository. | ## Get the path to repository storage > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29861) in GitLab 14.0. -Get the path to repository storage for specified project. Available for administrators only. +Get the path to repository storage for specified project if Gitaly Cluster is not being used. If Gitaly Cluster is being used, see +[Praefect-generated replica paths (GitLab 15.0 and later)](../administration/gitaly/index.md#praefect-generated-replica-paths-gitlab-150-and-later). + +Available for administrators only. ```plaintext GET /projects/:id/storage @@ -2964,7 +3014,7 @@ GET /projects/:id/storage | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `id` | integer or string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | ```json [ diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 6b702ad7e03..5f6e03fde4d 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -27,7 +27,7 @@ GET /projects/:id/protected_branches | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `search` | string | no | Name or part of the name of protected branches to be searched for | ```shell @@ -83,7 +83,8 @@ Example response: ``` Users on GitLab Premium or higher also see -the `user_id` and `group_id` parameters: +the `user_id`, `group_id` and `inherited` parameters. If the `inherited` parameter +exists, means the setting was inherited from the project's group. Example response: @@ -111,7 +112,8 @@ Example response: } ], "allow_force_push":false, - "code_owner_approval_required": false + "code_owner_approval_required": false, + "inherited": true }, ... ] @@ -127,7 +129,7 @@ GET /projects/:id/protected_branches/:name | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch or wildcard | ```shell @@ -206,7 +208,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch or wildcard | | `push_access_level` | integer | no | Access levels allowed to push (defaults: `40`, Maintainer role) | | `merge_access_level` | integer | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | @@ -418,7 +420,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | ## Update a protected branch @@ -437,7 +439,7 @@ curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitl | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | | `allow_force_push` | boolean | no | When enabled, members who can push to this branch can also force push. | | `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). Defaults to `false`. | diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index ec0657148da..1ea3fc5adda 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -40,7 +40,7 @@ GET /projects/:id/protected_environments | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_environments/" @@ -77,7 +77,7 @@ GET /projects/:id/protected_environments/:name | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the protected environment | ```shell @@ -113,7 +113,7 @@ POST /projects/:id/protected_environments | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the environment. | | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. | | `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | @@ -183,7 +183,7 @@ PUT /projects/:id/protected_environments/:name | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the environment. | | `deploy_access_levels` | array | no | Array of access levels allowed to deploy, with each described by a hash. | | `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. | @@ -353,7 +353,7 @@ DELETE /projects/:id/protected_environments/:name | 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. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the protected environment. | ```shell diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index 88b868a3965..633ca441fad 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -27,7 +27,7 @@ GET /projects/:id/protected_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_tags" @@ -62,7 +62,7 @@ GET /projects/:id/protected_tags/:name | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag or wildcard | ```shell @@ -99,7 +99,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag or wildcard | | `create_access_level` | string | no | Access levels allowed to create (defaults: `40`, Maintainer role) | | `allowed_to_create` | array | no | Array of access levels allowed to create tags, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | @@ -133,5 +133,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the tag | diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index d5d858c1647..f23f2b36ed0 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -36,19 +36,24 @@ GET /projects/:id/releases | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `order_by` | string | no | The field to use as order. Either `released_at` (default) or `created_at`. | | `sort` | string | no | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | -If successful, returns [`200 OK`](../../api/index.md#status-codes) and the following +If successful, returns [`200 OK`](../../api/rest/index.md#status-codes) and the following response attributes: -| Attribute | Type | Description | -|:---------------------|:--------|:------------------------------------- | -| `[]._links` | object | Links of the release. | -| `[]._links.self` | string | HTTP URL of the release. | -| `[]._links.edit_url` | string | HTTP URL of the release's edit page. | +| Attribute | Type | Description | +|:--------------------------------------|:-------|:-------------------------------------------------| +| `[]._links` | object | Links of the release. | +| `[]._links.closed_issues_url` | string | HTTP URL of the release's closed issues. | +| `[]._links.closed_merge_requests_url` | string | HTTP URL of the release's closed merge requests. | +| `[]._links.edit_url` | string | HTTP URL of the release's edit page. | +| `[]._links.merged_merge_requests_url` | string | HTTP URL of the release's merged merge requests. | +| `[]._links.opened_issues_url` | string | HTTP URL of the release's open issues. | +| `[]._links.opened_merge_requests_url` | string | HTTP URL of the release's open merge requests. | +| `[]._links.self` | string | HTTP URL of the release. | Example request: @@ -153,14 +158,14 @@ Example response: "id":2, "name":"awesome-v0.2.msi", "url":"http://192.168.10.15:3000/msi", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" }, { "id":1, "name":"awesome-v0.2.dmg", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ], @@ -237,8 +242,13 @@ Example response: } ], "_links": { - "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1", - "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit" + "closed_issues_url": "https://gitlab.example.com/root/awesome-app/-/issues?release_tag=v0.1&scope=all&state=closed", + "closed_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=closed", + "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit", + "merged_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=merged", + "opened_issues_url": "https://gitlab.example.com/root/awesome-app/-/issues?release_tag=v0.1&scope=all&state=opened", + "opened_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=opened", + "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1" } } ] @@ -256,18 +266,23 @@ GET /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | |----------------------------| -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | -If successful, returns [`200 OK`](../../api/index.md#status-codes) and the following +If successful, returns [`200 OK`](../../api/rest/index.md#status-codes) and the following response attributes: -| Attribute | Type | Description | -|:------------------|:--------|:------------------------------------- | -| `_links` | object | Links of the release. | -| `_links.self` | string | HTTP URL of the release. | -| `_links.edit_url` | string | HTTP URL of the release's edit page. | +| Attribute | Type | Description | +|:--------------------------------------|:-------|:-------------------------------------------------| +| `[]._links` | object | Links of the release. | +| `[]._links.closed_issues_url` | string | HTTP URL of the release's closed issues. | +| `[]._links.closed_merge_requests_url` | string | HTTP URL of the release's closed merge requests. | +| `[]._links.edit_url` | string | HTTP URL of the release's edit page. | +| `[]._links.merged_merge_requests_url` | string | HTTP URL of the release's merged merge requests. | +| `[]._links.opened_issues_url` | string | HTTP URL of the release's open issues. | +| `[]._links.opened_merge_requests_url` | string | HTTP URL of the release's open merge requests. | +| `[]._links.self` | string | HTTP URL of the release. | Example request: @@ -371,7 +386,7 @@ Example response: "id":3, "name":"hoge", "url":"https://gitlab.example.com/root/awesome-app/-/tags/v0.11.1/binaries/linux-amd64", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ] @@ -383,8 +398,13 @@ Example response: "collected_at": "2019-07-16T14:00:12.256Z" }, "_links": { - "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1", - "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit" + "closed_issues_url": "https://gitlab.example.com/root/awesome-app/-/issues?release_tag=v0.1&scope=all&state=closed", + "closed_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=closed", + "edit_url": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1/edit", + "merged_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=merged", + "opened_issues_url": "https://gitlab.example.com/root/awesome-app/-/issues?release_tag=v0.1&scope=all&state=opened", + "opened_merge_requests_url": "https://gitlab.example.com/root/awesome-app/-/merge_requests?release_tag=v0.1&scope=all&state=opened", + "self": "https://gitlab.example.com/root/awesome-app/-/releases/v0.1" } ] } @@ -397,14 +417,15 @@ Example response: Download a release asset file by making a request with the following format: ```plaintext -GET /projects/:id/releases/:tag_name/downloads/:filepath +GET /projects/:id/releases/:tag_name/downloads/:direct_asset_path ``` | Attribute | Type | Required | Description | |----------------------------| -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | -| `filepath` | string | yes | Path to the release asset file as specified when [creating](links.md#create-a-release-link) or [updating](links.md#update-a-release-link) its link. | +| `filepath` | string | yes | Deprecated: Use `direct_asset_path` instead. | +| `direct_asset_path` | string | yes | Path to the release asset file as specified when [creating](links.md#create-a-release-link) or [updating](links.md#update-a-release-link) its link. | Example request: @@ -453,7 +474,7 @@ POST /projects/:id/releases | Attribute | Type | Required | Description | | -------------------| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `name` | string | no | The release name. | | `tag_name` | string | yes | The tag where the release is created from. | | `tag_message` | string | no | Message to use if creating a new annotated tag. | @@ -463,15 +484,16 @@ POST /projects/:id/releases | `assets:links` | array of hash | no | An array of assets links. | | `assets:links:name`| string | required by: `assets:links` | The name of the link. Link names must be unique within the release. | | `assets:links:url` | string | required by: `assets:links` | The URL of the link. Link URLs must be unique within the release. | -| `assets:links:filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). -| `assets:links:link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. +| `assets:links:filepath` | string | no | Deprecated: Use `direct_asset_path` instead. | +| `assets:links:direct_asset_path` | string | no | Optional path for a [direct asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). | +| `assets:links:link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | | `released_at` | datetime | no | Date and time for the release. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Only provide this field if creating an [upcoming](../../user/project/releases/index.md#upcoming-releases) or [historical](../../user/project/releases/index.md#historical-releases) release. | Example request: ```shell curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: <your_access_token>" \ - --data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "milestones": ["v1.0", "v1.0-rc"], "assets": { "links": [{ "name": "hoge", "url": "https://google.com", "filepath": "/binaries/linux-amd64", "link_type":"other" }] } }' \ + --data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "milestones": ["v1.0", "v1.0-rc"], "assets": { "links": [{ "name": "hoge", "url": "https://google.com", "direct_asset_path": "/binaries/linux-amd64", "link_type":"other" }] } }' \ --request POST "https://gitlab.example.com/api/v4/projects/24/releases" ``` @@ -572,7 +594,7 @@ Example response: "id":3, "name":"hoge", "url":"https://gitlab.example.com/root/awesome-app/-/tags/v0.11.1/binaries/linux-amd64", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ], @@ -603,7 +625,7 @@ POST /projects/:id/releases/:tag_name/evidence | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | Example request: @@ -630,7 +652,7 @@ PUT /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | | `name` | string | no | The release name. | | `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). | @@ -739,7 +761,7 @@ DELETE /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The Git tag the release is associated with. | Example request: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 732f5ea57ef..74f6b1c9efa 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -23,7 +23,7 @@ GET /projects/:id/releases/:tag_name/assets/links | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | Example request: @@ -40,14 +40,14 @@ Example response: "id":2, "name":"awesome-v0.2.msi", "url":"http://192.168.10.15:3000/msi", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" }, { "id":1, "name":"awesome-v0.2.dmg", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ] @@ -63,7 +63,7 @@ GET /projects/:id/releases/:tag_name/assets/links/:link_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | | `link_id` | integer | yes | The ID of the link. | @@ -80,7 +80,7 @@ Example response: "id":1, "name":"awesome-v0.2.dmg", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ``` @@ -93,14 +93,15 @@ Creates an asset as a link from a release. POST /projects/:id/releases/:tag_name/assets/links ``` -| Attribute | Type | Required | Description | -|-------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | -| `tag_name` | string | yes | The tag associated with the Release. | -| `name` | string | yes | The name of the link. Link names must be unique in the release. | -| `url` | string | yes | The URL of the link. Link URLs must be unique in the release. | -| `filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). | -| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | +| Attribute | Type | Required | Description | +|----------------------|----------------|----------|---------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `name` | string | yes | The name of the link. Link names must be unique in the release. | +| `url` | string | yes | The URL of the link. Link URLs must be unique in the release. | +| `filepath` | string | no | Deprecated: Use `direct_asset_path` instead. | +| `direct_asset_path` | string | no | Optional path for a [direct asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). | +| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | Example request: @@ -109,7 +110,7 @@ curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data name="hellodarwin-amd64" \ --data url="https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64" \ - --data filepath="/bin/hellodarwin-amd64" \ + --data direct_asset_path="/bin/hellodarwin-amd64" \ "https://gitlab.example.com/api/v4/projects/20/releases/v1.7.0/assets/links" ``` @@ -121,7 +122,7 @@ Example response: "name":"hellodarwin-amd64", "url":"https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64", "direct_asset_url":"https://gitlab.example.com/mynamespace/hello/-/releases/v1.7.0/downloads/bin/hellodarwin-amd64", - "external":false, + "external":false, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ``` @@ -134,15 +135,16 @@ Updates an asset as a link from a release. PUT /projects/:id/releases/:tag_name/assets/links/:link_id ``` -| Attribute | Type | Required | Description | -| ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | -| `tag_name` | string | yes | The tag associated with the Release. | -| `link_id` | integer | yes | The ID of the link. | -| `name` | string | no | The name of the link. | -| `url` | string | no | The URL of the link. | -| `filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). -| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | +| Attribute | Type | Required | Description | +| -------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `link_id` | integer | yes | The ID of the link. | +| `name` | string | no | The name of the link. | +| `url` | string | no | The URL of the link. | +| `filepath` | string | no | Deprecated: Use `direct_asset_path` instead. | +| `direct_asset_path` | string | no | Optional path for a [direct asset link](../../user/project/releases/release_fields.md#permanent-links-to-release-assets). | +| `link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | NOTE: You have to specify at least one of `name` or `url` @@ -162,7 +164,7 @@ Example response: "id":1, "name":"new name", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"runbook" } ``` @@ -177,7 +179,7 @@ DELETE /projects/:id/releases/:tag_name/assets/links/:link_id | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../rest/index.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag associated with the Release. | | `link_id` | integer | yes | The ID of the link. | @@ -194,7 +196,7 @@ Example response: "id":1, "name":"new name", "url":"http://192.168.10.15:3000", - "external":true, + "external":true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type":"other" } ``` diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index 00dc34e261a..93dffe69ef5 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -14,6 +14,11 @@ can query and modify the state of these mirrors with the remote mirror API. For security reasons, the `url` attribute in the API response is always scrubbed of username and password information. +NOTE: +[Pull mirrors](../user/project/repository/mirror/pull.md) use +[a different API endpoint](projects.md#configure-pull-mirroring-for-a-project) to +display and update them. + ## List a project's remote mirrors Returns an array of remote mirrors and their statuses: diff --git a/doc/api/repositories.md b/doc/api/repositories.md index dcbb5d14741..a34fde54e90 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -20,7 +20,7 @@ command. For more information, refer to the section in the Git internals documentation. WARNING: -This endpoint changed to [keyset-based pagination](index.md#keyset-based-pagination) +This endpoint changed to [keyset-based pagination](rest/index.md#keyset-based-pagination) in GitLab 15.0. Iterating pages of results with a number (`?page=2`) is unsupported. ```plaintext @@ -31,11 +31,11 @@ Supported attributes: | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `page_token` | string | no | The tree record ID at which to fetch the next page. Used only with keyset pagination. | -| `pagination` | string | no | If `keyset`, use the [keyset-based pagination method](index.md#keyset-based-pagination). | +| `pagination` | string | no | If `keyset`, use the [keyset-based pagination method](rest/index.md#keyset-based-pagination). | | `path` | string | no | The path inside the repository. Used to get content of subdirectories. | -| `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](index.md#pagination). | +| `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. For more information, see [Pagination](rest/index.md#pagination). | | `recursive` | boolean | no | Boolean value used to get a recursive tree. Default is `false`. | | `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch. | @@ -107,7 +107,7 @@ Supported attributes: | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | yes | The blob SHA. | ## Raw blob content @@ -123,7 +123,7 @@ Supported attributes: | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | yes | The blob SHA. | ## Get file archive @@ -157,7 +157,7 @@ Supported attributes: | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `path` | string | no | The subpath of the repository to download. If an empty string, defaults to the whole repository. | | `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. If not specified, defaults to the tip of the default branch. | @@ -181,7 +181,7 @@ Supported attributes: | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `from` | string | yes | The commit SHA or branch name. | | `to` | string | yes | The commit SHA or branch name. | | `from_project_id` | integer | no | The ID to compare from. | @@ -243,7 +243,7 @@ Supported attributes: | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`. | | `sort` | string | no | Return contributors sorted in `asc` or `desc` order. Default is `asc`. | @@ -275,7 +275,7 @@ GET /projects/:id/repository/merge_base | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ---------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | | `refs` | array | yes | The refs to find the common ancestor of. Accepts multiple refs. | Example request: @@ -316,11 +316,15 @@ of commits, GitLab generates a changelog for all commits that use a particular a new Markdown-formatted section to a changelog file in the Git repository of the project. The output format can be customized. +For user-facing documentation, see [Changelogs](../user/project/changelogs.md). + ```plaintext POST /projects/:id/repository/changelog ``` -Supported attributes: +### Supported attributes + +Changelogs support these attributes: | Attribute | Type | Required | Description | | :-------- | :------- | :--------- | :---------- | @@ -403,319 +407,6 @@ To store the results in a different file, use the `file` parameter: curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog" ``` -### How it works - -Changelogs are generated based on commit titles. Commits are only included if -they contain a specific Git trailer. GitLab uses the value of this trailer to -categorize the changes. - -GitLab uses Git trailers, because Git trailers are -supported by Git out of the box. We use commits as input, as this is the only -source of data every project uses. In addition, commits can be retrieved when -operating on a mirror. This is important for GitLab itself, because during a security -release we might need to include changes from both public projects and private -security mirrors. - -Changelogs are generated by taking the title of the commits to include and using -these as the changelog entries. You can enrich entries with additional data, -such as a link to the merge request or details about the commit author. You can -[customize the format of a changelog](#customize-the-changelog-output) section with a template. - -Trailers can be manually added while editing a commit message. To include a commit -using the default trailer of `Changelog` and categorize it as a feature, the -trailer could be added to a commit message like so: - -```plaintext -<Commit message subject> - -<Commit message description> - -Changelog: feature -``` - -### Reverted commits - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. - -When generating a changelog for a range, GitLab ignores commits both added and -reverted in that range. Revert commits themselves _are_ included if they use the -Git trailer used for generating changelogs. - -Imagine the following scenario: you have three commits: A, B, and C. To generate -changelogs, you use the default trailer `Changelog`. Both A and B use this -trailer. Commit C is a commit that reverts commit B. When generating a changelog -for this range, GitLab only includes commit A. - -Revert commits are detected by looking for commits where the message contains -the pattern `This reverts commit SHA`, where `SHA` is the SHA of the commit that -is reverted. - -If a revert commit includes the trailer used for generating changelogs -(`Changelog` in the above example), the revert commit itself _is_ included. - -### Customize the changelog output - -The output is customized using a YAML configuration file stored in your -project's Git repository. This default configuration file path is -`.gitlab/changelog_config.yml`. - -You can set the following variables in this file: - -- `date_format`: the date format to use in the title of the newly added - changelog data. This uses regular `strftime` formatting. -- `template`: a custom template to use for generating the changelog data. -- `categories`: a hash that maps raw category names to the names to use in the - changelog. -- `include_groups`: a list of group full paths containing users whose - contributions should be credited regardless of project membership. The user - generating the changelog must have access to each group or the members will - not be credited. - -Using the default settings, generating a changelog results in a section along -the lines of the following: - -```markdown -## 1.0.0 (2021-01-05) - -### Features (4 changes) - -- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123)) -- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) -- [Feature 3](gitlab-org/gitlab@234abc) by @steve -- [Feature 4](gitlab-org/gitlab@456) -``` - -Each section starts with a title that contains the version and release date. -While the format of the date can be customized, the rest of the title can't be -changed. When adding a new section, GitLab parses these titles to determine -where in the file the new section should be placed. GitLab sorts sections -according to their versions, not their dates. - -Each section can have categories, each with their -corresponding changes. In the above example, "Features" is one such category. -You can customize the format of these sections. - -The section names are derived from the values of the Git trailer used to include -or exclude commits. - -For example, if the trailer to use is called `Changelog`, -and its value is `feature`, then the commit is grouped in the `feature` -category. The names of these raw values might differ from what you want to -show in a changelog, you can remap them. Let's say we use the `Changelog` -trailer and developers use the following values: `feature`, `bug`, and -`performance`. - -You can remap these using the following YAML configuration file: - -```yaml ---- -categories: - feature: Features - bug: Bug fixes - performance: Performance improvements -``` - -When generating the changelog data, the category titles are then `### Features`, -`### Bug fixes`, and `### Performance improvements`. - -### Custom templates - -The category sections are generated using a template. The default template is as -follows: - -```plaintext -{% if categories %} -{% each categories %} -### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %}) - -{% each entries %} -- [{{ title }}]({{ commit.reference }})\ -{% if author.credit %} by {{ author.reference }}{% end %}\ -{% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} - -{% end %} - -{% end %} -{% else %} -No changes. -{% end %} -``` - -The `{% ... %}` tags are for statements, and `{{ ... }}` is used for printing -data. Statements must be terminated using a `{% end %}` tag. Both the `if` and -`each` statements require a single argument. - -For example, if we have a variable `valid`, and we want to display "yes" -when this value is true, and display "nope" otherwise. We can do so as follows: - -```plaintext -{% if valid %} -yes -{% else %} -nope -{% end %} -``` - -The use of `else` is optional. A value is considered true when it's a non-empty -value or boolean `true`. Empty arrays and hashes are considered false. - -Looping is done using `each`, and variables inside a loop are scoped to it. -Referring to the current value in a loop is done using the variable tag `{{ it -}}`. Other variables read their value from the current loop value. Take -this template for example: - -```plaintext -{% each users %} -{{name}} -{% end %} -``` - -Assuming `users` is an array of objects, each with a `name` field, this would -then print the name of every user. - -Using variable tags, you can access nested objects. For example, `{{ -users.0.name }}` prints the name of the first user in the `users` variable. - -If a line ends in a backslash, the next newline is ignored. This allows you to -wrap code across multiple lines, without introducing unnecessary newlines in the -Markdown output. - -Tags that use `{%` and `%}` (known as expression tags) consume the newline that -directly follows them, if any. This means that this: - -```plaintext ---- -{% if foo %} -bar -{% end %} ---- -``` - -Compiles into this: - -```plaintext ---- -bar ---- -``` - -Instead of this: - -```plaintext ---- - -bar - ---- -``` - -You can specify a custom template in your configuration like so: - -```yaml ---- -template: | - {% if categories %} - {% each categories %} - ### {{ title }} - - {% each entries %} - - [{{ title }}]({{ commit.reference }})\ - {% if author.credit %} by {{ author.reference }}{% end %} - - {% end %} - - {% end %} - {% else %} - No changes. - {% end %} -``` - -When specifying the template you should use `template: |` and not -`template: >`, as the latter doesn't preserve newlines in the template. - -### Template data - -At the top level, the following variable is available: - -- `categories`: an array of objects, one for every changelog category. - -In a category, the following variables are available: - -- `count`: the number of entries in this category. -- `entries`: the entries that belong to this category. -- `single_change`: a boolean that indicates if there is only one change (`true`), - or multiple changes (`false`). -- `title`: the title of the category (after it has been remapped). - -In an entry, the following variables are available (here `foo.bar` means that -`bar` is a sub-field of `foo`): - -- `author.contributor`: a boolean set to `true` when the author is not a project - member, otherwise `false`. -- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or - when `include_groups` is configured, and the author is a member of one of the - groups. -- `author.reference`: a reference to the commit author (for example, `@alice`). -- `commit.reference`: a reference to the commit, for example, - `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. -- `commit.trailers`: an object containing all the Git trailers that were present - in the commit body. -- `merge_request.reference`: a reference to the merge request that first - introduced the change (for example, `gitlab-org/gitlab!50063`). -- `title`: the title of the changelog entry (this is the commit title). - -The `author` and `merge_request` objects might not be present if the data -couldn't be determined. For example, when a commit is created without a -corresponding merge request, no merge request is displayed. - -### Customize the tag format when extracting versions - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56889) in GitLab 13.11. - -GitLab uses a regular expression (using the -[re2](https://github.com/google/re2/) engine and syntax) to extract a semantic -version from tag names. The default regular expression is: - -```plaintext -^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ -``` - -This regular expression is based on the official -[semantic versioning](https://semver.org/) regular expression, and also includes -support for tag names that start with the letter `v`. - -If your project uses a different format for tags, you can specify a different -regular expression. The regular expression used _must_ produce the following -capture groups. If any of these capture groups are missing, the tag is ignored: - -- `major` -- `minor` -- `patch` - -The following capture groups are optional: - -- `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate - tags and other pre-release tags are not considered when determining the range of - commits to generate a changelog for. -- `meta`: Optional. Specifies build metadata. - -Using this information, GitLab builds a map of Git tags and their release -versions. It then determines what the latest tag is, based on the version -extracted from each tag. - -To specify a custom regular expression, use the `tag_regex` setting in your -changelog configuration YAML file. For example, this pattern matches tag names -such as `version-1.2.3` but not `version-1.2`. - -```yaml ---- -tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$' -``` - -To test if your regular expression is working, you can use websites such as -[regex101](https://regex101.com/). If the regular expression syntax is invalid, -an error is produced when generating a changelog. - ## Generate changelog data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345934) in GitLab 14.6. @@ -738,7 +429,7 @@ Supported attributes: | `config_file` | string | no | The path of changelog configuration file in the project's Git repository, defaults to `.gitlab/changelog_config.yml`. | | `date` | datetime | no | The date and time of the release, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z`. Defaults to the current time. | | `from` | string | no | The start of the range of commits (as a SHA) to use for generating the changelog. This commit itself isn't included in the list. | -| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the branch specified in the `branch` attribute. | +| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the HEAD of the default project branch. | | `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | ```shell @@ -752,3 +443,8 @@ Example Response: "notes": "## 1.0.0 (2021-11-17)\n\n### feature (2 changes)\n\n- [Title 2](namespace13/project13@ad608eb642124f5b3944ac0ac772fecaf570a6bf) ([merge request](namespace13/project13!2))\n- [Title 1](namespace13/project13@3c6b80ff7034fa0d585314e1571cc780596ce3c8) ([merge request](namespace13/project13!1))\n" } ``` + +## Related topics + +- User documentation for [changelogs](../user/project/changelogs.md) +- Developer documentation for [changelog entries](../development/changelog.md) in GitLab. diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index e105f5ee5e3..23243cdadc2 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -39,7 +39,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `file_path` | string | yes | URL encoded full path to new file, such as `lib%2Fclass%2Erb`. | | `ref` | string | yes | The name of branch, tag or commit. | @@ -103,7 +103,7 @@ GET /projects/:id/repository/files/:file_path/blame | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `file_path` | string | yes | URL-encoded full path to new file, such as`lib%2Fclass%2Erb`. | | `ref` | string | yes | The name of branch, tag or commit. | | `range[end]` | integer | yes | The last line of the range to blame. | @@ -211,7 +211,7 @@ GET /projects/:id/repository/files/:file_path/raw | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `file_path` | string | yes | URL-encoded full path to new file, such as `lib%2Fclass%2Erb`. | | `ref` | string | yes | The name of branch, tag or commit. Default is the `HEAD` of the project. | | `lfs` | boolean | no | Determines if the response should be Git LFS file contents, rather than the pointer. If the file is not tracked by Git LFS, ignored. Defaults to `false`. | @@ -240,7 +240,7 @@ POST /projects/:id/repository/files/:file_path | `commit_message` | string | yes | The commit message. | | `content` | string | yes | The file's content. | | `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `author_email` | string | no | The commit author's email address. | | `author_name` | string | no | The commit author's name. | | `encoding` | string | no | Change encoding to `base64`. Default is `text`. | @@ -281,7 +281,7 @@ PUT /projects/:id/repository/files/:file_path | `commit_message` | string | yes | The commit message. | | `content` | string | yes | The file's content. | | `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `author_email` | string | no | The commit author's email address. | | `author_name` | string | no | The commit author's name. | | `encoding` | string | no | Change encoding to `base64`. Default is `text`. | @@ -329,7 +329,7 @@ DELETE /projects/:id/repository/files/:file_path | `branch` | string | yes | Name of the new branch to create. The commit is added to this branch. | | `commit_message` | string | yes | The commit message. | | `file_path` | string | yes | URL-encoded full path to new file. For example: `lib%2Fclass%2Erb`. | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `author_email` | string | no | The commit author's email address. | | `author_name` | string | no | The commit author's name. | | `last_commit_id` | string | no | Last known file commit ID. | diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 1dd65ed60b8..b4988b39eaf 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -19,7 +19,7 @@ PUT /projects/:id/repository/submodules/:submodule | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `submodule` | string | yes | URL-encoded full path to the submodule. For example, `lib%2Fclass%2Erb` | | `branch` | string | yes | Name of the branch to commit into | | `commit_sha` | string | yes | Full commit SHA to update the submodule to | diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md index 114dc4e383e..cdba0c01f4f 100644 --- a/doc/api/resource_groups.md +++ b/doc/api/resource_groups.md @@ -16,7 +16,7 @@ GET /projects/:id/resource_groups | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/resource_groups" @@ -44,7 +44,7 @@ GET /projects/:id/resource_groups/:key | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The key of the resource group | ```shell @@ -71,7 +71,7 @@ GET /projects/:id/resource_groups/:key/upcoming_jobs | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The key of the resource group | ```shell @@ -170,7 +170,7 @@ PUT /projects/:id/resource_groups/:key | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The key of the resource group | | `process_mode` | string | no | The process mode of the resource group. One of `unordered`, `oldest_first` or `newest_first`. Read [process modes](../ci/resource_groups/index.md#process-modes) for more information. | diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md index 41e1ddd725b..e8537750f0d 100644 --- a/doc/api/resource_iteration_events.md +++ b/doc/api/resource_iteration_events.md @@ -26,7 +26,7 @@ GET /projects/:id/issues/:issue_iid/resource_iteration_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -108,7 +108,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_iteration_event_id` | integer | yes | The ID of an iteration event | diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index 62a37806459..9f0c9db6d71 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -21,7 +21,7 @@ GET /projects/:id/issues/:issue_iid/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | ```json @@ -87,7 +87,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | | `resource_label_event_id` | integer | yes | The ID of a label event | @@ -107,7 +107,7 @@ GET /groups/:id/epics/:epic_id/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | ```json @@ -173,7 +173,7 @@ Parameters: | Attribute | Type | Required | Description | | --------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of an epic | | `resource_label_event_id` | integer | yes | The ID of a label event | @@ -193,7 +193,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_label_events | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | ```json @@ -259,7 +259,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_label_event_id` | integer | yes | The ID of a label event | diff --git a/doc/api/resource_milestone_events.md b/doc/api/resource_milestone_events.md index d1e0b4fe053..897f5bf7ca2 100644 --- a/doc/api/resource_milestone_events.md +++ b/doc/api/resource_milestone_events.md @@ -25,7 +25,7 @@ GET /projects/:id/issues/:issue_iid/resource_milestone_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -109,7 +109,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_milestone_event_id` | integer | yes | The ID of a milestone event | @@ -131,7 +131,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_milestone_events | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `merge_request_iid` | integer | yes | The IID of a merge request | Example request: @@ -215,7 +215,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_milestone_event_id` | integer | yes | The ID of a milestone event | diff --git a/doc/api/resource_state_events.md b/doc/api/resource_state_events.md index 5ea588167a0..d17b6c39686 100644 --- a/doc/api/resource_state_events.md +++ b/doc/api/resource_state_events.md @@ -25,7 +25,7 @@ GET /projects/:id/issues/:issue_iid/resource_state_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -83,7 +83,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_state_event_id` | integer | yes | The ID of a state event | @@ -125,7 +125,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_state_events | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `merge_request_iid` | integer | yes | The IID of a merge request | Example request: @@ -183,7 +183,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `resource_state_event_id` | integer | yes | The ID of a state event | @@ -227,7 +227,7 @@ GET /groups/:id/epics/:epic_id/resource_state_events | Attribute | Type | Required | Description | |-------------| -------------- | -------- |--------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `epic_id` | integer | yes | The ID of an epic. | Example request: @@ -285,7 +285,7 @@ Parameters: | Attribute | Type | Required | Description | |---------------------------| -------------- | -------- |-------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | | `epic_id` | integer | yes | The ID of an epic. | | `resource_state_event_id` | integer | yes | The ID of a state event. | diff --git a/doc/api/resource_weight_events.md b/doc/api/resource_weight_events.md index 14596556b7b..1c18e85479c 100644 --- a/doc/api/resource_weight_events.md +++ b/doc/api/resource_weight_events.md @@ -24,7 +24,7 @@ GET /projects/:id/issues/:issue_iid/resource_weight_events | Attribute | Type | Required | Description | | ----------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `issue_iid` | integer | yes | The IID of an issue | Example request: @@ -80,7 +80,7 @@ Parameters: | Attribute | Type | Required | Description | | ----------------------------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project | | `issue_iid` | integer | yes | The IID of an issue | | `resource_weight_event_id` | integer | yes | The ID of a weight event | diff --git a/doc/api/rest/index.md b/doc/api/rest/index.md new file mode 100644 index 00000000000..57d13f2a54f --- /dev/null +++ b/doc/api/rest/index.md @@ -0,0 +1,784 @@ +--- +stage: Manage +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# REST API **(FREE)** + +The REST APIs have been around for a longer time compared to GraphQL APIs, which +may make them more familiar to some developers. It is often a good choice for +developers who are more comfortable with traditional API architecture. + +## Compatibility guidelines + +The HTTP API is versioned with a single number, which is currently `4`. This number +symbolizes the major version number, as described by [SemVer](https://semver.org/). +Because of this, backward-incompatible changes require this version number to +change. + +The minor version isn't explicit, which allows for a stable API +endpoint. New features can be added to the API in the same +version number. + +New features and bug fixes are released in tandem with GitLab. Apart +from incidental patch and security releases, GitLab is released on the 22nd of each +month. Major API version changes, and removal of entire API versions, are done in tandem +with major GitLab releases. + +All deprecations and changes between versions are in the documentation. + +### Current status + +Only API version v4 is available. + +## How to use the API + +API requests must include both `api` and the API version. The API +version is defined in [`lib/api.rb`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/api/api.rb). +For example, the root of the v4 API is at `/api/v4`. + +### Valid API request + +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" +``` + +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: + +```shell +curl --include "https://gitlab.example.com/api/v4/projects" +HTTP/2 200 +... +``` + +This request can help you investigate an unexpected response. + +### API request that includes the exit code + +If you want to expose the HTTP exit code, include the `--fail` option: + +```shell +curl --fail "https://gitlab.example.com/api/v4/does-not-exist" +curl: (22) The requested URL returned error: 404 +``` + +The HTTP exit code can help you diagnose the success or failure of your REST request. + +## Authentication + +Most API requests require authentication, or only return public data when +authentication isn't provided. When authentication is not required, the documentation +for each endpoint specifies this. For example, the +[`/projects/:id` endpoint](../projects.md#get-single-project) does not require authentication. + +There are several ways you can authenticate with the GitLab API: + +- [OAuth2 tokens](#oauth2-tokens) +- [Personal access tokens](../../user/profile/personal_access_tokens.md) +- [Project access tokens](../../user/project/settings/project_access_tokens.md) +- [Group access tokens](../../user/group/settings/group_access_tokens.md) +- [Session cookie](#session-cookie) +- [GitLab CI/CD job token](../../ci/jobs/ci_job_token.md) **(Specific endpoints only)** + +Project access tokens are supported by: + +- Self-managed GitLab Free and higher. +- GitLab SaaS Premium and higher. + +If you are an administrator, you or your application can authenticate as a specific user. +To do so, use: + +- [Impersonation tokens](#impersonation-tokens) +- [Sudo](#sudo) + +If authentication information is not valid or is missing, GitLab returns an error +message with a status code of `401`: + +```json +{ + "message": "401 Unauthorized" +} +``` + +NOTE: +Deploy tokens can't be used with the GitLab public API. For details, see +[Deploy Tokens](../../user/project/deploy_tokens/index.md). + +### OAuth2 tokens + +You can use an [OAuth2 token](../oauth2.md) to authenticate with the API by passing +it in either the `access_token` parameter or the `Authorization` header. + +Example of using the OAuth2 token in a parameter: + +```shell +curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN" +``` + +Example of using the OAuth2 token in a header: + +```shell +curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects" +``` + +Read more about [GitLab as an OAuth2 provider](../oauth2.md). + +NOTE: +We recommend OAuth access tokens have an expiration. You can use the `refresh_token` parameter +to refresh tokens. Integrations may need to be updated to use refresh tokens prior to +expiration, which is based on the [`expires_in`](https://datatracker.ietf.org/doc/html/rfc6749#appendix-A.14) +property in the token endpoint response. See [OAuth2 token](../oauth2.md) documentation +for examples requesting a new access token using a refresh token. + +A default refresh setting of two hours is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336598). + +### Personal/project/group access tokens + +You can use access tokens to authenticate with the API by passing it in either +the `private_token` parameter or the `PRIVATE-TOKEN` header. + +Example of using the personal, project, or group access token in a parameter: + +```shell +curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>" +``` + +Example of using the personal, project, or group access token in a header: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" +``` + +You can also use personal, project, or group access tokens with OAuth-compliant headers: + +```shell +curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects" +``` + +### Session cookie + +Signing in to the main GitLab application sets a `_gitlab_session` cookie. The +API uses this cookie for authentication if it's present. Using the API to +generate a new session cookie isn't supported. + +The primary user of this authentication method is the web frontend of GitLab +itself. The web frontend can use the API as the authenticated user to get a +list of projects without explicitly passing an access token. + +### Impersonation tokens + +Impersonation tokens are a type of [personal access token](../../user/profile/personal_access_tokens.md). +They can be created only by an administrator, and are used to authenticate with the +API as a specific user. + +Use impersonation tokens as an alternative to: + +- The user's password or one of their personal access tokens. +- The [Sudo](#sudo) feature. The user's or administrator's password or token + may not be known, or may change over time. + +For more information, see the [users API](../users.md#create-an-impersonation-token) +documentation. + +Impersonation tokens are used exactly like regular personal access tokens, and +can be passed in either the `private_token` parameter or the `PRIVATE-TOKEN` +header. + +#### Disable impersonation + +By default, impersonation is enabled. To disable impersonation: + +**For Omnibus installations** + +1. Edit the `/etc/gitlab/gitlab.rb` file: + + ```ruby + gitlab_rails['impersonation_enabled'] = false + ``` + +1. Save the file, and then [reconfigure](../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +To re-enable impersonation, remove this configuration, and then reconfigure +GitLab. + +**For installations from source** + +1. Edit the `config/gitlab.yml` file: + + ```yaml + gitlab: + impersonation_enabled: false + ``` + +1. Save the file, and then [restart](../../administration/restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. + +To re-enable impersonation, remove this configuration, and then restart GitLab. + +### Sudo + +All API requests support performing an API request as if you were another user, +provided you're authenticated as an administrator with an OAuth or personal +access token that has the `sudo` scope. The API requests are executed with the +permissions of the impersonated user. + +As an [administrator](../../user/permissions.md), pass the `sudo` parameter either +by using query string or a header with an ID or username (case insensitive) of +the user you want to perform the operation as. If passed as a header, the header +name must be `Sudo`. + +If a non administrative access token is provided, GitLab returns an error +message with a status code of `403`: + +```json +{ + "message": "403 Forbidden - Must be admin to use sudo" +} +``` + +If an access token without the `sudo` scope is provided, an error message is +returned with a status code of `403`: + +```json +{ + "error": "insufficient_scope", + "error_description": "The request requires higher privileges than provided by the access token.", + "scope": "sudo" +} +``` + +If the sudo user ID or username cannot be found, an error message is +returned with a status code of `404`: + +```json +{ + "message": "404 User with ID or username '123' Not Found" +} +``` + +Example of a valid API request and a request using cURL with sudo request, +providing a username: + +```plaintext +GET /projects?private_token=<your_access_token>&sudo=username +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" +``` + +Example of a valid API request and a request using cURL with sudo request, +providing an ID: + +```plaintext +GET /projects?private_token=<your_access_token>&sudo=23 +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" +``` + +## Status codes + +The API is designed to return different status codes according to context and +action. This way, if a request results in an error, you can get +insight into what went wrong. + +The following table gives an overview of how the API functions generally behave. + +| Request type | Description | +|---------------|-------------| +| `GET` | Access one or more resources and return the result as JSON. | +| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | +| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. | +| `DELETE` | Returns `204 No Content` if the resource was deleted successfully or `202 Accepted` if the resource is scheduled to be deleted. | + +The following table shows the possible return codes for API requests. + +| Return values | Description | +|--------------------------|-------------| +| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, and the resource itself is returned as JSON. | +| `202 Accepted` | The `GET`, `PUT` or `DELETE` request was successful, and the resource is scheduled for processing. | +| `204 No Content` | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. | +| `201 Created` | The `POST` request was successful, and the resource is returned as JSON. | +| `304 Not Modified` | The resource hasn't been modified since the last request. | +| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | +| `401 Unauthorized` | The user isn't authenticated. A valid [user token](#authentication) is necessary. | +| `403 Forbidden` | The request isn't allowed. For example, the user isn't allowed to delete a project. | +| `404 Not Found` | A resource couldn't be accessed. For example, an ID for a resource couldn't be found. | +| `405 Method Not Allowed` | The request isn't supported. | +| `409 Conflict` | A conflicting resource already exists. For example, creating a project with a name that already exists. | +| `412` | The request was denied. This can happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | +| `422 Unprocessable` | The entity couldn't be processed. | +| `429 Too Many Requests` | The user exceeded the [application rate limits](../../administration/instance_limits.md#rate-limits). | +| `500 Server Error` | While handling the request, something went wrong on the server. | + +## Pagination + +GitLab supports the following pagination methods: + +- Offset-based pagination. This is the default method and is available on all endpoints. +- Keyset-based pagination. Added to selected endpoints but being + [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). + +For large collections, for performance reasons we recommend keyset pagination +(when available) instead of offset pagination. + +### Offset-based pagination + +Sometimes, the returned result spans many pages. When listing resources, you can +pass the following parameters: + +| Parameter | Description | +|------------|-------------| +| `page` | Page number (default: `1`). | +| `per_page` | Number of items to list per page (default: `20`, max: `100`). | + +In the following example, we list 50 [namespaces](../namespaces.md) per page: + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50" +``` + +NOTE: +There is a [max offset allowed limit](../../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination) for offset pagination. You can change the limit in self-managed instances. + +#### Pagination `Link` header + +[`Link` headers](https://www.w3.org/wiki/LinkHeader) are returned with each +response. They have `rel` set to `prev`, `next`, `first`, or `last` and contain +the relevant URL. Be sure to use these links instead of generating your own URLs. + +For GitLab.com users, [some pagination headers may not be returned](../../user/gitlab_com/index.md#pagination-response-headers). + +In the following cURL example, we limit the output to three items per page +(`per_page=3`) and we request the second page (`page=2`) of [comments](../notes.md) +of the issue with ID `8` which belongs to the project with ID `9`: + +```shell +curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" +``` + +The response is: + +```http +HTTP/2 200 OK +cache-control: no-cache +content-length: 1103 +content-type: application/json +date: Mon, 18 Jan 2016 09:43:18 GMT +link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last" +status: 200 OK +vary: Origin +x-next-page: 3 +x-page: 2 +x-per-page: 3 +x-prev-page: 1 +x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86 +x-runtime: 0.108688 +x-total: 8 +x-total-pages: 3 +``` + +#### Other pagination headers + +GitLab also returns the following additional pagination headers: + +| Header | Description | +|-----------------|-------------| +| `x-next-page` | The index of the next page. | +| `x-page` | The index of the current page (starting at 1). | +| `x-per-page` | The number of items per page. | +| `x-prev-page` | The index of the previous page. | +| `x-total` | The total number of items. | +| `x-total-pages` | The total number of pages. | + +For GitLab.com users, [some pagination headers may not be returned](../../user/gitlab_com/index.md#pagination-response-headers). + +### Keyset-based pagination + +Keyset-pagination allows for more efficient retrieval of pages and - in contrast +to offset-based pagination - runtime is independent of the size of the +collection. + +This method is controlled by the following parameters. `order_by` and `sort` are both mandatory. + +| Parameter | Required | Description | +|--------------| ------------ | --------- | +| `pagination` | yes | `keyset` (to enable keyset pagination). | +| `per_page` | no | Number of items to list per page (default: `20`, max: `100`). | +| `order_by` | yes | Column by which to order by. | +| `sort` | yes | Sort order (`asc` or `desc`) | + +In the following example, we list 50 [projects](../projects.md) per page, ordered +by `id` ascending. + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" +``` + +The response header includes a link to the next page. For example: + +```http +HTTP/1.1 200 OK +... +Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next" +Status: 200 OK +... +``` + +The link to the next page contains an additional filter `id_after=42` that +excludes already-retrieved records. + +As another example, the following request lists 50 [groups](../groups.md) per page ordered +by `name` ascending using keyset pagination: + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc" +``` + +The response header includes a link to the next page: + +```http +HTTP/1.1 200 OK +... +Link: <https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc&cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9>; rel="next" +Status: 200 OK +... +``` + +The link to the next page contains an additional filter `cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9` that +excludes already-retrieved records. + +The type of filter depends on the +`order_by` option used, and we can have more than one additional filter. + +WARNING: +The `Links` header was removed in GitLab 14.0 to be aligned with the +[W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` +header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) +and should be used instead. + +When the end of the collection is reached and there are no additional +records to retrieve, the `Link` header is absent and the resulting array is +empty. + +We recommend using only the given link to retrieve the next page instead of +building your own URL. Apart from the headers shown, we don't expose additional +pagination headers. + +Keyset-based pagination is supported only for selected resources and ordering +options: + +| Resource | Options | Availability | +|:---------------------------------------------------------|:---------------------------------|:-------------------------------------------------------------------------------------------------------------| +| [Projects](../projects.md) | `order_by=id` only | Authenticated and unauthenticated users | +| [Groups](../groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | +| [Group audit events](../audit_events.md#group-audit-events) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333968) in GitLab 15.2) | +| [Jobs](../jobs.md) | `order_by=id`, `sort=desc` only | Authenticated users only ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362172) in GitLab 15.9) | + +### Pagination response headers + +For performance reasons, if a query returns more than 10,000 records, GitLab +doesn't return the following headers: + +- `x-total`. +- `x-total-pages`. +- `rel="last"` `link` + +## Path parameters + +If an endpoint has path parameters, the documentation displays them with a +preceding colon. + +For example: + +```plaintext +DELETE /projects/:id/share/:group_id +``` + +The `:id` path parameter needs to be replaced with the project ID, and the +`:group_id` needs to be replaced with the ID of the group. The colons `:` +shouldn't be included. + +The resulting cURL request for a project with ID `5` and a group ID of `17` is then: + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/share/17" +``` + +Path parameters that are required to be URL-encoded must be followed. If not, +it doesn't match an API endpoint and responds with a 404. If there's +something in front of the API (for example, Apache), ensure that it doesn't decode +the URL-encoded path parameters. + +## Namespaced path encoding + +If using namespaced API requests, make sure that the `NAMESPACE/PROJECT_PATH` is +URL-encoded. + +For example, `/` is represented by `%2F`: + +```plaintext +GET /api/v4/projects/diaspora%2Fdiaspora +``` + +A project's _path_ isn't necessarily the same as its _name_. A project's path is +found in the project's URL or in the project's settings, under +**General > Advanced > Change path**. + +## File path, branches, and tags name encoding + +If a file path, branch or tag contains a `/`, make sure it is URL-encoded. + +For example, `/` is represented by `%2F`: + +```plaintext +GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master +GET /api/v4/projects/1/branches/my%2Fbranch/commits +GET /api/v4/projects/1/repository/tags/my%2Ftag +``` + +## Request Payload + +API Requests can use parameters sent as [query strings](https://en.wikipedia.org/wiki/Query_string) +or as a [payload body](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-p3-payload-14#section-3.2). +GET requests usually send a query string, while PUT or POST requests usually +send the payload body: + +- Query string: + + ```shell + curl --request POST "https://gitlab/api/v4/projects?name=<example-name>&description=<example-description>" + ``` + +- Request payload (JSON): + + ```shell + curl --request POST --header "Content-Type: application/json" \ + --data '{"name":"<example-name>", "description":"<example-description>"}' "https://gitlab/api/v4/projects" + ``` + +URL encoded query strings have a length limitation. Requests that are too large +result in a `414 Request-URI Too Large` error message. This can be resolved by +using a payload body instead. + +## Encoding API parameters of `array` and `hash` types + +You can request the API with `array` and `hash` types parameters: + +### `array` + +`import_sources` is a parameter of type `array`: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +-d "import_sources[]=github" \ +-d "import_sources[]=bitbucket" \ +"https://gitlab.example.com/api/v4/some_endpoint" +``` + +### `hash` + +`override_params` is a parameter of type `hash`: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--form "namespace=email" \ +--form "path=impapi" \ +--form "file=@/path/to/somefile.txt" \ +--form "override_params[visibility]=private" \ +--form "override_params[some_other_param]=some_value" \ +"https://gitlab.example.com/api/v4/projects/import" +``` + +### Array of hashes + +`variables` is a parameter of type `array` containing hash key/value pairs +`[{ 'key': 'UPLOAD_TO_S3', 'value': 'true' }]`: + +```shell +curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world" + +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--header "Content-Type: application/json" \ +--data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \ +"https://gitlab.example.com/api/v4/projects/169/pipeline" +``` + +## `id` vs `iid` + +Some resources have two similarly-named fields. For example, [issues](../issues.md), +[merge requests](../merge_requests.md), and [project milestones](../merge_requests.md). +The fields are: + +- `id`: ID that is unique across all projects. +- `iid`: Additional, internal ID (displayed in the web UI) that's unique in the + scope of a single project. + +If a resource has both the `iid` field and the `id` field, the `iid` field is +usually used instead of `id` to fetch the resource. + +For example, suppose a project with `id: 42` has an issue with `id: 46` and +`iid: 5`. In this case: + +- A valid API request to retrieve the issue is `GET /projects/42/issues/5`. +- An invalid API request to retrieve the issue is `GET /projects/42/issues/46`. + +Not all resources with the `iid` field are fetched by `iid`. For guidance +regarding which field to use, see the documentation for the specific resource. + +## Data validation and error reporting + +When working with the API you may encounter validation errors, in which case +the API returns an HTTP `400` error. + +Such errors appear in the following cases: + +- A required attribute of the API request is missing (for example, the title of + an issue isn't given). +- An attribute did not pass the validation (for example, the user bio is too + long). + +When an attribute is missing, you receive something like: + +```http +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message":"400 (Bad request) \"title\" not given" +} +``` + +When a validation error occurs, error messages are different. They hold +all details of validation errors: + +```http +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message": { + "bio": [ + "is too long (maximum is 255 characters)" + ] + } +} +``` + +This makes error messages more machine-readable. The format can be described as +follows: + +```json +{ + "message": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + "<embed-entity>": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + } + } +} +``` + +## Unknown route + +When you attempt to access an API URL that doesn't exist, you receive a +404 Not Found message. + +```http +HTTP/1.1 404 Not Found +Content-Type: application/json +{ + "error": "404 Not Found" +} +``` + +## Encoding `+` in ISO 8601 dates + +If you need to include a `+` in a query parameter, you may need to use `%2B` +instead, due to a [W3 recommendation](https://www.w3.org/Addressing/URL/4_URI_Recommentations.html) +that causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, +you may want to include a specific time in ISO 8601 format, such as: + +```plaintext +2017-10-17T23:11:13.000+05:30 +``` + +The correct encoding for the query parameter would be: + +```plaintext +2017-10-17T23:11:13.000%2B05:30 +``` + +## Clients + +Many unofficial GitLab API Clients are available for most of the popular programming +languages. For a complete list, see the [GitLab website](https://about.gitlab.com/partners/technology-partners/#api-clients). + +## Rate limits + +For administrator documentation on rate limit settings, see +[Rate limits](../../security/rate_limits.md). To find the settings that are +specifically used by GitLab.com, see +[GitLab.com-specific rate limits](../../user/gitlab_com/index.md#gitlabcom-specific-rate-limits). + +## Content type + +The GitLab API supports the `application/json` content type by default, though +some API endpoints also support `text/plain`. + +In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/250342), +API endpoints do not support `text/plain` by default, unless it's explicitly documented. + +## Resolve requests detected as spam + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352913) in GitLab 14.9. + +REST API requests can be detected as spam. If a request is detected as spam and: + +- A CAPTCHA service is not configured, an error response is returned. For example: + + ```json + {"message":{"error":"Your snippet has been recognized as spam and has been discarded."}} + ``` + +- A CAPTCHA service is configured, you receive a response with: + - `needs_captcha_response` set to `true`. + - The `spam_log_id` and `captcha_site_key` fields set. + + For example: + + ```json + {"needs_captcha_response":true,"spam_log_id":42,"captcha_site_key":"REDACTED","message":{"error":"Your snippet has been recognized as spam. Please, change the content or solve the reCAPTCHA to proceed."}} + ``` + +- Use the `captcha_site_key` to obtain a CAPTCHA response value using the appropriate CAPTCHA API. + Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported. +- Resubmit the request with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set. + +```shell +export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>" +export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>" +curl --request POST --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" "https://gitlab.example.com/api/v4/snippets?title=Title&file_name=FileName&content=Content&visibility=public" +``` diff --git a/doc/api/runners.md b/doc/api/runners.md index c692faf9490..be69b762555 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -6,7 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Runners API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5. +[Pagination](rest/index.md#pagination) is available on the following API endpoints (they return 20 items by default): + +```plaintext +GET /runners +GET /runners/all +GET /runners/:id/jobs +GET /projects/:id/runners +GET /groups/:id/runners +``` ## Registration and authentication tokens @@ -33,7 +41,7 @@ GitLab and the runner are then connected. ## List owned runners -Get a list of specific runners available to the user. +Get a list of runners available to the user. ```plaintext GET /runners @@ -46,7 +54,7 @@ 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 return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | | `type` | string | no | The type of runners to return, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to return, one of: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 | | `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | @@ -97,7 +105,7 @@ Example response: ## List all runners **(FREE SELF)** -Get a list of all runners in the GitLab instance (specific and shared). Access +Get a list of all runners in the GitLab instance (project and shared). Access is restricted to users with administrator access. ```plaintext @@ -184,7 +192,7 @@ Example response: ] ``` -To view more than the first 20 runners, use [pagination](index.md#pagination). +To view more than the first 20 runners, use [pagination](rest/index.md#pagination). ## Get runner's details @@ -325,7 +333,7 @@ Example response: ### Pause a runner -Pause a specific runner. +Pause a runner. ```plaintext PUT --form "paused=true" /runners/:runner_id @@ -462,8 +470,8 @@ 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 return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | | `type` | string | no | The type of runners to return, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to return, one of: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 | | `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | @@ -514,7 +522,7 @@ Example response: ## Enable a runner in project -Enable an available specific runner in the project. +Enable an available project runner in the project. ```plaintext POST /projects/:id/runners @@ -522,7 +530,7 @@ POST /projects/:id/runners | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ```shell @@ -548,7 +556,7 @@ Example response: ## Disable a runner from project -Disable a specific runner from the project. It works only if the project isn't +Disable a project runner from the project. It works only if the project isn't the only project associated with the specified runner. If so, an error is returned. Use the call to [delete a runner](#delete-a-runner) instead. @@ -558,7 +566,7 @@ DELETE /projects/:id/runners/:runner_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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ```shell @@ -739,9 +747,10 @@ Validates authentication credentials for a registered runner. POST /runners/verify ``` -| Attribute | Type | Required | Description | -|-------------|---------|----------|-------------------------------------------------------------------------------| -| `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). | +| Attribute | Type | Required | Description | +|-------------|---------|----------|------------------------------------------------------------------------------------------------| +| `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). | +| `system_id` | string | no | The runner's system identifier. This attribute is required if the `token` starts with `glrt-`. | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \ @@ -755,13 +764,23 @@ Response: | 200 | Credentials are valid | | 403 | Credentials are invalid | +Example response: + +```json +{ + "id": 12345, + "token": "glrt-6337ff461c94fd3fa32ba3b1ff4125", + "token_expires_at": "2021-09-27T21:05:03.203Z" +} +``` + ## Reset instance's runner registration token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for the GitLab instance. @@ -780,7 +799,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for a project. @@ -799,7 +818,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for a group. diff --git a/doc/api/saml.md b/doc/api/saml.md index 4b0e57111cc..6b2e7cffaab 100644 --- a/doc/api/saml.md +++ b/doc/api/saml.md @@ -24,7 +24,7 @@ Supported attributes: |:------------------|:--------|:---------|:----------------------| | `id` | integer | Yes | Group ID for the group to return SAML identities. | -If successful, returns [`200`](index.md#status-codes) and the following +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: | Attribute | Type | Description | diff --git a/doc/api/scim.md b/doc/api/scim.md index 46896d7a4c8..6e022afb2f5 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98354) in GitLab 15.5. -GitLab provides an SCIM API that both implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) +GitLab provides an SCIM API that both implements [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644) and provides the `/Users` endpoint. The base URL is `/api/scim/v2/groups/:group_path/Users/`. To use this API, [Group SSO](../user/group/saml_sso/index.md) must be enabled for the group. @@ -30,13 +30,14 @@ Supported attributes: |:------------------|:--------|:---------|:----------------------| | `id` | integer | Yes | Return SCIM identities for the given group ID. | -If successful, returns [`200`](index.md#status-codes) and the following +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: -| Attribute | Type | Description | -| ------------ | ------ | ------------------------- | -| `extern_uid` | string | External UID for the user | -| `user_id` | string | ID for the user | +| Attribute | Type | Description | +| ------------ | ------- | ------------------------- | +| `extern_uid` | string | External UID for the user | +| `user_id` | integer | ID for the user | +| `active` | boolean | Status of the identity | Example response: @@ -44,7 +45,8 @@ Example response: [ { "extern_uid": "4", - "user_id": 48 + "user_id": 48, + "active": true } ] ``` @@ -67,7 +69,7 @@ Fields that can be updated are: | `id/externalId` | `extern_uid` | ```plaintext -PATCH groups/:groups_id/scim/:uid +PATCH /groups/:groups_id/scim/:uid ``` Parameters: diff --git a/doc/api/search.md b/doc/api/search.md index f4540e899f0..3c3ad3f6ab9 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -445,7 +445,7 @@ GET /groups/:id/search | Attribute | Type | Required | Description | | --------- | ---- | -------- | -------------| -| `id` | integer or string | Yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `scope` | string | Yes | The scope to search in. Values include `issues`, `merge_requests`, `milestones`, `projects`, `users`. [Additional scopes](#additional-scopes): `blobs`, `commits`, `notes`, `wiki_blobs`. | | `search` | string | Yes | The search query. | | `confidential` | boolean | No | Filter by confidentiality. Supports only `issues` scope; other scopes are ignored. | @@ -834,7 +834,7 @@ GET /projects/:id/search | 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. | +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `scope` | string | Yes | The scope to search in. Values include `blobs`, `commits`, `issues`, `merge_requests`, `milestones`, `notes`, `users`, and `wiki_blobs`. | | `search` | string | Yes | The search query. | | `confidential` | boolean | No | Filter by confidentiality. Supports `issues` scope; other scopes are ignored. | diff --git a/doc/api/secure_files.md b/doc/api/secure_files.md index a47c9654557..11c718dde01 100644 --- a/doc/api/secure_files.md +++ b/doc/api/secure_files.md @@ -24,7 +24,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | Example request: @@ -85,7 +85,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer | **{check-circle}** Yes | The `id` of a secure file. | Example request: @@ -120,7 +120,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | **{check-circle}** Yes | The `name` of the file being uploaded. The filename must be unique within the project. | | `file` | file | **{check-circle}** Yes | The `file` being uploaded (5 MB limit). | @@ -157,7 +157,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer | **{check-circle}** Yes | The `id` of a secure file. | Example request: @@ -178,7 +178,7 @@ Supported attributes: | Attribute | Type | Required | Description | |--------------|----------------|------------------------|-------------| -| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `project_id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer | **{check-circle}** Yes | The `id` of a secure file. | Example request: diff --git a/doc/api/settings.md b/doc/api/settings.md index 1fa491ef41c..94ed2b2e3db 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -282,7 +282,7 @@ listed in the descriptions of the relevant settings. | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It automatically builds, tests, and deploys applications based on a predefined CI/CD configuration. | | `automatic_purchased_storage_allocation` | boolean | no | Enabling this permits automatic allocation of purchased storage in a namespace. | -| `bulk_import_enabled` | boolean | no | Enable migrating GitLab groups by direct transfer. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. Requires [`bulk_import_projects` feature flag](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended) to also migrate projects. | +| `bulk_import_enabled` | boolean | no | Enable migrating GitLab groups by direct transfer. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. Requires [`bulk_import_projects` feature flag](../user/group/import/index.md#migrate-groups-by-direct-transfer-recommended) to also migrate projects. Setting also [available](../user/admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) in the Admin Area. | | `can_create_group` | boolean | no | Indicates whether users can create top-level groups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. Defaults to `true`. | | `check_namespace_plan` **(PREMIUM)** | boolean | no | Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | @@ -307,7 +307,6 @@ listed in the descriptions of the relevant settings. | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `delayed_project_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed project deletion by default in new groups. Default is `false`. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), can only be enabled when `delayed_group_deletion` is true. | | `delayed_group_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed group deletion. Default is `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352959) in GitLab 15.0. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), disables and locks the group-level setting for delayed protect deletion when set to `false`. | -| `delete_inactive_projects` | boolean | no | Enable inactive project deletion feature. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational without feature flag](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96803) in GitLab 15.4. | | `deletion_adjourned_period` **(PREMIUM SELF)** | integer | no | The number of days to wait before deleting a project or group that is marked for deletion. Value must be between `1` and `90`. Defaults to `7`. [From GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/352960), a hook on `deletion_adjourned_period` sets the period to `1` on every update, and sets both `delayed_project_deletion` and `delayed_group_deletion` to `false` if the period is `0`. | | `diff_max_patch_bytes` | integer | no | Maximum [diff patch size](../user/admin_area/diff_limits.md), in bytes. | | `diff_max_files` | integer | no | Maximum [files in a diff](../user/admin_area/diff_limits.md). | @@ -389,9 +388,6 @@ listed in the descriptions of the relevant settings. | `html_emails_enabled` | boolean | no | Enable HTML emails. | | `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `bitbucket_server`, `gitlab`, `fogbugz`, `git`, `gitlab_project`, `gitea`, `manifest`, and `phabricator`. | | `in_product_marketing_emails_enabled` | boolean | no | Enable [in-product marketing emails](../user/profile/notifications.md#global-notification-settings). Enabled by default. | -| `inactive_projects_delete_after_months` | integer | no | If `delete_inactive_projects` is `true`, the time (in months) to wait before deleting inactive projects. Default is `2`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | -| `inactive_projects_min_size_mb` | integer | no | If `delete_inactive_projects` is `true`, the minimum repository size for projects to be checked for inactivity. Default is `0`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | -| `inactive_projects_send_warning_email_after_months` | integer | no | If `delete_inactive_projects` is `true`, sets the time (in months) to wait before emailing maintainers that the project is scheduled be deleted because it is inactive. Default is `1`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | | `invisible_captcha_enabled` | boolean | no | Enable Invisible CAPTCHA spam detection during sign-up. Disabled by default. | | `issues_create_limit` | integer | no | Max number of issue creation requests per minute per user. Disabled by default.| | `keep_latest_artifact` | boolean | no | Prevent the deletion of the artifacts from the most recent successful jobs, regardless of the expiry time. Enabled by default. | @@ -412,6 +408,7 @@ listed in the descriptions of the relevant settings. | `max_number_of_repository_downloads` **(ULTIMATE SELF)** | integer | no | Maximum number of unique repositories a user can download in the specified time period before they are banned. Default: 0, Maximum: 10,000 repositories. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | | `max_number_of_repository_downloads_within_time_period` **(ULTIMATE SELF)** | integer | no | Reporting time period (in seconds). Default: 0, Maximum: 864000 seconds (10 days). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87980) in GitLab 15.1. | | `git_rate_limit_users_allowlist` **(ULTIMATE SELF)** | array of strings | no | List of usernames excluded from Git anti-abuse rate limits. Default: `[]`, Maximum: 100 usernames. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90815) in GitLab 15.2. | +| `git_rate_limit_users_alertlist` **(ULTIMATE SELF)** | array of integers | no | List of user IDs that are emailed when the Git abuse rate limit is exceeded. Default: `[]`, Maximum: 100 user IDs. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110201) in GitLab 15.9. | | `auto_ban_user_on_excessive_projects_download` **(ULTIMATE SELF)** | boolean | no | When enabled, users will get automatically banned from the application when they download more than the maximum number of unique projects in the time period specified by `max_number_of_repository_downloads` and `max_number_of_repository_downloads_within_time_period` respectively. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/94153) in GitLab 15.4 | | `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Administrators can configure repository mirroring. | | `mirror_capacity_threshold` **(PREMIUM)** | integer | no | Minimum capacity to be available before scheduling more mirrors preemptively. | @@ -522,10 +519,20 @@ listed in the descriptions of the relevant settings. | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the `You won't be able to pull or push project code via SSH` warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | | `whats_new_variant` | string | no | What's new variant, possible values: `all_tiers`, `current_tier`, and `disabled`. | -| `web_ide_clientside_preview_enabled` | boolean | no | Live Preview (allow live previews of JavaScript projects in the Web IDE using CodeSandbox Live Preview). | | `wiki_page_max_content_bytes` | integer | no | Maximum wiki page content size in **bytes**. Default: 52428800 Bytes (50 MB). The minimum value is 1024 bytes. | -| `jira_connect_application_key` | String | no | Application ID of the OAuth application that should be used to authenticate with the GitLab.com for Jira Cloud app | -| `jira_connect_proxy_url` | String | no | URL of the GitLab instance that should be used as a proxy for the GitLab.com for Jira Cloud app | +| `jira_connect_application_key` | String | no | Application ID of the OAuth application that should be used to authenticate with the GitLab for Jira Cloud app | +| `jira_connect_proxy_url` | String | no | URL of the GitLab instance that should be used as a proxy for the GitLab for Jira Cloud app | + +### Configure inactive project deletion + +You can configure inactive projects deletion or turn it off. + +| Attribute | Type | Required | Description | +|------------------------------------------|------------------|:------------------------------------:|-------------| +| `delete_inactive_projects` | boolean | no | Enable [inactive project deletion](../administration/inactive_project_deletion.md). Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational without feature flag](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96803) in GitLab 15.4. | +| `inactive_projects_delete_after_months` | integer | no | If `delete_inactive_projects` is `true`, the time (in months) to wait before deleting inactive projects. Default is `2`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | +| `inactive_projects_min_size_mb` | integer | no | If `delete_inactive_projects` is `true`, the minimum repository size for projects to be checked for inactivity. Default is `0`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | +| `inactive_projects_send_warning_email_after_months` | integer | no | If `delete_inactive_projects` is `true`, sets the time (in months) to wait before emailing maintainers that the project is scheduled be deleted because it is inactive. Default is `1`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. [Became operational](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85689) in GitLab 15.0. | ## Housekeeping fields diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md index 90cbe19112c..37bbe6bbf49 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -28,7 +28,7 @@ To ensure data integrity, snippets are put in a temporary read-only state for th duration of the move. During this time, users receive a `The repository is temporarily read-only. Please try again later.` message if they try to push new commits. -This API requires you to [authenticate yourself](index.md#authentication) as an administrator. +This API requires you to [authenticate yourself](rest/index.md#authentication) as an administrator. For other repository types see: @@ -42,7 +42,7 @@ GET /snippet_repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Example request: @@ -84,7 +84,7 @@ GET /snippets/:snippet_id/repository_storage_moves ``` By default, `GET` requests return 20 results at a time because the API results -are [paginated](index.md#pagination). +are [paginated](rest/index.md#pagination). Supported attributes: diff --git a/doc/api/tags.md b/doc/api/tags.md index 099448d5609..3f15cdd02f4 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -21,7 +21,7 @@ Parameters: | 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. | +| `id` | integer or string| yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return tags ordered by `name`, `updated`, or `version`. 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. No other regular expressions are supported. | @@ -70,7 +70,7 @@ Parameters: | 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 | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of the tag | ```shell @@ -117,7 +117,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of a tag | | `ref` | string | yes | Create tag using commit SHA, another tag name, or branch name | | `message` | string | no | Creates annotated tag | @@ -174,7 +174,7 @@ Parameters: | 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 | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of a tag | ## Get X.509 signature of a tag @@ -192,7 +192,7 @@ Parameters: | 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. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `tag_name` | string | yes | The name of a tag. | ```shell diff --git a/doc/api/users.md b/doc/api/users.md index a577dc26043..4ecb3d48c0f 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -142,6 +142,7 @@ GET /users "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "", @@ -183,6 +184,7 @@ GET /users "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "", @@ -319,6 +321,7 @@ Parameters: "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "Operations Specialist", @@ -365,6 +368,7 @@ Example Responses: "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "Operations Specialist", @@ -508,6 +512,7 @@ Parameters: | `skype` | No | Skype ID | | `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#navigation-theme) for more information) | | `twitter` | No | Twitter account | +| `discord` | No | Discord account | | `username` | Yes | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | | `website_url` | No | Website URL | @@ -558,6 +563,7 @@ Parameters: | `skype` | No | Skype ID | | `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#navigation-theme) for more information) | | `twitter` | No | Twitter account | +| `discord` | No | Discord account | | `username` | No | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | | `website_url` | No | Website URL | @@ -626,6 +632,7 @@ GET /user "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "", @@ -690,6 +697,7 @@ Parameters: "skype": "", "linkedin": "", "twitter": "", + "discord": "", "website_url": "", "organization": "", "job_title": "", @@ -946,7 +954,7 @@ Example response: ## User counts -Get the counts (same as in top right menu) of the authenticated user. +Get the counts (same as in the upper-right menu) of the authenticated user. | Attribute | Type | Description | | --------------------------------- | ------ | ---------------------------------------------------------------------------- | diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index 4b9a7d4f88a..f966af82b10 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -25,7 +25,7 @@ Parameters: | Attribute | Type | Required | Description | | ------------------------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of a merge request | | `body` | string | yes | The content of the thread | | `position` | hash | no | Position when creating a diff note | diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index 6ee2bbf9811..6f790227dea 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -21,7 +21,7 @@ across GitLab releases. Please use the [GraphQL API](graphql/reference/index.md#queryvulnerabilities) instead. See the [GraphQL examples](#replace-vulnerability-rest-api-with-graphql) to get started. -Every API call to vulnerabilities must be [authenticated](index.md#authentication). +Every API call to vulnerabilities must be [authenticated](rest/index.md#authentication). If an authenticated user does not have permission to [view vulnerabilities](../user/permissions.md#project-members-permissions), diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 94f373c1c0a..e1473ba68b6 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -13,7 +13,7 @@ This API is in an [Alpha](../policy/alpha-beta-support.md#alpha-features) stage The response payload may be subject to change or breakage across GitLab releases. -Every API call to vulnerability exports must be [authenticated](index.md#authentication). +Every API call to vulnerability exports must be [authenticated](rest/index.md#authentication). ## Create a project-level vulnerability export @@ -31,7 +31,7 @@ POST /security/projects/:id/vulnerability_exports | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the project which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the project which the authenticated user is a member of | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/projects/1/vulnerability_exports" @@ -74,7 +74,7 @@ POST /security/groups/:id/vulnerability_exports | Attribute | Type | Required | Description | | ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path](index.md#namespaced-path-encoding) of the group which the authenticated user is a member of | +| `id` | integer or string | yes | The ID or [URL-encoded path](rest/index.md#namespaced-path-encoding) of the group which the authenticated user is a member of | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/security/groups/1/vulnerability_exports" diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index 89acbdee98a..8cc4ed31425 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -14,7 +14,7 @@ for serving [Vulnerability objects](https://gitlab.com/gitlab-org/gitlab/-/issue To fix any broken integrations with the former Vulnerabilities API, change the `vulnerabilities` URL part to be `vulnerability_findings`. -Every API call to vulnerability findings must be [authenticated](index.md#authentication). +Every API call to vulnerability findings must be [authenticated](rest/index.md#authentication). If a user does not have permission to [use the Project Security Dashboard](../user/permissions.md#project-members-permissions), @@ -32,7 +32,7 @@ instead. See the [GraphQL examples](#replace-vulnerability-findings-rest-api-wit By default, `GET` requests return 20 results at a time because the API results are paginated. -Read more on [pagination](index.md#pagination). +Read more on [pagination](rest/index.md#pagination). ## List project vulnerability findings @@ -55,7 +55,7 @@ Beginning with GitLab 12.9, the `undefined` severity and confidence level is no | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) which the authenticated user is a member of. | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) which the authenticated user is a member of. | | `report_type` | string array | no | Returns vulnerability findings belonging to specified report type. Valid values: `sast`, `dast`, `dependency_scanning`, or `container_scanning`. Defaults to all. | | `scope` | string | no | Returns vulnerability findings for the given scope: `all` or `dismissed`. Defaults to `dismissed`. | | `severity` | string array | no | Returns vulnerability findings belonging to specified severity level: `info`, `unknown`, `low`, `medium`, `high`, or `critical`. Defaults to all. | diff --git a/doc/api/wikis.md b/doc/api/wikis.md index b092338aaa5..046901af56b 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -23,7 +23,7 @@ GET /projects/:id/wikis | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `with_content` | boolean | no | Include pages' content | ```shell @@ -67,7 +67,7 @@ GET /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `slug` | string | yes | URL encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | | `render_html` | boolean | no | Return the rendered HTML of the wiki page | | `version` | string | no | Wiki page version SHA | @@ -98,7 +98,7 @@ POST /projects/:id/wikis | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `content` | string | yes | The content of the wiki page | | `title` | string | yes | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -130,7 +130,7 @@ PUT /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `content` | string | yes if `title` is not provided | The content of the wiki page | | `title` | string | yes if `content` is not provided | The title of the wiki page | | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | @@ -163,7 +163,7 @@ DELETE /projects/:id/wikis/:slug | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` | ```shell @@ -183,7 +183,7 @@ POST /projects/:id/wikis/attachments | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | | `file` | string | yes | The attachment to be uploaded | | `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch | |