diff options
Diffstat (limited to 'doc/api')
45 files changed, 1489 insertions, 386 deletions
diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index eabaa4217b5..f6d1e554aae 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -21,76 +21,77 @@ See also: The following API resources are available in the project context: -| Resource | Available endpoints | -|:------------------------------------------------------------------------|:--------------------| -| [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | -| [Access tokens](resource_access_tokens.md) | `/projects/:id/access_tokens` (also available for groups) | -| [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | -| [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | -| [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` | -| [Container Registry](container_registry.md) | `/projects/:id/registry/repositories` | -| [Custom attributes](custom_attributes.md) | `/projects/:id/custom_attributes` (also available for groups and users) | -| [Debian distributions](packages/debian_project_distributions.md) | `/projects/:id/debian_distributions` (also available for groups) | -| [Dependencies](dependencies.md) **(ULTIMATE)** | `/projects/:id/dependencies` | -| [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | -| [Deploy tokens](deploy_tokens.md) | `/projects/:id/deploy_tokens` (also available for groups and standalone) | -| [Deployments](deployments.md) | `/projects/:id/deployments` | +| Resource | Available endpoints | +|:------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | +| [Access tokens](resource_access_tokens.md) | `/projects/:id/access_tokens` (also available for groups) | +| [Agents](cluster_agents.md) | `/projects/:id/cluster_agents` | +| [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | +| [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | +| [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` | +| [Container Registry](container_registry.md) | `/projects/:id/registry/repositories` | +| [Custom attributes](custom_attributes.md) | `/projects/:id/custom_attributes` (also available for groups and users) | +| [Debian distributions](packages/debian_project_distributions.md) | `/projects/:id/debian_distributions` (also available for groups) | +| [Dependencies](dependencies.md) **(ULTIMATE)** | `/projects/:id/dependencies` | +| [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | +| [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) | -| [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) | -| [Feature Flag User Lists](feature_flag_user_lists.md) | `/projects/:id/feature_flags_user_lists` | -| [Feature Flags](feature_flags.md) | `/projects/:id/feature_flags` | -| [Freeze Periods](freeze_periods.md) | `/projects/:id/freeze_periods` | -| [Integrations](integrations.md) (Formerly "services") | `/projects/:id/integrations` | -| [Invitations](invitations.md) | `/projects/:id/invitations` (also available for groups) | -| [Issue boards](boards.md) | `/projects/:id/boards` | -| [Issue links](issue_links.md) | `/projects/:id/issues/.../links` | -| [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | -| [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | -| [Iterations](iterations.md) **(PREMIUM)** | `/projects/:id/iterations` (also available for groups) | -| [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | -| [Labels](labels.md) | `/projects/:id/labels` | -| [Managed licenses](managed_licenses.md) **(ULTIMATE)** | `/projects/:id/managed_licenses` | -| [Members](members.md) | `/projects/:id/members` (also available for groups) | -| [Merge request approvals](merge_request_approvals.md) **(PREMIUM)** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | -| [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | -| [Merge trains](merge_trains.md) | `/projects/:id/merge_trains` | -| [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups) | -| [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | -| [Packages](packages.md) | `/projects/:id/packages` | -| [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) | -| [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | -| [Pipeline triggers](pipeline_triggers.md) | `/projects/:id/triggers` | -| [Pipelines](pipelines.md) | `/projects/:id/pipelines` | -| [Project badges](project_badges.md) | `/projects/:id/badges` | -| [Project clusters](project_clusters.md) | `/projects/:id/clusters` | -| [Project import/export](project_import_export.md) | `/projects/:id/export`, `/projects/import`, `/projects/:id/import` | -| [Project milestones](milestones.md) | `/projects/:id/milestones` | -| [Project snippets](project_snippets.md) | `/projects/:id/snippets` | -| [Project templates](project_templates.md) | `/projects/:id/templates` | -| [Project vulnerabilities](project_vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/templates` | -| [Project wikis](wikis.md) | `/projects/:id/wikis` | -| [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | -| [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | -| [Protected branches](protected_branches.md) | `/projects/:id/protected_branches` | -| [Protected environments](protected_environments.md) | `/projects/:id/protected_environments` | -| [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | -| [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` | -| [Releases](releases/index.md) | `/projects/:id/releases` | -| [Remote mirrors](remote_mirrors.md) | `/projects/:id/remote_mirrors` | -| [Repositories](repositories.md) | `/projects/:id/repository` | -| [Repository files](repository_files.md) | `/projects/:id/repository/files` | -| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | -| [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups) | -| [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | -| [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | -| [Tags](tags.md) | `/projects/:id/repository/tags` | -| [User-starred metrics dashboards](metrics_user_starred_dashboards.md ) | `/projects/:id/metrics/user_starred_dashboards` | -| [Visual Review discussions](visual_review_discussions.md) **(PREMIUM)** | `/projects/:id/merge_requests/:merge_request_id/visual_review_discussions` | -| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)** | `/vulnerabilities/:id` | -| [Vulnerability exports](vulnerability_exports.md) **(ULTIMATE)** | `/projects/:id/vulnerability_exports` | -| [Vulnerability findings](vulnerability_findings.md) **(ULTIMATE)** | `/projects/:id/vulnerability_findings` | +| [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) | +| [Feature Flag User Lists](feature_flag_user_lists.md) | `/projects/:id/feature_flags_user_lists` | +| [Feature Flags](feature_flags.md) | `/projects/:id/feature_flags` | +| [Freeze Periods](freeze_periods.md) | `/projects/:id/freeze_periods` | +| [Integrations](integrations.md) (Formerly "services") | `/projects/:id/integrations` | +| [Invitations](invitations.md) | `/projects/:id/invitations` (also available for groups) | +| [Issue boards](boards.md) | `/projects/:id/boards` | +| [Issue links](issue_links.md) | `/projects/:id/issues/.../links` | +| [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | +| [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | +| [Iterations](iterations.md) **(PREMIUM)** | `/projects/:id/iterations` (also available for groups) | +| [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | +| [Labels](labels.md) | `/projects/:id/labels` | +| [Managed licenses](managed_licenses.md) **(ULTIMATE)** | `/projects/:id/managed_licenses` | +| [Members](members.md) | `/projects/:id/members` (also available for groups) | +| [Merge request approvals](merge_request_approvals.md) **(PREMIUM)** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | +| [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | +| [Merge trains](merge_trains.md) | `/projects/:id/merge_trains` | +| [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups) | +| [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | +| [Packages](packages.md) | `/projects/:id/packages` | +| [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) | +| [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | +| [Pipeline triggers](pipeline_triggers.md) | `/projects/:id/triggers` | +| [Pipelines](pipelines.md) | `/projects/:id/pipelines` | +| [Project badges](project_badges.md) | `/projects/:id/badges` | +| [Project clusters](project_clusters.md) | `/projects/:id/clusters` | +| [Project import/export](project_import_export.md) | `/projects/:id/export`, `/projects/import`, `/projects/:id/import` | +| [Project milestones](milestones.md) | `/projects/:id/milestones` | +| [Project snippets](project_snippets.md) | `/projects/:id/snippets` | +| [Project templates](project_templates.md) | `/projects/:id/templates` | +| [Project vulnerabilities](project_vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/templates` | +| [Project wikis](wikis.md) | `/projects/:id/wikis` | +| [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | +| [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | +| [Protected branches](protected_branches.md) | `/projects/:id/protected_branches` | +| [Protected environments](protected_environments.md) | `/projects/:id/protected_environments` | +| [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | +| [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` | +| [Releases](releases/index.md) | `/projects/:id/releases` | +| [Remote mirrors](remote_mirrors.md) | `/projects/:id/remote_mirrors` | +| [Repositories](repositories.md) | `/projects/:id/repository` | +| [Repository files](repository_files.md) | `/projects/:id/repository/files` | +| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | +| [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups) | +| [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | +| [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | +| [Tags](tags.md) | `/projects/:id/repository/tags` | +| [User-starred metrics dashboards](metrics_user_starred_dashboards.md ) | `/projects/:id/metrics/user_starred_dashboards` | +| [Visual Review discussions](visual_review_discussions.md) **(PREMIUM)** | `/projects/:id/merge_requests/:merge_request_id/visual_review_discussions` | +| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)** | `/vulnerabilities/:id` | +| [Vulnerability exports](vulnerability_exports.md) **(ULTIMATE)** | `/projects/:id/vulnerability_exports` | +| [Vulnerability findings](vulnerability_findings.md) **(ULTIMATE)** | `/projects/:id/vulnerability_findings` | ## Group resources @@ -103,10 +104,10 @@ The following API resources are available in the group context: | [Custom attributes](custom_attributes.md) | `/groups/:id/custom_attributes` (also available for projects and users) | | [Debian distributions](packages/debian_group_distributions.md) | `/groups/:id/-/packages/debian` (also available for projects) | | [Deploy tokens](deploy_tokens.md) | `/groups/:id/deploy_tokens` (also available for projects and standalone) | -| [Discussions](discussions.md) (threaded comments) **(ULTIMATE)** | `/groups/:id/epics/.../discussions` (also available for projects) | -| [Epic issues](epic_issues.md) **(ULTIMATE)** | `/groups/:id/epics/.../issues` | -| [Epic links](epic_links.md) **(ULTIMATE)** | `/groups/:id/epics/.../epics` | -| [Epics](epics.md) **(ULTIMATE)** | `/groups/:id/epics` | +| [Discussions](discussions.md) (comments and threads) | `/groups/:id/epics/.../discussions` (also available for projects) | +| [Epic issues](epic_issues.md) **(PREMIUM)** | `/groups/:id/epics/.../issues` | +| [Epic links](epic_links.md) **(PREMIUM)** | `/groups/:id/epics/.../epics` | +| [Epics](epics.md) **(PREMIUM)** | `/groups/:id/epics` | | [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | | [Group badges](group_badges.md) | `/groups/:id/badges` | | [Group issue boards](group_boards.md) | `/groups/:id/boards` | @@ -114,6 +115,7 @@ The following API resources are available in the group context: | [Group labels](group_labels.md) | `/groups/:id/labels` | | [Group-level variables](group_level_variables.md) | `/groups/:id/variables` | | [Group milestones](group_milestones.md) | `/groups/:id/milestones` | +| [Group releases](group_releases.md) | `/groups/:id/releases`| | [Group wikis](group_wikis.md) **(PREMIUM)** | `/groups/:id/wikis` | | [Invitations](invitations.md) | `/groups/:id/invitations` (also available for projects) | | [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md index 2b71c83b224..cae23b35fbe 100644 --- a/doc/api/bulk_imports.md +++ b/doc/api/bulk_imports.md @@ -58,11 +58,12 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla GET /bulk_imports ``` -| Attribute | Type | Required | Description | -|:-----------|:--------|:---------|:---------------------------------------| -| `per_page` | integer | no | Number of records to return per page. | -| `page` | integer | no | Page to retrieve. | -| `status` | string | no | Import status. | +| Attribute | Type | Required | Description | +|:-----------|:--------|:---------|:--------------------------------------------------------------------------------------------| +| `per_page` | integer | no | Number of records to return per page. | +| `page` | integer | no | Page to retrieve. | +| `sort` | string | no | Return GitLab migration sorted in `asc` or `desc` order by creation date. Default is `desc` | +| `status` | string | no | Import status. | The status can be one of the following: @@ -100,11 +101,12 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab GET /bulk_imports/entities ``` -| Attribute | Type | Required | Description | -|:-----------|:--------|:---------|:---------------------------------------| -| `per_page` | integer | no | Number of records to return per page. | -| `page` | integer | no | Page to retrieve. | -| `status` | string | no | Import status. | +| Attribute | Type | Required | Description | +|:-----------|:--------|:---------|:-----------------------------------------------------------------------------------------------------| +| `per_page` | integer | no | Number of records to return per page. | +| `page` | integer | no | Page to retrieve. | +| `sort` | string | no | Return GitLab migration entities sorted in `asc` or `desc` order by creation date. Default is `desc` | +| `status` | string | no | Import status. | The status can be one of the following: @@ -184,11 +186,12 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab GET /bulk_imports/:id/entities ``` -| Attribute | Type | Required | Description | -|:-----------|:--------|:---------|:---------------------------------------| -| `per_page` | integer | no | Number of records to return per page. | -| `page` | integer | no | Page to retrieve. | -| `status` | string | no | Import status. | +| Attribute | Type | Required | Description | +|:-----------|:--------|:---------|:--------------------------------------------------------------------------------------------| +| `per_page` | integer | no | Number of records to return per page. | +| `page` | integer | no | Page to retrieve. | +| `sort` | string | no | Return GitLab migration sorted in `asc` or `desc` order by creation date. Default is `desc` | +| `status` | string | no | Import status. | The status can be one of the following: diff --git a/doc/api/cluster_agents.md b/doc/api/cluster_agents.md new file mode 100644 index 00000000000..37cc4a24342 --- /dev/null +++ b/doc/api/cluster_agents.md @@ -0,0 +1,238 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Agents API **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83270) in GitLab 14.10. + +Use the Agents API to work with the GitLab agent for Kubernetes. + +## List the agents for a project + +Returns the list of agents registered for the project. + +You must have at least the Developer role to use this endpoint. + +```plaintext +GET /projects/:id/cluster_agents +``` + +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 | + +Response: + +The response is a list of agents with the following fields: + +| Attribute | Type | Description | +|--------------------------------------|----------|------------------------------------------------------| +| `id` | integer | ID of the agent | +| `name` | string | Name of the agent | +| `config_project` | object | Object representing the project the agent belongs to | +| `config_project.id` | integer | ID of the project | +| `config_project.description` | string | Description of the project | +| `config_project.name` | string | Name of the project | +| `config_project.name_with_namespace` | string | Full name with namespace of the project | +| `config_project.path` | string | Path to the project | +| `config_project.path_with_namespace` | string | Full path with namespace to the project | +| `config_project.created_at` | string | ISO8601 datetime when the project was created | +| `created_at` | string | ISO8601 datetime when the agent was created | +| `created_by_user_id` | integer | ID of the user who created the agent | + +Example request: + +```shell +curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents" +``` + +Example response: + +```json +[ + { + "id": 1, + "name": "agent-1", + "config_project": { + "id": 20, + "description": "", + "name": "test", + "name_with_namespace": "Administrator / test", + "path": "test", + "path_with_namespace": "root/test", + "created_at": "2022-03-20T20:42:40.221Z" + }, + "created_at": "2022-04-20T20:42:40.221Z", + "created_by_user_id": 42 + }, + { + "id": 2, + "name": "agent-2", + "config_project": { + "id": 20, + "description": "", + "name": "test", + "name_with_namespace": "Administrator / test", + "path": "test", + "path_with_namespace": "root/test", + "created_at": "2022-03-20T20:42:40.221Z" + }, + "created_at": "2022-04-20T20:42:40.221Z", + "created_by_user_id": 42 + } +] +``` + +## Get details about an agent + +Gets a single agent details. + +You must have at least the Developer role to use this endpoint. + +```shell +GET /projects/:id/cluster_agents/:agent_id +``` + +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 | +| `agent_id` | integer | yes | ID of the agent | + +Response: + +The response is a single agent with the following fields: + +| Attribute | Type | Description | +|--------------------------------------|---------|------------------------------------------------------| +| `id` | integer | ID of the agent | +| `name` | string | Name of the agent | +| `config_project` | object | Object representing the project the agent belongs to | +| `config_project.id` | integer | ID of the project | +| `config_project.description` | string | Description of the project | +| `config_project.name` | string | Name of the project | +| `config_project.name_with_namespace` | string | Full name with namespace of the project | +| `config_project.path` | string | Path to the project | +| `config_project.path_with_namespace` | string | Full path with namespace to the project | +| `config_project.created_at` | string | ISO8601 datetime when the project was created | +| `created_at` | string | ISO8601 datetime when the agent was created | +| `created_by_user_id` | integer | ID of the user who created the agent | + +Example request: + +```shell +curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1" +``` + +Example response: + +```json +{ + "id": 1, + "name": "agent-1", + "config_project": { + "id": 20, + "description": "", + "name": "test", + "name_with_namespace": "Administrator / test", + "path": "test", + "path_with_namespace": "root/test", + "created_at": "2022-03-20T20:42:40.221Z" + }, + "created_at": "2022-04-20T20:42:40.221Z", + "created_by_user_id": 42 +} +``` + +## Register an agent with a project + +Registers an agent to the project. + +You must have at least the Maintainer role to use this endpoint. + +```shell +POST /projects/:id/cluster_agents +``` + +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 | +| `name` | string | yes | Name for the agent | + +Response: + +The response is the new agent with the following fields: + +| Attribute | Type | Description | +|--------------------------------------|---------|------------------------------------------------------| +| `id` | integer | ID of the agent | +| `name` | string | Name of the agent | +| `config_project` | object | Object representing the project the agent belongs to | +| `config_project.id` | integer | ID of the project | +| `config_project.description` | string | Description of the project | +| `config_project.name` | string | Name of the project | +| `config_project.name_with_namespace` | string | Full name with namespace of the project | +| `config_project.path` | string | Path to the project | +| `config_project.path_with_namespace` | string | Full path with namespace to the project | +| `config_project.created_at` | string | ISO8601 datetime when the project was created | +| `created_at` | string | ISO8601 datetime when the agent was created | +| `created_by_user_id` | integer | ID of the user who created the agent | + +Example request: + +```shell +curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents" \ + -H "Content-Type:application/json" \ + -X POST --data '{"name":"some-agent"}' +``` + +Example response: + +```json +{ + "id": 1, + "name": "agent-1", + "config_project": { + "id": 20, + "description": "", + "name": "test", + "name_with_namespace": "Administrator / test", + "path": "test", + "path_with_namespace": "root/test", + "created_at": "2022-03-20T20:42:40.221Z" + }, + "created_at": "2022-04-20T20:42:40.221Z", + "created_by_user_id": 42 +} +``` + +## Delete a registered agent + +Deletes an existing agent registration. + +You must have at least the Maintainer role to use this endpoint. + +```plaintext +DELETE /projects/:id/cluster_agents/:agent_id +``` + +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 | +| `agent_id` | integer | yes | ID of the agent | + +Example request: + +```shell +curl --request DELETE --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1 +``` diff --git a/doc/api/commits.md b/doc/api/commits.md index d7be9559527..7be5bc3d985 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -49,11 +49,11 @@ Example response: "title": "Replace sanitize with escape once", "author_name": "Example User", "author_email": "user@example.com", - "authored_date": "2012-09-20T11:50:22+03:00", + "authored_date": "2021-09-20T11:50:22.001+00:00", "committer_name": "Administrator", "committer_email": "admin@example.com", - "committed_date": "2012-09-20T11:50:22+03:00", - "created_at": "2012-09-20T11:50:22+03:00", + "committed_date": "2021-09-20T11:50:22.001+00:00", + "created_at": "2021-09-20T11:50:22.001+00:00", "message": "Replace sanitize with escape once", "parent_ids": [ "6104942438c14ec7bd21c6cd5bd995272b3faff6" @@ -68,7 +68,7 @@ Example response: "author_email": "user@example.com", "committer_name": "ExampleName", "committer_email": "user@example.com", - "created_at": "2012-09-20T09:06:12+03:00", + "created_at": "2021-09-20T09:06:12.201+00:00", "message": "Sanitize for network graph", "parent_ids": [ "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba" @@ -234,10 +234,10 @@ Example response: "author_email": "user@example.com", "committer_name": "Dmitriy", "committer_email": "user@example.com", - "created_at": "2012-09-20T09:06:12+03:00", + "created_at": "2021-09-20T09:06:12.300+03:00", "message": "Sanitize for network graph", - "committed_date": "2012-09-20T09:06:12+03:00", - "authored_date": "2012-09-20T09:06:12+03:00", + "committed_date": "2021-09-20T09:06:12.300+03:00", + "authored_date": "2021-09-20T09:06:12.420+03:00", "parent_ids": [ "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba" ], diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 4a09f9a6605..fb255bfa226 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -265,7 +265,7 @@ Example response: } ``` -Deployments created by users on GitLab Premium or higher include the `approvals` and `pending_approval_count` properties: +When the [unified approval setting](../ci/environments/deployment_approvals.md#unified-approval-setting) is configured, deployments created by users on GitLab Premium or higher include the `approvals` and `pending_approval_count` properties: ```json { @@ -282,13 +282,56 @@ Deployments created by users on GitLab Premium or higher include the `approvals` "web_url": "http://localhost:3000/project_6_bot" }, "status": "approved", - "created_at": "2022-02-24T20:22:30.097Z" + "created_at": "2022-02-24T20:22:30.097Z", + "comment": "Looks good to me" } ], ... } ``` +When the [multiple approval rules](../ci/environments/deployment_approvals.md#multiple-approval-rules) is configured, deployments created by users on GitLab Premium or higher include the `approval_summary` property: + +```json +{ + "approval_summary": { + "rules": [ + { + "user_id": null, + "group_id": 134, + "access_level": null, + "access_level_description": "qa-group", + "required_approvals": 1, + "deployment_approvals": [] + }, + { + "user_id": null, + "group_id": 135, + "access_level": null, + "access_level_description": "security-group", + "required_approvals": 2, + "deployment_approvals": [ + { + "user": { + "id": 100, + "username": "security-user-1", + "name": "security user-1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e130fcd3a1681f41a3de69d10841afa9?s=80&d=identicon", + "web_url": "http://localhost:3000/security-user-1" + }, + "status": "approved", + "created_at": "2022-04-11T03:37:03.058Z", + "comment": null + } + ] + } + ] + } + ... +} +``` + ## Create a deployment ```plaintext @@ -342,20 +385,7 @@ Deployments created by users on GitLab Premium or higher include the `approvals` { "status": "created", "pending_approval_count": 0, - "approvals": [ - { - "user": { - "id": 49, - "username": "project_6_bot", - "name": "****", - "state": "active", - "avatar_url": "https://www.gravatar.com/avatar/e83ac685f68ea07553ad3054c738c709?s=80&d=identicon", - "web_url": "http://localhost:3000/project_6_bot" - }, - "status": "approved", - "created_at": "2022-02-24T20:22:30.097Z" - } - ], + "approvals": [], ... } ``` @@ -420,7 +450,8 @@ Deployments created by users on GitLab Premium or higher include the `approvals` "web_url": "http://localhost:3000/project_6_bot" }, "status": "approved", - "created_at": "2022-02-24T20:22:30.097Z" + "created_at": "2022-02-24T20:22:30.097Z", + "comment": "Looks good to me" } ], ... @@ -466,9 +497,10 @@ POST /projects/:id/deployments/:deployment_id/approval | `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 | +| `represented_as`| string | no | The name of the User/Group/Role to use for the approval, when the user belongs to [multiple approval rules](../ci/environments/deployment_approvals.md#multiple-approval-rules). | ```shell -curl --data "status=approved&comment=Looks good to me" \ +curl --data "status=approved&comment=Looks good to me&represented_as=security" \ --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/1/approval" ``` @@ -477,12 +509,12 @@ Example response: ```json { "user": { - "name": "Administrator", - "username": "root", - "id": 1, + "id": 100, + "username": "security-user-1", + "name": "security user-1", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "http://localhost:3000/root" + "avatar_url": "https://www.gravatar.com/avatar/e130fcd3a1681f41a3de69d10841afa9?s=80&d=identicon", + "web_url": "http://localhost:3000/security-user-1" }, "status": "approved", "created_at": "2022-02-24T20:22:30.097Z", diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 5f750df4a48..c30c00cef67 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -11,13 +11,14 @@ Discussions are a set of related notes on: - Snippets - Issues -- Epics **(ULTIMATE)** +- [Epics](../user/group/epics/index.md) - Merge requests - Commits -This includes system notes, which are notes about changes to the object (for example, -when a milestone changes, a corresponding system note is added). Label notes are -not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). +This includes [comments and threads](../user/discussions/index.md) and system notes. +System notes are notes about changes to the object (for example, when a milestone changes). +Label notes are not part of this API, but recorded as separate events in +[resource label events](resource_label_events.md). ## Discussions pagination @@ -993,7 +994,11 @@ curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]"\ ### Resolve a merge request thread -Resolve/unresolve whole thread of a merge request. +Resolve or unresolve a thread of discussion in a merge request. + +Prerequisite: + +- You must have at least the Developer role, or be the author of the change being reviewed. ```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/discussions/:discussion_id diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index afc29f03598..f5373d02156 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -24,7 +24,7 @@ GET /projects/:id/dora/metrics | Attribute | Type | Required | Description | |-------------- |-------- |----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | -| `metric` | string | yes | The [metric name](../../user/analytics/ci_cd_analytics.md#supported-metrics-in-gitlab). One of `deployment_frequency`, `lead_time_for_changes` or `time_to_restore_service`.| +| `metric` | string | yes | The metric name: `deployment_frequency`, `lead_time_for_changes` or `time_to_restore_service`.| | `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | | `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | | `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | @@ -61,14 +61,14 @@ Get group-level DORA metrics. GET /groups/:id/dora/metrics ``` -| Attribute | Type | Required | Description | -|-------------- |-------- |----------|----------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | -| `metric` | string | yes | The [metric name](../../user/analytics/ci_cd_analytics.md#supported-metrics-in-gitlab). One of `deployment_frequency`, `lead_time_for_changes` or `time_to_restore_service`. | -| `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | -| `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | -| `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | -| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | +| Attribute | Type | Required | Description | +|-------------- |-------- |----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../index.md#namespaced-path-encoding) can be accessed by the authenticated user. | +| `metric` | string | yes | One of `deployment_frequency`, `lead_time_for_changes`, `time_to_restore_service` or `change_failure_rate`. | +| `start_date` | string | no | Date range to start from. ISO 8601 Date format, for example `2021-03-01`. Default is 3 months ago. | +| `end_date` | string | no | Date range to end at. ISO 8601 Date format, for example `2021-03-01`. Default is the current date. | +| `interval` | string | no | The bucketing interval. One of `all`, `monthly` or `daily`. Default is `daily`. | +| `environment_tier` | string | no | The [tier of the environment](../../ci/environments/index.md#deployment-tier-of-environments). Default is `production`. | Example request: @@ -101,4 +101,5 @@ parameter: | ------------------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------| | `deployment_frequency` | The number of successful deployments during the time period. | | `lead_time_for_changes` | The median number of seconds between the merge of the merge request (MR) and the deployment of the MR's commits for all MRs deployed during the time period. | -| `time_to_restore_service` | The median number of seconds an incident was open during the time period. Available only for production environment | +| `time_to_restore_service` | The median number of seconds an incident was open during the time period. Available only for production environment. | +| `change_failure_rate` | The number of incidents divided by the number of deployments during the time period. Available only for production environment. | diff --git a/doc/api/events.md b/doc/api/events.md index 265fc0e5fd2..3f032c72870 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ### Actions -See [User contribution events](../user/index.md#user-contribution-events) for available types for the `action` parameter. +See [User contribution events](../user/profile/index.md#user-contribution-events) for available types for the `action` parameter. These options are in lowercase. ### Target Types diff --git a/doc/api/feature_flags_legacy.md b/doc/api/feature_flags_legacy.md index 262e1c537a4..1cf05144a1b 100644 --- a/doc/api/feature_flags_legacy.md +++ b/doc/api/feature_flags_legacy.md @@ -1,13 +1,11 @@ --- -stage: Release -group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'feature_flags.md' +remove_date: '2022-06-22' --- -# Legacy Feature Flags API **(FREE)** +This document was moved to [another location](feature_flags). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in GitLab Premium 12.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5. - -This API was removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). -Please use [the new API](feature_flags.md) instead. +<!-- This redirect file can be deleted after <2022-06-22>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/api/features.md b/doc/api/features.md index 593e4adedd7..0ad76829651 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -89,22 +89,24 @@ Example response: ```json [ { - "name": "api_kaminari_count_with_limit", - "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23931", - "rollout_issue_url": null, - "milestone": "11.8", - "type": "ops", - "group": "group::ecosystem", + "name": "geo_pages_deployment_replication", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68662", + "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/337676", + "milestone": "14.3", + "log_state_changes": null, + "type": "development", + "group": "group::geo", "default_enabled": true }, { - "name": "marginalia", - "introduced_by_url": null, - "rollout_issue_url": null, - "milestone": null, - "type": "ops", - "group": null, - "default_enabled": false + "name": "analytics_devops_adoption_codeowners", + "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59874", + "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/328542", + "milestone": "13.12", + "log_state_changes": null, + "type": "development", + "group": "group::optimize", + "default_enabled": true } ] ``` diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index d2cca1a5856..93478bcf95f 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -75,7 +75,7 @@ Example response: WARNING: The `web_geo_projects_url` attribute is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80106) -for use in GitLab 14.9. +in GitLab 14.9. ## Retrieve configuration about all Geo nodes @@ -147,7 +147,7 @@ Example response: WARNING: The `web_geo_projects_url` attribute is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80106) -for use in GitLab 14.9. +in GitLab 14.9. ## Retrieve configuration about a specific Geo node @@ -249,7 +249,7 @@ Example response: WARNING: The `web_geo_projects_url` attribute is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80106) -for use in GitLab 14.9. +in GitLab 14.9. ## Delete a Geo node diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index f86ad985b5e..7ef9897a170 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -628,6 +628,8 @@ Input type: `AdminSidekiqQueuesDeleteJobsInput` | <a id="mutationadminsidekiqqueuesdeletejobsclientid"></a>`clientId` | [`String`](#string) | Delete jobs matching client_id in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationadminsidekiqqueuesdeletejobsfeaturecategory"></a>`featureCategory` | [`String`](#string) | Delete jobs matching feature_category in the context metadata. | +| <a id="mutationadminsidekiqqueuesdeletejobsjobid"></a>`jobId` | [`String`](#string) | Delete jobs matching job_id in the context metadata. | +| <a id="mutationadminsidekiqqueuesdeletejobspipelineid"></a>`pipelineId` | [`String`](#string) | Delete jobs matching pipeline_id in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobsproject"></a>`project` | [`String`](#string) | Delete jobs matching project in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobsqueuename"></a>`queueName` | [`String!`](#string) | Name of the queue to delete jobs from. | | <a id="mutationadminsidekiqqueuesdeletejobsrelatedclass"></a>`relatedClass` | [`String`](#string) | Delete jobs matching related_class in the context metadata. | @@ -1456,7 +1458,7 @@ Input type: `CreateIssueInput` WARNING: **Deprecated** in 14.0. -Use iterationCreate. +Manual iteration management is deprecated. Only automatic iteration cadences will be supported in the future. Input type: `CreateIterationInput` @@ -1468,7 +1470,7 @@ Input type: `CreateIterationInput` | <a id="mutationcreateiterationdescription"></a>`description` | [`String`](#string) | Description of the iteration. | | <a id="mutationcreateiterationduedate"></a>`dueDate` | [`String`](#string) | End date of the iteration. | | <a id="mutationcreateiterationgrouppath"></a>`groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | -| <a id="mutationcreateiterationiterationscadenceid"></a>`iterationsCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global ID of the iterations cadence to be assigned to newly created iteration. | +| <a id="mutationcreateiterationiterationscadenceid"></a>`iterationsCadenceId` **{warning-solid}** | [`IterationsCadenceID`](#iterationscadenceid) | **Deprecated:** `iterationCadenceId` is deprecated and will be removed in the future. This argument is ignored, because you can't create an iteration in a specific cadence. In the future only automatic iteration cadences will be allowed. Deprecated in 14.10. | | <a id="mutationcreateiterationprojectpath"></a>`projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | | <a id="mutationcreateiterationstartdate"></a>`startDate` | [`String`](#string) | Start date of the iteration. | | <a id="mutationcreateiterationtitle"></a>`title` | [`String`](#string) | Title of the iteration. | @@ -1806,8 +1808,9 @@ Input type: `DastScannerProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastscannerprofilecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdastscannerprofilecreatedastscannerprofile"></a>`dastScannerProfile` | [`DastScannerProfile`](#dastscannerprofile) | Created scanner profile. | | <a id="mutationdastscannerprofilecreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationdastscannerprofilecreateid"></a>`id` | [`DastScannerProfileID`](#dastscannerprofileid) | ID of the scanner profile. | +| <a id="mutationdastscannerprofilecreateid"></a>`id` **{warning-solid}** | [`DastScannerProfileID`](#dastscannerprofileid) | **Deprecated:** use `dastScannerProfile` field. Deprecated in 14.10. | ### `Mutation.dastScannerProfileDelete` @@ -1851,8 +1854,9 @@ Input type: `DastScannerProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastscannerprofileupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdastscannerprofileupdatedastscannerprofile"></a>`dastScannerProfile` | [`DastScannerProfile`](#dastscannerprofile) | Updated scanner profile. | | <a id="mutationdastscannerprofileupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationdastscannerprofileupdateid"></a>`id` | [`DastScannerProfileID`](#dastscannerprofileid) | ID of the scanner profile. | +| <a id="mutationdastscannerprofileupdateid"></a>`id` **{warning-solid}** | [`DastScannerProfileID`](#dastscannerprofileid) | **Deprecated:** use `dastScannerProfile` field. Deprecated in 14.10. | ### `Mutation.dastSiteProfileCreate` @@ -1877,8 +1881,9 @@ Input type: `DastSiteProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastsiteprofilecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdastsiteprofilecreatedastsiteprofile"></a>`dastSiteProfile` | [`DastSiteProfile`](#dastsiteprofile) | Site Profile object. | | <a id="mutationdastsiteprofilecreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationdastsiteprofilecreateid"></a>`id` | [`DastSiteProfileID`](#dastsiteprofileid) | ID of the site profile. | +| <a id="mutationdastsiteprofilecreateid"></a>`id` **{warning-solid}** | [`DastSiteProfileID`](#dastsiteprofileid) | **Deprecated:** use `dastSiteProfile.id` field. Deprecated in 14.10. | ### `Mutation.dastSiteProfileDelete` @@ -1923,8 +1928,9 @@ Input type: `DastSiteProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationdastsiteprofileupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdastsiteprofileupdatedastsiteprofile"></a>`dastSiteProfile` | [`DastSiteProfile`](#dastsiteprofile) | Site profile object. | | <a id="mutationdastsiteprofileupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationdastsiteprofileupdateid"></a>`id` | [`DastSiteProfileID`](#dastsiteprofileid) | ID of the site profile. | +| <a id="mutationdastsiteprofileupdateid"></a>`id` **{warning-solid}** | [`DastSiteProfileID`](#dastsiteprofileid) | **Deprecated:** use `dastSiteProfile.id` field. Deprecated in 14.10. | ### `Mutation.dastSiteTokenCreate` @@ -2372,6 +2378,8 @@ Input type: `EnableDevopsAdoptionNamespaceInput` ### `Mutation.environmentsCanaryIngressUpdate` +**Deprecated** This endpoint is planned to be removed along with certificate-based clusters. [See this epic](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) for more information. + Input type: `EnvironmentsCanaryIngressUpdateInput` #### Arguments @@ -3209,6 +3217,10 @@ Input type: `IterationCadenceUpdateInput` ### `Mutation.iterationCreate` +WARNING: +**Deprecated** in 14.10. +Manual iteration management is deprecated. Only automatic iteration cadences will be supported in the future. + Input type: `iterationCreateInput` #### Arguments @@ -3219,7 +3231,7 @@ Input type: `iterationCreateInput` | <a id="mutationiterationcreatedescription"></a>`description` | [`String`](#string) | Description of the iteration. | | <a id="mutationiterationcreateduedate"></a>`dueDate` | [`String`](#string) | End date of the iteration. | | <a id="mutationiterationcreategrouppath"></a>`groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | -| <a id="mutationiterationcreateiterationscadenceid"></a>`iterationsCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global ID of the iterations cadence to be assigned to newly created iteration. | +| <a id="mutationiterationcreateiterationscadenceid"></a>`iterationsCadenceId` **{warning-solid}** | [`IterationsCadenceID`](#iterationscadenceid) | **Deprecated:** `iterationCadenceId` is deprecated and will be removed in the future. This argument is ignored, because you can't create an iteration in a specific cadence. In the future only automatic iteration cadences will be allowed. Deprecated in 14.10. | | <a id="mutationiterationcreateprojectpath"></a>`projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | | <a id="mutationiterationcreatestartdate"></a>`startDate` | [`String`](#string) | Start date of the iteration. | | <a id="mutationiterationcreatetitle"></a>`title` | [`String`](#string) | Title of the iteration. | @@ -3234,6 +3246,10 @@ Input type: `iterationCreateInput` ### `Mutation.iterationDelete` +WARNING: +**Deprecated** in 14.10. +Manual iteration management is deprecated. Only automatic iteration cadences will be supported in the future. + Input type: `IterationDeleteInput` #### Arguments @@ -4261,7 +4277,26 @@ Input type: `SavedReplyCreateInput` | ---- | ---- | ----------- | | <a id="mutationsavedreplycreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationsavedreplycreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationsavedreplycreatesavedreply"></a>`savedReply` | [`SavedReply`](#savedreply) | Updated saved reply. | +| <a id="mutationsavedreplycreatesavedreply"></a>`savedReply` | [`SavedReply`](#savedreply) | Saved reply after mutation. | + +### `Mutation.savedReplyDestroy` + +Input type: `SavedReplyDestroyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsavedreplydestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsavedreplydestroyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | Global ID of the saved reply. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationsavedreplydestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsavedreplydestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationsavedreplydestroysavedreply"></a>`savedReply` | [`SavedReply`](#savedreply) | Saved reply after mutation. | ### `Mutation.savedReplyUpdate` @@ -4282,11 +4317,11 @@ Input type: `SavedReplyUpdateInput` | ---- | ---- | ----------- | | <a id="mutationsavedreplyupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationsavedreplyupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationsavedreplyupdatesavedreply"></a>`savedReply` | [`SavedReply`](#savedreply) | Updated saved reply. | +| <a id="mutationsavedreplyupdatesavedreply"></a>`savedReply` | [`SavedReply`](#savedreply) | Saved reply after mutation. | ### `Mutation.scanExecutionPolicyCommit` -Commits the `policy_yaml` content to the assigned security policy project for the given project(`project_path`). +Commits the `policy_yaml` content to the assigned security policy project for the given project (`full_path`). Input type: `ScanExecutionPolicyCommitInput` @@ -4295,10 +4330,11 @@ Input type: `ScanExecutionPolicyCommitInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationscanexecutionpolicycommitclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationscanexecutionpolicycommitfullpath"></a>`fullPath` | [`String`](#string) | Full path of the project. | | <a id="mutationscanexecutionpolicycommitname"></a>`name` | [`String`](#string) | Name of the policy. If the name is null, the `name` field from `policy_yaml` is used. | | <a id="mutationscanexecutionpolicycommitoperationmode"></a>`operationMode` | [`MutationOperationMode!`](#mutationoperationmode) | Changes the operation mode. | | <a id="mutationscanexecutionpolicycommitpolicyyaml"></a>`policyYaml` | [`String!`](#string) | YAML snippet of the policy. | -| <a id="mutationscanexecutionpolicycommitprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | +| <a id="mutationscanexecutionpolicycommitprojectpath"></a>`projectPath` **{warning-solid}** | [`ID`](#id) | **Deprecated:** Use `fullPath`. Deprecated in 14.10. | #### Fields @@ -4310,7 +4346,7 @@ Input type: `ScanExecutionPolicyCommitInput` ### `Mutation.securityPolicyProjectAssign` -Assigns the specified project(`security_policy_project_id`) as security policy project for the given project(`project_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`. +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`. Input type: `SecurityPolicyProjectAssignInput` @@ -4319,7 +4355,8 @@ Input type: `SecurityPolicyProjectAssignInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationsecuritypolicyprojectassignclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationsecuritypolicyprojectassignprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | +| <a id="mutationsecuritypolicyprojectassignfullpath"></a>`fullPath` | [`String`](#string) | Full path of the project. | +| <a id="mutationsecuritypolicyprojectassignprojectpath"></a>`projectPath` **{warning-solid}** | [`ID`](#id) | **Deprecated:** Use `fullPath`. Deprecated in 14.10. | | <a id="mutationsecuritypolicyprojectassignsecuritypolicyprojectid"></a>`securityPolicyProjectId` | [`ProjectID!`](#projectid) | ID of the security policy project. | #### Fields @@ -4331,7 +4368,7 @@ Input type: `SecurityPolicyProjectAssignInput` ### `Mutation.securityPolicyProjectCreate` -Creates and assigns a security policy project for the given project(`project_path`). +Creates and assigns a security policy project for the given project (`full_path`). Input type: `SecurityPolicyProjectCreateInput` @@ -4340,7 +4377,8 @@ Input type: `SecurityPolicyProjectCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationsecuritypolicyprojectcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationsecuritypolicyprojectcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | +| <a id="mutationsecuritypolicyprojectcreatefullpath"></a>`fullPath` | [`String`](#string) | Full path of the project. | +| <a id="mutationsecuritypolicyprojectcreateprojectpath"></a>`projectPath` **{warning-solid}** | [`ID`](#id) | **Deprecated:** Use `fullPath`. Deprecated in 14.10. | #### Fields @@ -4352,7 +4390,7 @@ Input type: `SecurityPolicyProjectCreateInput` ### `Mutation.securityPolicyProjectUnassign` -Unassigns the security policy project for the given project(`project_path`). +Unassigns the security policy project for the given project (`full_path`). Input type: `SecurityPolicyProjectUnassignInput` @@ -4361,7 +4399,8 @@ Input type: `SecurityPolicyProjectUnassignInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationsecuritypolicyprojectunassignclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationsecuritypolicyprojectunassignprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project. | +| <a id="mutationsecuritypolicyprojectunassignfullpath"></a>`fullPath` | [`String`](#string) | Full path of the project. | +| <a id="mutationsecuritypolicyprojectunassignprojectpath"></a>`projectPath` **{warning-solid}** | [`ID`](#id) | **Deprecated:** Use `fullPath`. Deprecated in 14.10. | #### Fields @@ -4611,6 +4650,7 @@ Input type: `TodosMarkAllDoneInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationtodosmarkalldoneclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationtodosmarkalldonetargetid"></a>`targetId` | [`TodoableID`](#todoableid) | Global ID of the to-do item's parent. Issues, merge requests, designs, and epics are supported. If argument is omitted, all pending to-do items of the current user are marked as done. | #### Fields @@ -4922,11 +4962,11 @@ Input type: `UpdateIterationInput` | ---- | ---- | ----------- | | <a id="mutationupdateiterationclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationupdateiterationdescription"></a>`description` | [`String`](#string) | Description of the iteration. | -| <a id="mutationupdateiterationduedate"></a>`dueDate` | [`String`](#string) | End date of the iteration. | +| <a id="mutationupdateiterationduedate"></a>`dueDate` **{warning-solid}** | [`String`](#string) | **Deprecated:** Manual iteration updates are deprecated, only `description` updates will be allowed in the future. Deprecated in 14.10. | | <a id="mutationupdateiterationgrouppath"></a>`groupPath` | [`ID!`](#id) | Group of the iteration. | | <a id="mutationupdateiterationid"></a>`id` | [`ID!`](#id) | Global ID of the iteration. | -| <a id="mutationupdateiterationstartdate"></a>`startDate` | [`String`](#string) | Start date of the iteration. | -| <a id="mutationupdateiterationtitle"></a>`title` | [`String`](#string) | Title of the iteration. | +| <a id="mutationupdateiterationstartdate"></a>`startDate` **{warning-solid}** | [`String`](#string) | **Deprecated:** Manual iteration updates are deprecated, only `description` updates will be allowed in the future. Deprecated in 14.10. | +| <a id="mutationupdateiterationtitle"></a>`title` **{warning-solid}** | [`String`](#string) | **Deprecated:** Manual iteration updates are deprecated, only `description` updates will be allowed in the future. Deprecated in 14.10. | #### Fields @@ -4974,7 +5014,7 @@ Input type: `UpdateNoteInput` | ---- | ---- | ----------- | | <a id="mutationupdatenotebody"></a>`body` | [`String`](#string) | Content of the note. | | <a id="mutationupdatenoteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationupdatenoteconfidential"></a>`confidential` | [`Boolean`](#boolean) | Confidentiality flag of a note. Default is false. | +| <a id="mutationupdatenoteconfidential"></a>`confidential` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated:** No longer allowed to update confidentiality of notes. Deprecated in 14.10. | | <a id="mutationupdatenoteid"></a>`id` | [`NoteID!`](#noteid) | Global ID of the note to update. | #### Fields @@ -9317,6 +9357,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="cijobduration"></a>`duration` | [`Int`](#int) | Duration of the job in seconds. | | <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. | | <a id="cijobmanualjob"></a>`manualJob` | [`Boolean`](#boolean) | Whether the job has a manual action. | | <a id="cijobname"></a>`name` | [`String`](#string) | Name of the job. | | <a id="cijobneeds"></a>`needs` | [`CiBuildNeedConnection`](#cibuildneedconnection) | References to builds that must complete before the jobs run. (see [Connections](#connections)) | @@ -9409,6 +9450,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="cirunnershortsha"></a>`shortSha` | [`String`](#string) | First eight characters of the runner's token used to authenticate new job requests. Used as the runner's unique ID. | | <a id="cirunnertaglist"></a>`tagList` | [`[String!]`](#string) | Tags associated with the runner. | | <a id="cirunnertokenexpiresat"></a>`tokenExpiresAt` | [`Time`](#time) | Runner token expiration time. | +| <a id="cirunnerupgradestatus"></a>`upgradeStatus` **{warning-solid}** | [`CiRunnerUpgradeStatusType`](#cirunnerupgradestatustype) | **Deprecated** in 14.10. This feature is in Alpha, and can be removed or changed at any point. | | <a id="cirunneruserpermissions"></a>`userPermissions` | [`RunnerPermissions!`](#runnerpermissions) | Permissions for the current user on the resource. | | <a id="cirunnerversion"></a>`version` | [`String`](#string) | Version of the runner. | @@ -9731,6 +9773,7 @@ A container repository. | <a id="containerrepositoryexpirationpolicystartedat"></a>`expirationPolicyStartedAt` | [`Time`](#time) | Timestamp when the cleanup done by the expiration policy was started on the container repository. | | <a id="containerrepositoryid"></a>`id` | [`ID!`](#id) | ID of the container repository. | | <a id="containerrepositorylocation"></a>`location` | [`String!`](#string) | URL of the container repository. | +| <a id="containerrepositorymigrationstate"></a>`migrationState` | [`String!`](#string) | Migration state of the container repository. | | <a id="containerrepositoryname"></a>`name` | [`String!`](#string) | Name of the container repository. | | <a id="containerrepositorypath"></a>`path` | [`String!`](#string) | Path of the container repository. | | <a id="containerrepositoryproject"></a>`project` | [`Project!`](#project) | Project of the container registry. | @@ -9752,6 +9795,7 @@ Details of a container repository. | <a id="containerrepositorydetailsexpirationpolicystartedat"></a>`expirationPolicyStartedAt` | [`Time`](#time) | Timestamp when the cleanup done by the expiration policy was started on the container repository. | | <a id="containerrepositorydetailsid"></a>`id` | [`ID!`](#id) | ID of the container repository. | | <a id="containerrepositorydetailslocation"></a>`location` | [`String!`](#string) | URL of the container repository. | +| <a id="containerrepositorydetailsmigrationstate"></a>`migrationState` | [`String!`](#string) | Migration state of the container repository. | | <a id="containerrepositorydetailsname"></a>`name` | [`String!`](#string) | Name of the container repository. | | <a id="containerrepositorydetailspath"></a>`path` | [`String!`](#string) | Path of the container repository. | | <a id="containerrepositorydetailsproject"></a>`project` | [`Project!`](#project) | Project of the container registry. | @@ -9981,6 +10025,7 @@ Input type for DastSiteProfile authentication. | <a id="dastsiteprofileauthenabled"></a>`enabled` | [`Boolean`](#boolean) | Indicates whether authentication is enabled. | | <a id="dastsiteprofileauthpassword"></a>`password` | [`String`](#string) | Redacted password to authenticate with on the target website. | | <a id="dastsiteprofileauthpasswordfield"></a>`passwordField` | [`String`](#string) | Name of password field at the sign-in HTML form. | +| <a id="dastsiteprofileauthsubmitfield"></a>`submitField` | [`String`](#string) | Name or ID of sign-in submit button at the sign-in HTML form. | | <a id="dastsiteprofileauthurl"></a>`url` | [`String`](#string) | The URL of the page containing the sign-in HTML form on the target website. | | <a id="dastsiteprofileauthusername"></a>`username` | [`String`](#string) | Username to authenticate with on the target website. | | <a id="dastsiteprofileauthusernamefield"></a>`usernameField` | [`String`](#string) | Name of username field at the sign-in HTML form. | @@ -10059,6 +10104,7 @@ Dependency proxy manifest. | <a id="dependencyproxymanifestid"></a>`id` | [`DependencyProxyManifestID!`](#dependencyproxymanifestid) | ID of the manifest. | | <a id="dependencyproxymanifestimagename"></a>`imageName` | [`String!`](#string) | Name of the image. | | <a id="dependencyproxymanifestsize"></a>`size` | [`String!`](#string) | Size of the manifest file. | +| <a id="dependencyproxymanifeststatus"></a>`status` | [`DependencyProxyManifestStatus!`](#dependencyproxymanifeststatus) | Status of the manifest (default, pending_destruction, processing, error). | | <a id="dependencyproxymanifestupdatedat"></a>`updatedAt` | [`Time!`](#time) | Date of most recent update. | ### `DependencyProxySetting` @@ -10381,7 +10427,6 @@ Snapshot. | <a id="devopsadoptionsnapshotrecordedat"></a>`recordedAt` | [`Time!`](#time) | Time the snapshot was recorded. | | <a id="devopsadoptionsnapshotrunnerconfigured"></a>`runnerConfigured` | [`Boolean!`](#boolean) | At least one runner was used. | | <a id="devopsadoptionsnapshotsastenabledcount"></a>`sastEnabledCount` | [`Int`](#int) | Total number of projects with enabled SAST. | -| <a id="devopsadoptionsnapshotsecurityscansucceeded"></a>`securityScanSucceeded` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 14.1. Substituted with specific security metrics. Always false. | | <a id="devopsadoptionsnapshotstarttime"></a>`startTime` | [`Time!`](#time) | Start time for the snapshot where the data points were collected. | | <a id="devopsadoptionsnapshottotalprojectscount"></a>`totalProjectsCount` | [`Int`](#int) | Total number of projects. | | <a id="devopsadoptionsnapshotvulnerabilitymanagementusedcount"></a>`vulnerabilityManagementUsedCount` | [`Int`](#int) | Total number of projects with vulnerability management used at least once. | @@ -11024,7 +11069,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `GeoNode.jobArtifactRegistries` -Find Job Artifact registries on this Geo node Available only when feature flag `geo_job_artifact_replication` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. +Find Job Artifact registries on this Geo node. Returns [`JobArtifactRegistryConnection`](#jobartifactregistryconnection). @@ -12590,7 +12635,7 @@ A user assigned to a merge request. | <a id="mergerequestassigneeprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="mergerequestassigneeprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | <a id="mergerequestassigneepublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | -| <a id="mergerequestassigneesavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | +| <a id="mergerequestassigneesavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. Will not return saved replies if `saved_replies` feature flag is disabled. (see [Connections](#connections)) | | <a id="mergerequestassigneestate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="mergerequestassigneestatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | | <a id="mergerequestassigneeuserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | @@ -12820,7 +12865,7 @@ The author of the merge request. | <a id="mergerequestauthorprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="mergerequestauthorprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | <a id="mergerequestauthorpublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | -| <a id="mergerequestauthorsavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | +| <a id="mergerequestauthorsavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. Will not return saved replies if `saved_replies` feature flag is disabled. (see [Connections](#connections)) | | <a id="mergerequestauthorstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="mergerequestauthorstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | | <a id="mergerequestauthoruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | @@ -13067,7 +13112,7 @@ A user participating in a merge request. | <a id="mergerequestparticipantprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="mergerequestparticipantprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | <a id="mergerequestparticipantpublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | -| <a id="mergerequestparticipantsavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | +| <a id="mergerequestparticipantsavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. Will not return saved replies if `saved_replies` feature flag is disabled. (see [Connections](#connections)) | | <a id="mergerequestparticipantstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="mergerequestparticipantstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | | <a id="mergerequestparticipantuserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | @@ -13315,7 +13360,7 @@ A user assigned to a merge request as a reviewer. | <a id="mergerequestreviewerprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="mergerequestreviewerprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | <a id="mergerequestreviewerpublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | -| <a id="mergerequestreviewersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | +| <a id="mergerequestreviewersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. Will not return saved replies if `saved_replies` feature flag is disabled. (see [Connections](#connections)) | | <a id="mergerequestreviewerstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="mergerequestreviewerstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | | <a id="mergerequestrevieweruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | @@ -16020,6 +16065,7 @@ Represents a URL related to a security training. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="securitytrainingurlidentifier"></a>`identifier` | [`String`](#string) | Name of the vulnerability identifier. | | <a id="securitytrainingurlname"></a>`name` | [`String`](#string) | Name of the training provider. | | <a id="securitytrainingurlstatus"></a>`status` | [`TrainingUrlRequestStatus`](#trainingurlrequeststatus) | Status of the request to training provider. | | <a id="securitytrainingurlurl"></a>`url` | [`String`](#string) | URL of the link for security training content. | @@ -16694,7 +16740,7 @@ Core represention of a GitLab user. | <a id="usercoreprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="usercoreprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | <a id="usercorepublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | -| <a id="usercoresavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | +| <a id="usercoresavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. Will not return saved replies if `saved_replies` feature flag is disabled. (see [Connections](#connections)) | | <a id="usercorestate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="usercorestatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | | <a id="usercoreuserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | @@ -17736,6 +17782,13 @@ Values for YAML processor result. | <a id="ciconfigstatusinvalid"></a>`INVALID` | Configuration file is not valid. | | <a id="ciconfigstatusvalid"></a>`VALID` | Configuration file is valid. | +### `CiJobKind` + +| Value | Description | +| ----- | ----------- | +| <a id="cijobkindbridge"></a>`BRIDGE` | Bridge CI job connecting a parent and child pipeline. | +| <a id="cijobkindbuild"></a>`BUILD` | Standard CI job. | + ### `CiJobStatus` | Value | Description | @@ -17792,6 +17845,14 @@ Values for sorting runners. | <a id="cirunnertypeinstance_type"></a>`INSTANCE_TYPE` | A runner that is instance type. | | <a id="cirunnertypeproject_type"></a>`PROJECT_TYPE` | A runner that is project type. | +### `CiRunnerUpgradeStatusType` + +| Value | Description | +| ----- | ----------- | +| <a id="cirunnerupgradestatustypeavailable"></a>`AVAILABLE` | An update is available for the runner. | +| <a id="cirunnerupgradestatustypenot_available"></a>`NOT_AVAILABLE` | An update is not available for the runner. | +| <a id="cirunnerupgradestatustyperecommended"></a>`RECOMMENDED` | An update is available and recommended for the runner. | + ### `CodeQualityDegradationSeverity` | Value | Description | @@ -18038,6 +18099,15 @@ Weight of the data visualization palette. | <a id="datavisualizationweightenumweight_900"></a>`WEIGHT_900` | 900 weight. | | <a id="datavisualizationweightenumweight_950"></a>`WEIGHT_950` | 950 weight. | +### `DependencyProxyManifestStatus` + +| Value | Description | +| ----- | ----------- | +| <a id="dependencyproxymanifeststatusdefault"></a>`DEFAULT` | Dependency proxy manifest has a status of default. | +| <a id="dependencyproxymanifeststatuserror"></a>`ERROR` | Dependency proxy manifest has a status of error. | +| <a id="dependencyproxymanifeststatuspending_destruction"></a>`PENDING_DESTRUCTION` | Dependency proxy manifest has a status of pending_destruction. | +| <a id="dependencyproxymanifeststatusprocessing"></a>`PROCESSING` | Dependency proxy manifest has a status of processing. | + ### `DeploymentTier` All environment deployment tiers. @@ -18096,6 +18166,7 @@ All supported DORA metric types. | Value | Description | | ----- | ----------- | +| <a id="dorametrictypechange_failure_rate"></a>`CHANGE_FAILURE_RATE` | Change failure rate. | | <a id="dorametrictypedeployment_frequency"></a>`DEPLOYMENT_FREQUENCY` | Deployment frequency. | | <a id="dorametrictypelead_time_for_changes"></a>`LEAD_TIME_FOR_CHANGES` | Lead time for changes. | | <a id="dorametrictypetime_to_restore_service"></a>`TIME_TO_RESTORE_SERVICE` | Time to restore service. | @@ -18279,6 +18350,8 @@ Values for sorting issues. | <a id="issuesortcreated_desc"></a>`CREATED_DESC` | Created at descending order. | | <a id="issuesortdue_date_asc"></a>`DUE_DATE_ASC` | Due date by ascending order. | | <a id="issuesortdue_date_desc"></a>`DUE_DATE_DESC` | Due date by descending order. | +| <a id="issuesortescalation_status_asc"></a>`ESCALATION_STATUS_ASC` | Status from triggered to resolved. Defaults to `CREATED_DESC` if `incident_escalations` feature flag is disabled. | +| <a id="issuesortescalation_status_desc"></a>`ESCALATION_STATUS_DESC` | Status from resolved to triggered. Defaults to `CREATED_DESC` if `incident_escalations` feature flag is disabled. | | <a id="issuesortlabel_priority_asc"></a>`LABEL_PRIORITY_ASC` | Label priority by ascending order. | | <a id="issuesortlabel_priority_desc"></a>`LABEL_PRIORITY_DESC` | Label priority by descending order. | | <a id="issuesortmilestone_due_asc"></a>`MILESTONE_DUE_ASC` | Milestone due date by ascending order. | @@ -19044,6 +19117,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumgeo_migrate_hashed_storage"></a>`GEO_MIGRATE_HASHED_STORAGE` | Callout feature name for geo_migrate_hashed_storage. | | <a id="usercalloutfeaturenameenumgke_cluster_integration"></a>`GKE_CLUSTER_INTEGRATION` | Callout feature name for gke_cluster_integration. | | <a id="usercalloutfeaturenameenumgold_trial_billings"></a>`GOLD_TRIAL_BILLINGS` | Callout feature name for gold_trial_billings. | +| <a id="usercalloutfeaturenameenumminute_limit_banner"></a>`MINUTE_LIMIT_BANNER` | Callout feature name for minute_limit_banner. | | <a id="usercalloutfeaturenameenumnew_user_signups_cap_reached"></a>`NEW_USER_SIGNUPS_CAP_REACHED` | Callout feature name for new_user_signups_cap_reached. | | <a id="usercalloutfeaturenameenumpersonal_access_token_expiry"></a>`PERSONAL_ACCESS_TOKEN_EXPIRY` | Callout feature name for personal_access_token_expiry. | | <a id="usercalloutfeaturenameenumpipeline_needs_banner"></a>`PIPELINE_NEEDS_BANNER` | Callout feature name for pipeline_needs_banner. | @@ -20213,7 +20287,7 @@ Implementations: | <a id="userprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | | <a id="userprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | | <a id="userpublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | -| <a id="usersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | +| <a id="usersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. Will not return saved replies if `saved_replies` feature flag is disabled. (see [Connections](#connections)) | | <a id="userstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="userstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | | <a id="useruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | @@ -20499,8 +20573,8 @@ Field that are available while modifying the custom mapping attributes for an HT | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="complianceviolationinputmergedafter"></a>`mergedAfter` | [`Date`](#date) | Merged date of merge requests merged after a compliance violation was created. | -| <a id="complianceviolationinputmergedbefore"></a>`mergedBefore` | [`Date`](#date) | Merged date of merge requests merged before a compliance violation was created. | +| <a id="complianceviolationinputmergedafter"></a>`mergedAfter` | [`Date`](#date) | Merge requests merged after this date (inclusive). | +| <a id="complianceviolationinputmergedbefore"></a>`mergedBefore` | [`Date`](#date) | Merge requests merged before this date (inclusive). | | <a id="complianceviolationinputprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter compliance violations by project. | ### `DastProfileCadenceInput` @@ -20538,6 +20612,7 @@ Input type for DastSiteProfile authentication. | <a id="dastsiteprofileauthinputenabled"></a>`enabled` | [`Boolean`](#boolean) | Indicates whether authentication is enabled. | | <a id="dastsiteprofileauthinputpassword"></a>`password` | [`String`](#string) | Password to authenticate with on the target website. | | <a id="dastsiteprofileauthinputpasswordfield"></a>`passwordField` | [`String`](#string) | Name of password field at the sign-in HTML form. | +| <a id="dastsiteprofileauthinputsubmitfield"></a>`submitField` | [`String`](#string) | Name or ID of sign-in submit button at the sign-in HTML form. | | <a id="dastsiteprofileauthinputurl"></a>`url` | [`String`](#string) | The URL of the page containing the sign-in HTML form on the target website. | | <a id="dastsiteprofileauthinputusername"></a>`username` | [`String`](#string) | Username to authenticate with on the target website. | | <a id="dastsiteprofileauthinputusernamefield"></a>`usernameField` | [`String`](#string) | Name of username field at the sign-in HTML form. | diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md index 45366885c5c..0d1878ebf39 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 | The 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](index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens" @@ -44,6 +44,41 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ] ``` +## Get a group access token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82714) in GitLab 14.10. + +Get a [group access token](../user/group/settings/group_access_tokens.md) by ID. + +```plaintext +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) | +| `token_id` | integer or string | yes | ID of the group access token | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>" +``` + +```json +{ + "user_id" : 141, + "scopes" : [ + "api" + ], + "name" : "token", + "expires_at" : "2021-01-31", + "id" : 42, + "active" : true, + "created_at" : "2021-01-20T22:11:48.151Z", + "revoked" : false, + "access_level": 40 +} +``` + ## Create a group access token > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77236) in GitLab 14.7. @@ -56,11 +91,11 @@ POST groups/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | -| `name` | String | yes | The name of the group access token | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](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 | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). | -| `expires_at` | Date | no | The token expires at midnight UTC on that date | +| `expires_at` | Date | no | Token expires at midnight UTC on that date | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -99,8 +134,8 @@ DELETE groups/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | -| `token_id` | integer or string | yes | The ID of the group access token | +| `id` | integer or string | yes | ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `token_id` | integer or string | yes | ID of the group access token | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>" diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 360790daf8c..b1166ba5b54 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication and Authorization +group: Workspace info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index 6ce4e1791b0..f8f9b853354 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -107,6 +107,7 @@ POST /groups/:id/protected_environments | `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. This is part of Deployment Approvals, which isn't yet available for use. For details, see [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343864). | +| `approval_rules` | array | no | Array of access levels allowed to approve, 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. You can also specify the number of required approvals from the specified entity with `required_approvals` field. See [Multiple approval rules](../ci/environments/deployment_approvals.md#multiple-approval-rules) for more information. | The assignable `user_id` are the users who belong to the given group with the Maintainer role (or above). The assignable `group_id` are the sub-groups under the given group. diff --git a/doc/api/group_releases.md b/doc/api/group_releases.md new file mode 100644 index 00000000000..06ce55b7d48 --- /dev/null +++ b/doc/api/group_releases.md @@ -0,0 +1,77 @@ +--- +stage: Release +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Group releases API **(FREE)** + +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. + +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`. + +## List group releases + +Returns a list of group releases. + +```plaintext +GET /groups/:id/releases +GET /groups/:id/releases?simple=true +``` + +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. | +| `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. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/releases" +``` + +Example response: + +```json +[ + { + "name": "standard release", + "tag_name": "releasetag", + "description": "", + "created_at": "2022-01-10T15:23:15.529Z", + "released_at": "2022-01-10T15:23:15.529Z", + "author": { + "id": 1, + "username": "root", + "name": "Administrator", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "https://gitlab.com/root" + }, + "commit": { + "id": "e8cbb845ae5a53a2fef2938cf63cf82efc10d993", + "short_id": "e8cbb845", + "created_at": "2022-01-10T15:20:29.000+00:00", + "parent_ids": [], + "title": "Update test", + "message": "Update test", + "author_name": "Administrator", + "author_email": "admin@example.com", + "authored_date": "2022-01-10T15:20:29.000+00:00", + "committer_name": "Administrator", + "committer_email": "admin@example.com", + "committed_date": "2022-01-10T15:20:29.000+00:00", + "trailers": {}, + "web_url": "https://gitlab.com/groups/gitlab-org/-/commit/e8cbb845ae5a53a2fef2938cf63cf82efc10d993" + }, + "upcoming_release": false, + "commit_path": "/testgroup/test/-/commit/e8cbb845ae5a53a2fef2938cf63cf82efc10d993", + "tag_path": "/testgroup/test/-/tags/testtag" + } +] +``` diff --git a/doc/api/groups.md b/doc/api/groups.md index 120090c18a2..e04e5207c95 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication and Authorization +group: Workspace info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -483,6 +483,8 @@ Example response: ## Details of a group +> The `membership_lock` field was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82271) in GitLab 14.10. + Get all details of a group. This endpoint can be accessed without authentication if the group is publicly accessible. In case the user that requests is an administrator if the group is publicly accessible. With authentication, it returns the `runners_token` @@ -715,6 +717,18 @@ the `marked_for_deletion_on` attribute: } ``` +Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see +the `membership_lock` attribute: + +```json +{ + "id": 4, + "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", + "membership_lock": false, + ... +} +``` + When adding the parameter `with_projects=false`, projects aren't returned. ```shell @@ -795,24 +809,24 @@ Parameters: | ------------------------------------------------------- | ------- | -------- | ----------- | | `name` | string | yes | The name of the group. | | `path` | string | yes | The path of the group. | -| `description` | string | no | The group's description. | -| `membership_lock` **(PREMIUM)** | boolean | no | Prevent adding new members to projects within this group. | -| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | -| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | -| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | -| `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | -| `project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (users with the Maintainer role), or `developer` (users with the Developer or Maintainer role). | | `auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group. | -| `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#create-a-subgroup). Can be `owner` (Owners), or `maintainer` (users with the Maintainer role). | -| `emails_disabled` | boolean | no | Disable email notifications | | `avatar` | mixed | no | Image file for avatar of the group. [Introduced in GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) | -| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned | +| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | +| `description` | string | no | The group's description. | +| `emails_disabled` | boolean | no | Disable email notifications. | | `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | -| `request_access_enabled` | boolean | no | Allow users to request member access. | +| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned. | | `parent_id` | integer | no | The parent group ID for creating nested group. | -| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | -| `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | +| `project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (users with the Maintainer role), or `developer` (users with the Developer or Maintainer role). | +| `request_access_enabled` | boolean | no | Allow users to request member access. | +| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | +| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | +| `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#create-a-subgroup). Can be `owner` (Owners), or `maintainer` (users with the Maintainer role). | +| `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | +| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | +| `membership_lock` **(PREMIUM)** | boolean | no | Prevent adding new members to projects within this group. | | `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | +| `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | ### Options for `default_branch_protection` @@ -898,27 +912,27 @@ PUT /groups/:id | `id` | integer | yes | The ID of the group. | | `name` | string | no | The name of the group. | | `path` | string | no | The path of the group. | -| `description` | string | no | The description of the group. | -| `membership_lock` **(PREMIUM)** | boolean | no | Prevent adding new members to projects within this group. | -| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | -| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | -| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | -| `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | -| `project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (users with the Maintainer role), or `developer` (users with the Developer or Maintainer role). | | `auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group. | -| `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#create-a-subgroup). Can be `owner` (Owners), or `maintainer` (users with the Maintainer role). | -| `emails_disabled` | boolean | no | Disable email notifications | | `avatar` | mixed | no | Image file for avatar of the group. [Introduced in GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) | -| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned | -| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | -| `request_access_enabled` | boolean | no | Allow users to request member access. | | `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). | +| `description` | string | no | The description of the group. | +| `emails_disabled` | boolean | no | Disable email notifications. | +| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | +| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned. | +| `prevent_sharing_groups_outside_hierarchy` | boolean | no | See [Prevent group sharing outside the group hierarchy](../user/group/index.md#prevent-group-sharing-outside-the-group-hierarchy). This attribute is only available on top-level groups. [Introduced in GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/333721) | +| `project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (users with the Maintainer role), or `developer` (users with the Developer or Maintainer role). | +| `request_access_enabled` | boolean | no | Allow users to request member access. | +| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | +| `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | +| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | +| `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#create-a-subgroup). Can be `owner` (Owners), or `maintainer` (users with the Maintainer role). | +| `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | +| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | +| `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | | `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | +| `membership_lock` **(PREMIUM)** | boolean | no | Prevent adding new members to projects within this group. | +| `prevent_forking_outside_group` **(PREMIUM)** | boolean | no | When enabled, users can **not** fork projects from this group to external namespaces. | | `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | -| `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | -| `prevent_forking_outside_group` **(PREMIUM)** | boolean | no | When enabled, users can **not** fork projects from this group to external namespaces -| `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | -| `prevent_sharing_groups_outside_hierarchy` | boolean | no | See [Prevent group sharing outside the group hierarchy](../user/group/index.md#prevent-group-sharing-outside-the-group-hierarchy). This attribute is only available on top-level groups. [Introduced in GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/333721) | NOTE: The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). diff --git a/doc/api/index.md b/doc/api/index.md index 178c2f05a6d..f78a501fb11 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -150,6 +150,10 @@ message with a status code of `401`: } ``` +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 diff --git a/doc/api/integrations.md b/doc/api/integrations.md index 90bb26ffd3d..c1564826944 100644 --- a/doc/api/integrations.md +++ b/doc/api/integrations.md @@ -315,14 +315,15 @@ PUT /projects/:id/integrations/datadog Parameters: -| Parameter | Type | Required | Description | -| ---------------------- | ------- | -------- | ----------- | -| `api_key` | string | true | API key used for authentication with Datadog | -| `api_url` | string | false | (Advanced) The full URL for your Datadog site | -| `datadog_env` | string | false | For self-managed deployments, set the env% tag for all the data sent to Datadog. | -| `datadog_service` | string | false | Tag all data from this GitLab instance in Datadog. Useful when managing several self-managed deployments | -| `datadog_site` | string | false | The Datadog site to send data to. To send data to the EU site, use `datadoghq.eu` | -| `datadog_tags` | string | false | Custom tags in Datadog. Specify one tag per line in the format: `key:value\nkey2:value2` ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79665) in GitLab 14.8.) | +| Parameter | Type | Required | Description | +|:-----------------:|:------:|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api_key` | string | true | API key used for authentication with Datadog. | +| `api_url` | string | false | (Advanced) The full URL for your Datadog site | +| `datadog_env` | string | false | For self-managed deployments, set the env% tag for all the data sent to Datadog. | +| `datadog_service` | string | false | Tag all data from this GitLab instance in Datadog. Useful when managing several self-managed deployments | +| `datadog_site` | string | false | The Datadog site to send data to. To send data to the EU site, use `datadoghq.eu` | +| `datadog_tags` | string | false | Custom tags in Datadog. Specify one tag per line in the format: `key:value\nkey2:value2` ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79665) in GitLab 14.8.) | + <!-- | `archive_trace_events` | boolean | false | When enabled, job logs are collected by Datadog and displayed along with pipeline execution traces ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346339) in GitLab 14.7) | --> <!-- TODO: uncomment the archive_trace_events field once :datadog_integration_logs_collection is rolled out. Rollout issue: https://gitlab.com/gitlab-org/gitlab/-/issues/346339 --> diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 0bf9d106404..eb7351c2e09 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Invitations API **(FREE)** -Use the Invitations API to send email to users you want to join a group or project, and to list pending +Use the Invitations API to invite or add users to a group or project, and to list pending invitations. ## Valid access levels @@ -26,9 +26,9 @@ WARNING: Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), projects in personal namespaces don't show owner (`50`) permission. -## Invite by email to group or project +## Add a member to a group or project -Invites a new user by email to join a group or project. +Adds a new member. You can specify a user ID or invite a user by email. ```plaintext POST /groups/:id/invitations @@ -38,7 +38,8 @@ 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 | -| `email` | string | yes | The email of the new member or multiple emails separated by commas | +| `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 | | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | | `invite_source` | string | no | The source of the invitation that starts the member creation process. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327120). | @@ -47,9 +48,9 @@ POST /projects/:id/invitations ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ - --data "email=test@example.com&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations" + --data "email=test@example.com&user_id=1&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations" curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ - --data "email=test@example.com&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations" + --data "email=test@example.com&user_id=1&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations" ``` Example responses: @@ -67,7 +68,8 @@ When there was any error sending the email: "status": "error", "message": { "test@example.com": "Invite email has already been taken", - "test2@example.com": "User already exists in source" + "test2@example.com": "User already exists in source", + "test_username": "Access level is not included in the list" } } ``` @@ -77,7 +79,7 @@ When there was any error sending the email: Gets a list of invited group or project members viewable by the authenticated user. Returns invitations to direct members only, and not through inherited ancestors' groups. -This function takes pagination parameters `page` and `per_page` to restrict the list of users. +This function takes pagination parameters `page` and `per_page` to restrict the list of members. ```plaintext GET /groups/:id/invitations diff --git a/doc/api/issues.md b/doc/api/issues.md index ef0727e1c13..e82aa8da8ed 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -165,6 +165,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "_links":{ "self":"http://gitlab.example.com/api/v4/projects/1/issues/76", "notes":"http://gitlab.example.com/api/v4/projects/1/issues/76/notes", @@ -390,6 +391,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "_links":{ "self":"http://gitlab.example.com/api/v4/projects/4/issues/41", "notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes", @@ -598,6 +600,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "_links":{ "self":"http://gitlab.example.com/api/v4/projects/4/issues/41", "notes":"http://gitlab.example.com/api/v4/projects/4/issues/41/notes", @@ -755,6 +758,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "task_completion_status": { "count": 0, "completed_count": 0 @@ -917,6 +921,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -1064,6 +1069,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -1238,6 +1244,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -1421,6 +1428,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -1560,6 +1568,7 @@ Example response: "confidential":false, "discussion_locked":null, "issue_type":"issue", + "severity": "UNKNOWN", "web_url":"https://gitlab.example.com/namespace1/project2/-/issues/1", "time_stats":{ "time_estimate":0, @@ -1669,6 +1678,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "_links": { "self": "http://gitlab.example.com/api/v4/projects/1/issues/2", "notes": "http://gitlab.example.com/api/v4/projects/1/issues/2/notes", @@ -1797,6 +1807,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "task_completion_status":{ "count":0, "completed_count":0 @@ -1906,6 +1917,7 @@ Example response: "confidential": false, "discussion_locked": false, "issue_type": "issue", + "severity": "UNKNOWN", "task_completion_status":{ "count":0, "completed_count":0 diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index d272f259ddf..517ffde0046 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -287,11 +287,8 @@ If the artifacts were deleted successfully, a response with status `204 No Conte ## Delete project artifacts -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223793) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `bulk_expire_project_artifacts`. Enabled by default on GitLab self-managed. Enabled on GitLab.com. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to -[disable the `bulk_expire_project_artifacts` flag](../administration/feature_flags.md). On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223793) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `bulk_expire_project_artifacts`. Enabled by default on GitLab self-managed. Enabled on GitLab.com. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350609) in GitLab 14.10. Delete artifacts of a project that can be deleted. diff --git a/doc/api/linked_epics.md b/doc/api/linked_epics.md index 89168c344f3..df302be0555 100644 --- a/doc/api/linked_epics.md +++ b/doc/api/linked_epics.md @@ -88,3 +88,239 @@ Example response: } ] ``` + +## Create a related epic link + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352840) in GitLab 14.10. + +Create a two-way relation between two epics. The user must be allowed to +update both epics to succeed. + +```plaintext +POST /groups/:id/epics/:epic_iid/related_epics +``` + +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. | +| `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). | +| `link_type` | string | **{dotted-circle}** No | Type of the relation (`relates_to`, `blocks`, `is_blocked_by`), defaults to `relates_to`. | + +Example request: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/26/epics/1/related_epics?target_group_id=26&target_epic_iid=5" +``` + +Example response: + +```json +{ + "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 + } + }, + "link_type": "relates_to" +} +``` + +## Delete a related epic link + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352840) in GitLab 14.10. + +Delete a two-way relation between two epics. The user must be allowed to +update both epics to succeed. + +```plaintext +DELETE /groups/:id/epics/:epic_iid/related_epics/:related_epic_link_id +``` + +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. | +| `related_epic_link_id` | integer/string | **{check-circle}** Yes | Internal ID of a related epic link. | + +Example request: + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/26/epics/1/related_epics/1" +``` + +Example response: + +```json +{ + "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 + } + }, + "link_type": "relates_to" +} +``` diff --git a/doc/api/members.md b/doc/api/members.md index 10072baf2ff..77a91436e6c 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -18,10 +18,9 @@ The access levels are defined in the `Gitlab::Access` module. Currently, these l - Maintainer (`40`) - Owner (`50`) - Only valid to set for groups -WARNING: -Due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299), -projects in personal namespaces don't show owner (`50`) permission -for owner. +NOTE: +In [GitLab 14.9](https://gitlab.com/gitlab-org/gitlab/-/issues/351211) and later, projects in personal namespaces have an `access_level` of `50`(Owner). +In GitLab 14.8 and earlier, projects in personal namespaces have an `access_level` of `40` (Maintainer) due to [an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299) ## Limitations @@ -63,6 +62,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-09-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "group_saml_identity": null, @@ -75,6 +83,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-09-22T14:13:35Z", + "created_by": { + "id": 1, + "username": "raymond_smith", + "name": "Raymond Smith", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "email": "john@example.com", @@ -132,6 +149,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-09-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "group_saml_identity": null, @@ -144,6 +170,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-09-22T14:13:35Z", + "created_by": { + "id": 1, + "username": "raymond_smith", + "name": "Raymond Smith", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "email": "john@example.com", @@ -161,6 +196,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-10-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-11-22T14:13:35Z", "access_level": 30, "group_saml_identity": null, @@ -201,6 +245,14 @@ Example response: "access_level": 30, "email": "john@example.com", "created_at": "2012-10-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": null, "group_saml_identity": null, "membership_state": "active" @@ -239,6 +291,15 @@ Example response: "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", "access_level": 30, + "created_at": "2012-10-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "email": "john@example.com", "expires_at": null, "group_saml_identity": null, @@ -250,7 +311,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217384) in GitLab 13.5. -Gets a list of group members that count as billable. The list includes members in the subgroup or subproject. +Gets a list of group members that count as billable. The list includes members in subgroups and projects. This API endpoint works on top-level groups only. It does not work on subgroups. @@ -267,11 +328,12 @@ respectively. 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 | -| `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. | +| 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 | +| `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. | +| `include_awaiting_members` | boolean | no | Determines if awaiting members are included. | The supported values for the `sort` attribute are: @@ -454,6 +516,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-10-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, "email": "john@example.com", @@ -492,6 +563,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-10-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-10-22T14:13:35Z", "access_level": 40, "email": "john@example.com", @@ -529,6 +609,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-10-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-10-22T14:13:35Z", "access_level": 40, "email": "john@example.com", @@ -566,6 +655,15 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", + "created_at": "2012-10-22T14:13:35Z", + "created_by": { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + }, "expires_at": "2012-10-22", "access_level": 40, "email": "john@example.com", diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index e569abd323e..721e4db3314 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -281,7 +281,7 @@ GET /projects/:id/approval_rules/:approval_rule_id WARNING: The Vulnerability-Check feature, including the Vulnerability-Check attributes listed here, is in its end-of-life process. It is [deprecated](../update/deprecations.md#vulnerability-check) -for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new +in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new [Security Approval Policies](../user/application_security/policies/#scan-result-policy-editor). You can create project approval rules using the following endpoint: @@ -413,7 +413,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ WARNING: The Vulnerability-Check feature, including the Vulnerability-Check attributes listed here, is in its end-of-life process. It is [deprecated](../update/deprecations.md#vulnerability-check) -for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new +in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new [Security Approval Policies](../user/application_security/policies/#scan-result-policy-editor). You can update project approval rules using the following endpoint: @@ -776,6 +776,82 @@ GET /projects/:id/merge_requests/:merge_request_iid/approval_rules ] ``` +### Get a single merge request level rule + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82767) in GitLab 14.10. + +You can request information about a single merge request approval rule using the following endpoint: + +```plaintext +GET /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id +``` + +**Parameters:** + +| Attribute | Type | Required | Description | +|---------------------|---------|----------|------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | yes | The IID of a merge request. | +| `approval_rule_id` | integer | yes | The ID of an approval rule. | + +```json +{ + "id": 1, + "name": "security", + "rule_type": "regular", + "eligible_approvers": [ + { + "id": 5, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + }, + { + "id": 50, + "name": "Group Member 1", + "username": "group_member_1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/group_member_1" + } + ], + "approvals_required": 3, + "source_rule": null, + "users": [ + { + "id": 5, + "name": "John Doe", + "username": "jdoe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/0?s=80&d=identicon", + "web_url": "http://localhost/jdoe" + } + ], + "groups": [ + { + "id": 5, + "name": "group1", + "path": "group1", + "description": "", + "visibility": "public", + "lfs_enabled": false, + "avatar_url": null, + "web_url": "http://localhost/groups/group1", + "request_access_enabled": false, + "full_name": "group1", + "full_path": "group1", + "parent_id": null, + "ldap_cn": null, + "ldap_access": null + } + ], + "contains_hidden_groups": false, + "overridden": false +} +``` + ### Create merge request level rule > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. @@ -881,13 +957,13 @@ These are system generated rules. | Attribute | Type | Required | Description | |----------------------|---------|----------|------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | -| `merge_request_iid` | integer | yes | The ID of MR | -| `approval_rule_id` | integer | yes | The ID of a approval rule | -| `name` | string | yes | The name of the approval rule | -| `approvals_required` | integer | yes | The number of required approvals for this rule | -| `user_ids` | Array | no | The ids of users as approvers | -| `group_ids` | Array | no | The ids of groups as approvers | +| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | +| `merge_request_iid` | integer | yes | The IID of a merge request. | +| `approval_rule_id` | integer | yes | The ID of an approval rule. | +| `name` | string | yes | The name of the approval rule. | +| `approvals_required` | integer | yes | The number of required approvals for this rule. | +| `user_ids` | Array | no | The IDs of users as approvers. | +| `group_ids` | Array | no | The IDs of groups as approvers. | ```json { diff --git a/doc/api/notes.md b/doc/api/notes.md index 83631c70f8a..fbcf5e28f79 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -142,8 +142,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). | -| `issue_iid` | integer | yes | The IID of an issue. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](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 | The confidential flag of a note. Default is false. | | `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | @@ -162,13 +162,13 @@ PUT /projects/:id/issues/:issue_iid/notes/:note_id Parameters: -| Attribute | Type | Required | Description | -|----------------|----------------|----------|----------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](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. | -| `confidential` | boolean | no | The confidential flag of a note. | +| Attribute | Type | Required | Description | +|----------------|----------------|-------------|----------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](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. | +| `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note" @@ -403,7 +403,7 @@ Parameters: | `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) | -| `merge_request_diff_sha`| string | no | The SHA of the head commit which is used to ensure that the merge request hasn't been updated since the API request was sent. This is required for the /merge quick action | +| `merge_request_diff_sha`| string | no | Required for the `/merge` [quick action](../user/project/quick_actions.md). The SHA of the head commit, which ensures the merge request wasn't updated after the API request was sent. | ### Modify existing merge request note @@ -415,12 +415,13 @@ PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id Parameters: -| Attribute | Type | Required | Description | -|---------------------|----------------|----------|---------------------------------------------------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](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. | +| Attribute | Type | Required | Description | +|---------------------|-------------------|----------|----------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](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. | +| `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note" @@ -452,6 +453,11 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git Gets a list of all notes for a single epic. Epic notes are comments users can post to an epic. +NOTE: +The epics notes API uses the epic ID instead of epic IID. If you use the epic's IID, GitLab returns either a 404 +error or notes for the wrong epic. It's different from the [issue notes API](#issues) and +[merge requests notes API](#merge-requests). + ```plaintext GET /groups/:id/epics/:epic_id/notes GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at @@ -519,11 +525,12 @@ POST /groups/:id/epics/:epic_id/notes Parameters: -| Attribute | Type | Required | Description | -| --------- | -------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | -| `epic_id` | integer | yes | The ID of an epic | -| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | ----------- | +| `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) | +| `confidential` | boolean | no | The confidential flag of a note. Default is `false`. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note" @@ -539,12 +546,13 @@ PUT /groups/:id/epics/:epic_id/notes/:note_id Parameters: -| Attribute | Type | Required | Description | -| --------- | -------------- | -------- | ----------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the group](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. | +| Attribute | Type | Required | Description | +| ---------------| ----------------- | -------- | ---------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](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. | +| `confidential` | boolean | no | **Deprecated:** will be removed in GitLab 16.0. The confidential flag of a note. Default is false. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note" diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 7b38ac39b96..ad93d8033d0 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -24,10 +24,6 @@ GitLab supports the following authorization flows: and is recommended for both client and server apps. - **Authorization code:** Secure and common flow. Recommended option for secure server-side apps. -- **Implicit grant:** Originally designed for user-agent only apps, such as - single page web apps running on GitLab Pages. - The [Internet Engineering Task Force (IETF)](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2) - recommends against Implicit grant flow. - **Resource owner password credentials:** To be used **only** for securely hosted, first-party services. GitLab recommends against use of this flow. @@ -64,7 +60,7 @@ As OAuth 2.0 bases its security entirely on the transport layer, you should not URIs. For more information, see the [OAuth 2.0 RFC](https://tools.ietf.org/html/rfc6749#section-3.1.2.1) and the [OAuth 2.0 Threat Model RFC](https://tools.ietf.org/html/rfc6819#section-4.4.2.1). These factors are particularly important when using the -[Implicit grant flow](#implicit-grant-flow), where actual credentials are included in the `redirect_uri`. +[Implicit grant flow](#implicit-grant-flow-deprecated), where actual credentials are included in the `redirect_uri`. In the following sections you can find detailed instructions on how to obtain authorization with each flow. @@ -242,40 +238,6 @@ authorization request. You can now make requests to the API with the access token returned. -### Implicit grant flow - -WARNING: -Implicit grant flow is inherently insecure and the IETF has removed it in [OAuth 2.1](https://oauth.net/2.1/). -It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/288516) for use in GitLab 14.0, and is planned for -[removal](https://gitlab.com/gitlab-org/gitlab/-/issues/344609) in GitLab 15.0. - -We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce) -instead. - -Unlike the authorization code flow, the client receives an `access token` -immediately as a result of the authorization request. The flow does not use the -client secret or the authorization code, as the application -code and storage is accessible on client browsers and mobile devices. - -To request the access token, you should redirect the user to the -`/oauth/authorize` endpoint using `token` response type: - -```plaintext -https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES -``` - -This prompts the user to approve the applications access to their account -based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to -the `REDIRECT_URI` you provided. The [scope parameter](../integration/oauth_provider.md#authorized-applications) - is a space-separated list of scopes you want to have access to (for example, `scope=read_user+profile` -would request `read_user` and `profile` scopes). The redirect -includes a fragment with `access_token` as well as token details in GET -parameters, for example: - -```plaintext -https://example.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600 -``` - ### Resource owner password credentials flow NOTE: @@ -357,6 +319,40 @@ access_token = client.password.get_token('user@example.com', 'secret') puts access_token.token ``` +### Implicit grant flow (DEPRECATED) + +WARNING: +Implicit grant flow is inherently insecure and the IETF has removed it in [OAuth 2.1](https://oauth.net/2.1/). +It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/288516) in GitLab 14.0, and is planned for +[removal](https://gitlab.com/gitlab-org/gitlab/-/issues/344609) in GitLab 15.0. + +We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce) +instead. + +Unlike the authorization code flow, the client receives an `access token` +immediately as a result of the authorization request. The flow does not use the +client secret or the authorization code, as the application +code and storage is accessible on client browsers and mobile devices. + +To request the access token, you should redirect the user to the +`/oauth/authorize` endpoint using `token` response type: + +```plaintext +https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&state=YOUR_UNIQUE_STATE_HASH&scope=REQUESTED_SCOPES +``` + +This prompts the user to approve the applications access to their account +based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to +the `REDIRECT_URI` you provided. The [scope parameter](../integration/oauth_provider.md#authorized-applications) + is a space-separated list of scopes you want to have access to (for example, `scope=read_user+profile` +would request `read_user` and `profile` scopes). The redirect +includes a fragment with `access_token` as well as token details in GET +parameters, for example: + +```plaintext +https://example.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600 +``` + ## Access GitLab API with `access token` The `access token` allows you to make requests to the API on behalf of a user. diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md index b3a27519729..ea2e917bbba 100644 --- a/doc/api/packages/composer.md +++ b/doc/api/packages/composer.md @@ -262,6 +262,8 @@ Example response: ## Download a package archive +> Authorization for this endpoint was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331601) in GitLab 14.10. + Download a Composer package. This URL is provided in the [v1](#v1-package-metadata) or [v2 package metadata](#v2-package-metadata) response. A `.zip` file extension must be in the request. @@ -287,3 +289,6 @@ curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v ``` This writes the downloaded file to `package.tar.gz` in the current directory. + +NOTE: +This endpoint requires authorization in GitLab 14.10 and later. In GitLab 14.9 and earlier, it was publicly accessible. diff --git a/doc/api/pages.md b/doc/api/pages.md index 7316d225dbc..57982188858 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index c1f81ffa361..610fd97c810 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md index f6eced4f08a..b13005ec436 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 | The 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](index.md#namespaced-path-encoding) | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" @@ -44,9 +44,46 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ] ``` +## Get a project access token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82714) in GitLab 14.10. + +Get a [project access token](../user/project/settings/project_access_tokens.md) by ID. + +```plaintext +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) | +| `token_id` | integer or string | yes | ID of the project access token | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>" +``` + +```json +{ + "user_id" : 141, + "scopes" : [ + "api" + ], + "name" : "token", + "expires_at" : "2021-01-31", + "id" : 42, + "active" : true, + "created_at" : "2021-01-20T22:11:48.151Z", + "revoked" : false, + "access_level": 40, + "last_used_at": "2022-03-15T11:05:42.437Z" +} +``` + ## Create a project access token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55408) in GitLab 13.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55408) in GitLab 13.10. +> - The `token` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55408) in GitLab 13.10. Create a [project access token](../user/project/settings/project_access_tokens.md). @@ -56,11 +93,11 @@ POST projects/:id/access_tokens | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | -| `name` | String | yes | The name of the project access token | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](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 | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). | -| `expires_at` | Date | no | The token expires at midnight UTC on that date | +| `expires_at` | Date | no | Token expires at midnight UTC on that date | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -99,8 +136,8 @@ DELETE projects/:id/access_tokens/:token_id | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | -| `token_id` | integer or string | yes | The ID of the project access token | +| `id` | integer or string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `token_id` | integer or string | yes | ID of the project access token | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>" diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 46fa05d6cbc..b9ebfa0fc5c 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -248,10 +248,11 @@ The `Content-Type` header must be `application/gzip`. ## Import a file from AWS S3 -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348874) in GitLab 14.9 in [Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta), [with a flag](../administration/feature_flags.md) named `import_project_from_remote_file_s3`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348874) in GitLab 14.9 in [Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta), [with a flag](../administration/feature_flags.md) named `import_project_from_remote_file_s3`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/348874) in GitLab 14.10. FLAG: -On self-managed GitLab and GitLab.com, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `import_project_from_remote_file_s3`. This feature is not ready for production use. +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 `import_project_from_remote_file_s3`. On GitLab.com, this feature is available. ```plaintext POST /projects/remote-import-s3 @@ -261,6 +262,7 @@ POST /projects/remote-import-s3 | ------------------- | -------------- | -------- | ---------------------------------------- | | `namespace` | integer/string | no | The ID or path of the namespace to import the project to. Defaults to the current user's namespace. | | `name` | string | no | The name of the project to import. If not provided, defaults to the path of the project. | +| `path` | string | yes | The full path of the new project. | | `region` | string | yes | [AWS S3 region name where the file is stored.](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html#Regions) | | `bucket_name` | string | yes | [AWS S3 bucket name where the file is stored.](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) | | `file_key` | string | yes | [AWS S3 file key to identify the file.](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingObjects.html) | @@ -271,7 +273,7 @@ The passed override parameters take precedence over all values defined in the ex ```shell curl --request POST \ - --url "http://localhost:3000/api/v4/projects/remote-import-s3" \ + --url "https://gitlab.example.com/api/v4/projects/remote-import-s3" \ --header "PRIVATE-TOKEN: <your gitlab access key>" \ --header 'Content-Type: application/json' \ --data '{ diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 2251b0fc7fd..4205e6699fe 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -170,5 +170,5 @@ This parameter is used for filtering by attributes, such as `environment_scope`. Example usage: ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1?filter[environment_scope]=production" +curl --request DELETE --globoff --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1?filter[environment_scope]=production" ``` diff --git a/doc/api/projects.md b/doc/api/projects.md index ee649377745..c40d39ee981 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -19,7 +19,7 @@ Values for the project visibility level are: - `internal`: the project can be cloned by any signed-in user except [external users](../user/permissions.md#external-users). - `public`: the project can be accessed without any authentication. -For more, read [Project visibility](../public_access/public_access.md). +For more, read [Project visibility](../user/public_access.md). ## Project merge method @@ -49,6 +49,7 @@ GET /projects | `archived` | boolean | **{dotted-circle}** No | Limit by archived status. | | `id_after` | integer | **{dotted-circle}** No | Limit results to projects with IDs greater than the specified ID. | | `id_before` | integer | **{dotted-circle}** No | Limit results to projects with IDs less than the specified ID. | +| `imported` | boolean | **{dotted-circle}** No | Limit results to projects which were imported from external systems by current user. | | `last_activity_after` | datetime | **{dotted-circle}** No | Limit results to projects with last_activity after specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | | `last_activity_before` | datetime | **{dotted-circle}** No | Limit results to projects with last_activity before specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | @@ -374,7 +375,7 @@ Get a list of visible projects owned by the given user. When accessed without 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. +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) for selected `order_by` options. @@ -1228,7 +1229,7 @@ POST /projects | `build_timeout` | integer | **{dotted-circle}** No | The maximum amount of time, in seconds, that a job can run. | | `builds_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `ci_config_path` | string | **{dotted-circle}** No | The path to CI configuration file. | -| `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). Valid values for `cadence` are: `1d` (every day), `7d` (every week), `14d` (every two weeks), `1month` (every month), or `3month` (every quarter). | +| `container_expiration_policy_attributes` | hash | **{dotted-circle}** No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). See the [Container Registry](../user/packages/container_registry/reduce_container_registry_storage.md#use-the-cleanup-policy-api) documentation for more information on `cadence`, `keep_n` and `older_than` values. | | `container_registry_access_level` | string | **{dotted-circle}** No | Set visibility of container registry, for this project, to one of `disabled`, `private` or `enabled`. | | `container_registry_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `default_branch` | string | **{dotted-circle}** No | The [default branch](../user/project/repository/branches/default.md) name. Requires `initialize_with_readme` to be `true`. | @@ -2563,7 +2564,7 @@ POST /projects/:id/push_rule | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `author_email_regex` | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | -| `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `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. | | `commit_message_negative_regex` | string | **{dotted-circle}** No | No commit message is allowed to match this, for example `ssh\:\/\/`. | | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | @@ -2586,7 +2587,7 @@ PUT /projects/:id/push_rule | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `author_email_regex` | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | -| `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `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. | | `commit_message_negative_regex` | string | **{dotted-circle}** No | No commit message is allowed to match this, for example `ssh\:\/\/`. | | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 61587136a14..fc7eb5caf6d 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -99,7 +99,7 @@ POST /projects/:id/protected_environments ```shell curl --header 'Content-Type: application/json' --request POST \ - --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' \ + --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}], "approval_rules": [{"group_id": 134}, {"group_id": 135, "required_approvals": 2}]}' \ --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/22034114/protected_environments" ``` @@ -110,8 +110,9 @@ curl --header 'Content-Type: application/json' --request POST \ | `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. This is part of Deployment Approvals, which isn't yet available for use. For details, see [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343864). | +| `approval_rules` | array | no | Array of access levels allowed to approve, with each described by a hash. See [Multiple approval rules](../ci/environments/deployment_approvals.md#multiple-approval-rules) for more information. | -Elements in the `deploy_access_levels` array should be one of `user_id`, `group_id` or +Elements in the `deploy_access_levels` and `approval_rules` array should be one of `user_id`, `group_id` or `access_level`, and take the form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). @@ -129,7 +130,23 @@ Example response: "group_id": 9899826 } ], - "required_approval_count": 0 + "required_approval_count": 0, + "approval_rules": [ + { + "user_id": null, + "group_id": 134, + "access_level": null, + "access_level_description": "qa-group", + "required_approvals": 1 + }, + { + "user_id": null, + "group_id": 135, + "access_level": null, + "access_level_description": "security-group", + "required_approvals": 2 + } + ] } ``` diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index c603be9489c..6023adb79d0 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -53,7 +53,7 @@ Example response: [ { "tag_name":"v0.2", - "description":"## CHANGELOG\r\n\r\n- Escape label and milestone titles to prevent XSS in GFM autocomplete. !2740\r\n- Prevent private snippets from being embeddable.\r\n- Add subresources removal to member destroy service.", + "description":"## CHANGELOG\r\n\r\n- Escape label and milestone titles to prevent XSS in GLFM autocomplete. !2740\r\n- Prevent private snippets from being embeddable.\r\n- Add subresources removal to member destroy service.", "name":"Awesome app v0.2 beta", "created_at":"2019-01-03T01:56:19.539Z", "released_at":"2019-01-03T01:56:19.539Z", @@ -241,10 +241,10 @@ Get a Release for the given tag. 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). | -| `tag_name` | string | yes | The Git tag the release is associated with. | +| 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 Git tag the release is associated with. | | `include_html_description` | boolean | no | If `true`, a response includes HTML rendered Markdown of the release description. | Example request: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 282ef0adc78..66808900ab6 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -11,6 +11,16 @@ links. For manipulating other Release assets, see [Release API](index.md). GitLab supports links to `http`, `https`, and `ftp` assets. +## Authentication + +For authentication, the Release Links API accepts: + +- A [Personal Access Token](../../user/profile/personal_access_tokens.md) using the + `PRIVATE-TOKEN` header. +- A [Project Access Token](../../user/project/settings/project_access_tokens.md) using the `PRIVATE-TOKEN` header. + +The [GitLab CI/CD job token](../../ci/jobs/ci_job_token.md) `$CI_JOB_TOKEN` is not supported. See [GitLab issue #50819](https://gitlab.com/gitlab-org/gitlab/-/issues/250819) for more details. + ## Get links Get assets as links from a Release. diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index 8b584285033..351706e8514 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -51,6 +51,43 @@ NOTE: For security reasons, the `url` attribute is always scrubbed of username and password information. +## Get a single project's remote mirror + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82770) in GitLab 14.10. + +Returns a remote mirror and its statuses: + +```plaintext +GET /projects/:id/remote_mirrors/:mirror_id +``` + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486" +``` + +Example response: + +```json +{ + "enabled": true, + "id": 101486, + "last_error": null, + "last_successful_update_at": "2020-01-06T17:32:02.823Z", + "last_update_at": "2020-01-06T17:32:02.823Z", + "last_update_started_at": "2020-01-06T17:31:55.864Z", + "only_protected_branches": true, + "keep_divergent_refs": true, + "update_status": "finished", + "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git" +} +``` + +NOTE: +For security reasons, the `url` attribute is always scrubbed of username +and password information. + ## Create a pull mirror Learn how to [configure a pull mirror](projects.md#configure-pull-mirroring-for-a-project) using the Projects API. @@ -136,3 +173,23 @@ Example response: "url": "https://*****:*****@gitlab.com/gitlab-org/security/gitlab.git" } ``` + +## Delete a remote mirror + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82778) in GitLab 14.10. + +Delete a remote mirror. + +```plaintext +DELETE /projects/:id/remote_mirrors/:mirror_id +``` + +| Attribute | Type | Required | Description | +| :---------- | :----- | :--------- |:------------------| +| `mirror_id` | Integer | yes | Remote mirror ID. | + +Example request: + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/remote_mirrors/101486" +``` diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 23acebf5aab..1fdc48a6d92 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -23,6 +23,8 @@ in the following table. ## Get file from repository +> The `execute_filemode` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83499) in GitLab 14.10. + Allows you to receive information about file in repository like name, size, content. File content is Base64 encoded. This endpoint can be accessed without authentication if the repository is publicly accessible. @@ -54,7 +56,8 @@ Example response: "ref": "master", "blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83", "commit_id": "d5a3ff139356ce33e37e73add446f16869741b50", - "last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d" + "last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d", + "execute_filemode": false } ``` @@ -85,6 +88,7 @@ X-Gitlab-File-Path: app/models/key.rb X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d X-Gitlab-Ref: master X-Gitlab-Size: 1476 +X-Gitlab-Execute-Filemode: false ... ``` @@ -155,6 +159,7 @@ X-Gitlab-File-Path: path/to/file.rb X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d X-Gitlab-Ref: master X-Gitlab-Size: 1476 +X-Gitlab-Execute-Filemode: false ... ``` @@ -179,6 +184,8 @@ Like [Get file from repository](repository_files.md#get-file-from-repository) yo ## Create new file in repository +> The `execute_filemode` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83499) in GitLab 14.10. + This allows you to create a single file. For creating multiple files with a single request see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions). ```plaintext @@ -196,6 +203,7 @@ POST /projects/:id/repository/files/:file_path | `author_name` | string | no | The commit author's name. | | `content` | string | yes | The file's content. | | `commit_message` | string | yes | The commit message. | +| `execute_filemode` | boolean | no | Enables or disables the `execute` flag on the file. Can be `true` or `false`. | ```shell curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' \ @@ -216,6 +224,8 @@ Example response: ## Update existing file in repository +> The `execute_filemode` parameter was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83499) in GitLab 14.10. + This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions). ```plaintext @@ -234,6 +244,7 @@ PUT /projects/:id/repository/files/:file_path | `content` | string | yes | The file's content. | | `commit_message` | string | yes | The commit message. | | `last_commit_id` | string | no | Last known file commit ID. | +| `execute_filemode` | boolean | no | Enables or disables the `execute` flag on the file. Can be `true` or `false`. | ```shell curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' \ diff --git a/doc/api/runners.md b/doc/api/runners.md index 7437860239e..304f2494f70 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -48,7 +48,7 @@ GET /runners?tag_list=tag1,tag2 |------------|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | | `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | -| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 | +| `status` | string | no | The status of runners to show, one of: `online`, `offline` and `not_connected`. `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 | | `tag_list` | string array | no | List of the runner's tags | @@ -332,7 +332,7 @@ PUT --form "paused=true" /runners/:runner_id # --or-- -# Deprecated: removal planned in 15.0 +# Deprecated: removal planned in 16.0 PUT --form "active=false" /runners/:runner_id ``` @@ -346,7 +346,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ # --or-- -# Deprecated: removal planned in 15.0 +# Deprecated: removal planned in 16.0 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ --form "active=false" "https://gitlab.example.com/api/v4/runners/6" ``` @@ -448,7 +448,7 @@ Example response: ## List project's runners -List all runners available in the project, including from ancestor groups and [any allowed shared runners](../ci/runners/runners_scope.md#enable-shared-runners). +List all runners available in the project, including from ancestor groups and [any allowed shared runners](../ci/runners/runners_scope.md#enable-shared-runners-for-a-project). ```plaintext GET /projects/:id/runners @@ -566,7 +566,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ## List group's runners -List all runners available in the group as well as its ancestor groups, including [any allowed shared runners](../ci/runners/runners_scope.md#enable-shared-runners). +List all runners available in the group as well as its ancestor groups, including [any allowed shared runners](../ci/runners/runners_scope.md#enable-shared-runners-for-a-group). ```plaintext GET /groups/:id/runners diff --git a/doc/api/secure_files.md b/doc/api/secure_files.md index 96190920a33..7d30cc0c4c7 100644 --- a/doc/api/secure_files.md +++ b/doc/api/secure_files.md @@ -11,8 +11,7 @@ type: reference, api 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 `ci_secure_files`. -The feature is not ready for production use. +ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `ci_secure_files`. Limited to 100 secure files per project. Files must be smaller than 5 MB. The feature is not ready for production use. ## List project secure files @@ -101,12 +100,12 @@ POST /projects/:project_id/secure_files 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. | -| `name` | string | **{check-circle}** Yes | The `name` of the file being uploaded. | -| `file` | file | **{check-circle}** Yes | The `file` being uploaded. | -| `permissions` | string | **{dotted-circle}** No | The file is created with the specified permissions when created in the CI/CD job. Available types are: `read_only` (default), `read_write`, and `execute`. | +| 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. | +| `name` | string | **{check-circle}** Yes | The `name` of the file being uploaded. The file name must be unique within the project. | +| `file` | file | **{check-circle}** Yes | The `file` being uploaded (5 MB limit). | +| `permissions` | string | **{dotted-circle}** No | The file is created with the specified permissions when created in the CI/CD job. Available types are: `read_only` (default), `read_write`, and `execute`. | Example request: diff --git a/doc/api/settings.md b/doc/api/settings.md index 16e281af916..cc9df7917e2 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -274,6 +274,7 @@ listed in the descriptions of the relevant settings. | `default_projects_limit` | integer | no | Project limit per user. Default is `100000`. | | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `delayed_project_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed project deletion by default in new groups. Default is `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. | | `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 0 and 90. | `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). | @@ -342,7 +343,7 @@ listed in the descriptions of the relevant settings. | `help_text` **(PREMIUM)** | string | no | GitLab server administrator information. | | `hide_third_party_offers` | boolean | no | Do not display offers from third parties in GitLab. | | `home_page_url` | string | no | Redirect to this URL when not logged in. | -| `housekeeping_bitmaps_enabled` | boolean | required by: `housekeeping_enabled` | Enable Git pack file bitmap creation. | +| `housekeeping_bitmaps_enabled` | boolean | no | Git pack file bitmap creation is always enabled and cannot be changed via API and UI. This API field is deprecated and always returns `true`. | | `housekeeping_enabled` | boolean | no | (**If enabled, requires:** `housekeeping_bitmaps_enabled`, `housekeeping_full_repack_period`, `housekeeping_gc_period`, and `housekeeping_incremental_repack_period`) Enable or disable Git housekeeping. | | `housekeeping_full_repack_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which an incremental `git repack` is run. | | `housekeeping_gc_period` | integer | required by: `housekeeping_enabled` | Number of Git pushes after which `git gc` is run. | @@ -350,6 +351,9 @@ 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. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. | +| `inactive_projects_min_size_mb` | integer | no | If `delete_inactive_projects` is `true`, the minimum repository size for projects to be checked for inactivity. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. | +| `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 will be deleted because it is inactive. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84519) in GitLab 14.10. | | `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. | @@ -437,6 +441,9 @@ listed in the descriptions of the relevant settings. | `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | | `throttle_authenticated_api_period_in_seconds` | integer | required by:<br>`throttle_authenticated_api_enabled` | Rate limit period (in seconds). | | `throttle_authenticated_api_requests_per_period` | integer | required by:<br>`throttle_authenticated_api_enabled` | Maximum requests per period per user. | +| `throttle_authenticated_packages_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_packages_api_period_in_seconds` and `throttle_authenticated_packages_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). View [Package Registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md) for more details. | +| `throttle_authenticated_packages_api_period_in_seconds` | integer | required by:<br>`throttle_authenticated_packages_api_enabled` | Rate limit period (in seconds). View [Package Registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md) for more details. | +| `throttle_authenticated_packages_api_requests_per_period` | integer | required by:<br>`throttle_authenticated_packages_api_enabled` | Maximum requests per period per user. View [Package Registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md) for more details. | | `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | | `throttle_authenticated_web_period_in_seconds` | integer | required by:<br>`throttle_authenticated_web_enabled` | Rate limit period (in seconds). | | `throttle_authenticated_web_requests_per_period` | integer | required by:<br>`throttle_authenticated_web_enabled` | Maximum requests per period per user. | @@ -446,6 +453,9 @@ listed in the descriptions of the relevant settings. | `throttle_unauthenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_api_period_in_seconds` and `throttle_unauthenticated_api_requests_per_period`) Enable unauthenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | | `throttle_unauthenticated_api_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_api_enabled` | Rate limit period in seconds. | | `throttle_unauthenticated_api_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_api_enabled` | Max requests per period per IP. | +| `throttle_unauthenticated_packages_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_packages_api_period_in_seconds` and `throttle_unauthenticated_packages_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). View [Package Registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md) for more details. | +| `throttle_unauthenticated_packages_api_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_packages_api_enabled` | Rate limit period (in seconds). View [Package Registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md) for more details. | +| `throttle_unauthenticated_packages_api_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_packages_api_enabled` | Maximum requests per period per user. View [Package Registry rate limits](../user/admin_area/settings/package_registry_rate_limits.md) for more details. | | `throttle_unauthenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_web_period_in_seconds` and `throttle_unauthenticated_web_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | | `throttle_unauthenticated_web_period_in_seconds` | integer | required by:<br>`throttle_unauthenticated_web_enabled` | Rate limit period in seconds. | | `throttle_unauthenticated_web_requests_per_period` | integer | required by:<br>`throttle_unauthenticated_web_enabled` | Max requests per period per IP. | diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index f14f1322184..a883c3c1613 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -13,7 +13,7 @@ You can configure the URL endpoint of the system hooks from the GitLab user inte 1. On the top bar, select **Menu > Admin**. 1. Select **System Hooks** (`/admin/hooks`). -Read more about [system hooks](../system_hooks/system_hooks.md). +Read more about [system hooks](../administration/system_hooks.md). ## List system hooks diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index abed008218c..8a55ee84402 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -135,7 +135,7 @@ Example response: ```json { "name": "Ruby", - "content": "# This file is a template, and might need editing before it works on your project.\n# Official language image. Look for the different tagged releases at:\n# https://hub.docker.com/r/library/ruby/tags/\nimage: \"ruby:2.5\"\n\n# Pick zero or more services to be used on all builds.\n# Only needed when using a docker container to run your tests in.\n# Check out: http://docs.gitlab.com/ee/ci/services/index.html\n - mysql:latest\n - redis:latest\n - postgres:latest\n\nvariables:\n POSTGRES_DB: database_name\n\n# Cache gems in between builds\ncache:\n paths:\n - vendor/ruby\n\n# This is a basic example for a gem or script which doesn't use\n# services such as redis or postgres\nbefore_script:\n - ruby -v # Print out ruby version for debugging\n # Uncomment next line if your rails app needs a JS runtime:\n # - apt-get update -q && apt-get install nodejs -yqq\n - bundle install -j $(nproc) --path vendor # Install dependencies into ./vendor/ruby\n\n# Optional - Delete if not using `rubocop`\nrubocop:\n script:\n - rubocop\n\nrspec:\n script:\n - rspec spec\n\nrails:\n variables:\n DATABASE_URL: \"postgresql://postgres:postgres@postgres:5432/$POSTGRES_DB\"\n script:\n - rails db:migrate\n - rails db:seed\n - rails test\n\n# This deploy job uses a simple deploy flow to Heroku, other providers, e.g. AWS Elastic Beanstalk\n# are supported too: https://github.com/travis-ci/dpl\ndeploy:\n type: deploy\n environment: production\n script:\n - gem install dpl\n - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_PRODUCTION_KEY\n" + "content": "# This file is a template, and might need editing before it works on your project.\n# To contribute improvements to CI/CD templates, please follow the Development guide at:\n# https://docs.gitlab.com/ee/development/cicd/templates.html\n# This specific template is located at:\n# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Ruby.gitlab-ci.yml\n\n# Official language image. Look for the different tagged releases at:\n# https://hub.docker.com/r/library/ruby/tags/\nimage: ruby:latest\n\n# Pick zero or more services to be used on all builds.\n# Only needed when using a docker container to run your tests in.\n# Check out: http://docs.gitlab.com/ee/ci/docker/using_docker_images.html#what-is-a-service\nservices:\n - mysql:latest\n - redis:latest\n - postgres:latest\n\nvariables:\n POSTGRES_DB: database_name\n\n# Cache gems in between builds\ncache:\n paths:\n - vendor/ruby\n\n# This is a basic example for a gem or script which doesn't use\n# services such as redis or postgres\nbefore_script:\n - ruby -v # Print out ruby version for debugging\n # Uncomment next line if your rails app needs a JS runtime:\n # - apt-get update -q && apt-get install nodejs -yqq\n - bundle config set path 'vendor' # Install dependencies into ./vendor/ruby\n - bundle install -j $(nproc)\n\n# Optional - Delete if not using `rubocop`\nrubocop:\n script:\n - rubocop\n\nrspec:\n script:\n - rspec spec\n\nrails:\n variables:\n DATABASE_URL: \"postgresql://postgres:postgres@postgres:5432/$POSTGRES_DB\"\n script:\n - rails db:migrate\n - rails db:seed\n - rails test\n\n# This deploy job uses a simple deploy flow to Heroku, other providers, e.g. AWS Elastic Beanstalk\n# are supported too: https://github.com/travis-ci/dpl\ndeploy:\n stage: deploy\n environment: production\n script:\n - gem install dpl\n - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_PRODUCTION_KEY\n" } ``` diff --git a/doc/api/users.md b/doc/api/users.md index de9af59de93..7b4962735e6 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -97,8 +97,18 @@ In addition, to exclude external users from the users' list, you can use the par GET /users?exclude_external=true ``` +To exclude [bot users for projects](../user/project/settings/project_access_tokens.md#bot-users-for-projects) +and [bot users for groups](../user/group/settings/group_access_tokens.md#bot-users-for-groups), you can use the +parameter `without_project_bots=true`. + +```plaintext +GET /users?without_project_bots=true +``` + ### For admins +> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. + ```plaintext GET /users ``` @@ -151,7 +161,8 @@ GET /users "external": false, "private_profile": false, "current_sign_in_ip": "196.165.1.102", - "last_sign_in_ip": "172.127.2.22" + "last_sign_in_ip": "172.127.2.22", + "namespace_id": 1 }, { "id": 2, @@ -185,7 +196,8 @@ GET /users "external": false, "private_profile": false, "current_sign_in_ip": "10.165.1.102", - "last_sign_in_ip": "172.127.2.22" + "last_sign_in_ip": "172.127.2.22", + "namespace_id": 2 } ] ``` @@ -293,13 +305,18 @@ Parameters: "website_url": "", "organization": "", "job_title": "Operations Specialist", + "pronouns": "he/him", + "work_information": null, "followers": 1, - "following": 1 + "following": 1, + "local_time": "3:38 PM" } ``` ### For admin +> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. + ```plaintext GET /users/:id ``` @@ -332,6 +349,11 @@ Example Responses: "website_url": "", "organization": "", "job_title": "Operations Specialist", + "pronouns": "he/him", + "work_information": null, + "followers": 1, + "following": 1, + "local_time": "3:38 PM", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", "theme_id": 1, @@ -355,7 +377,8 @@ Example Responses: "last_sign_in_ip": "172.127.2.22", "plan": "gold", "trial": true, - "sign_in_count": 1337 + "sign_in_count": 1337, + "namespace_id": 1 } ``` @@ -404,6 +427,8 @@ GET /users/:id?with_custom_attributes=true ## User creation +> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. + Creates a new user. Note only administrators can create new users. Either `password`, `reset_password`, or `force_random_password` must be specified. If `reset_password` and `force_random_password` are @@ -459,6 +484,8 @@ Parameters: ## User modification +> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. + Modifies an existing user. Only administrators can change attributes of a user. ```plaintext @@ -561,6 +588,13 @@ GET /user "twitter": "", "website_url": "", "organization": "", + "job_title": "", + "pronouns": "he/him", + "bot": false, + "work_information": null, + "followers": 0, + "following": 0, + "local_time": "3:38 PM", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", "theme_id": 1, @@ -577,12 +611,17 @@ GET /user "can_create_project": true, "two_factor_enabled": true, "external": false, - "private_profile": false + "private_profile": false, + "commit_email": "admin@example.com", } ``` +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit` parameters. + ## List current user (for admins) +> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. + ```plaintext GET /user ``` @@ -632,7 +671,9 @@ Parameters: "private_profile": false, "commit_email": "john-codes@example.com", "current_sign_in_ip": "196.165.1.102", - "last_sign_in_ip": "172.127.2.22" + "last_sign_in_ip": "172.127.2.22", + "namespace_id": 1, + "note": null } ``` @@ -1566,7 +1607,7 @@ Returns: - `404 User Not Found` if the user cannot be found. - `403 Forbidden` when trying to unban a user that is not banned. -### Get user contribution events +## Get user contribution events Please refer to the [Events API documentation](events.md#get-user-contribution-events) @@ -1828,7 +1869,7 @@ POST /users/:user_id/personal_access_tokens | `user_id` | integer | yes | The ID of the user | | `name` | string | yes | The name of the personal access token | | `expires_at` | date | no | The expiration date of the personal access token in ISO format (`YYYY-MM-DD`) | -| `scopes` | array | yes | The array of scopes of the personal access token (`api`, `read_user`, `read_api`, `read_repository`, `write_repository`) | +| `scopes` | array | yes | The array of scopes of the personal access token. See [personal access token scopes](../user/profile/personal_access_tokens.md#personal-access-token-scopes) for possible values. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \ |