diff options
Diffstat (limited to 'doc/api')
57 files changed, 1374 insertions, 786 deletions
diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index d496ecbca5b..f489cb780ef 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -22,160 +22,159 @@ 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` | -| [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) | -| [Dependencies](dependencies.md) **(ULTIMATE)** | `/projects/:id/dependencies` | -| [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | -| [Freeze Periods](freeze_periods.md) | `/projects/:id/freeze_periods` | -| [Debian distributions](packages/debian_project_distributions.md) | `/projects/:id/debian_distributions` (also available for groups) | -| [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 Flags](feature_flags.md) | `/projects/:id/feature_flags` | -| [Feature Flag User Lists](feature_flag_user_lists.md) | `/projects/:id/feature_flags_user_lists` | -| [Integrations](integrations.md) | `/projects/:id/integrations` | -| [Invitations](invitations.md) | `/projects/:id/invitations` (also available for groups) | -| [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | -| [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | -| [Issue boards](boards.md) | `/projects/:id/boards` | -| [Issue links](issue_links.md). | `/projects/:id/issues/.../links` | -| [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) | -| [Pipelines](pipelines.md) | `/projects/:id/pipelines` | -| [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | -| [Pipeline triggers](pipeline_triggers.md) | `/projects/:id/triggers` | -| [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | -| [Project badges](project_badges.md) | `/projects/:id/badges` | -| [Project clusters](project_clusters.md) | `/projects/:id/clusters` | -| [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | -| [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` | -| [Protected environments](protected_environments.md) | `/projects/:id/protected_environments` | -| [Protected branches](protected_branches.md) | `/projects/:id/protected_branches` | -| [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | -| [Releases](releases/index.md) | `/projects/:id/releases` | -| [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` | -| [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) | -| [Services](services.md) (renamed to [Integrations](integrations.md)) | `/projects/:id/services` | -| [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` | -| [Project wikis](wikis.md) | `/projects/:id/wikis` | +| 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` | +| [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) | +| [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` | ## Group resources The following API resources are available in the group context: -| Resource | Available endpoints | -|:-----------------------------------------------------------------|:---------------------------------------------------------------------------------| -| [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) | -| [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) | -| [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` | -| [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | -| [Group badges](group_badges.md) | `/groups/:id/badges` | -| [Group issue boards](group_boards.md) | `/groups/:id/boards` | -| [Group iterations](group_iterations.md) **(PREMIUM)** | `/groups/:id/iterations` (also available for projects) | -| [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` | -| [Invitations](invitations.md) | `/groups/:id/invitations` (also available for projects) | -| [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | -| [Issues Statistics](issues_statistics.md) | `/groups/:id/issues_statistics` (also available for projects and standalone) | -| [Members](members.md) | `/groups/:id/members` (also available for projects) | -| [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | -| [Notes](notes.md) (comments) | `/groups/:id/epics/.../notes` (also available for projects) | +| Resource | Available endpoints | +|:-----------------------------------------------------------------|:--------------------| +| [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) | +| [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) | +| [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` | +| [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | +| [Group badges](group_badges.md) | `/groups/:id/badges` | +| [Group issue boards](group_boards.md) | `/groups/:id/boards` | +| [Group iterations](group_iterations.md) **(PREMIUM)** | `/groups/:id/iterations` (also available for projects) | +| [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 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) | +| [Issues Statistics](issues_statistics.md) | `/groups/:id/issues_statistics` (also available for projects and standalone) | +| [Members](members.md) | `/groups/:id/members` (also available for projects) | +| [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | +| [Notes](notes.md) (comments) | `/groups/:id/epics/.../notes` (also available for projects) | | [Notification settings](notification_settings.md) | `/groups/:id/notification_settings` (also available for projects and standalone) | -| [Resource label events](resource_label_events.md) | `/groups/:id/epics/.../resource_label_events` (also available for projects) | -| [Search](search.md) | `/groups/:id/search` (also available for projects and standalone) | -| [Group wikis](group_wikis.md) **(PREMIUM)** | `/groups/:id/wikis` | +| [Resource label events](resource_label_events.md) | `/groups/:id/epics/.../resource_label_events` (also available for projects) | +| [Search](search.md) | `/groups/:id/search` (also available for projects and standalone) | ## Standalone resources The following API resources are available outside of project and group contexts (including `/users`): -| Resource | Available endpoints | -|:---------------------------------------------------|:------------------------------------------------------------------------| -| [Instance-level CI/CD variables](instance_level_ci_variables.md) **(FREE SELF)** | `/admin/ci/variables` | -| [Sidekiq queues administration](admin_sidekiq_queues.md) **(FREE SELF)** | `/admin/sidekiq/queues/:queue_name` | -| [Appearance](appearance.md) **(FREE SELF)** | `/application/appearance` | -| [Applications](applications.md) | `/applications` | -| [Audit Events](audit_events.md) **(PREMIUM SELF)** | `/audit_events` | -| [Avatar](avatar.md) | `/avatar` | -| [Broadcast messages](broadcast_messages.md) | `/broadcast_messages` | -| [Code snippets](snippets.md) | `/snippets` | -| [Custom attributes](custom_attributes.md) | `/users/:id/custom_attributes` (also available for groups and projects) | -| [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | -| [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | -| [Feature flags](features.md) | `/features` | -| [Geo Nodes](geo_nodes.md) **(PREMIUM SELF)** | `/geo_nodes` | -| [Group Activity Analytics](group_activity_analytics.md) | `/analytics/group_activity/{issues_count | merge_requests_count | new_members_count }` | -| [Group repository storage moves](group_repository_storage_moves.md) **(PREMIUM SELF)** | `/group_repository_storage_moves` | -| [Import repository from GitHub](import.md) | `/import/github` | -| [Instance clusters](instance_clusters.md) **(FREE SELF)** | `/admin/clusters` | -| [Issues](issues.md) | `/issues` (also available for groups and projects) | -| [Issues Statistics](issues_statistics.md) | `/issues_statistics` (also available for groups and projects) | -| [Jobs](jobs.md) | `/job` | -| [Keys](keys.md) | `/keys` | -| [License](license.md) **(FREE SELF)** | `/license` | -| [Markdown](markdown.md) | `/markdown` | -| [Merge requests](merge_requests.md) | `/merge_requests` (also available for groups and projects) | -| [Metrics dashboard annotations](metrics_dashboard_annotations.md) | `/environments/:id/metrics_dashboard/annotations`, `/clusters/:id/metrics_dashboard/annotations` | -| [Namespaces](namespaces.md) | `/namespaces` | -| [Notification settings](notification_settings.md) | `/notification_settings` (also available for groups and projects) | -| [Pages domains](pages_domains.md) | `/pages/domains` (also available for projects) | -| [Plan limits](plan_limits.md) | `/application/plan_limits` | -| [Personal access tokens](personal_access_tokens.md) | `/personal_access_tokens` | -| [Projects](projects.md) | `/users/:id/projects` (also available for projects) | +| Resource | Available endpoints | +|:----------------------------------------------------------------------------------------|:--------------------| +| [Appearance](appearance.md) **(FREE SELF)** | `/application/appearance` | +| [Applications](applications.md) | `/applications` | +| [Audit Events](audit_events.md) **(PREMIUM SELF)** | `/audit_events` | +| [Avatar](avatar.md) | `/avatar` | +| [Broadcast messages](broadcast_messages.md) | `/broadcast_messages` | +| [Code snippets](snippets.md) | `/snippets` | +| [Custom attributes](custom_attributes.md) | `/users/:id/custom_attributes` (also available for groups and projects) | +| [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | +| [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | +| [Feature flags](features.md) | `/features` | +| [Geo Nodes](geo_nodes.md) **(PREMIUM SELF)** | `/geo_nodes` | +| [Group Activity Analytics](group_activity_analytics.md) | `/analytics/group_activity/{issues_count}` | +| [Group repository storage moves](group_repository_storage_moves.md) **(PREMIUM SELF)** | `/group_repository_storage_moves` | +| [Import repository from GitHub](import.md) | `/import/github` | +| [Instance clusters](instance_clusters.md) **(FREE SELF)** | `/admin/clusters` | +| [Instance-level CI/CD variables](instance_level_ci_variables.md) **(FREE SELF)** | `/admin/ci/variables` | +| [Issues Statistics](issues_statistics.md) | `/issues_statistics` (also available for groups and projects) | +| [Issues](issues.md) | `/issues` (also available for groups and projects) | +| [Jobs](jobs.md) | `/job` | +| [Keys](keys.md) | `/keys` | +| [License](license.md) **(FREE SELF)** | `/license` | +| [Markdown](markdown.md) | `/markdown` | +| [Merge requests](merge_requests.md) | `/merge_requests` (also available for groups and projects) | +| [Metrics dashboard annotations](metrics_dashboard_annotations.md) | `/environments/:id/metrics_dashboard/annotations`, `/clusters/:id/metrics_dashboard/annotations` | +| [Namespaces](namespaces.md) | `/namespaces` | +| [Notification settings](notification_settings.md) | `/notification_settings` (also available for groups and projects) | +| [Pages domains](pages_domains.md) | `/pages/domains` (also available for projects) | +| [Personal access tokens](personal_access_tokens.md) | `/personal_access_tokens` | +| [Plan limits](plan_limits.md) | `/application/plan_limits` | | [Project repository storage moves](project_repository_storage_moves.md) **(FREE SELF)** | `/project_repository_storage_moves` | -| [Runners](runners.md) | `/runners` (also available for projects) | -| [Search](search.md) | `/search` (also available for groups and projects) | -| [Settings](settings.md) **(FREE SELF)** | `/application/settings` | +| [Projects](projects.md) | `/users/:id/projects` (also available for projects) | +| [Runners](runners.md) | `/runners` (also available for projects) | +| [Search](search.md) | `/search` (also available for groups and projects) | +| [Service Data](usage_data.md) | `/usage_data` (For GitLab instance [Administrator](../user/permissions.md) users only) | +| [Settings](settings.md) **(FREE SELF)** | `/application/settings` | +| [Sidekiq metrics](sidekiq_metrics.md) **(FREE SELF)** | `/sidekiq` | +| [Sidekiq queues administration](admin_sidekiq_queues.md) **(FREE SELF)** | `/admin/sidekiq/queues/:queue_name` | | [Snippet repository storage moves](snippet_repository_storage_moves.md) **(FREE SELF)** | `/snippet_repository_storage_moves` | -| [Statistics](statistics.md) | `/application/statistics` | -| [Sidekiq metrics](sidekiq_metrics.md) **(FREE SELF)** | `/sidekiq` | -| [Suggestions](suggestions.md) | `/suggestions` | -| [System hooks](system_hooks.md) | `/hooks` | -| [To-dos](todos.md) | `/todos` | -| [Topics](topics.md) | `/topics` | -| [Service Data](usage_data.md) | `/usage_data` (For GitLab instance [Administrator](../user/permissions.md) users only) | -| [Users](users.md) | `/users` | -| [Validate `.gitlab-ci.yml` file](lint.md) | `/lint` | -| [Version](version.md) | `/version` | +| [Statistics](statistics.md) | `/application/statistics` | +| [Suggestions](suggestions.md) | `/suggestions` | +| [System hooks](system_hooks.md) | `/hooks` | +| [To-dos](todos.md) | `/todos` | +| [Topics](topics.md) | `/topics` | +| [Users](users.md) | `/users` | +| [Validate `.gitlab-ci.yml` file](lint.md) | `/lint` | +| [Version](version.md) | `/version` | ## Templates API resources diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 3ffcae04791..888323f9362 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -277,7 +277,7 @@ Example response: "entity_id": 7, "entity_type": "Project", "details": { - "change": "prevent merge request approval from reviewers", + "change": "prevent merge request approval from committers", "from": "", "to": "true", "author_name": "Administrator", @@ -312,7 +312,7 @@ Example response: ### Retrieve a specific project audit event -Only available to project maintainers or owners. +Only available to users with at least the [Maintainer role](../user/permissions.md) for the project. ```plaintext GET /projects/:id/audit_events/:audit_event_id @@ -336,7 +336,7 @@ Example response: "entity_id": 7, "entity_type": "Project", "details": { - "change": "prevent merge request approval from reviewers", + "change": "prevent merge request approval from committers", "from": "", "to": "true", "author_name": "Administrator", diff --git a/doc/api/branches.md b/doc/api/branches.md index 7b9354f3264..4e2a0306845 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -40,14 +40,14 @@ Example response: ```json [ { - "name": "master", + "name": "main", "merged": false, "protected": true, "default": true, "developers_can_push": false, "developers_can_merge": false, "can_push": true, - "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/master", + "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main", "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -89,7 +89,7 @@ Parameters: Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches/master" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches/main" ``` Example response: @@ -103,7 +103,7 @@ Example response: "developers_can_push": false, "developers_can_merge": false, "can_push": true, - "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/master", + "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main", "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -151,7 +151,7 @@ Parameters: Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=main" ``` Example response: diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index c7189586230..0f2b9a13a3f 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -165,8 +165,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ ## Group deploy tokens -Group maintainers and owners can list group deploy -tokens. Only group owners can create and delete group deploy tokens. +Users with at least the [Maintainer role](../user/permissions.md) for the group can list group deploy +tokens. Only group Owners can create and delete group deploy tokens. ### List group deploy tokens diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 18b74e1450f..5f750df4a48 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -987,7 +987,7 @@ addition by referencing line 157 in the *new* file: ```shell curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]"\ --form "note=This is brilliant!" --form "path=hello.rb"\ - --form "line=157" --form "line_type=old"\ + --form "line=157" --form "line_type=new"\ "https://gitlab.com/api/v4/projects/47/repository/commits/<COMMIT_ID>/comments" ``` diff --git a/doc/api/dora4_project_analytics.md b/doc/api/dora4_project_analytics.md index f69c918c6e2..c202b075c42 100644 --- a/doc/api/dora4_project_analytics.md +++ b/doc/api/dora4_project_analytics.md @@ -25,9 +25,6 @@ GET /projects/:id/analytics/deployment_frequency?environment=:environment&from=: | Attribute | Type | Required | Description | |--------------|--------|----------|-----------------------| | `id` | string | yes | The ID of the project | - -| Parameter | Type | Required | Description | -|--------------|--------|----------|-----------------------| | `environment`| string | yes | The name of the environment to filter by | | `from` | string | yes | Datetime range to start from, inclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | | `to` | string | no | Datetime range to end at, exclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | diff --git a/doc/api/epics.md b/doc/api/epics.md index 263cfe5806e..6d572303460 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -49,6 +49,8 @@ NOTE: ## List epics for a group +> `parent_iid` and `_links[parent]` in response were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347527) in GitLab 14.6. + Gets all epics of the requested group and its subgroups. ```plaintext @@ -62,7 +64,7 @@ GET /groups/:id/epics?state=opened | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `author_id` | integer | no | Return epics created by the given user `id` | -| `labels` | string | no | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used | +| `labels` | string | no | Return epics matching a comma-separated list of labels names. Label names from the epic group or a parent group can be used | | `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Available in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) and later | | `order_by` | string | no | Return epics ordered by `created_at`, `updated_at`, or `title` fields. Default is `created_at` | | `sort` | string | no | Return epics sorted in `asc` or `desc` order. Default is `desc` | @@ -75,6 +77,7 @@ GET /groups/:id/epics?state=opened | `include_ancestor_groups` | boolean | no | Include epics from the requested group's ancestors. Default is `false` | | `include_descendant_groups` | boolean | no | Include epics from the requested group's descendants. Default is `true` | | `my_reaction_emoji` | string | no | Return epics reacted by the authenticated user by the given emoji. `None` returns epics not given a reaction. `Any` returns epics given at least one reaction. Available in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31479) and later | +| `not` | Hash | no | Return epics that do not match the parameters supplied. Accepts: `author_id` and `labels`. Available in [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/347525) and later | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics" @@ -89,6 +92,7 @@ Example response: "iid": 4, "group_id": 7, "parent_id": 23, + "parent_iid": 3, "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "state": "opened", @@ -128,7 +132,8 @@ Example response: "_links":{ "self": "http://gitlab.example.com/api/v4/groups/7/epics/4", "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/4/issues", - "group":"http://gitlab.example.com/api/v4/groups/7" + "group":"http://gitlab.example.com/api/v4/groups/7", + "parent":"http://gitlab.example.com/api/v4/groups/7/epics/3" } }, { @@ -136,6 +141,7 @@ Example response: "iid": 35, "group_id": 17, "parent_id": 19, + "parent_iid": 1, "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "state": "opened", @@ -174,7 +180,8 @@ Example response: "_links":{ "self": "http://gitlab.example.com/api/v4/groups/17/epics/35", "epic_issues": "http://gitlab.example.com/api/v4/groups/17/epics/35/issues", - "group":"http://gitlab.example.com/api/v4/groups/17" + "group":"http://gitlab.example.com/api/v4/groups/17", + "parent":"http://gitlab.example.com/api/v4/groups/17/epics/1" } } ] @@ -182,6 +189,8 @@ Example response: ## Single epic +> `parent_iid` and `_links[parent]` in response were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347527) in GitLab 14.6. + Gets a single epic ```plaintext @@ -204,6 +213,8 @@ Example response: "id": 30, "iid": 5, "group_id": 7, + "parent_id": null, + "parent_iid": null, "title": "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.", "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", "state": "opened", @@ -243,13 +254,16 @@ Example response: "_links":{ "self": "http://gitlab.example.com/api/v4/groups/7/epics/5", "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/5/issues", - "group":"http://gitlab.example.com/api/v4/groups/7" + "group":"http://gitlab.example.com/api/v4/groups/7", + "parent": null } } ``` ## New epic +> `parent_iid` and `_links[parent]` in response were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347527) in GitLab 14.6. + Creates a new epic. NOTE: @@ -265,7 +279,7 @@ POST /groups/:id/epics | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | The title of the epic | -| `labels` | string | no | The comma separated list of labels | +| `labels` | string | no | The comma-separated list of labels | | `description` | string | no | The description of the epic. Limited to 1,048,576 characters. | | `confidential` | boolean | no | Whether the epic should be confidential | | `created_at` | string | no | When the epic was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([available](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5 and later) | @@ -276,7 +290,7 @@ POST /groups/:id/epics | `parent_id` | integer/string | no | The ID of a parent epic (in GitLab 11.11 and later) | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description&parent_id=29" ``` Example response: @@ -286,6 +300,8 @@ Example response: "id": 33, "iid": 6, "group_id": 7, + "parent_id": 29, + "parent_iid": 4, "title": "Epic", "description": "Epic description", "state": "opened", @@ -325,13 +341,16 @@ Example response: "_links":{ "self": "http://gitlab.example.com/api/v4/groups/7/epics/6", "epic_issues": "http://gitlab.example.com/api/v4/groups/7/epics/6/issues", - "group":"http://gitlab.example.com/api/v4/groups/7" + "group":"http://gitlab.example.com/api/v4/groups/7", + "parent": "http://gitlab.example.com/api/v4/groups/7/epics/4" } } ``` ## Update epic +> `parent_iid` and `_links[parent]` in response were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347527) in GitLab 14.6. + Updates an epic. NOTE: @@ -371,6 +390,8 @@ Example response: "id": 33, "iid": 6, "group_id": 7, + "parent_id": null, + "parent_iid": null, "title": "New Title", "description": "Epic description", "state": "opened", diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 203c1a23996..c62d33f82f4 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Error Tracking project settings The project settings API allows you to retrieve the [Error Tracking](../operations/error_tracking.md) -settings for a project. Only for project maintainers. +settings for a project. Only for users with [Maintainer role](../user/permissions.md) for the project. ### Get Error Tracking settings @@ -41,7 +41,8 @@ Example response: ### Enable or disable the Error Tracking project settings -The API allows you to enable or disable the Error Tracking settings for a project. Only for project maintainers. +The API allows you to enable or disable the Error Tracking settings for a project. Only for users with the +[Maintainer role](../user/permissions.md) for the project. ```plaintext PATCH /projects/:id/error_tracking/settings @@ -73,7 +74,8 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68384) in GitLab 14.3. -For [integrated error tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) feature. Only for project maintainers. +For [integrated error tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) feature. Only for users with the +[Maintainer role](../user/permissions.md) for the project. ### List project client keys diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index 4306167603d..46ed44d8808 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -71,7 +71,7 @@ POST /projects/:id/feature_flags_user_lists | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the feature flag. | -| `user_xids` | string | yes | A comma separated list of user IDs. | +| `user_xids` | string | yes | A comma-separated list of user IDs. | ```shell curl "https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists" \ @@ -143,7 +143,7 @@ PUT /projects/:id/feature_flags_user_lists/:iid | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `iid` | integer/string | yes | The internal ID of the project's feature flag user list. | | `name` | string | no | The name of the feature flag. | -| `user_xids` | string | no | A comma separated list of user IDs. | +| `user_xids` | string | no | A comma-separated list of user IDs. | ```shell curl "https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists/1" \ diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index fb821824dd1..3952a87e698 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Geo Nodes API **(PREMIUM SELF)** -To interact with Geo node endpoints, you need to authenticate yourself as an +To interact with Geo node endpoints, you must authenticate yourself as an administrator. ## Create a new Geo node @@ -26,7 +26,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/ | Attribute | Type | Required | Description | | ----------------------------| ------- | -------- | -----------------------------------------------------------------| -| `primary` | boolean | no | Specifying whether this node will be primary. Defaults to false. | +| `primary` | boolean | no | Specifying whether this node should be primary. Defaults to false. | | `enabled` | boolean | no | Flag indicating if the Geo node is enabled. Defaults to true. | | `name` | string | yes | The unique identifier for the Geo node. Must match `geo_node_name` if it is set in `gitlab.rb`, otherwise it must match `external_url` | | `url` | string | yes | The user-facing URL for the Geo node. | @@ -35,11 +35,11 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/ | `repos_max_capacity` | integer | no | Control the maximum concurrency of repository backfill for this secondary node. Defaults to 25. | | `verification_max_capacity` | integer | no | Control the maximum concurrency of repository verification for this node. Defaults to 100. | | `container_repositories_max_capacity` | integer | no | Control the maximum concurrency of container repository sync for this node. Defaults to 10. | -| `sync_object_storage` | boolean | no | Flag indicating if the secondary Geo node will replicate blobs in Object Storage. Defaults to false. | +| `sync_object_storage` | boolean | no | Flag indicating if the secondary Geo node should replicate blobs in Object Storage. Defaults to false. | | `selective_sync_type` | string | no | Limit syncing to only specific groups or shards. Valid values: `"namespaces"`, `"shards"`, or `null`. | | `selective_sync_shards` | array | no | The repository storage for the projects synced if `selective_sync_type` == `shards`. | | `selective_sync_namespace_ids` | array | no | The IDs of groups that should be synced, if `selective_sync_type` == `namespaces`. | -| `minimum_reverification_interval` | integer | no | The interval (in days) in which the repository verification is valid. Once expired, it will be reverified. This has no effect when set on a secondary node. | +| `minimum_reverification_interval` | integer | no | The interval (in days) in which the repository verification is valid. Once expired, it is reverified. This has no effect when set on a secondary node. | Example response: @@ -199,11 +199,11 @@ PUT /geo_nodes/:id | `repos_max_capacity` | integer | no | Control the maximum concurrency of repository backfill for this secondary node. | | `verification_max_capacity` | integer | no | Control the maximum concurrency of verification for this node. | | `container_repositories_max_capacity` | integer | no | Control the maximum concurrency of container repository sync for this node. | -| `sync_object_storage` | boolean | no | Flag indicating if the secondary Geo node will replicate blobs in Object Storage. | +| `sync_object_storage` | boolean | no | Flag indicating if the secondary Geo node should replicate blobs in Object Storage. | | `selective_sync_type` | string | no | Limit syncing to only specific groups or shards. Valid values: `"namespaces"`, `"shards"`, or `null`. | | `selective_sync_shards` | array | no | The repository storage for the projects synced if `selective_sync_type` == `shards`. | | `selective_sync_namespace_ids` | array | no | The IDs of groups that should be synced, if `selective_sync_type` == `namespaces`. | -| `minimum_reverification_interval` | integer | no | The interval (in days) in which the repository verification is valid. Once expired, it will be reverified. This has no effect when set on a secondary node. | +| `minimum_reverification_interval` | integer | no | The interval (in days) in which the repository verification is valid. Once expired, it is reverified. This has no effect when set on a secondary node. | Example response: @@ -241,7 +241,7 @@ Example response: Removes the Geo node. NOTE: -Only a Geo primary node will accept this request. +Only a Geo primary node accepts this request. ```plaintext DELETE /geo_nodes/:id @@ -307,11 +307,18 @@ Example response: "health_status": "Healthy", "missing_oauth_application": false, "db_replication_lag_seconds": null, - "lfs_objects_count": 0, + "lfs_objects_count": 5, + "lfs_objects_checksum_total_count": 5, + "lfs_objects_checksummed_count": 5, + "lfs_objects_checksum_failed_count": 0, "lfs_objects_synced_count": null, "lfs_objects_failed_count": null, - "lfs_objects_synced_missing_on_primary_count": 0, + "lfs_objects_registry_count": null, + "lfs_objects_verification_total_count": null, + "lfs_objects_verified_count": null, + "lfs_objects_verification_failed_count": null, "lfs_objects_synced_in_percentage": "0.00%", + "lfs_objects_verified_in_percentage": "0.00%", "job_artifacts_count": 2, "job_artifacts_synced_count": null, "job_artifacts_failed_count": null, @@ -453,6 +460,13 @@ Example response: "uploads_failed_count": 0, "uploads_registry_count": null, "uploads_synced_in_percentage": "0.00%", + "uploads_checksum_total_count": 5, + "uploads_checksummed_count": 5, + "uploads_checksum_failed_count": null, + "uploads_verification_total_count": null, + "uploads_verified_count": null, + "uploads_verification_failed_count": null, + "uploads_verified_in_percentage": "0.00%", }, { "geo_node_id": 2, @@ -461,11 +475,18 @@ Example response: "health_status": "Healthy", "missing_oauth_application": false, "db_replication_lag_seconds": 0, - "lfs_objects_count": 0, - "lfs_objects_synced_count": 0, - "lfs_objects_failed_count": 0, - "lfs_objects_synced_missing_on_primary_count": 0, + "lfs_objects_count": 5, + "lfs_objects_checksum_total_count": 5, + "lfs_objects_checksummed_count": 5, + "lfs_objects_checksum_failed_count": 0, + "lfs_objects_synced_count": null, + "lfs_objects_failed_count": null, + "lfs_objects_registry_count": null, + "lfs_objects_verification_total_count": null, + "lfs_objects_verified_count": null, + "lfs_objects_verification_failed_count": null, "lfs_objects_synced_in_percentage": "0.00%", + "lfs_objects_verified_in_percentage": "0.00%", "job_artifacts_count": 2, "job_artifacts_synced_count": 1, "job_artifacts_failed_count": 1, @@ -595,6 +616,13 @@ Example response: "uploads_failed_count": 0, "uploads_registry_count": null, "uploads_synced_in_percentage": "0.00%", + "uploads_checksum_total_count": 5, + "uploads_checksummed_count": 5, + "uploads_checksum_failed_count": null, + "uploads_verification_total_count": null, + "uploads_verified_count": null, + "uploads_verification_failed_count": null, + "uploads_verified_in_percentage": "0.00%", } ] ``` @@ -619,11 +647,18 @@ Example response: "health_status": "Healthy", "missing_oauth_application": false, "db_replication_lag_seconds": 0, - "lfs_objects_count": 0, - "lfs_objects_synced_count": 0, - "lfs_objects_failed_count": 0, - "lfs_objects_synced_missing_on_primary_count": 0, + "lfs_objects_count": 5, + "lfs_objects_checksum_total_count": 5, + "lfs_objects_checksummed_count": 5, + "lfs_objects_checksum_failed_count": 0, + "lfs_objects_synced_count": null, + "lfs_objects_failed_count": null, + "lfs_objects_registry_count": null, + "lfs_objects_verification_total_count": null, + "lfs_objects_verified_count": null, + "lfs_objects_verification_failed_count": null, "lfs_objects_synced_in_percentage": "0.00%", + "lfs_objects_verified_in_percentage": "0.00%", "job_artifacts_count": 2, "job_artifacts_synced_count": 1, "job_artifacts_failed_count": 1, @@ -734,6 +769,13 @@ Example response: "uploads_failed_count": 0, "uploads_registry_count": null, "uploads_synced_in_percentage": "0.00%", + "uploads_checksum_total_count": 5, + "uploads_checksummed_count": 5, + "uploads_checksum_failed_count": null, + "uploads_verification_total_count": null, + "uploads_verified_count": null, + "uploads_verification_failed_count": null, + "uploads_verified_in_percentage": "0.00%", } ``` diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 3523276bdf5..bcaa5930faf 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -6,27 +6,42 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GraphQL API **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19008) in GitLab 11.0 (enabled by feature flag `graphql`). -> - [Always enabled](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19008) in GitLab 11.0 [with a flag](../../administration/feature_flags.md) named `graphql`. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. -## Getting Started +[GraphQL](https://graphql.org/) is a query language for APIs. You can use it to +request the exact data you need, and therefore limit the number of requests you need. -For those new to the GitLab GraphQL API, see -[Getting started with GitLab GraphQL API](getting_started.md). +GraphQL data is arranged in types, so your client can use +[client-side GraphQL libraries](https://graphql.org/code/#graphql-clients) +to consume the API and avoid manual parsing. -### Quick Reference +There are no fixed endpoints and no data model, so you can add +to the API without creating [breaking changes](../../development/contributing/#breaking-changes). +This enables us to have a [versionless API](https://graphql.org/learn/best-practices/#versioning). -- The GitLab GraphQL API endpoint is located at `/api/graphql`. -- Get an [introduction to GraphQL from graphql.org](https://graphql.org/). -- GitLab supports a wide range of resources, listed in the [GraphQL API Reference](reference/index.md). +## Vision + +We want the GraphQL API to be the **primary** means of interacting +programmatically with GitLab. To achieve this, it needs full coverage - anything +possible in the REST API should also be possible in the GraphQL API. -### Examples +To help us meet this vision, the frontend should use GraphQL in preference to +the REST API for new features. -To work with sample queries that pull data from public projects on GitLab.com, -see the menu options in the left-hand -documentation menu, under API > GraphQL at `https://docs.gitlab.com/ee/api/graphql/`. +There are no plans to deprecate the REST API. To reduce the technical burden of +supporting two APIs in parallel, they should share implementations as much as +possible. -The [Getting started](getting_started.md) page includes different methods to customize GraphQL queries. +## Work with GraphQL + +If you're new to the GitLab GraphQL API, see [Get started with GitLab GraphQL API](getting_started.md). + +You can view the available resources in the [GraphQL API reference](reference/index.md). +The reference is automatically generated from the GitLab GraphQL schema and +written to a Markdown file. + +The GitLab GraphQL API endpoint is located at `/api/graphql`. ### GraphiQL @@ -34,104 +49,102 @@ Explore the GraphQL API using the interactive [GraphiQL explorer](https://gitlab or on your self-managed GitLab instance on `https://<your-gitlab-site.com>/-/graphql-explorer`. -See the [GitLab GraphQL overview](getting_started.md#graphiql) for more information about the GraphiQL Explorer. +For more information, see [GraphiQL](getting_started.md#graphiql). -## What is GraphQL? +### View GraphQL examples -[GraphQL](https://graphql.org/) is a query language for APIs that -allows clients to request exactly the data they need, making it -possible to get all required data in a limited number of requests. +You can work with sample queries that pull data from public projects on GitLab.com: -The GraphQL data (fields) can be described in the form of types, -allowing clients to use [client-side GraphQL -libraries](https://graphql.org/code/#graphql-clients) to consume the -API and avoid manual parsing. +- [Create an audit report](audit_report.md) +- [Identify issue boards](sample_issue_boards.md) +- [Query users](users_example.md) +- [Use custom emojis](custom_emoji.md) -Since there's no fixed endpoints and data model, new abilities can be -added to the API without creating [breaking changes](../../development/contributing/#breaking-changes). This allows us to -have a versionless API as described in [the GraphQL -documentation](https://graphql.org/learn/best-practices/#versioning). +The [get started](getting_started.md) page includes different methods to customize GraphQL queries. -## Vision +### Update the GraphQL API reference -We want the GraphQL API to be the **primary** means of interacting -programmatically with GitLab. To achieve this, it needs full coverage - anything -possible in the REST API should also be possible in the GraphQL API. +If you change the GraphQL schema, create a merge request to get your changes approved. +To generate the required documentation and schema, see +[Rake tasks for developers](../../development/rake_tasks.md#update-graphql-documentation-and-schema-definitions). -To help us meet this vision, the frontend should use GraphQL in preference to -the REST API for new features. - -There are no plans to deprecate the REST API. To reduce the technical burden of -supporting two APIs in parallel, they should share implementations as much as -possible. +Run the commands using the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/). ## Breaking changes -The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and -changes are made to the API in a way that maintains backwards-compatibility. +The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible. -Occasionally GitLab needs to change the GraphQL API in a way that is not backwards-compatible. -These changes include the removal or renaming of fields, arguments or other parts of the schema. +However, GitLab sometimes changes the GraphQL API in a way that is not backward-compatible. These changes are considered breaking changes, and +can include removing or renaming fields, arguments, or other parts of the schema. +When creating a breaking change, GitLab follows a [deprecation and removal process](#deprecation-and-removal-process). -In these situations, GitLab follows a [Deprecation and removal process](#deprecation-and-removal-process) -where the deprecated part of the schema is supported for a period of time before being removed. +Learn more about [breaking changes](../../development/contributing/#breaking-changes). -There are some changes which are explicitly [not considered breaking](../../development/contributing/#breaking-changes). +Fields behind a feature flag and disabled by default do not follow the deprecation and removal process, and can be removed at any time without notice. -Clients should familiarize themselves with the process to avoid breaking changes affecting their integrations. +To avoid having a breaking change affect your integrations, you should +familiarize yourself with the deprecation and removal process. WARNING: -While GitLab will make all attempts to follow the [deprecation and removal process](#deprecation-and-removal-process), -GitLab may on very rare occasions need to make immediate breaking changes to the GraphQL API to patch critical security or performance -concerns and where the deprecation process would be considered to pose significant risk. +GitLab makes all attempts to follow the [deprecation and removal process](#deprecation-and-removal-process). +On rare occasions, GitLab might make immediate breaking changes to the GraphQL +API to patch critical security or performance concerns if the deprecation +process would pose significant risk. -NOTE: -Fields behind a feature flag and disabled by default are exempt from the deprecation process, -and can be removed at any time without notice. +### Deprecation and removal process -### Deprecation and Removal process +The deprecation and removal process for the GitLab GraphQL API aligns with the wider GitLab +[deprecation process](https://about.gitlab.com/handbook/product/gitlab-the-product/#breaking-changes-deprecations-and-removing-features). -Parts of the schema marked for removal from the GitLab GraphQL API are first **deprecated** but still available -for at least six releases, and then **removed entirely**. -Removals occur at `X.0` and `X.6` releases. +Parts of the schema marked for removal from the GitLab GraphQL API are first +[deprecated](https://about.gitlab.com/handbook/product/gitlab-the-product/#deprecation) +but still available for at least six releases. They are then [removed](https://about.gitlab.com/handbook/product/gitlab-the-product/#removal) +entirely during the next `XX.0` major release. -The process is as follows: +Items are marked as deprecated in: -1. The item is marked as deprecated in the schema. It will be displayed as deprecated in the - [GraphQL API Reference](reference/index.md) and in introspection queries. -1. Removals are announced at least one release prior in the [Deprecations](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations) - section of the release post (at or prior to `X.11` and `X.5` releases). -1. Items meeting criteria are removed in `X.0` or `X.6` and added to: +- The [schema](https://spec.graphql.org/October2021/#sec--deprecated). +- The [GraphQL API reference](reference/index.md). +- The [deprecation feature removal schedule](../../update/deprecations.md), which is linked from release posts. +- Introspection queries of the GraphQL API. - - The [Removals](https://about.gitlab.com/handbook/marketing/blog/release-posts/#removals) section of the Release Post. - - The [Removed items page](removed_items.md). +NOTE: +If you use the GraphQL API, we recommend you remove the deprecated schema from your GraphQL +API calls as soon as possible to avoid experiencing breaking changes. -This gives consumers of the GraphQL API a minimum of six months to update their GraphQL queries. +The deprecation message provides an alternative for the deprecated schema item, +if applicable. -When an item is deprecated or removed, an alternative is provided if available. +#### Deprecation example -**Example:** +The following fields are deprecated in different minor releases, but both +removed in GitLab 14.0: -A field marked as deprecated in `12.7` can be used until its removal in `13.6`. +| Field deprecated in | Reason | +| ------------------- | --- | +| 12.7 | GitLab traditionally has 12 minor releases per major release. To ensure the field is available for 6 more releases, it is removed in the 14.0 major release (and not 13.0). | +| 13.6 | The removal in 14.0 allows for 6 months of availability. | ### List of removed items -View the [fields, enums, and other items we removed](removed_items.md) from the GraphQL API. +View the [list of items removed](removed_items.md) in previous releases. ## Available queries The GraphQL API includes the following queries at the root level: -1. `project` : Project information, with many of its associations such as issues and merge requests. -1. `group` : Basic group information and epics **(ULTIMATE)** are currently supported. -1. `user` : Information about a particular user. -1. `namespace` : Within a namespace it is also possible to fetch `projects`. -1. `currentUser`: Information about the currently logged in user. -1. `users`: Information about a collection of users. -1. `metaData`: Metadata about GitLab and the GraphQL API. -1. `snippets`: Snippets visible to the currently logged in user. - -New associations and root level objects are constantly being added. +Query | Description +--------------|------------ +`project` | Project information and many of its associations, such as issues and merge requests. +`group` | Basic group information and epics. +`user` | Information about a particular user. +`namespace` | The namespace and the `projects` in it. +`currentUser` | Information about the signed-in user. +`users` | Information about a collection of users. +`metaData` | Metadata about GitLab and the GraphQL API. +`snippets` | Snippets visible to the signed-in user. + +New associations and root level objects are regularly added. See the [GraphQL API Reference](reference/index.md) for up-to-date information. Root-level queries are defined in @@ -149,41 +162,33 @@ library GitLab uses on the backend. The following limits apply to the GitLab GraphQL API. -### Max page size - -By default, connections return at most `100` records ("nodes") per page, -and this limit applies to most connections in the API. Particular connections -may have different max page size limits that are higher or lower. +Limit | Default +---------------------|--------------------------------------------------------------------- +Max page size | 100 records (nodes) per page. Applies to most connections in the API. Particular connections may have different max page size limits that are higher or lower. +[Max query complexity](#max-query-complexity) | `200` for unauthenticated requests and `250` for authenticated requests. +Request timeout | 30 seconds. ### Max query complexity The GitLab GraphQL API scores the _complexity_ of a query. Generally, larger -queries will have a higher complexity score. This limit is designed to protect +queries have a higher complexity score. This limit is designed to protect the API from performing queries that could negatively impact its overall performance. -The complexity of a single query is limited to a maximum of: - -- `200` for unauthenticated requests. -- `250` for authenticated requests. +You can [query](getting_started.md#query-complexity) the complexity score of a query +and the limit for the request. -The complexity score of a query and limit for the request [can be queried for](getting_started.md#query-complexity). +If a query exceeds the complexity limit, an error message response is +returned. -If a query exceeds the complexity limit an error message response will -be returned. - -In general, each field in a query will add `1` to the complexity score, although -this can be higher or lower for particular fields. Sometimes the addition of +In general, each field in a query adds `1` to the complexity score, although +this can be higher or lower for particular fields. Sometimes, adding certain arguments may also increase the complexity of a query. NOTE: The complexity limits may be revised in future, and additionally, the complexity of a query may be altered. -### Request timeout - -Requests time out at 30 seconds. - -### Spam +## Spam GraphQL mutations can be detected as spam. If this happens, a [GraphQL top-level error](https://spec.graphql.org/June2018/#sec-Errors) is raised. For example: @@ -208,11 +213,11 @@ GraphQL mutations can be detected as spam. If this happens, a } ``` -If mutation is detected as potential spam and a CAPTCHA service is configured: +If a mutation is detected as potential spam and a CAPTCHA service is configured: -- The `captchaSiteKey` should be used to obtain a CAPTCHA response value using the appropriate CAPTCHA API. +- Use the `captchaSiteKey` to obtain a CAPTCHA response value using the appropriate CAPTCHA API. Only [Google reCAPTCHA v2](https://developers.google.com/recaptcha/docs/display) is supported. -- The request can be resubmitted with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set. +- Resubmit the request with the `X-GitLab-Captcha-Response` and `X-GitLab-Spam-Log-Id` headers set. ```json { @@ -235,17 +240,3 @@ If mutation is detected as potential spam and a CAPTCHA service is configured: } } ``` - -## Reference - -The GitLab GraphQL reference [is available](reference/index.md). - -It is automatically generated from the GitLab GraphQL schema and embedded in a Markdown file. - -## Generate updates for documentation - -If you've changed the GraphQL schema, you should set up an MR to gain approval of your changes. -To generate the required documentation and schema, follow the instructions given in the -[Rake tasks for developers](../../development/rake_tasks.md#update-graphql-documentation-and-schema-definitions) page. - -Be sure to run these commands using the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit/). diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 905b6d418a9..123e65162d8 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -370,6 +370,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="queryrunnersactive"></a>`active` | [`Boolean`](#boolean) | Filter runners by active (true) or paused (false) status. | | <a id="queryrunnerssearch"></a>`search` | [`String`](#string) | Filter by full token or partial text in description field. | | <a id="queryrunnerssort"></a>`sort` | [`CiRunnerSort`](#cirunnersort) | Sort order of results. | | <a id="queryrunnersstatus"></a>`status` | [`CiRunnerStatus`](#cirunnerstatus) | Filter runners by status. | @@ -397,6 +398,16 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="querysnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | Type of snippet. | | <a id="querysnippetsvisibility"></a>`visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | +### `Query.subscriptionFutureEntries` + +Fields related to entries in future subscriptions. + +Returns [`SubscriptionFutureEntryConnection`](#subscriptionfutureentryconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + ### `Query.timelogs` Find timelogs visible to the current user. @@ -500,6 +511,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="queryvulnerabilitiesclusteragentid"></a>`clusterAgentId` | [`[ClustersAgentID!]`](#clustersagentid) | Filter vulnerabilities by `cluster_agent_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="queryvulnerabilitiesclusterid"></a>`clusterId` | [`[ClustersClusterID!]`](#clustersclusterid) | Filter vulnerabilities by `cluster_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="queryvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="queryvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | @@ -676,9 +688,9 @@ Input type: `ApiFuzzingCiConfigurationCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationapifuzzingciconfigurationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationapifuzzingciconfigurationcreateconfigurationyaml"></a>`configurationYaml` | [`String`](#string) | A YAML snippet that can be inserted into the project's `.gitlab-ci.yml` to set up API fuzzing scans. | +| <a id="mutationapifuzzingciconfigurationcreateconfigurationyaml"></a>`configurationYaml` **{warning-solid}** | [`String`](#string) | **Deprecated:** The configuration snippet is now generated client-side. Deprecated in 14.6. | | <a id="mutationapifuzzingciconfigurationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationapifuzzingciconfigurationcreategitlabciyamleditpath"></a>`gitlabCiYamlEditPath` | [`String`](#string) | Location at which the project's `.gitlab-ci.yml` file can be edited in the browser. | +| <a id="mutationapifuzzingciconfigurationcreategitlabciyamleditpath"></a>`gitlabCiYamlEditPath` **{warning-solid}** | [`String`](#string) | **Deprecated:** The configuration snippet is now generated client-side. Deprecated in 14.6. | ### `Mutation.awardEmojiAdd` @@ -2846,7 +2858,7 @@ Input type: `IssueSetCrmContactsInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationissuesetcrmcontactsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationissuesetcrmcontactscrmcontactids"></a>`crmContactIds` | [`[CustomerRelationsContactID!]!`](#customerrelationscontactid) | Customer relations contact IDs to set. Replaces existing contacts by default. | +| <a id="mutationissuesetcrmcontactscontactids"></a>`contactIds` | [`[CustomerRelationsContactID!]!`](#customerrelationscontactid) | Customer relations contact IDs to set. Replaces existing contacts by default. | | <a id="mutationissuesetcrmcontactsiid"></a>`iid` | [`String!`](#string) | IID of the issue to mutate. | | <a id="mutationissuesetcrmcontactsoperationmode"></a>`operationMode` | [`MutationOperationMode`](#mutationoperationmode) | Changes the operation mode. Defaults to REPLACE. | | <a id="mutationissuesetcrmcontactsprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | @@ -3757,7 +3769,7 @@ Input type: `ProjectSetComplianceFrameworkInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationprojectsetcomplianceframeworkclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationprojectsetcomplianceframeworkcomplianceframeworkid"></a>`complianceFrameworkId` | [`ComplianceManagementFrameworkID`](#compliancemanagementframeworkid) | ID of the compliance framework to assign to the project. | +| <a id="mutationprojectsetcomplianceframeworkcomplianceframeworkid"></a>`complianceFrameworkId` | [`ComplianceManagementFrameworkID`](#compliancemanagementframeworkid) | ID of the compliance framework to assign to the project. Set to `null` to unset. | | <a id="mutationprojectsetcomplianceframeworkprojectid"></a>`projectId` | [`ProjectID!`](#projectid) | ID of the project to change the compliance framework of. | #### Fields @@ -5457,6 +5469,30 @@ The edge type for [`CiStage`](#cistage). | <a id="cistageedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="cistageedgenode"></a>`node` | [`CiStage`](#cistage) | The item at the end of the edge. | +#### `ClusterAgentActivityEventConnection` + +The connection type for [`ClusterAgentActivityEvent`](#clusteragentactivityevent). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="clusteragentactivityeventconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | +| <a id="clusteragentactivityeventconnectionedges"></a>`edges` | [`[ClusterAgentActivityEventEdge]`](#clusteragentactivityeventedge) | A list of edges. | +| <a id="clusteragentactivityeventconnectionnodes"></a>`nodes` | [`[ClusterAgentActivityEvent]`](#clusteragentactivityevent) | A list of nodes. | +| <a id="clusteragentactivityeventconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ClusterAgentActivityEventEdge` + +The edge type for [`ClusterAgentActivityEvent`](#clusteragentactivityevent). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="clusteragentactivityeventedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="clusteragentactivityeventedgenode"></a>`node` | [`ClusterAgentActivityEvent`](#clusteragentactivityevent) | The item at the end of the edge. | + #### `ClusterAgentConnection` The connection type for [`ClusterAgent`](#clusteragent). @@ -5767,6 +5803,7 @@ The connection type for [`DastProfile`](#dastprofile). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="dastprofileconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="dastprofileconnectionedges"></a>`edges` | [`[DastProfileEdge]`](#dastprofileedge) | A list of edges. | | <a id="dastprofileconnectionnodes"></a>`nodes` | [`[DastProfile]`](#dastprofile) | A list of nodes. | | <a id="dastprofileconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -6476,6 +6513,29 @@ The edge type for [`JiraProject`](#jiraproject). | <a id="jiraprojectedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="jiraprojectedgenode"></a>`node` | [`JiraProject`](#jiraproject) | The item at the end of the edge. | +#### `JobNeedUnionConnection` + +The connection type for [`JobNeedUnion`](#jobneedunion). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="jobneedunionconnectionedges"></a>`edges` | [`[JobNeedUnionEdge]`](#jobneedunionedge) | A list of edges. | +| <a id="jobneedunionconnectionnodes"></a>`nodes` | [`[JobNeedUnion]`](#jobneedunion) | A list of nodes. | +| <a id="jobneedunionconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `JobNeedUnionEdge` + +The edge type for [`JobNeedUnion`](#jobneedunion). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="jobneedunionedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="jobneedunionedgenode"></a>`node` | [`JobNeedUnion`](#jobneedunion) | The item at the end of the edge. | + #### `LabelConnection` The connection type for [`Label`](#label). @@ -7540,6 +7600,29 @@ The edge type for [`Submodule`](#submodule). | <a id="submoduleedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="submoduleedgenode"></a>`node` | [`Submodule`](#submodule) | The item at the end of the edge. | +#### `SubscriptionFutureEntryConnection` + +The connection type for [`SubscriptionFutureEntry`](#subscriptionfutureentry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="subscriptionfutureentryconnectionedges"></a>`edges` | [`[SubscriptionFutureEntryEdge]`](#subscriptionfutureentryedge) | A list of edges. | +| <a id="subscriptionfutureentryconnectionnodes"></a>`nodes` | [`[SubscriptionFutureEntry]`](#subscriptionfutureentry) | A list of nodes. | +| <a id="subscriptionfutureentryconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `SubscriptionFutureEntryEdge` + +The edge type for [`SubscriptionFutureEntry`](#subscriptionfutureentry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="subscriptionfutureentryedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="subscriptionfutureentryedgenode"></a>`node` | [`SubscriptionFutureEntry`](#subscriptionfutureentry) | The item at the end of the edge. | + #### `TerraformStateConnection` The connection type for [`TerraformState`](#terraformstate). @@ -8339,6 +8422,7 @@ Represents an epic on an issue board. | <a id="boardepicdownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the epic has received. | | <a id="boardepicduedate"></a>`dueDate` | [`Time`](#time) | Due date of the epic. | | <a id="boardepicduedatefixed"></a>`dueDateFixed` | [`Time`](#time) | Fixed due date of the epic. | +| <a id="boardepicduedatefrominheritedsource"></a>`dueDateFromInheritedSource` | [`Time`](#time) | Inherited due date of the epic from child epics or milestones. | | <a id="boardepicduedatefrommilestones"></a>`dueDateFromMilestones` | [`Time`](#time) | Inherited due date of the epic from milestones. | | <a id="boardepicduedateisfixed"></a>`dueDateIsFixed` | [`Boolean`](#boolean) | Indicates if the due date has been manually set. | | <a id="boardepicevents"></a>`events` | [`EventConnection`](#eventconnection) | List of events associated with the object. (see [Connections](#connections)) | @@ -8358,6 +8442,7 @@ Represents an epic on an issue board. | <a id="boardepicrelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the epic in the epic tree. | | <a id="boardepicstartdate"></a>`startDate` | [`Time`](#time) | Start date of the epic. | | <a id="boardepicstartdatefixed"></a>`startDateFixed` | [`Time`](#time) | Fixed start date of the epic. | +| <a id="boardepicstartdatefrominheritedsource"></a>`startDateFromInheritedSource` | [`Time`](#time) | Inherited start date of the epic from child epics or milestones. | | <a id="boardepicstartdatefrommilestones"></a>`startDateFromMilestones` | [`Time`](#time) | Inherited start date of the epic from milestones. | | <a id="boardepicstartdateisfixed"></a>`startDateIsFixed` | [`Boolean`](#boolean) | Indicates if the start date has been manually set. | | <a id="boardepicstate"></a>`state` | [`EpicState!`](#epicstate) | State of the epic. | @@ -8557,7 +8642,7 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="cibuildneedid"></a>`id` | [`ID!`](#id) | ID of the job we need to complete. | +| <a id="cibuildneedid"></a>`id` | [`ID!`](#id) | ID of the BuildNeed. | | <a id="cibuildneedname"></a>`name` | [`String`](#string) | Name of the job we need to complete. | ### `CiConfig` @@ -8661,6 +8746,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="cijobneeds"></a>`needs` | [`CiBuildNeedConnection`](#cibuildneedconnection) | References to builds that must complete before the jobs run. (see [Connections](#connections)) | | <a id="cijobpipeline"></a>`pipeline` | [`Pipeline`](#pipeline) | Pipeline the job belongs to. | | <a id="cijobplayable"></a>`playable` | [`Boolean!`](#boolean) | Indicates the job can be played. | +| <a id="cijobpreviousstagejobsorneeds"></a>`previousStageJobsOrNeeds` | [`JobNeedUnionConnection`](#jobneedunionconnection) | Jobs that must complete before the job runs. Returns `BuildNeed`, which is the needed jobs if the job uses the `needs` keyword, or the previous stage jobs otherwise. (see [Connections](#connections)) | | <a id="cijobqueuedat"></a>`queuedAt` | [`Time`](#time) | When the job was enqueued and marked as pending. | | <a id="cijobqueuedduration"></a>`queuedDuration` | [`Duration`](#duration) | How long the job was enqueued before starting. | | <a id="cijobrefname"></a>`refName` | [`String`](#string) | Ref name of the job. | @@ -8723,7 +8809,7 @@ Represents the total number of issues and their weights for a particular day. | ---- | ---- | ----------- | | <a id="cirunneraccesslevel"></a>`accessLevel` | [`CiRunnerAccessLevel!`](#cirunneraccesslevel) | Access level of the runner. | | <a id="cirunneractive"></a>`active` | [`Boolean!`](#boolean) | Indicates the runner is allowed to receive jobs. | -| <a id="cirunneradminurl"></a>`adminUrl` | [`String`](#string) | Admin URL of the runner. Only available for adminstrators. | +| <a id="cirunneradminurl"></a>`adminUrl` | [`String`](#string) | Admin URL of the runner. Only available for administrators. | | <a id="cirunnercontactedat"></a>`contactedAt` | [`Time`](#time) | Last contact from the runner. | | <a id="cirunnerdescription"></a>`description` | [`String`](#string) | Description of the runner. | | <a id="cirunnerid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner. | @@ -8738,11 +8824,24 @@ Represents the total number of issues and their weights for a particular day. | <a id="cirunnerrununtagged"></a>`runUntagged` | [`Boolean!`](#boolean) | Indicates the runner is able to run untagged jobs. | | <a id="cirunnerrunnertype"></a>`runnerType` | [`CiRunnerType!`](#cirunnertype) | Type of the runner. | | <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="cirunnerstatus"></a>`status` | [`CiRunnerStatus!`](#cirunnerstatus) | Status of the runner. | | <a id="cirunnertaglist"></a>`tagList` | [`[String!]`](#string) | Tags associated with the runner. | | <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. | +#### Fields with arguments + +##### `CiRunner.status` + +Status of the runner. + +Returns [`CiRunnerStatus!`](#cirunnerstatus). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cirunnerstatuslegacymode"></a>`legacyMode` **{warning-solid}** | [`String`](#string) | **Deprecated** in 14.6. Will be removed in 15.0. From that release onward, the field will behave as if legacyMode is null. | + ### `CiStage` #### Fields @@ -8773,6 +8872,7 @@ GitLab CI/CD configuration template. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="clusteragentactivityevents"></a>`activityEvents` | [`ClusterAgentActivityEventConnection`](#clusteragentactivityeventconnection) | Recent activity for the cluster agent. (see [Connections](#connections)) | | <a id="clusteragentconnections"></a>`connections` | [`ConnectedAgentConnection`](#connectedagentconnection) | Active connections for the cluster agent. (see [Connections](#connections)) | | <a id="clusteragentcreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp the cluster agent was created. | | <a id="clusteragentcreatedbyuser"></a>`createdByUser` | [`UserCore`](#usercore) | User object, containing information about the person who created the agent. | @@ -8783,6 +8883,18 @@ GitLab CI/CD configuration template. | <a id="clusteragentupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp the cluster agent was updated. | | <a id="clusteragentwebpath"></a>`webPath` | [`String`](#string) | Web path of the cluster agent. | +### `ClusterAgentActivityEvent` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="clusteragentactivityeventagenttoken"></a>`agentToken` | [`ClusterAgentToken`](#clusteragenttoken) | Agent token associated with the event. | +| <a id="clusteragentactivityeventkind"></a>`kind` | [`String`](#string) | Type of event. | +| <a id="clusteragentactivityeventlevel"></a>`level` | [`String`](#string) | Severity of the event. | +| <a id="clusteragentactivityeventrecordedat"></a>`recordedAt` | [`Time`](#time) | Timestamp the event was recorded. | +| <a id="clusteragentactivityeventuser"></a>`user` | [`UserCore`](#usercore) | User associated with the event. | + ### `ClusterAgentToken` #### Fields @@ -9008,10 +9120,28 @@ Details of a 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. | | <a id="containerrepositorydetailsstatus"></a>`status` | [`ContainerRepositoryStatus`](#containerrepositorystatus) | Status of the container repository. | -| <a id="containerrepositorydetailstags"></a>`tags` | [`ContainerRepositoryTagConnection`](#containerrepositorytagconnection) | Tags of the container repository. (see [Connections](#connections)) | | <a id="containerrepositorydetailstagscount"></a>`tagsCount` | [`Int!`](#int) | Number of tags associated with this image. | | <a id="containerrepositorydetailsupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp when the container repository was updated. | +#### Fields with arguments + +##### `ContainerRepositoryDetails.tags` + +Tags of the container repository. + +Returns [`ContainerRepositoryTagConnection`](#containerrepositorytagconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="containerrepositorydetailstagsname"></a>`name` | [`String`](#string) | Search by tag name. | +| <a id="containerrepositorydetailstagssort"></a>`sort` | [`ContainerRepositoryTagSort`](#containerrepositorytagsort) | Sort tags by these criteria. | + ### `ContainerRepositoryTag` A tag from a container repository. @@ -9765,6 +9895,7 @@ Represents an epic. | <a id="epicdownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the epic has received. | | <a id="epicduedate"></a>`dueDate` | [`Time`](#time) | Due date of the epic. | | <a id="epicduedatefixed"></a>`dueDateFixed` | [`Time`](#time) | Fixed due date of the epic. | +| <a id="epicduedatefrominheritedsource"></a>`dueDateFromInheritedSource` | [`Time`](#time) | Inherited due date of the epic from child epics or milestones. | | <a id="epicduedatefrommilestones"></a>`dueDateFromMilestones` | [`Time`](#time) | Inherited due date of the epic from milestones. | | <a id="epicduedateisfixed"></a>`dueDateIsFixed` | [`Boolean`](#boolean) | Indicates if the due date has been manually set. | | <a id="epicevents"></a>`events` | [`EventConnection`](#eventconnection) | List of events associated with the object. (see [Connections](#connections)) | @@ -9784,6 +9915,7 @@ Represents an epic. | <a id="epicrelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the epic in the epic tree. | | <a id="epicstartdate"></a>`startDate` | [`Time`](#time) | Start date of the epic. | | <a id="epicstartdatefixed"></a>`startDateFixed` | [`Time`](#time) | Fixed start date of the epic. | +| <a id="epicstartdatefrominheritedsource"></a>`startDateFromInheritedSource` | [`Time`](#time) | Inherited start date of the epic from child epics or milestones. | | <a id="epicstartdatefrommilestones"></a>`startDateFromMilestones` | [`Time`](#time) | Inherited start date of the epic from milestones. | | <a id="epicstartdateisfixed"></a>`startDateIsFixed` | [`Boolean`](#boolean) | Indicates if the start date has been manually set. | | <a id="epicstate"></a>`state` | [`EpicState!`](#epicstate) | State of the epic. | @@ -10843,6 +10975,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="grouprunnersactive"></a>`active` | [`Boolean`](#boolean) | Filter runners by active (true) or paused (false) status. | | <a id="grouprunnersmembership"></a>`membership` | [`RunnerMembershipFilter`](#runnermembershipfilter) | Control which runners to include in the results. | | <a id="grouprunnerssearch"></a>`search` | [`String`](#string) | Filter by full token or partial text in description field. | | <a id="grouprunnerssort"></a>`sort` | [`CiRunnerSort`](#cirunnersort) | Sort order of results. | @@ -10886,6 +11019,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="groupvulnerabilitiesclusteragentid"></a>`clusterAgentId` | [`[ClustersAgentID!]`](#clustersagentid) | Filter vulnerabilities by `cluster_agent_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="groupvulnerabilitiesclusterid"></a>`clusterId` | [`[ClustersClusterID!]`](#clustersclusterid) | Filter vulnerabilities by `cluster_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="groupvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="groupvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | @@ -12388,7 +12522,7 @@ Represents a package in the Package Registry. Note that this type is in beta and | <a id="packagemetadata"></a>`metadata` | [`PackageMetadata`](#packagemetadata) | Package metadata. | | <a id="packagename"></a>`name` | [`String!`](#string) | Name of the package. | | <a id="packagepackagetype"></a>`packageType` | [`PackageTypeEnum!`](#packagetypeenum) | Package type. | -| <a id="packagepipelines"></a>`pipelines` | [`PipelineConnection`](#pipelineconnection) | Pipelines that built the package. (see [Connections](#connections)) | +| <a id="packagepipelines"></a>`pipelines` **{warning-solid}** | [`PipelineConnection`](#pipelineconnection) | **Deprecated** in 14.6. Due to scalability concerns, this field is going to be removed. | | <a id="packageproject"></a>`project` | [`Project!`](#project) | Project where the package is stored. | | <a id="packagestatus"></a>`status` | [`PackageStatus!`](#packagestatus) | Package status. | | <a id="packagetags"></a>`tags` | [`PackageTagConnection`](#packagetagconnection) | Package tags. (see [Connections](#connections)) | @@ -12450,7 +12584,7 @@ Represents a package details in the Package Registry. Note that this type is in | <a id="packagedetailstypename"></a>`name` | [`String!`](#string) | Name of the package. | | <a id="packagedetailstypepackagefiles"></a>`packageFiles` | [`PackageFileConnection`](#packagefileconnection) | Package files. (see [Connections](#connections)) | | <a id="packagedetailstypepackagetype"></a>`packageType` | [`PackageTypeEnum!`](#packagetypeenum) | Package type. | -| <a id="packagedetailstypepipelines"></a>`pipelines` | [`PipelineConnection`](#pipelineconnection) | Pipelines that built the package. (see [Connections](#connections)) | +| <a id="packagedetailstypepipelines"></a>`pipelines` **{warning-solid}** | [`PipelineConnection`](#pipelineconnection) | **Deprecated** in 14.6. Due to scalability concerns, this field is going to be removed. | | <a id="packagedetailstypeproject"></a>`project` | [`Project!`](#project) | Project where the package is stored. | | <a id="packagedetailstypestatus"></a>`status` | [`PackageStatus!`](#packagestatus) | Package status. | | <a id="packagedetailstypetags"></a>`tags` | [`PackageTagConnection`](#packagetagconnection) | Package tags. (see [Connections](#connections)) | @@ -12862,6 +12996,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectservicedeskenabled"></a>`serviceDeskEnabled` | [`Boolean`](#boolean) | Indicates if the project has service desk enabled. | | <a id="projectsharedrunnersenabled"></a>`sharedRunnersEnabled` | [`Boolean`](#boolean) | Indicates if shared runners are enabled for the project. | | <a id="projectsnippetsenabled"></a>`snippetsEnabled` | [`Boolean`](#boolean) | Indicates if Snippets are enabled for the current user. | +| <a id="projectsquashcommittemplate"></a>`squashCommitTemplate` | [`String`](#string) | Template used to create squash commit message in merge requests. | | <a id="projectsquashreadonly"></a>`squashReadOnly` | [`Boolean!`](#boolean) | Indicates if `squashReadOnly` is enabled. | | <a id="projectsshurltorepo"></a>`sshUrlToRepo` | [`String`](#string) | URL to connect to the project via SSH. | | <a id="projectstarcount"></a>`starCount` | [`Int!`](#int) | Number of times the project has been starred. | @@ -13602,7 +13737,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectscanexecutionpoliciesactionscantypes"></a>`actionScanTypes` | [`[SecurityReportTypeEnum!]`](#securityreporttypeenum) | Filters policies by the action scan type. Only these scan types are supported: `dast`, `secret_detection`, `cluster_image_scanning`, `container_scanning`. | +| <a id="projectscanexecutionpoliciesactionscantypes"></a>`actionScanTypes` | [`[SecurityReportTypeEnum!]`](#securityreporttypeenum) | Filters policies by the action scan type. Only these scan types are supported: `dast`, `secret_detection`, `cluster_image_scanning`, `container_scanning`, `sast`. | ##### `Project.sentryDetailedError` @@ -13698,6 +13833,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="projectvulnerabilitiesclusteragentid"></a>`clusterAgentId` | [`[ClustersAgentID!]`](#clustersagentid) | Filter vulnerabilities by `cluster_agent_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="projectvulnerabilitiesclusterid"></a>`clusterId` | [`[ClustersClusterID!]`](#clustersclusterid) | Filter vulnerabilities by `cluster_id`. Vulnerabilities with a `reportType` of `cluster_image_scanning` are only included with this filter. | | <a id="projectvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="projectvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | @@ -14066,7 +14202,9 @@ Returns [`Tree`](#tree). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="repositoryblobcancurrentuserpushtobranch"></a>`canCurrentUserPushToBranch` | [`Boolean`](#boolean) | Whether the current user can push to the branch. | | <a id="repositoryblobcanmodifyblob"></a>`canModifyBlob` | [`Boolean`](#boolean) | Whether the current user can modify the blob. | +| <a id="repositoryblobcodeowners"></a>`codeOwners` | [`[UserCore!]`](#usercore) | List of code owners for the blob. | | <a id="repositoryblobeditblobpath"></a>`editBlobPath` | [`String`](#string) | Web path to edit the blob in the old-style editor. | | <a id="repositoryblobexternalstorageurl"></a>`externalStorageUrl` | [`String`](#string) | Web path to download the raw blob via external storage, if enabled. | | <a id="repositoryblobfiletype"></a>`fileType` | [`String`](#string) | Expected format of the blob based on the extension. | @@ -14660,6 +14798,23 @@ Represents the Geo sync and verification state of a snippet repository. | <a id="submoduletype"></a>`type` | [`EntryType!`](#entrytype) | Type of tree entry. | | <a id="submoduleweburl"></a>`webUrl` | [`String`](#string) | Web URL for the sub-module. | +### `SubscriptionFutureEntry` + +Represents an entry from the future subscriptions. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="subscriptionfutureentrycompany"></a>`company` | [`String`](#string) | Company of the licensee. | +| <a id="subscriptionfutureentryemail"></a>`email` | [`String`](#string) | Email of the licensee. | +| <a id="subscriptionfutureentryexpiresat"></a>`expiresAt` | [`Date`](#date) | Date when the license expires. | +| <a id="subscriptionfutureentryname"></a>`name` | [`String`](#string) | Name of the licensee. | +| <a id="subscriptionfutureentryplan"></a>`plan` | [`String!`](#string) | Name of the subscription plan. | +| <a id="subscriptionfutureentrystartsat"></a>`startsAt` | [`Date`](#date) | Date when the license started. | +| <a id="subscriptionfutureentrytype"></a>`type` | [`String!`](#string) | Type of license the subscription will yield. | +| <a id="subscriptionfutureentryusersinlicensecount"></a>`usersInLicenseCount` | [`Int`](#int) | Number of paid user seats. | + ### `TaskCompletionStatus` Completion status of tasks. @@ -15235,6 +15390,7 @@ Represents a vulnerability. | <a id="vulnerabilityconfirmedat"></a>`confirmedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to confirmed. | | <a id="vulnerabilityconfirmedby"></a>`confirmedBy` | [`UserCore`](#usercore) | User that confirmed the vulnerability. | | <a id="vulnerabilitydescription"></a>`description` | [`String`](#string) | Description of the vulnerability. | +| <a id="vulnerabilitydescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | | <a id="vulnerabilitydetails"></a>`details` | [`[VulnerabilityDetail!]!`](#vulnerabilitydetail) | Details of the vulnerability. | | <a id="vulnerabilitydetectedat"></a>`detectedAt` | [`Time!`](#time) | Timestamp of when the vulnerability was first detected. | | <a id="vulnerabilitydiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | @@ -15505,6 +15661,19 @@ Represents a link related to a vulnerability. | <a id="vulnerabilitylinkname"></a>`name` | [`String`](#string) | Name of the link. | | <a id="vulnerabilitylinkurl"></a>`url` | [`String!`](#string) | URL of the link. | +### `VulnerabilityLocationClusterImageScanning` + +Represents the location of a vulnerability found by a cluster image scan. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerabilitylocationclusterimagescanningdependency"></a>`dependency` | [`VulnerableDependency`](#vulnerabledependency) | Dependency containing the vulnerability. | +| <a id="vulnerabilitylocationclusterimagescanningimage"></a>`image` | [`String`](#string) | Name of the vulnerable container image. | +| <a id="vulnerabilitylocationclusterimagescanningkubernetesresource"></a>`kubernetesResource` | [`VulnerableKubernetesResource`](#vulnerablekubernetesresource) | Kubernetes resource which uses the vulnerable container image. | +| <a id="vulnerabilitylocationclusterimagescanningoperatingsystem"></a>`operatingSystem` | [`String`](#string) | Operating system that runs on the vulnerable container image. | + ### `VulnerabilityLocationContainerScanning` Represents the location of a vulnerability found by a container security scan. @@ -15655,6 +15824,21 @@ Represents a vulnerable dependency. Used in vulnerability location data. | <a id="vulnerabledependencypackage"></a>`package` | [`VulnerablePackage`](#vulnerablepackage) | Package associated with the vulnerable dependency. | | <a id="vulnerabledependencyversion"></a>`version` | [`String`](#string) | Version of the vulnerable dependency. | +### `VulnerableKubernetesResource` + +Represents a vulnerable Kubernetes resource. Used in vulnerability location data. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerablekubernetesresourceagent"></a>`agent` | [`ClusterAgent`](#clusteragent) | Kubernetes Agent which performed the scan. | +| <a id="vulnerablekubernetesresourceclusterid"></a>`clusterId` | [`ClustersClusterID`](#clustersclusterid) | ID of the Cluster integration which was used to perform the scan. | +| <a id="vulnerablekubernetesresourcecontainername"></a>`containerName` | [`String!`](#string) | Name of the container that had its image scanned. | +| <a id="vulnerablekubernetesresourcekind"></a>`kind` | [`String!`](#string) | Kind of the Kubernetes resource. | +| <a id="vulnerablekubernetesresourcename"></a>`name` | [`String!`](#string) | Name of the Kubernetes resource. | +| <a id="vulnerablekubernetesresourcenamespace"></a>`namespace` | [`String!`](#string) | Kubernetes namespace which the resource resides in. | + ### `VulnerablePackage` Represents a vulnerable package. Used in vulnerability dependency data. @@ -15894,11 +16078,13 @@ Values for sorting runners. | Value | Description | | ----- | ----------- | -| <a id="cirunnerstatusactive"></a>`ACTIVE` | A runner that is not paused. | -| <a id="cirunnerstatusnot_connected"></a>`NOT_CONNECTED` | A runner that has never contacted this instance. | -| <a id="cirunnerstatusoffline"></a>`OFFLINE` | A runner that has not contacted this instance within the last 2 hours. | -| <a id="cirunnerstatusonline"></a>`ONLINE` | A runner that contacted this instance within the last 2 hours. | -| <a id="cirunnerstatuspaused"></a>`PAUSED` | A runner that is paused. | +| <a id="cirunnerstatusactive"></a>`ACTIVE` **{warning-solid}** | **Deprecated** in 14.6. Use CiRunnerType.active instead. | +| <a id="cirunnerstatusnever_contacted"></a>`NEVER_CONTACTED` | Runner that has never contacted this instance. Set legacyMode to null to utilize this value. Will replace NOT_CONNECTED starting in 15.0. | +| <a id="cirunnerstatusnot_connected"></a>`NOT_CONNECTED` **{warning-solid}** | **Deprecated** in 14.6. Use NEVER_CONTACTED instead. NEVER_CONTACTED will have a slightly different scope starting in 15.0, with STALE being returned instead after 3 months of no contact. | +| <a id="cirunnerstatusoffline"></a>`OFFLINE` **{warning-solid}** | **Deprecated** in 14.6. This field will have a slightly different scope starting in 15.0, with STALE being returned after a certain period offline. | +| <a id="cirunnerstatusonline"></a>`ONLINE` | Runner that contacted this instance within the last 2 hours. | +| <a id="cirunnerstatuspaused"></a>`PAUSED` **{warning-solid}** | **Deprecated** in 14.6. Use CiRunnerType.active instead. | +| <a id="cirunnerstatusstale"></a>`STALE` | Runner that has not contacted this instance within the last 3 months. Only available if legacyMode is null. Will be a possible return value starting in 15.0. | ### `CiRunnerType` @@ -16014,6 +16200,15 @@ Status of a container repository. | <a id="containerrepositorystatusdelete_failed"></a>`DELETE_FAILED` | Delete Failed status. | | <a id="containerrepositorystatusdelete_scheduled"></a>`DELETE_SCHEDULED` | Delete Scheduled status. | +### `ContainerRepositoryTagSort` + +Values for sorting tags. + +| Value | Description | +| ----- | ----------- | +| <a id="containerrepositorytagsortname_asc"></a>`NAME_ASC` | Ordered by name in ascending order. | +| <a id="containerrepositorytagsortname_desc"></a>`NAME_DESC` | Ordered by name in descending order. | + ### `DastProfileCadenceUnit` Unit for the duration of Dast Profile Cadence. @@ -17021,7 +17216,6 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumcanary_deployment"></a>`CANARY_DEPLOYMENT` | Callout feature name for canary_deployment. | | <a id="usercalloutfeaturenameenumcloud_licensing_subscription_activation_banner"></a>`CLOUD_LICENSING_SUBSCRIPTION_ACTIVATION_BANNER` | Callout feature name for cloud_licensing_subscription_activation_banner. | | <a id="usercalloutfeaturenameenumcluster_security_warning"></a>`CLUSTER_SECURITY_WARNING` | Callout feature name for cluster_security_warning. | -| <a id="usercalloutfeaturenameenumcustomize_homepage"></a>`CUSTOMIZE_HOMEPAGE` | Callout feature name for customize_homepage. | | <a id="usercalloutfeaturenameenumeoa_bronze_plan_banner"></a>`EOA_BRONZE_PLAN_BANNER` | Callout feature name for eoa_bronze_plan_banner. | | <a id="usercalloutfeaturenameenumfeature_flags_new_version"></a>`FEATURE_FLAGS_NEW_VERSION` | Callout feature name for feature_flags_new_version. | | <a id="usercalloutfeaturenameenumgcp_signup_offer"></a>`GCP_SIGNUP_OFFER` | Callout feature name for gcp_signup_offer. | @@ -17048,6 +17242,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumtwo_factor_auth_recovery_settings_check"></a>`TWO_FACTOR_AUTH_RECOVERY_SETTINGS_CHECK` | Callout feature name for two_factor_auth_recovery_settings_check. | | <a id="usercalloutfeaturenameenumultimate_trial"></a>`ULTIMATE_TRIAL` | Callout feature name for ultimate_trial. | | <a id="usercalloutfeaturenameenumunfinished_tag_cleanup_callout"></a>`UNFINISHED_TAG_CLEANUP_CALLOUT` | Callout feature name for unfinished_tag_cleanup_callout. | +| <a id="usercalloutfeaturenameenumverification_reminder"></a>`VERIFICATION_REMINDER` | Callout feature name for verification_reminder. | | <a id="usercalloutfeaturenameenumweb_ide_alert_dismissed"></a>`WEB_IDE_ALERT_DISMISSED` | Callout feature name for web_ide_alert_dismissed. | | <a id="usercalloutfeaturenameenumweb_ide_ci_environments_guidance"></a>`WEB_IDE_CI_ENVIRONMENTS_GUIDANCE` | Callout feature name for web_ide_ci_environments_guidance. | @@ -17777,6 +17972,13 @@ One of: - [`Issue`](#issue) - [`MergeRequest`](#mergerequest) +#### `JobNeedUnion` + +One of: + +- [`CiBuildNeed`](#cibuildneed) +- [`CiJob`](#cijob) + #### `NoteableType` Represents an object that supports notes. @@ -17825,6 +18027,7 @@ Represents a vulnerability location. The fields with data will depend on the vul One of: +- [`VulnerabilityLocationClusterImageScanning`](#vulnerabilitylocationclusterimagescanning) - [`VulnerabilityLocationContainerScanning`](#vulnerabilitylocationcontainerscanning) - [`VulnerabilityLocationCoverageFuzzing`](#vulnerabilitylocationcoveragefuzzing) - [`VulnerabilityLocationDast`](#vulnerabilitylocationdast) @@ -18288,9 +18491,11 @@ Field that are available while modifying the custom mapping attributes for an HT | <a id="boardissueinputassigneeusername"></a>`assigneeUsername` | [`[String]`](#string) | Filter by assignee username. | | <a id="boardissueinputassigneewildcardid"></a>`assigneeWildcardId` | [`AssigneeWildcardId`](#assigneewildcardid) | Filter by assignee wildcard. Incompatible with assigneeUsername. | | <a id="boardissueinputauthorusername"></a>`authorUsername` | [`String`](#string) | Filter by author username. | +| <a id="boardissueinputconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter by confidentiality. | | <a id="boardissueinputepicid"></a>`epicId` | [`EpicID`](#epicid) | Filter by epic ID. Incompatible with epicWildcardId. | | <a id="boardissueinputepicwildcardid"></a>`epicWildcardId` | [`EpicWildcardId`](#epicwildcardid) | Filter by epic ID wildcard. Incompatible with epicId. | | <a id="boardissueinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example `["1", "2"]`. | +| <a id="boardissueinputiterationcadenceid"></a>`iterationCadenceId` | [`[IterationsCadenceID!]`](#iterationscadenceid) | Filter by a list of iteration cadence IDs. | | <a id="boardissueinputiterationid"></a>`iterationId` | [`[IterationID!]`](#iterationid) | Filter by a list of iteration IDs. Incompatible with iterationWildcardId. | | <a id="boardissueinputiterationtitle"></a>`iterationTitle` | [`String`](#string) | Filter by iteration title. | | <a id="boardissueinputiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | @@ -18413,6 +18618,7 @@ Input type for DastSiteProfile authentication. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="epicfiltersauthorusername"></a>`authorUsername` | [`String`](#string) | Filter by author username. | +| <a id="epicfiltersconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter by confidentiality. | | <a id="epicfilterslabelname"></a>`labelName` | [`[String]`](#string) | Filter by label name. | | <a id="epicfiltersmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="epicfiltersnot"></a>`not` | [`NegatedEpicBoardIssueInput`](#negatedepicboardissueinput) | Negated epic arguments. | diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index 0048148ab11..f70add0de45 100644 --- a/doc/api/graphql/removed_items.md +++ b/doc/api/graphql/removed_items.md @@ -1,10 +1,10 @@ --- -stage: Plan -group: Product Planning +stage: Ecosystem +group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GraphQL API removed items +# GraphQL API removed items **(FREE)** GraphQL is a versionless API, unlike the REST API. Occasionally, items have to be updated or removed from the GraphQL API. @@ -38,6 +38,8 @@ Fields [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63293) in ## GitLab 13.6 +Prior to GitLab 14.0, deprecated items could be removed in `XX.6` releases. + Fields [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44866) in GitLab 13.6: | Field name | GraphQL type | Deprecated in | Use instead | diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 212a62516f1..dbdc2c3669e 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -4,7 +4,7 @@ group: Import 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 Import/Export API **(FREE)** +# Group import/export API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20353) in GitLab 12.8. diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 04a619c8fa9..96b8a162e34 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -77,7 +77,7 @@ GET /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | @@ -152,7 +152,7 @@ PUT /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `new_name` | string | no | The new name of the label | | `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | @@ -193,7 +193,7 @@ DELETE /groups/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -214,7 +214,7 @@ POST /groups/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -250,7 +250,7 @@ POST /groups/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell diff --git a/doc/api/groups.md b/doc/api/groups.md index 5faa63585c1..13dea42f3c6 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -275,24 +275,24 @@ GET /groups/:id/projects 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 | -| `archived` | boolean | no | Limit by archived status | -| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | -| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity` (1), or `last_activity_at` fields. Default is `created_at` | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Return list of authorized projects matching the search criteria | -| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | -| `owned` | boolean | no | Limit by projects owned by the current user | -| `starred` | boolean | no | Limit by projects starred by the current user | -| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | -| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | -| `with_shared` | boolean | no | Include projects shared to this group. Default is `true` | -| `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` | -| `min_access_level` | integer | no | Limit to projects where current user has at least this [access level](members.md#valid-access-levels) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | -| `with_security_reports` | boolean | no | **(ULTIMATE)** Return only projects that have security reports artifacts present in any of their builds. This means "projects with security reports enabled". Default is `false` | +| 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 | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity` (1), or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of authorized projects matching the search criteria | +| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | +| `owned` | boolean | no | Limit by projects owned by the current user | +| `starred` | boolean | no | Limit by projects starred by the current user | +| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | +| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | +| `with_shared` | boolean | no | Include projects shared to this group. Default is `true` | +| `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` | +| `min_access_level` | integer | no | Limit to projects where current user has at least this [access level](members.md#valid-access-levels) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | +| `with_security_reports` **(ULTIMATE)** | boolean | no | Return only projects that have security reports artifacts present in any of their builds. This means "projects with security reports enabled". Default is `false` | 1. Order by similarity: Orders the results by a similarity score calculated from the provided `search` URL parameter. When using `order_by=similarity`, the `sort` parameter is ignored. When the `search` @@ -783,38 +783,38 @@ POST /groups Parameters: -| Attribute | Type | Required | Description | -| ------------------------------------ | ------- | -------- | ----------- | -| `name` | string | yes | The name of the group. | -| `path` | string | yes | The path of the group. | -| `description` | string | no | The group's description. | -| `membership_lock` | boolean | no | **(PREMIUM)** Prevent adding new members to project membership within this group. | -| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | -| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | -| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | -| `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` (Maintainers), or `developer` (Developers + Maintainers). | -| `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#creating-a-subgroup). Can be `owner` (Owners), or `maintainer` (Maintainers). | -| `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` | 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. | -| `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` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| Attribute | Type | Required | Description | +| ------------------------------------------------------- | ------- | -------- | ----------- | +| `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#creating-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` | 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. | +| `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 SELF)** | integer | no | Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | +| `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | ### Options for `default_branch_protection` -The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table: +The `default_branch_protection` attribute determines whether users with the Developer or [Maintainer role](../user/permissions.md) can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table: | Value | Description | |-------|-------------------------------------------------------------------------------------------------------------| -| `0` | No protection. Developers and maintainers can: <br>- Push new commits<br>- Force push changes<br>- Delete the branch | -| `1` | Partial protection. Developers and maintainers can: <br>- Push new commits | -| `2` | Full protection. Only maintainers can: <br>- Push new commits | +| `0` | No protection. Users with the Developer or Maintainer role can: <br>- Push new commits<br>- Force push changes<br>- Delete the branch | +| `1` | Partial protection. Users with the Developer or Maintainer role can: <br>- Push new commits | +| `2` | Full protection. Only users with the Maintainer role can: <br>- Push new commits | ## New Subgroup @@ -850,6 +850,32 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/groups/4/projects/56" ``` +## Transfer a group to a new parent group / Turn a subgroup to a top-level group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23831) in GitLab 14.6. + +Transfer a group to a new parent group or turn a subgroup to a top-level group. Available to administrators and users: + +- With the Owner role for the group to transfer. +- With permission to [create a subgroup](../user/group/subgroups/index.md#creating-a-subgroup) in the new parent group if transferring a group. +- With [permission to create a top-level group](../administration/user_settings.md#prevent-users-from-creating-top-level-groups) if turning a subgroup into a top-level group. + +```plaintext +POST /groups/:id/transfer +``` + +Parameters: + +| Attribute | Type | Required | Description | +| ------------ | -------------- | -------- | ----------- | +| `id` | integer | yes | ID of the group to transfer. | +| `group_id` | integer | no | ID of the new parent group. When not specified, the group to transfer is instead turned into a top-level group. | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/groups/4/transfer?group_id=7" +``` + ## Update group Updates the project group. Only available to group owners and administrators. @@ -858,32 +884,32 @@ Updates the project group. Only available to group owners and administrators. PUT /groups/:id ``` -| Attribute | Type | Required | Description | -| ------------------------------------------ | ------- | -------- | ----------- | -| `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` | boolean | no | **(PREMIUM)** Prevent adding new members to project membership within this group. | -| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | -| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | -| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | -| `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` (Maintainers), or `developer` (Developers + Maintainers). | -| `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#creating-a-subgroup). Can be `owner` (Owners), or `maintainer` (Maintainers). | -| `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). | -| `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from. | -| `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | -| `prevent_forking_outside_group` | boolean | no | **(PREMIUM)** 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) | +| Attribute | Type | Required | Description | +| ------------------------------------------------------- | ------- | -------- | ----------- | +| `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#creating-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). | +| `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | +| `shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | +| `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `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/import.md b/doc/api/import.md index 18c0eb04fff..1baea5d1500 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -4,7 +4,7 @@ group: Import 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 --- -# Import API +# Import API **(FREE)** ## Import repository from GitHub diff --git a/doc/api/index.md b/doc/api/index.md index 7b599b6ae0a..a4e7a893618 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -8,10 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use the GitLab APIs to automate GitLab. -You can also use a partial [OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/openapi/openapi.yaml), -to test the API directly from the GitLab user interface. -Contributions are welcome. - ## REST API A REST API is available in GitLab. @@ -19,6 +15,10 @@ Usage instructions are below. For a list of the available resources and their endpoints, see [REST API resources](api_resources.md). +You can also use a partial [OpenAPI definition](openapi/openapi_interactive.md), +to test the API directly from the GitLab user interface. +Contributions are welcome. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an introduction and basic steps, see [How to make GitLab API calls](https://www.youtube.com/watch?v=0LsMC3ZiXkA). @@ -43,11 +43,6 @@ There were some patenting and licensing concerns with GraphQL. However, these have been resolved to our satisfaction. The reference implementations were re-licensed under MIT, and the OWF license used for the GraphQL specification. -When GraphQL is fully implemented, GitLab: - -- Can delete controller-specific endpoints. -- Will no longer maintain two different APIs. - ## Compatibility guidelines The HTTP API is versioned with a single number, which is currently `4`. This number @@ -214,7 +209,7 @@ Impersonation tokens are a type of [personal access token](../user/profile/perso They can be created only by an administrator, and are used to authenticate with the API as a specific user. -Use impersonation tokens an alternative to: +Use impersonation tokens as an alternative to: - The user's password or one of their personal access tokens. - The [Sudo](#sudo) feature. The user's or administrator's password or token @@ -283,7 +278,7 @@ message with a status code of `403`: ``` If an access token without the `sudo` scope is provided, an error message is -be returned with a status code of `403`: +returned with a status code of `403`: ```json { diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index 85046388275..f29ac5cd7f2 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -97,7 +97,6 @@ Example response: ... } ] - ``` ## Get a single instance cluster @@ -184,7 +183,6 @@ curl --header "Private-Token:<your_access_token>" "http://gitlab.example.com/api -H "Accept:application/json" \ -H "Content-Type:application/json" \ -X POST --data '{"name":"cluster-3", "environment_scope":"production", "platform_kubernetes_attributes":{"api_url":"https://example.com", "token":"12345", "ca_cert":"-----BEGIN CERTIFICATE-----qpoeiXXZafCM0ZDJkZjM...-----END CERTIFICATE-----"}}' - ``` Example response: @@ -255,7 +253,6 @@ Example request: curl --header "Private-Token: <your_access_token>" "http://gitlab.example.com/api/v4/admin/clusters/9" \ -H "Content-Type:application/json" \ -X PUT --data '{"name":"update-cluster-name", "platform_kubernetes_attributes":{"api_url":"https://new-example.com","token":"new-token"}}' - ``` Example response: @@ -290,7 +287,6 @@ Example response: "management_project": null, "project": null } - ``` ## Delete instance cluster diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 80a05f8ea0d..0bf9d106404 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -42,9 +42,8 @@ POST /projects/:id/invitations | `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). | -| `areas_of_focus` | string | no | Areas the inviter wants the member to focus upon. | -| `tasks_to_be_done` | array of strings | no | Tasks the inviter wants the member to focus on. The tasks are added as issues to a specified project. The possible values are: `ci`, `code` and `issues`. If specified, requires `tasks_project_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `invite_members_for_task`. Disabled by default. | -| `tasks_project_id` | integer | no | The project ID in which to create the task issues. If specified, requires `tasks_to_be_done`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `invite_members_for_task`. Disabled by default. | +| `tasks_to_be_done` | array of strings | no | Tasks the inviter wants the member to focus on. The tasks are added as issues to a specified project. The possible values are: `ci`, `code` and `issues`. If specified, requires `tasks_project_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.6 | +| `tasks_project_id` | integer | no | The project ID in which to create the task issues. If specified, requires `tasks_to_be_done`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.6 | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index a760424f6a2..11f24d94763 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -49,7 +49,7 @@ GET /issues_statistics?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `confidential` | boolean | no | Filter confidential or public issues. | +| `confidential` | boolean | no | Filter confidential or public issues. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues_statistics" @@ -105,7 +105,7 @@ GET /groups/:id/issues_statistics?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `confidential` | boolean | no | Filter confidential or public issues. | +| `confidential` | boolean | no | Filter confidential or public issues. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/issues_statistics" @@ -161,7 +161,7 @@ GET /projects/:id/issues_statistics?confidential=true | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `confidential` | boolean | no | Filter confidential or public issues. | +| `confidential` | boolean | no | Filter confidential or public issues. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues_statistics" diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 6d8c256d5aa..7c7847bf368 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -252,6 +252,7 @@ Example response: "finished_at": "2016-01-11T10:15:10.506Z", "duration": 97.0, "status": "failed", + "failure_reason": "script_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/42", "user": null diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 2a07e2d92c5..8dcd898b8c3 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -71,6 +71,7 @@ Example of response "runner": null, "stage": "test", "status": "failed", + "failure_reason": "script_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/7", "user": { @@ -126,6 +127,7 @@ Example of response "runner": null, "stage": "test", "status": "failed", + "failure_reason": "stuck_or_timeout_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/6", "user": { @@ -207,6 +209,7 @@ Example of response "runner": null, "stage": "test", "status": "failed", + "failure_reason": "stuck_or_timeout_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/6", "user": { @@ -271,6 +274,7 @@ Example of response "runner": null, "stage": "test", "status": "failed", + "failure_reason": "script_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/7", "user": { @@ -443,6 +447,7 @@ Example of response "runner": null, "stage": "test", "status": "failed", + "failure_reason": "script_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/8", "user": { @@ -465,12 +470,12 @@ Example of response } ``` -## Get Kubernetes Agents by `CI_JOB_TOKEN` **(PREMIUM)** +## Get GitLab Agent by `CI_JOB_TOKEN` **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324269) in GitLab 13.11. -Retrieve the job that generated the `CI_JOB_TOKEN`, along with a list of allowed GitLab -Kubernetes Agents. +Retrieve the job that generated the `CI_JOB_TOKEN`, along with a list of allowed +[agents](../user/clusters/agent/index.md). ```plaintext GET /job/allowed_agents @@ -801,6 +806,10 @@ Example of response } ``` +NOTE: +You can't delete archived jobs with the API, but you can +[delete job artifacts and logs from jobs completed before a specific date](../administration/job_artifacts.md#delete-job-artifacts-and-logs-from-jobs-completed-before-a-specific-date) + ## Play a job Triggers a manual action to start a job. diff --git a/doc/api/labels.md b/doc/api/labels.md index a8cb56f1573..5de227c8e1f 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -119,7 +119,7 @@ GET /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label. | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | @@ -195,7 +195,7 @@ DELETE /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -216,7 +216,7 @@ PUT /projects/:id/labels/:label_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | | `new_name` | string | yes if `color` is not provided | The new name of the label | | `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | @@ -265,7 +265,7 @@ PUT /projects/:id/labels/:label_id/promote | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a group's label. | ```shell @@ -303,7 +303,7 @@ POST /projects/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```shell @@ -341,7 +341,7 @@ POST /projects/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```shell diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index 3967fe52a03..f2626574bf0 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.md @@ -6,6 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Managed Licenses API **(ULTIMATE)** +WARNING: +"approval" and "blacklisted" approval statuses are deprecated and scheduled to be changed to "allowed" and "denied" in GitLab 15.0. + ## List managed licenses Get all managed licenses for a given project. @@ -78,10 +81,10 @@ POST /projects/:id/managed_licenses | ------------- | ------- | -------- | ---------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the managed license | -| `approval_status` | string | yes | The approval status. "approved" or "blacklisted" | +| `approval_status` | string | yes | The approval status of the license. "allowed" or "denied". "blacklisted" and "approved" are deprecated. | ```shell -curl --data "name=MIT&approval_status=blacklisted" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses" +curl --data "name=MIT&approval_status=denied" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses" ``` Example response: @@ -125,10 +128,10 @@ PATCH /projects/:id/managed_licenses/:managed_license_id | --------------- | ------- | --------------------------------- | ------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `managed_license_id` | integer/string | yes | The ID or URL-encoded name of the license belonging to the project | -| `approval_status` | string | yes | The approval status. "approved" or "blacklisted" | +| `approval_status` | string | yes | The approval status of the license. "allowed" or "denied". "blacklisted" and "approved" are deprecated. | ```shell -curl --request PATCH --data "approval_status=blacklisted" \ +curl --request PATCH --data "approval_status=denied" \ --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/managed_licenses/6" ``` diff --git a/doc/api/members.md b/doc/api/members.md index ce276487f21..bc476980d2d 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -65,7 +65,8 @@ Example response: "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" }, { "id": 2, @@ -81,7 +82,8 @@ Example response: "extern_uid":"ABC-1234567890", "provider": "group_saml", "saml_provider_id": 10 - } + }, + "membership_state": "active" } ] ``` @@ -107,6 +109,7 @@ GET /projects/:id/members/all | `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 | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | +| `state` | string | no | Filter results by member state, one of `awaiting`, `active` or `created` **(PREMIUM)** | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/all" @@ -126,7 +129,8 @@ Example response: "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-10-22T14:13:35Z", "access_level": 30, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" }, { "id": 2, @@ -142,7 +146,8 @@ Example response: "extern_uid":"ABC-1234567890", "provider": "group_saml", "saml_provider_id": 10 - } + }, + "membership_state": "active" }, { "id": 3, @@ -153,7 +158,8 @@ Example response: "web_url": "http://192.168.1.8:3000/root", "expires_at": "2012-11-22T14:13:35Z", "access_level": 30, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" } ] ``` @@ -191,7 +197,8 @@ Example response: "email": "john@example.com", "created_at": "2012-10-22T14:13:35Z", "expires_at": null, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" } ``` @@ -229,7 +236,8 @@ Example response: "access_level": 30, "email": "john@example.com", "expires_at": null, - "group_saml_identity": null + "group_saml_identity": null, + "membership_state": "active" } ``` @@ -421,7 +429,6 @@ POST /projects/:id/members | `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). | -| `areas_of_focus` | string | no | Areas the inviter wants the member to focus upon. | | `tasks_to_be_done` | array of strings | no | Tasks the inviter wants the member to focus on. The tasks are added as issues to a specified project. The possible values are: `ci`, `code` and `issues`. If specified, requires `tasks_project_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `invite_members_for_task`. Disabled by default. | | `tasks_project_id` | integer | no | The project ID in which to create the task issues. If specified, requires `tasks_to_be_done`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69299) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `invite_members_for_task`. Disabled by default. | @@ -589,26 +596,26 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/members/:user_id" ``` -## Approve a member for a group +## Approve a member for a group -Approves a pending user for a group and its subgroups and projects. +Approves a pending user for a group and its subgroups and projects. ```plaintext -PUT /groups/:id/members/:user_id/approve +PUT /groups/:id/members/:member_id/approve ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the root group](index.md#namespaced-path-encoding) owned by the authenticated user | -| `user_id` | integer | yes | The user ID of the member | +| `member_id` | integer | yes | The ID of the member | Example request: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:user_id/approve" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/:member_id/approve" ``` -## Approve all pending members for a group +## Approve all pending members for a group Approves all pending users for a group and its subgroups and projects. @@ -626,6 +633,65 @@ Example request: curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/approve_all" ``` +## List pending members of a group and its subgroups and projects + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332596) in GitLab 14.6. + +For a group and its subgroups and projects, get a list of all members in an `awaiting` state and those who are invited but do not have a GitLab account. + +This request returns all matching group and project members from all groups and projects in the root group's hierarchy. + +When the member is an invited user that has not signed up for a GitLab account yet, the invited email address is returned. + +This API endpoint works on top-level groups only. It does not work on subgroups. + +This API endpoint requires permission to administer members for the group. + +This API endpoint takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of members. + +```plaintext +GET /groups/:id/pending_members +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/pending_members" +``` + +Example response: + +```json +[ + { + "id": 168, + "name": "Alex Garcia", + "username": "alex_garcia", + "email": "alex@example.com", + "avatar_url": "http://example.com/uploads/user/avatar/1/cd8.jpeg", + "web_url": "http://example.com/alex_garcia", + "approved": false, + "invited": false + }, + { + "id": 169, + "email": "sidney@example.com", + "avatar_url": "http://gravatar.com/../e346561cd8.jpeg", + "approved": false, + "invited": true + }, + { + "id": 170, + "email": "zhang@example.com", + "avatar_url": "http://gravatar.com/../e32131cd8.jpeg", + "approved": true, + "invited": true + } +] +``` + ## Give a group access to a project See [share project with group](projects.md#share-project-with-group) diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 4ede95ea189..b6021d494fd 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -294,7 +294,12 @@ POST /projects/:id/approval_rules | `rule_type` | string | no | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0`. Other rules are `regular`. | `user_ids` | Array | no | The ids of users as approvers | | `group_ids` | Array | no | The ids of groups as approvers | -| `protected_branch_ids` | Array | no | **(PREMIUM)** The ids of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | +| `protected_branch_ids` | Array | no | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | +| `report_type` | string | no | The report type required when the rule type is `report_approver`. The supported report types are: `vulnerability`, `license_scanning`, `code_coverage`. | +| `scanners` | Array | no | The security scanners the `Vulnerability-Check` approval rule considers. The supported scanners are: `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing`. Defaults to all supported scanners. | +| `severity_levels` | Array | no | The severity levels the `Vulnerability-Check` approval rule considers. The supported severity levels are: `info`, `unknown`, `low`, `medium`, `high`, `critical`. Defaults to `unknown`, `high`, and `critical`. | +| `vulnerabilities_allowed` | integer | no | The number of vulnerabilities allowed for the `Vulnerability-Check` approval rule. Defaults to `0`. | +| `vulnerability_states` | Array | no | The vulnerability states the `Vulnerability-Check` approval rule considers. The supported vulnerability states are: `newly_detected` (default), `detected`, `confirmed`, `resolved`, `dismissed`. | ```json { @@ -417,7 +422,11 @@ PUT /projects/:id/approval_rules/:approval_rule_id | `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 | -| `protected_branch_ids` | Array | no | **(PREMIUM)** The ids of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | +| `protected_branch_ids` | Array | no | The IDs of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | +| `scanners` | Array | no | The security scanners the `Vulnerability-Check` approval rule considers. The supported scanners are: `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing`. Defaults to all supported scanners. | +| `severity_levels` | Array | no | The severity levels the `Vulnerability-Check` approval rule considers. The supported severity levels are: `info`, `unknown`, `low`, `medium`, `high`, `critical`. Defaults to `unknown`, `high`, and `critical`. | +| `vulnerabilities_allowed` | integer | no | The number of vulnerabilities allowed for the `Vulnerability-Check` approval rule. Defaults to `0`. | +| `vulnerability_states` | Array | no | The vulnerability states the `Vulnerability-Check` approval rule considers. The supported vulnerability states are: `newly_detected` (default), `detected`, `confirmed`, `resolved`, `dismissed`. | ```json { diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index b40d67ab4e3..9984c5abb70 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -17,8 +17,10 @@ GET /projects/:id/merge_requests/:merge_request_iid/context_commits Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `merge_request_iid` (required) - The internal ID of the merge request +| Attribute | Type | Required | Description | +|---------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `merge_request_iid` | integer | yes | The internal ID of the merge request | ```json [ @@ -49,8 +51,10 @@ POST /projects/:id/merge_requests/:merge_request_iid/context_commits Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `merge_request_iid` (required) - The internal ID of the merge request +| Attribute | Type | Required | Description | +|---------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `merge_request_iid` | integer | yes | The internal ID of the merge request | ```plaintext POST /projects/:id/merge_requests/ @@ -88,9 +92,8 @@ DELETE /projects/:id/merge_requests/:merge_request_iid/context_commits Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `merge_request_iid` (required) - The internal ID of the merge request - -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `commits` | string array | yes | The context commits' SHA | +| Attribute | Type | Required | Description | +|---------------------|--------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `merge_request_iid` | integer | yes | The internal ID of the merge request | +| `commits` | string array | yes | The context commits' SHA | diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 98af228a064..fa713558684 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -1,15 +1,11 @@ --- stage: Create group: Code Review -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, api +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 --- # Merge requests API **(FREE)** -> - `author_id`, `author_username`, and `assignee_id` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5. -> - `my_reaction_emoji` was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0. -> - For the `scope` attribute, `created-by-me` and `assigned-to-me` were [deprecated](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in favor of `created_by_me` and `assigned_to_me` in GitLab 11.0. > - `with_labels_details` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7. > - `author_username` and `author_username` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10. > - `reference` was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.10 in favour of `references`. @@ -52,8 +48,6 @@ still apply. ## List merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5. - Get all merge requests the authenticated user has access to. By default it returns only merge requests created by the current user. To get all merge requests, use parameter `scope=all`. @@ -85,7 +79,7 @@ Parameters: | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | +| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | | `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. | | `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | @@ -272,7 +266,7 @@ Parameters: | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | +| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | | `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. | | `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | @@ -459,7 +453,7 @@ Parameters: | `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | +| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7.| | `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. | | `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -467,14 +461,14 @@ Parameters: | `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. | -| `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5)_. | +| `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. | | `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10)_. | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5)_. | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | | `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | | `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_. | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `source_branch` | string | no | Return merge requests with the given source branch. | | `target_branch` | string | no | Return merge requests with the given target branch. | | `search` | string | no | Search merge requests against their `title` and `description`. | @@ -976,8 +970,6 @@ Parameters: ## List MR pipelines -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15454) in GitLab 10.5. - Get a list of merge request pipelines. ```plaintext diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 84b4e2fe39d..3c1e09eaace 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -27,7 +27,7 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------- | ------ | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | optional | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | | `state` | string | optional | Return only `active` or `closed` milestones | | `title` | string | optional | Return only the milestones having the given `title` | @@ -68,8 +68,10 @@ GET /projects/:id/milestones/:milestone_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `milestone_id` (required) - The ID of the project's milestone +| Attribute | Type | Required | Description | +|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `milestone_id` | integer | yes | The ID of the project's milestone | ## Create new milestone @@ -81,11 +83,13 @@ POST /projects/:id/milestones Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `title` (required) - The title of a milestone -- `description` (optional) - The description of the milestone -- `due_date` (optional) - The due date of the milestone -- `start_date` (optional) - The start date of the milestone +| Attribute | Type | Required | Description | +|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `title` | string | yes | The title of a milestone | +| `description` | string | no | The description of the milestone | +| `due_date` | string | no | The due date of the milestone | +| `start_date` | string | no | The start date of the milestone | ## Edit milestone @@ -97,13 +101,15 @@ PUT /projects/:id/milestones/:milestone_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `milestone_id` (required) - The ID of a project milestone -- `title` (optional) - The title of a milestone -- `description` (optional) - The description of a milestone -- `due_date` (optional) - The due date of the milestone -- `start_date` (optional) - The start date of the milestone -- `state_event` (optional) - The state event of the milestone (close or activate) +| Attribute | Type | Required | Description | +|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `milestone_id` | integer | yes | The ID of the project's milestone | +| `title` | string | no | The title of a milestone | +| `description` | string | no | The description of the milestone | +| `due_date` | string | no | The due date of the milestone | +| `start_date` | string | no | The start date of the milestone | +| `state_event` | string | no | The state event of the milestone (close or activate) | ## Delete project milestone @@ -115,8 +121,10 @@ DELETE /projects/:id/milestones/:milestone_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `milestone_id` (required) - The ID of the project's milestone +| Attribute | Type | Required | Description | +|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all issues assigned to a single milestone @@ -128,8 +136,10 @@ GET /projects/:id/milestones/:milestone_id/issues Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `milestone_id` (required) - The ID of a project milestone +| Attribute | Type | Required | Description | +|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all merge requests assigned to a single milestone @@ -141,8 +151,10 @@ GET /projects/:id/milestones/:milestone_id/merge_requests Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `milestone_id` (required) - The ID of a project milestone +| Attribute | Type | Required | Description | +|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `milestone_id` | integer | yes | The ID of the project's milestone | ## Promote project milestone to a group milestone @@ -156,8 +168,10 @@ POST /projects/:id/milestones/:milestone_id/promote Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `milestone_id` (required) - The ID of a project milestone +| Attribute | Type | Required | Description | +|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `milestone_id` | integer | yes | The ID of the project's milestone | ## Get all burndown chart events for a single milestone **(PREMIUM)** @@ -172,5 +186,7 @@ GET /projects/:id/milestones/:milestone_id/burndown_events Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `milestone_id` (required) - The ID of a project milestone +| Attribute | Type | Required | Description | +|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `milestone_id` | integer | yes | The ID of the project's milestone | diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 03aefaf4380..9a52b0983a7 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -4,7 +4,7 @@ group: Access 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 --- -# Namespaces API +# Namespaces API **(FREE)** Usernames and group names fall under a special category called [namespaces](../user/group/index.md#namespaces). diff --git a/doc/api/notes.md b/doc/api/notes.md index 6a3db0a2aab..879ffaca191 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -54,7 +54,7 @@ GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | `issue_iid` | integer | yes | The IID of an issue | `sort` | string | no | Return issue notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return issue notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -120,9 +120,11 @@ GET /projects/:id/issues/:issue_iid/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) -- `issue_iid` (required) - The IID of a project issue -- `note_id` (required) - The ID of an issue 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 a project issue | +| `note_id` | integer | yes | The ID of an issue note | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1" @@ -138,11 +140,13 @@ POST /projects/:id/issues/:issue_iid/notes Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) -- `issue_iid` (required) - The IID of an issue -- `body` (required) - The content of a note. Limited to 1,000,000 characters. -- `confidential` (optional) - The confidential flag of a note. Default is false. -- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) +| 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. | +| `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) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note" @@ -158,11 +162,13 @@ PUT /projects/:id/issues/:issue_iid/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). -- `issue_iid` (required) - The IID of an issue. -- `note_id` (required) - The ID of a note. -- `body` (optional) - The content of a note. Limited to 1,000,000 characters. -- `confidential` (optional) - 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 | The confidential flag of a note. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note" @@ -180,7 +186,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer 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 | @@ -203,7 +209,7 @@ GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | `snippet_id` | integer | yes | The ID of a project snippet | `sort` | string | no | Return snippet notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -222,9 +228,11 @@ GET /projects/:id/snippets/:snippet_id/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) -- `snippet_id` (required) - The ID of a project snippet -- `note_id` (required) - The ID of a snippet note +| Attribute | Type | Required | Description | +|--------------|----------------|----------|---------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `snippet_id` | integer | yes | The ID of a project snippet | +| `note_id` | integer | yes | The ID of a snippet note | ```json { @@ -260,10 +268,12 @@ POST /projects/:id/snippets/:snippet_id/notes Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) -- `snippet_id` (required) - The ID of a snippet -- `body` (required) - The content of a note. Limited to 1,000,000 characters. -- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) +| Attribute | Type | Required | Description | +|--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `snippet_id` | integer | yes | The ID of a snippet | +| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | +| `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note" @@ -279,10 +289,12 @@ PUT /projects/:id/snippets/:snippet_id/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) -- `snippet_id` (required) - The ID of a snippet -- `note_id` (required) - The ID of a note -- `body` (required) - 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) | +| `snippet_id` | integer | yes | The ID of a snippet | +| `note_id` | integer | yes | The ID of a snippet note | +| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note" @@ -300,7 +312,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `snippet_id` | integer | yes | The ID of a snippet | | `note_id` | integer | yes | The ID of a note | @@ -321,7 +333,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=upda | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | `merge_request_iid` | integer | yes | The IID of a project merge request | `sort` | string | no | Return merge request notes sorted in `asc` or `desc` order. Default is `desc` | `order_by` | string | no | Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at` @@ -340,9 +352,11 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) -- `merge_request_iid` (required) - The IID of a project merge request -- `note_id` (required) - The ID of a merge request note +| 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 | yes | The ID of a merge request note | ```json { @@ -383,10 +397,12 @@ POST /projects/:id/merge_requests/:merge_request_iid/notes Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) -- `merge_request_iid` (required) - The IID of a merge request -- `body` (required) - The content of a note. Limited to 1,000,000 characters. -- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) +| 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 | +| `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) | ### Modify existing merge request note @@ -398,10 +414,12 @@ PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) -- `merge_request_iid` (required) - The IID of a merge request -- `note_id` (required) - The ID of a note -- `body` (required) - 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. | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note" @@ -419,7 +437,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer 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 merge request | | `note_id` | integer | yes | The ID of a note | @@ -440,7 +458,7 @@ GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | | `epic_id` | integer | yes | The ID of a group epic | | `sort` | string | no | Return epic notes sorted in `asc` or `desc` order. Default is `desc` | | `order_by` | string | no | Return epic notes ordered by `created_at` or `updated_at` fields. Default is `created_at` | @@ -461,7 +479,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer 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 | @@ -502,7 +520,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer 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. | @@ -522,7 +540,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer 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. | @@ -543,7 +561,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `id` | integer 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 | diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 8a8a54a753a..778c229e3c8 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -98,7 +98,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD This page asks the user to approve the request from the app to access their account based on the scopes specified in `REQUESTED_SCOPES`. The user is then redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) - is a space separated list of scopes associated with the user. + is a space-separated list of scopes associated with the user. For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes. The redirect includes the authorization `code`, for example: @@ -126,7 +126,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD "created_at": 1607635748 } ``` - + 1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may be used even after the `access_token` itself expires. This request: - Invalidates the existing `access_token` and `refresh_token`. @@ -178,7 +178,7 @@ be used as a CSRF token. This page asks the user to approve the request from the app to access their account based on the scopes specified in `REQUESTED_SCOPES`. The user is then redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) - is a space separated list of scopes associated with the user. + is a space-separated list of scopes associated with the user. For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes. The redirect includes the authorization `code`, for example: @@ -206,7 +206,7 @@ be used as a CSRF token. "created_at": 1607635748 } ``` - + 1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may be used even after the `access_token` itself expires. This request: - Invalidates the existing `access_token` and `refresh_token`. @@ -266,7 +266,7 @@ https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIREC 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](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) - is a space separated list of scopes you want to have access to (for example, `scope=read_user+profile` + 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: diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index aee3a4fe542..f25a3a25754 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -287,12 +287,13 @@ Example response: Returns metadata for a specific package version: ```plaintext -GET <route-prefix>/metadata/:package_name/index +GET <route-prefix>/metadata/:package_name/:package_version ``` -| Attribute | Type | Required | Description | -| -------------- | ------ | -------- | ----------- | -| `package_name` | string | yes | The name of the package. | +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `package_name` | string | yes | The name of the package. | +| `package_version` | string | yes | The version of the package. | ```shell curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17" diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 9c9551a5103..b51866fe9b1 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -40,8 +40,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a "scopes": [ "api" ], - "active": true, "user_id": 24, + "last_used_at": "2021-10-06T17:58:37.550Z", + "active": true, "expires_at": null } ] @@ -61,8 +62,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a "scopes": [ "api" ], - "active": true, "user_id": 3, + "last_used_at": "2021-10-06T17:58:37.550Z", + "active": true, "expires_at": null } ] diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 4dddbbc7826..d850113f9b6 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -15,6 +15,8 @@ Read more on [pagination](index.md#pagination). ## List project pipelines +> `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6. + List pipelines in a project. Child pipelines are not included in the results, but you can [get child pipeline](pipelines.md#get-a-single-pipeline) individually. @@ -50,7 +52,7 @@ Example of response "iid": 12, "project_id": 1, "status": "pending", - "soure": "push", + "source": "push", "ref": "new-pipeline", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "web_url": "https://example.com/foo/bar/pipelines/47", @@ -62,7 +64,7 @@ Example of response "iid": 13, "project_id": 1, "status": "pending", - "soure": "web", + "source": "web", "ref": "new-pipeline", "sha": "eb94b618fb5865b26e80fdd8ae531b7a63ad851a", "web_url": "https://example.com/foo/bar/pipelines/48", @@ -74,6 +76,8 @@ Example of response ## Get a single pipeline +> `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6. + Get one pipeline from a project. You can also get a single [child pipeline](../ci/pipelines/parent_child_pipelines.md). @@ -267,6 +271,8 @@ Sample response: ## Create a new pipeline +> `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6. + ```plaintext POST /projects/:id/pipeline ``` @@ -275,7 +281,7 @@ POST /projects/:id/pipeline |-------------|---------|----------|---------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `ref` | string | yes | Reference to commit | -| `variables` | array | no | An array containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }]` | +| `variables` | array | no | An array containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=main" @@ -316,6 +322,8 @@ Example of response ## Retry jobs in a pipeline +> `iid` in response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342223) in GitLab 14.6. + ```plaintext POST /projects/:id/pipelines/:pipeline_id/retry ``` diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index 2e4ab0e2b8c..c6f979c1643 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -11,7 +11,7 @@ type: reference, api ## Placeholder tokens -Badges support placeholders that are replaced in real time in both the link and image URL. The allowed placeholders are: +Badges support placeholders that are replaced in real-time in both the link and image URL. The allowed placeholders are: <!-- vale gitlab.Spelling = NO --> diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index d2a574b5cbd..129b064c650 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -384,7 +384,6 @@ Example response: } } } - ``` ## Delete project cluster diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 92b1558551d..39c68041725 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -225,6 +225,7 @@ The passed override parameters take precedence over all values defined in the ex ```shell curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ --url "https://gitlab.example.com/api/v4/projects/remote-import" \ --data '{"url":"https://remoteobject/file?token=123123","path":"remote-project"}' ``` @@ -293,6 +294,7 @@ The `failed_relations` array is capped to 100 items. "path_with_namespace": "gitlab-org/gitlab-test", "created_at": "2017-08-29T04:36:44.383Z", "import_status": "started", + "import_type": "github", "correlation_id": "mezklWso3Za", "failed_relations": [ { @@ -301,8 +303,58 @@ The `failed_relations` array is capped to 100 items. "exception_class": "RuntimeError", "exception_message": "A failure occurred", "source": "custom error context", - "relation_name": "merge_requests" + "relation_name": "merge_requests", + "line_number": 0 } ] } ``` + +When importing from GitHub, the a `stats` field lists how many objects were already fetched from +GitHub and how many were already imported: + +```json +{ + "id": 1, + "description": "Itaque perspiciatis minima aspernatur corporis consequatur.", + "name": "Gitlab Test", + "name_with_namespace": "Gitlab Org / Gitlab Test", + "path": "gitlab-test", + "path_with_namespace": "gitlab-org/gitlab-test", + "created_at": "2017-08-29T04:36:44.383Z", + "import_status": "started", + "import_type": "github", + "correlation_id": "mezklWso3Za", + "failed_relations": [ + { + "id": 42, + "created_at": "2020-04-02T14:48:59.526Z", + "exception_class": "RuntimeError", + "exception_message": "A failure occurred", + "source": "custom error context", + "relation_name": "merge_requests", + "line_number": 0 + } + ], + "stats": { + "fetched": { + "diff_note": 19, + "issue": 3, + "label": 1, + "note": 3, + "pull_request": 2, + "pull_request_merged_by": 1, + "pull_request_review": 16 + }, + "imported": { + "diff_note": 19, + "issue": 3, + "label": 1, + "note": 3, + "pull_request": 2, + "pull_request_merged_by": 1, + "pull_request_review": 16 + } + } +} +``` diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index a2c2da9065f..2251b0fc7fd 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -15,7 +15,7 @@ Get list of a project's variables. GET /projects/:id/variables ``` -| Attribute | Type | required | Description | +| Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | @@ -52,7 +52,7 @@ Get the details of a project's specific variable. GET /projects/:id/variables/:key ``` -| Attribute | Type | required | Description | +| Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | @@ -81,7 +81,7 @@ Create a new variable. POST /projects/:id/variables ``` -| Attribute | Type | required | Description | +| Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | @@ -115,7 +115,7 @@ Update a project's variable. PUT /projects/:id/variables/:key ``` -| Attribute | Type | required | Description | +| Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | @@ -150,7 +150,7 @@ Remove a project's variable. DELETE /projects/:id/variables/:key ``` -| Attribute | Type | required | Description | +| Attribute | Type | Required | Description | | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 0ac2297e3c1..569270e5de1 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -36,7 +36,9 @@ GET /projects/:id/snippets Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | ## Single snippet @@ -48,8 +50,10 @@ GET /projects/:id/snippets/:snippet_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `snippet_id` (required) - The ID of a project's snippet +| Attribute | Type | Required | Description | +|--------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `snippet_id` | integer | yes | The ID of a project's snippet | ```json { @@ -85,7 +89,7 @@ Parameters: | Attribute | Type | Required | Description | |:------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | Title of a snippet | | `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | | `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | @@ -132,7 +136,7 @@ Parameters: | Attribute | Type | Required | Description | |:----------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------| -| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `snippet_id` | integer | yes | The ID of a project's snippet | | `title` | string | no | Title of a snippet | | `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | @@ -183,8 +187,10 @@ DELETE /projects/:id/snippets/:snippet_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `snippet_id` (required) - The ID of a project's snippet +| Attribute | Type | Required | Description | +|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `snippet_id` | integer | yes | The ID of a project's snippet | Example request: @@ -203,8 +209,10 @@ GET /projects/:id/snippets/:snippet_id/raw Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `snippet_id` (required) - The ID of a project's snippet +| Attribute | Type | Required | Description | +|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `snippet_id` | integer | yes | The ID of a project's snippet | Example request: @@ -223,10 +231,12 @@ GET /projects/:id/snippets/:snippet_id/files/:ref/:file_path/raw Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user -- `snippet_id` (required) - The ID of a project's snippet -- `ref` (required) - The name of a branch, tag or commit, such as `main` -- `file_path` (required) - The URL-encoded path to the file, such as `snippet%2Erb` +| Attribute | Type | Required | Description | +|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `snippet_id` | integer | yes | The ID of a project's snippet | +| `ref` | string | yes | The name of a branch, tag or commit e.g. master | +| `file_path` | string | yes | The URL-encoded path to the file, e.g. snippet%2Erb | Example request: @@ -245,10 +255,10 @@ Available only for users with the Administrator [role](../user/permissions.md). GET /projects/:id/snippets/:snippet_id/user_agent_detail ``` -| Attribute | Type | Required | Description | -|---------------|---------|----------|--------------------------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). | -| `snippet_id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|--------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `snippet_id` | Integer | yes | The ID of a snippet | Example request: diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index c69e41a423e..c0a1227b295 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -21,7 +21,7 @@ GET /projects/:id/statistics | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | Example response: diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index d4af0e8d78d..2ec30c80a6b 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -33,7 +33,7 @@ GET /projects/:id/templates/:type | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `type` | string | yes | The type of the template. Accepted values are: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, `merge_requests` | Example response (licenses): @@ -99,7 +99,7 @@ GET /projects/:id/templates/:type/:name | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `type` | string | yes| The type of the template. One of: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, or `merge_requests`. | | `name` | string | yes | The key of the template, as obtained from the collection endpoint | | `source_template_project_id` | integer | no | The project ID where a given template is being stored. This is useful when multiple templates from different projects have the same name. If multiple templates have the same name, the match from `closest ancestor` is returned if `source_template_project_id` is not specified | diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index 7ba359587f6..1267f748633 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -10,9 +10,11 @@ type: reference, api > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. WARNING: -This API is in an alpha stage and considered unstable. +This API is in the process of being deprecated and considered unstable. The response payload may be subject to change or breakage -across GitLab releases. +across GitLab releases. Please use the +[GraphQL API](graphql/reference/index.md#queryvulnerabilities) +instead. Every API call to vulnerabilities must be [authenticated](index.md#authentication). diff --git a/doc/api/projects.md b/doc/api/projects.md index d19019c9597..65911567f87 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -183,6 +183,7 @@ When the user is authenticated and `simple` is not set this returns something li "autoclose_referenced_issues": true, "suggestion_commit_message": null, "merge_commit_template": null, + "squash_commit_template": null, "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on "marked_for_deletion_on": "2020-04-03", "statistics": { @@ -300,6 +301,7 @@ When the user is authenticated and `simple` is not set this returns something li "autoclose_referenced_issues": true, "suggestion_commit_message": null, "merge_commit_template": null, + "squash_commit_template": null, "statistics": { "commit_count": 12, "storage_size": 2066080, @@ -369,6 +371,9 @@ Keyset pagination supports only `order_by=id`. Other sorting options aren't avai 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. + This endpoint supports [keyset pagination](index.md#keyset-based-pagination) for selected `order_by` options. @@ -467,6 +472,7 @@ GET /users/:user_id/projects "autoclose_referenced_issues": true, "suggestion_commit_message": null, "merge_commit_template": null, + "squash_commit_template": null, "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on "marked_for_deletion_on": "2020-04-03", "statistics": { @@ -584,6 +590,7 @@ GET /users/:user_id/projects "autoclose_referenced_issues": true, "suggestion_commit_message": null, "merge_commit_template": null, + "squash_commit_template": null, "statistics": { "commit_count": 12, "storage_size": 2066080, @@ -711,6 +718,7 @@ Example response: "autoclose_referenced_issues": true, "suggestion_commit_message": null, "merge_commit_template": null, + "squash_commit_template": null, "statistics": { "commit_count": 37, "storage_size": 1038090, @@ -823,6 +831,7 @@ Example response: "autoclose_referenced_issues": true, "suggestion_commit_message": null, "merge_commit_template": null, + "squash_commit_template": null, "statistics": { "commit_count": 12, "storage_size": 2066080, @@ -991,6 +1000,7 @@ GET /projects/:id "autoclose_referenced_issues": true, "suggestion_commit_message": null, "merge_commit_template": null, + "squash_commit_template": null, "marked_for_deletion_at": "2020-04-03", // Deprecated and will be removed in API v5 in favor of marked_for_deletion_on "marked_for_deletion_on": "2020-04-03", "compliance_frameworks": [ "sox" ], @@ -1062,7 +1072,7 @@ If the project is a fork, and you provide a valid token to authenticate, the "ssh_url_to_repo":"git@gitlab.com:gitlab-org/gitlab-foss.git", "http_url_to_repo":"https://gitlab.com/gitlab-org/gitlab-foss.git", "web_url":"https://gitlab.com/gitlab-org/gitlab-foss", - "avatar_url":"https://assets.gitlab-static.net/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png", + "avatar_url":"https://gitlab.com/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png", "license_url": "https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE", "license": { "key": "mit", @@ -1228,8 +1238,10 @@ POST /projects | `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. | | `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. | | `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | +| `merge_pipelines_enabled` | boolean | **{dotted-circle}** No | Enable or disable merge pipelines. | | `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | +| `merge_trains_enabled` | boolean | **{dotted-circle}** No | Enable or disable merge trains. | | `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | | `mirror` **(PREMIUM)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | | `namespace_id` | integer | **{dotted-circle}** No | Namespace for the new project (defaults to the current user's namespace). | @@ -1252,7 +1264,7 @@ POST /projects | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | | `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | -| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | +| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). When used with `use_custom_template`, name of a custom project template. | | `template_project_id` **(PREMIUM)** | integer | **{dotted-circle}** No | When used with `use_custom_template`, project ID of a custom project template. This is preferable to using `template_name` since `template_name` may be ambiguous. | | `topics` | array | **{dotted-circle}** No | The list of topics for a project; put array of topics, that should be finally assigned to a project. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0.)_ | | `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | @@ -1304,6 +1316,7 @@ POST /projects/user/:user_id | `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. | | `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. | | `merge_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create merge commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.)_ | +| `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ | | `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | | `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | @@ -1331,7 +1344,7 @@ POST /projects/user/:user_id | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | | `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request [suggestions](../user/project/merge_requests/reviews/suggestions.md). | | `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | -| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#built-in-templates). When used with `use_custom_template`, name of a custom project template. | +| `template_name` | string | **{dotted-circle}** No | When used without `use_custom_template`, name of a [built-in project template](../user/project/working_with_projects.md#create-a-project-from-a-built-in-template). When used with `use_custom_template`, name of a custom project template. | | `topics` | array | **{dotted-circle}** No | The list of topics for the project. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0.)_ | | `use_custom_template` **(PREMIUM)** | boolean | **{dotted-circle}** No | Use either custom [instance](../user/admin_area/custom_project_templates.md) or [group](../user/group/custom_project_templates.md) (with `group_with_project_templates_id`) project template. | | `visibility` | string | **{dotted-circle}** No | See [project visibility level](#project-visibility-level). | @@ -1350,6 +1363,17 @@ where `password` is a public access key with the `api` scope enabled. PUT /projects/:id ``` +For example, to toggle the setting for +[shared runners on a GitLab.com project](../ci/runners/index.md): + +```shell +curl --request PUT --header "PRIVATE-TOKEN: <your-token>" \ + --url 'https://gitlab.com/api/v4/projects/<your-project-ID>' \ + --data "shared_runners_enabled=true" # to turn off: "shared_runners_enabled=false" +``` + +Supported attributes: + | Attribute | Type | Required | Description | |-------------------------------------------------------------|----------------|------------------------|-------------| | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | @@ -1383,8 +1407,10 @@ PUT /projects/:id | `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. | | `merge_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create merge commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.)_ | | `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. | +| `merge_pipelines_enabled` | boolean | **{dotted-circle}** No | Enable or disable merge pipelines. | | `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | +| `merge_trains_enabled` | boolean | **{dotted-circle}** No | Enable or disable merge trains. | | `mirror_overwrites_diverged_branches` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirror overwrites diverged branches. | | `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | | `mirror_user_id` **(PREMIUM)** | integer | **{dotted-circle}** No | User responsible for all the activity surrounding a pull mirror event. _(administrators only)_ | @@ -1397,8 +1423,9 @@ PUT /projects/:id | `packages_enabled` | boolean | **{dotted-circle}** No | Enable or disable packages repository feature. | | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | | `requirements_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled` or `public` | -| `restrict_user_defined_variables` | boolean | **{dotted-circle}** No | Allow only maintainers to pass user-defined variables when triggering a pipeline. For example when the pipeline is triggered in the UI, with the API, or by a trigger token. | +| `restrict_user_defined_variables` | boolean | **{dotted-circle}** No | Allow only users with the [Maintainer role](../user/permissions.md) to pass user-defined variables when triggering a pipeline. For example when the pipeline is triggered in the UI, with the API, or by a trigger token. | | `path` | string | **{dotted-circle}** No | Custom repository name for the project. By default generated based on name. | +| `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | | `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | @@ -1410,6 +1437,7 @@ PUT /projects/:id | `show_default_award_emojis` | boolean | **{dotted-circle}** No | Show default award emojis. | | `snippets_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `snippets_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable snippets for this project. Use `snippets_access_level` instead. | +| `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ | | `squash_option` | string | **{dotted-circle}** No | One of `never`, `always`, `default_on`, or `default_off`. | | `suggestion_commit_message` | string | **{dotted-circle}** No | The commit message used to apply merge request suggestions. | | `tag_list` | array | **{dotted-circle}** No | _([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/328226) in GitLab 14.0)_ The list of tags for a project; put array of tags, that should be finally assigned to a project. Use `topics` instead. | @@ -2077,9 +2105,13 @@ This endpoint: - Deletes a project including all associated resources (including issues and merge requests). +- In [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) and later, on + [Premium or higher](https://about.gitlab.com/pricing/) tiers, + [delayed project deletion](../user/project/settings/index.md#delayed-project-deletion) + is applied if enabled. - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or higher](https://about.gitlab.com/pricing/) tiers, group - administrators can [configure](../user/group/index.md#enable-delayed-project-removal) + administrators can [configure](../user/group/index.md#enable-delayed-project-deletion) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after the number of days specified in the [default deletion delay](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). @@ -2087,7 +2119,7 @@ This endpoint: WARNING: The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) -in GitLab 13.2, as discussed in [Enable delayed project removal](../user/group/index.md#enable-delayed-project-removal). +in GitLab 13.2, as discussed in [Enable delayed project deletion](../user/group/index.md#enable-delayed-project-deletion). ```plaintext DELETE /projects/:id @@ -2477,8 +2509,8 @@ GET /projects/:id/push_rule { "id": 1, "project_id": 3, - "commit_message_regex": "Fixes \d+\..*", - "commit_message_negative_regex": "ssh\:\/\/", + "commit_message_regex": "Fixes \\d+\\..*", + "commit_message_negative_regex": "ssh\\:\\/\\/", "branch_name_regex": "", "deny_delete_tag": false, "created_at": "2012-10-12T17:04:47Z", diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index a75090c90d5..d17341759ad 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -197,18 +197,18 @@ POST /projects/:id/protected_branches curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40" ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the branch or wildcard | -| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, Maintainer role) | -| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | -| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, Maintainer role) | -| `allow_force_push` | boolean | no | Allow all users with push access to force push. (default: `false`) | -| `allowed_to_push` | array | no | **(PREMIUM)** Array of access levels allowed to push, with each described by a hash | -| `allowed_to_merge` | array | no | **(PREMIUM)** Array of access levels allowed to merge, with each described by a hash | -| `allowed_to_unprotect` | array | no | **(PREMIUM)** Array of access levels allowed to unprotect, with each described by a hash | -| `code_owner_approval_required` | boolean | no | **(PREMIUM)** Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false) | +| Attribute | Type | Required | Description | +| -------------------------------------------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the branch or wildcard | +| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, Maintainer role) | +| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | +| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, Maintainer role) | +| `allow_force_push` | boolean | no | Allow all users with push access to force push. (default: `false`) | +| `allowed_to_push` **(PREMIUM)** | array | no | Array of access levels allowed to push, with each described by a hash | +| `allowed_to_merge` **(PREMIUM)** | array | no | Array of access levels allowed to merge, with each described by a hash | +| `allowed_to_unprotect` **(PREMIUM)** | array | no | Array of access levels allowed to unprotect, with each described by a hash | +| `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false) | Example response: @@ -402,7 +402,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | -## Require code owner approvals for a single branch +## Require code owner approvals for a single branch **(PREMIUM)** Update the "code owner approval required" option for the given protected branch. @@ -411,11 +411,11 @@ PATCH /projects/:id/protected_branches/:name ``` ```shell -curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches/feature-branch" +curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/protected_branches/feature-branch?code_owner_approval_required=true" ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the branch | -| `code_owner_approval_required` | boolean | no | **(PREMIUM)** Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false)| +| Attribute | Type | Required | Description | +| -------------------------------------------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the branch | +| `code_owner_approval_required` | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false)| diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 82bb1e55e77..c7de4c504a4 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -117,13 +117,13 @@ Example response: ```json { - "name":"production", - "deploy_access_levels":[ + "name": "production", + "deploy_access_levels": [ { - "access_level":40, - "access_level_description":"protected-access-group", - "user_id":null, - "group_id":9899826 + "access_level": 40, + "access_level_description": "protected-access-group", + "user_id": null, + "group_id": 9899826 } ] } diff --git a/doc/api/repositories.md b/doc/api/repositories.md index e93ffbc5e72..ec5c97e5b25 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -28,7 +28,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `path` | string | no | The path inside repository. Used to get content of subdirectories. | | `ref` | string | no | The name of a repository branch or tag or if not given the default branch. | | `recursive` | boolean | no | Boolean value used to get a recursive tree (false by default). | @@ -104,7 +104,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | yes | The blob SHA. | ## Raw blob content @@ -146,7 +146,7 @@ Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:----------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. | | `path` | string | no | The subpath of the repository to download. This defaults to the whole repository (empty string). | @@ -169,7 +169,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :--------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `from` | string | yes | The commit SHA or branch name. | | `to` | string | yes | The commit SHA or branch name. | | `from_project_id` | integer | no | The ID to compare from | @@ -231,7 +231,7 @@ Supported attributes: | Attribute | Type | Required | Description | | :--------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `order_by` | string | no | Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`. | | `sort` | string | no | Return contributors sorted in `asc` or `desc` order. Default is `asc`. | @@ -263,7 +263,7 @@ GET /projects/:id/repository/merge_base | Attribute | Type | Required | Description | | --------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed | Example request: @@ -291,7 +291,7 @@ Example response: } ``` -## Generate changelog data +## Add changelog data to a changelog file > [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/351) in GitLab 13.9. @@ -373,26 +373,26 @@ If the last tag is `v0.9.0` and the default branch is `main`, the range of commi included in this example is `v0.9.0..main`: ```shell -curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0" "https://gitlab.com/api/v4/projects/42/repository/changelog" +curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0" "https://gitlab.com/api/v4/projects/42/repository/changelog" ``` To generate the data on a different branch, specify the `branch` parameter. This command generates data from the `foo` branch: ```shell -curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&branch=foo" "https://gitlab.com/api/v4/projects/42/repository/changelog" +curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0&branch=foo" "https://gitlab.com/api/v4/projects/42/repository/changelog" ``` To use a different trailer, use the `trailer` parameter: ```shell -curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&trailer=Type" "https://gitlab.com/api/v4/projects/42/repository/changelog" +curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0&trailer=Type" "https://gitlab.com/api/v4/projects/42/repository/changelog" ``` To store the results in a different file, use the `file` parameter: ```shell -curl --header "PRIVATE-TOKEN: token" --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog" +curl --request POST --header "PRIVATE-TOKEN: token" --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog" ``` ### How it works @@ -689,7 +689,7 @@ The following capture groups are optional: - `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate tags and other pre-release tags are not considered when determining the range of commits to generate a changelog for. -- `meta`: (Optional) Specifies build metadata. +- `meta`: Optional. Specifies build metadata. Using this information, GitLab builds a map of Git tags and their release versions. It then determines what the latest tag is, based on the version @@ -707,3 +707,39 @@ tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$' To test if your regular expression is working, you can use websites such as [regex101](https://regex101.com/). If the regular expression syntax is invalid, an error is produced when generating a changelog. + +## Generate changelog data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345934) in GitLab 14.6. + +Generate changelog data based on commits in a repository, without committing +them to a changelog file. + +Works exactly like `POST /projects/:id/repository/changelog`, except the changelog +data isn't committed to any changelog file. + +```plaintext +GET /projects/:id/repository/changelog +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +| :-------- | :------- | :--------- | :---------- | +| `version` | string | yes | The version to generate the changelog for. The format must follow [semantic versioning](https://semver.org/). | +| `from` | string | no | The start of the range of commits (as a SHA) to use for generating the changelog. This commit itself isn't included in the list. | +| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the branch specified in the `branch` attribute. | +| `date` | datetime | no | The date and time of the release, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z`. Defaults to the current time. | +| `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | + +```shell +curl --header "PRIVATE-TOKEN: token" "https://gitlab.com/api/v4/projects/42/repository/changelog?version=1.0.0" +``` + +Example Response: + +```json +{ + "notes": "## 1.0.0 (2021-11-17)\n\n### feature (2 changes)\n\n- [Title 2](namespace13/project13@ad608eb642124f5b3944ac0ac772fecaf570a6bf) ([merge request](namespace13/project13!2))\n- [Title 1](namespace13/project13@3c6b80ff7034fa0d585314e1571cc780596ce3c8) ([merge request](namespace13/project13!1))\n" +} +``` diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index cc210eacd49..fd024240e90 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -35,6 +35,12 @@ GET /projects/:id/repository/files/:file_path curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master" ``` +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | +| `ref` | string | yes | The name of branch, tag or commit | + Example response: ```json @@ -52,11 +58,6 @@ Example response: } ``` -Parameters: - -- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb -- `ref` (required) - The name of branch, tag or commit - NOTE: `blob_id` is the blob SHA, see [repositories - Get a blob from repository](repositories.md#get-a-blob-from-repository) @@ -95,6 +96,12 @@ Allows you to receive blame information. Each blame range contains lines and cor GET /projects/:id/repository/files/:file_path/blame ``` +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | +| `ref` | string | yes | The name of branch, tag or commit | + ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master" ``` @@ -127,11 +134,6 @@ Example response: ] ``` -Parameters: - -- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb -- `ref` (required) - The name of branch, tag or commit - NOTE: `HEAD` method return just file metadata as in [Get file from repository](repository_files.md#get-file-from-repository). @@ -162,15 +164,16 @@ X-Gitlab-Size: 1476 GET /projects/:id/repository/files/:file_path/raw ``` +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | +| `ref` | string | yes | The name of branch, tag or commit. Default is the `HEAD` of the project. | + ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master" ``` -Parameters: - -- `file_path` (required) - URL encoded full path to new file, such as lib%2Fclass%2Erb. -- `ref` (optional) - The name of branch, tag or commit. Default is the `HEAD` of the project. - NOTE: Like [Get file from repository](repository_files.md#get-file-from-repository) you can use `HEAD` to get just file metadata. @@ -182,6 +185,18 @@ This allows you to create a single file. For creating multiple files with a sing POST /projects/:id/repository/files/:file_path ``` +| Attribute | Type | Required | Description | +|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | +| `branch` | string | yes | Name of the branch | +| `start_branch` | string | no | Name of the branch to start the new commit from | +| `encoding` | string | no | Change encoding to `base64`. Default is `text`. | +| `author_email` | string | no | Specify the commit author's email address | +| `author_name` | string | no | Specify the commit author's name | +| `content` | string | yes | File content | +| `commit_message` | string | yes | Commit message | + ```shell curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' \ --header "Content-Type: application/json" \ @@ -199,17 +214,6 @@ Example response: } ``` -Parameters: - -- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb -- `branch` (required) - Name of the branch -- `start_branch` (optional) - Name of the branch to start the new commit from -- `encoding` (optional) - Change encoding to `base64`. Default is `text`. -- `author_email` (optional) - Specify the commit author's email address -- `author_name` (optional) - Specify the commit author's name -- `content` (required) - File content -- `commit_message` (required) - Commit message - ## Update existing file in repository 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). @@ -218,6 +222,19 @@ This allows you to update a single file. For updating multiple files with a sing PUT /projects/:id/repository/files/:file_path ``` +| Attribute | Type | Required | Description | +|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | +| `branch` | string | yes | Name of the branch | +| `start_branch` | string | no | Name of the branch to start the new commit from | +| `encoding` | string | no | Change encoding to `base64`. Default is `text`. | +| `author_email` | string | no | Specify the commit author's email address | +| `author_name` | string | no | Specify the commit author's name | +| `content` | string | yes | File content | +| `commit_message` | string | yes | Commit message | +| `last_commit_id` | string | no | Last known file commit ID | + ```shell curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' \ --header "Content-Type: application/json" \ @@ -235,18 +252,6 @@ Example response: } ``` -Parameters: - -- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb -- `branch` (required) - Name of the branch -- `start_branch` (optional) - Name of the branch to start the new commit from -- `encoding` (optional) - Change encoding to `base64`. Default is `text`. -- `author_email` (optional) - Specify the commit author's email address -- `author_name` (optional) - Specify the commit author's name -- `content` (required) - New file content -- `commit_message` (required) - Commit message -- `last_commit_id` (optional) - Last known file commit ID - If the commit fails for any reason we return a 400 error with a non-specific error message. Possible causes for a failed commit include: @@ -265,6 +270,17 @@ This allows you to delete a single file. For deleting multiple files with a sing DELETE /projects/:id/repository/files/:file_path ``` +| Attribute | Type | Required | Description | +|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. | +| `branch` | string | yes | Name of the branch | +| `start_branch` | string | no | Name of the branch to start the new commit from | +| `author_email` | string | no | Specify the commit author's email address. | +| `author_name` | string | no | Specify the commit author's name. | +| `commit_message` | string | yes | Commit message. | +| `last_commit_id` | string | no | Last known file commit ID. | + ```shell curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \ --header "Content-Type: application/json" \ @@ -272,13 +288,3 @@ curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \ "commit_message": "delete file"}' \ "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb" ``` - -Parameters: - -- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb -- `branch` (required) - Name of the branch -- `start_branch` (optional) - Name of the branch to start the new commit from -- `author_email` (optional) - Specify the commit author's email address -- `author_name` (optional) - Specify the commit author's name -- `commit_message` (required) - Commit message -- `last_commit_id` (optional) - Last known file commit ID diff --git a/doc/api/resource_access_tokens.md b/doc/api/resource_access_tokens.md index fa1e7aace9a..90e9769b896 100644 --- a/doc/api/resource_access_tokens.md +++ b/doc/api/resource_access_tokens.md @@ -58,7 +58,7 @@ POST projects/:id/access_tokens |-----------|---------|----------|---------------------| | `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 | -| `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#limiting-scopes-of-a-project-access-token) | +| `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#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 | diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md index ce4fa33d7f2..237ba6e7d72 100644 --- a/doc/api/resource_groups.md +++ b/doc/api/resource_groups.md @@ -2,12 +2,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 -type: concepts, howto --- -# Resource Groups API +# Resource group API **(FREE)** -You can read more about [controling the job concurrency with resource groups](../ci/resource_groups/index.md). +You can read more about [controlling the job concurrency with resource groups](../ci/resource_groups/index.md). ## Get a specific resource group diff --git a/doc/api/services.md b/doc/api/services.md deleted file mode 100644 index 7587e53c9db..00000000000 --- a/doc/api/services.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'integrations.md' -remove_date: '2021-11-09' ---- - -This file was moved to [another location](integrations.md). - -<!-- This redirect file can be deleted after <2021-11-09>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/settings.md b/doc/api/settings.md index dd32c882860..e953990c091 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -228,7 +228,7 @@ listed in the descriptions of the relevant settings. | `after_sign_up_text` | string | no | Text shown to the user after signing up. | | `akismet_api_key` | string | required by: `akismet_enabled` | API key for Akismet spam protection. | | `akismet_enabled` | boolean | no | (**If enabled, requires:** `akismet_api_key`) Enable or disable Akismet spam protection. | -| `allow_group_owners_to_manage_ldap` | boolean | no | **(PREMIUM)** Set to `true` to allow group owners to manage LDAP. | +| `allow_group_owners_to_manage_ldap` **(PREMIUM)** | boolean | no | Set to `true` to allow group owners to manage LDAP. | | `allow_local_requests_from_hooks_and_services` | boolean | no | (Deprecated: Use `allow_local_requests_from_web_hooks_and_services` instead) Allow requests to the local network from hooks and services. | | `allow_local_requests_from_system_hooks` | boolean | no | Allow requests to the local network from system hooks. | | `allow_local_requests_from_web_hooks_and_services` | boolean | no | Allow requests to the local network from web hooks and services. | @@ -242,21 +242,21 @@ listed in the descriptions of the relevant settings. | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It automatically builds, tests, and deploys applications based on a predefined CI/CD configuration. | | `automatic_purchased_storage_allocation` | boolean | no | Enabling this permits automatic allocation of purchased storage in a namespace. | -| `check_namespace_plan` | boolean | no | **(PREMIUM)** Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | +| `check_namespace_plan` **(PREMIUM)** | boolean | no | Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | | `deactivate_dormant_users` | boolean | no | Enable [automatic deactivation of dormant users](../user/admin_area/moderate_users.md#automatically-deactivate-dormant-users). | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts. | | `default_branch_name` | string | no | [Instance-level custom initial branch name](../user/project/repository/branches/default.md#instance-level-custom-initial-branch-name) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225258) in GitLab 13.2). | -| `default_branch_protection` | integer | no | Determine if developers can push to the default branch. Can take: `0` _(not protected, both developers and maintainers can push new commits and force push)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no one can force push)_ as a parameter. Default is `2`. | +| `default_branch_protection` | integer | no | Determine if developers can push to the default branch. Can take: `0` _(not protected, both users with the Developer role or Maintainer role can push new commits and force push)_, `1` _(partially protected, users with the Developer role or Maintainer role can push new commits, but cannot force push)_ or `2` _(fully protected, users with the Developer or Maintainer role cannot push new commits, but users with the Developer or Maintainer role can; no one can force push)_ as a parameter. Default is `2`. | | `default_ci_config_path` | string | no | Default CI/CD configuration file and path for new projects (`.gitlab-ci.yml` if not set). | | `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_project_creation` | integer | no | Default project creation protection. Can take: `0` _(No one)_, `1` _(Maintainers)_ or `2` _(Developers + Maintainers)_| | `default_project_visibility` | string | no | What visibility level new projects receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_projects_limit` | integer | no | Project limit per user. Default is `100000`. | | `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | -| `delayed_project_deletion` | boolean | no | **(PREMIUM SELF)** Enable delayed project deletion by default in new groups. Default is `false`. | -| `deletion_adjourned_period` | integer | no | **(PREMIUM SELF)** The number of days to wait before deleting a project or group that is marked for deletion. Value must be between 0 and 90. +| `delayed_project_deletion` **(PREMIUM SELF)** | boolean | no | Enable delayed project deletion by default in new groups. Default is `false`. | +| `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). | | `diff_max_lines` | integer | no | Maximum [lines in a diff](../user/admin_area/diff_limits.md). | @@ -273,23 +273,23 @@ listed in the descriptions of the relevant settings. | `eks_account_id` | string | no | Amazon account ID. | | `eks_integration_enabled` | boolean | no | Enable integration with Amazon EKS. | | `eks_secret_access_key` | string | no | AWS IAM secret access key. | -| `elasticsearch_aws_access_key` | string | no | **(PREMIUM)** AWS IAM access key. | -| `elasticsearch_aws_region` | string | no | **(PREMIUM)** The AWS region the Elasticsearch domain is configured. | -| `elasticsearch_aws_secret_access_key` | string | no | **(PREMIUM)** AWS IAM secret access key. | -| `elasticsearch_aws` | boolean | no | **(PREMIUM)** Enable the use of AWS hosted Elasticsearch. | -| `elasticsearch_indexed_field_length_limit` | integer | no | **(PREMIUM)** Maximum size of text fields to index by Elasticsearch. 0 value means no limit. This does not apply to repository and wiki indexing. | -| `elasticsearch_indexed_file_size_limit_kb` | integer | no | **(PREMIUM)** Maximum size of repository and wiki files that are indexed by Elasticsearch. | -| `elasticsearch_indexing` | boolean | no | **(PREMIUM)** Enable Elasticsearch indexing. | -| `elasticsearch_limit_indexing` | boolean | no | **(PREMIUM)** Limit Elasticsearch to index certain namespaces and projects. | -| `elasticsearch_max_bulk_concurrency` | integer | no | **(PREMIUM)** Maximum concurrency of Elasticsearch bulk requests per indexing operation. This only applies to repository indexing operations. | -| `elasticsearch_max_bulk_size_mb` | integer | no | **(PREMIUM)** Maximum size of Elasticsearch bulk indexing requests in MB. This only applies to repository indexing operations. | -| `elasticsearch_namespace_ids` | array of integers | no | **(PREMIUM)** The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | -| `elasticsearch_project_ids` | array of integers | no | **(PREMIUM)** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | -| `elasticsearch_search` | boolean | no | **(PREMIUM)** Enable Elasticsearch search. | -| `elasticsearch_url` | string | no | **(PREMIUM)** The URL to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (for example, `http://localhost:9200, http://localhost:9201"`). | -| `elasticsearch_username` | string | no | **(PREMIUM)** The `username` of your Elasticsearch instance. | -| `elasticsearch_password` | string | no | **(PREMIUM)** The password of your Elasticsearch instance. | -| `email_additional_text` | string | no | **(PREMIUM)** Additional text added to the bottom of every email for legal/auditing/compliance reasons. | +| `elasticsearch_aws_access_key` **(PREMIUM)** | string | no | AWS IAM access key. | +| `elasticsearch_aws_region` **(PREMIUM)** | string | no | The AWS region the Elasticsearch domain is configured. | +| `elasticsearch_aws_secret_access_key` **(PREMIUM)** | string | no | AWS IAM secret access key. | +| `elasticsearch_aws` **(PREMIUM)** | boolean | no | Enable the use of AWS hosted Elasticsearch. | +| `elasticsearch_indexed_field_length_limit` **(PREMIUM)** | integer | no | Maximum size of text fields to index by Elasticsearch. 0 value means no limit. This does not apply to repository and wiki indexing. | +| `elasticsearch_indexed_file_size_limit_kb` **(PREMIUM)** | integer | no | Maximum size of repository and wiki files that are indexed by Elasticsearch. | +| `elasticsearch_indexing` **(PREMIUM)** | boolean | no | Enable Elasticsearch indexing. | +| `elasticsearch_limit_indexing` **(PREMIUM)** | boolean | no | Limit Elasticsearch to index certain namespaces and projects. | +| `elasticsearch_max_bulk_concurrency` **(PREMIUM)** | integer | no | Maximum concurrency of Elasticsearch bulk requests per indexing operation. This only applies to repository indexing operations. | +| `elasticsearch_max_bulk_size_mb` **(PREMIUM)** | integer | no | Maximum size of Elasticsearch bulk indexing requests in MB. This only applies to repository indexing operations. | +| `elasticsearch_namespace_ids` **(PREMIUM)** | array of integers | no | The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `elasticsearch_project_ids` **(PREMIUM)** | array of integers | no | The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `elasticsearch_search` **(PREMIUM)** | boolean | no | Enable Elasticsearch search. | +| `elasticsearch_url` **(PREMIUM)** | string | no | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (for example, `http://localhost:9200, http://localhost:9201"`). | +| `elasticsearch_username` **(PREMIUM)** | string | no | The `username` of your Elasticsearch instance. | +| `elasticsearch_password` **(PREMIUM)** | string | no | The password of your Elasticsearch instance. | +| `email_additional_text` **(PREMIUM)** | string | no | Additional text added to the bottom of every email for legal/auditing/compliance reasons. | | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | | `enforce_namespace_storage_limit` | boolean | no | Enabling this permits enforcement of namespace storage limits. | @@ -302,13 +302,13 @@ listed in the descriptions of the relevant settings. | `external_authorization_service_timeout` | float | required by:<br>`external_authorization_service_enabled` | The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001). | | `external_authorization_service_url` | string | required by:<br>`external_authorization_service_enabled` | URL to which authorization requests are directed. | | `external_pipeline_validation_service_url` | string | no | URL to use for pipeline validation requests. | -| `external_pipeline_validation_service_token` | string | no | (Optional) Token to include as the `X-Gitlab-Token` header in requests to the URL in `external_pipeline_validation_service_url`. | +| `external_pipeline_validation_service_token` | string | no | Optional. Token to include as the `X-Gitlab-Token` header in requests to the URL in `external_pipeline_validation_service_url`. | | `external_pipeline_validation_service_timeout` | integer | no | How long to wait for a response from the pipeline validation service. Assumes `OK` if it times out. | -| `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from. | +| `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | | `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | -| `geo_node_allowed_ips` | string | yes | **(PREMIUM)** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | -| `geo_status_timeout` | integer | no | **(PREMIUM)** The amount of seconds after which a request to get a secondary node status times out. | -| `git_two_factor_session_expiry` | integer | no | **(PREMIUM)** Maximum duration (in minutes) of a session for Git operations when 2FA is enabled. | +| `geo_node_allowed_ips` **(PREMIUM)** | string | yes | Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | +| `geo_status_timeout` **(PREMIUM)** | integer | no | The amount of seconds after which a request to get a secondary node status times out. | +| `git_two_factor_session_expiry` **(PREMIUM)** | integer | no | Maximum duration (in minutes) of a session for Git operations when 2FA is enabled. | | `gitaly_timeout_default` | integer | no | Default Gitaly timeout, in seconds. This timeout is not enforced for Git fetch/push operations or Sidekiq jobs. Set to `0` to disable timeouts. | | `gitaly_timeout_fast` | integer | no | Gitaly fast operation timeout, in seconds. Some Gitaly operations are expected to be fast. If they exceed this threshold, there may be a problem with a storage shard and 'failing fast' can help maintain the stability of the GitLab instance. Set to `0` to disable timeouts. | | `gitaly_timeout_medium` | integer | no | Medium Gitaly timeout, in seconds. This should be a value between the Fast and the Default timeout. Set to `0` to disable timeouts. | @@ -319,7 +319,7 @@ listed in the descriptions of the relevant settings. | `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help. | | `help_page_support_url` | string | no | Alternate support URL for help page and help dropdown. | | `help_page_text` | string | no | Custom text displayed on the help page. | -| `help_text` | string | no | **(PREMIUM)** GitLab server administrator information. | +| `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. | @@ -336,20 +336,21 @@ listed in the descriptions of the relevant settings. | `local_markdown_version` | integer | no | Increase this value when any cached Markdown should be invalidated. | | `mailgun_signing_key` | string | no | The Mailgun HTTP webhook signing key for receiving events from webhook. | | `mailgun_events_enabled` | boolean | no | Enable Mailgun event receiver. | -| `maintenance_mode_message` | string | no | **(PREMIUM)** Message displayed when instance is in maintenance mode. | -| `maintenance_mode` | boolean | no | **(PREMIUM)** When instance is in maintenance mode, non-administrative users can sign in with read-only access and make read-only API requests. | +| `maintenance_mode_message` **(PREMIUM)** | string | no | Message displayed when instance is in maintenance mode. | +| `maintenance_mode` **(PREMIUM)** | boolean | no | When instance is in maintenance mode, non-administrative users can sign in with read-only access and make read-only API requests. | | `max_artifacts_size` | integer | no | Maximum artifacts size in MB. | | `max_attachment_size` | integer | no | Limit attachment size in MB. | | `max_import_size` | integer | no | Maximum import size in MB. 0 for unlimited. Default = 0 (unlimited) [Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. | | `max_pages_size` | integer | no | Maximum size of pages repositories in MB. | -| `max_personal_access_token_lifetime` | integer | no | **(ULTIMATE SELF)** Maximum allowable lifetime for personal access tokens in days. | +| `max_personal_access_token_lifetime` **(ULTIMATE SELF)** | integer | no | Maximum allowable lifetime for personal access tokens in days. | +| `max_ssh_key_lifetime` **(ULTIMATE SELF)** | integer | no | Maximum allowable lifetime for SSH keys in days. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.6. | | `metrics_method_call_threshold` | integer | no | A method call is only tracked when it takes longer than the given amount of milliseconds. | | `mirror_available` | boolean | no | Allow repository mirroring to configured by project Maintainers. If disabled, only Administrators can configure repository mirroring. | -| `mirror_capacity_threshold` | integer | no | **(PREMIUM)** Minimum capacity to be available before scheduling more mirrors preemptively. | -| `mirror_max_capacity` | integer | no | **(PREMIUM)** Maximum number of mirrors that can be synchronizing at the same time. | -| `mirror_max_delay` | integer | no | **(PREMIUM)** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | -| `npm_package_requests_forwarding` | boolean | no | **(PREMIUM)** Use npmjs.org as a default remote repository when the package is not found in the GitLab Package Registry for npm. | -| `pypi_package_requests_forwarding` | boolean | no | **(PREMIUM)** Use pypi.org as a default remote repository when the package is not found in the GitLab Package Registry for PyPI. | +| `mirror_capacity_threshold` **(PREMIUM)** | integer | no | Minimum capacity to be available before scheduling more mirrors preemptively. | +| `mirror_max_capacity` **(PREMIUM)** | integer | no | Maximum number of mirrors that can be synchronizing at the same time. | +| `mirror_max_delay` **(PREMIUM)** | integer | no | Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | +| `npm_package_requests_forwarding` **(PREMIUM)** | boolean | no | Use npmjs.org as a default remote repository when the package is not found in the GitLab Package Registry for npm. | +| `pypi_package_requests_forwarding` **(PREMIUM)** | boolean | no | Use pypi.org as a default remote repository when the package is not found in the GitLab Package Registry for PyPI. | | `outbound_local_requests_whitelist` | array of strings | no | Define a list of trusted domains or IP addresses to which local requests are allowed when local requests for hooks and services are disabled. | `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | | `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | @@ -364,7 +365,7 @@ listed in the descriptions of the relevant settings. | `project_export_enabled` | boolean | no | Enable project export. | | `prometheus_metrics_enabled` | boolean | no | Enable Prometheus metrics. | | `protected_ci_variables` | boolean | no | CI/CD variables are protected by default. | -| `pseudonymizer_enabled` | boolean | no | **(PREMIUM)** When enabled, GitLab runs a background job that produces pseudonymized CSVs of the GitLab database to upload to your configured object storage directory. +| `pseudonymizer_enabled` **(PREMIUM)** | boolean | no | When enabled, GitLab runs a background job that produces pseudonymized CSVs of the GitLab database to upload to your configured object storage directory. | `push_event_activities_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether individual push events or bulk push events are created. [Bulk push events are created](../user/admin_area/settings/push_event_activities_limit.md) if it surpasses that value. | | `push_event_hooks_limit` | integer | no | Number of changes (branches or tags) in a single push to determine whether webhooks and services fire or not. Webhooks and services aren't submitted if it surpasses that value. | | `rate_limiting_response_text` | string | no | When rate limiting is enabled via the `throttle_*` settings, send this plain text response when a rate limit is exceeded. 'Retry later' is sent if this is blank. | @@ -374,7 +375,7 @@ listed in the descriptions of the relevant settings. | `recaptcha_site_key` | string | required by: `recaptcha_enabled` | Site key for reCAPTCHA. | | `receive_max_input_size` | integer | no | Maximum push size (MB). | | `repository_checks_enabled` | boolean | no | GitLab periodically runs `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | -| `repository_size_limit` | integer | no | **(PREMIUM)** Size limit per repository (MB) | +| `repository_size_limit` **(PREMIUM)** | integer | no | Size limit per repository (MB) | | `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#configure-where-new-repositories-are-stored). New projects are created in one of these stores, chosen by a weighted random selection. | | `repository_storages` | array of strings | no | (GitLab 13.0 and earlier) List of names of enabled storage paths, taken from `gitlab.yml`. New projects are created in one of these stores, chosen at random. | | `require_admin_approval_after_user_signup` | boolean | no | When enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state and has to be explicitly [approved](../user/admin_area/moderate_users.md) by an administrator. | @@ -384,7 +385,7 @@ listed in the descriptions of the relevant settings. | `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. | | `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes. | | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | -| `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared runners per month. | +| `shared_runners_minutes` **(PREMIUM)** | integer | required by: `shared_runners_enabled` | Set the maximum number of pipeline minutes that a group can use on shared runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | | `sidekiq_job_limiter_mode` | string | no | `track` or `compress`. Sets the behavior for [Sidekiq job size limits](../user/admin_area/settings/sidekiq_job_limits.md). Default: 'compress'. | | `sidekiq_job_limiter_compression_threshold_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are compressed before being stored in Redis. Default: 100 000 bytes (100KB). | @@ -392,10 +393,10 @@ listed in the descriptions of the relevant settings. | `sign_in_text` | string | no | Text on the login page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | | `signup_enabled` | boolean | no | Enable registration. Default is `true`. | -| `slack_app_enabled` | boolean | no | **(PREMIUM)** (**If enabled, requires:** `slack_app_id`, `slack_app_secret` and `slack_app_secret`) Enable Slack app. | -| `slack_app_id` | string | required by: `slack_app_enabled` | **(PREMIUM)** The app ID of the Slack-app. | -| `slack_app_secret` | string | required by: `slack_app_enabled` | **(PREMIUM)** The app secret of the Slack-app. | -| `slack_app_verification_token` | string | required by: `slack_app_enabled` | **(PREMIUM)** The verification token of the Slack-app. | +| `slack_app_enabled` **(PREMIUM)** | boolean | no | (**If enabled, requires:** `slack_app_id`, `slack_app_secret` and `slack_app_secret`) Enable Slack app. | +| `slack_app_id` **(PREMIUM)** | string | required by: `slack_app_enabled` | The app ID of the Slack-app. | +| `slack_app_secret` **(PREMIUM)** | string | required by: `slack_app_enabled` | The app secret of the Slack-app. | +| `slack_app_verification_token` **(PREMIUM)** | string | required by: `slack_app_enabled` | The verification token of the Slack-app. | | `snippet_size_limit` | integer | no | Max snippet content size in **bytes**. Default: 52428800 Bytes (50MB).| | `snowplow_app_id` | string | no | The Snowplow site name / application ID. (for example, `gitlab`) | | `snowplow_collector_hostname` | string | required by: `snowplow_enabled` | The Snowplow collector hostname. (for example, `snowplow.trx.gitlab.net`) | @@ -404,9 +405,9 @@ listed in the descriptions of the relevant settings. | `sourcegraph_enabled` | boolean | no | Enables Sourcegraph integration. Default is `false`. **If enabled, requires** `sourcegraph_url`. | | `sourcegraph_public_only` | boolean | no | Blocks Sourcegraph from being loaded on private and internal projects. Default is `true`. | | `sourcegraph_url` | string | required by: `sourcegraph_enabled` | The Sourcegraph instance URL for integration. | -| `spam_check_endpoint_enabled` | boolean | no | Enables Spam Check via external API endpoint. Default is `false`. | -| `spam_check_endpoint_url` | string | no | URL of the external Spam Check service endpoint. | -| `spam_check_api_key` | string | no | The API key used by GitLab for accessing the Spam Check service endpoint. | +| `spam_check_endpoint_enabled` | boolean | no | Enables spam checking using external Spam Check API endpoint. Default is `false`. | +| `spam_check_endpoint_url` | string | no | URL of the external Spamcheck service endpoint. Valid URI schemes are `grpc` or `tls`. Specifying `tls` forces communication to be encrypted.| +| `spam_check_api_key` | string | no | API key used by GitLab for accessing the Spam Check service endpoint. | | `suggest_pipeline_enabled` | boolean | no | Enable pipeline suggestion banner. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. | | `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. | diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md index 0c72ee37348..c0dba71bdc5 100644 --- a/doc/api/status_checks.md +++ b/doc/api/status_checks.md @@ -145,6 +145,6 @@ PUT /projects/:id/external_status_checks/:check_id | `external_url` | string | no | URL of external status check resource | | `protected_branch_ids` | `array<Integer>` | no | IDs of protected branches to scope the rule by | -## Related links +## Related topics - [External status checks](../user/project/merge_requests/status_checks.md). diff --git a/doc/api/topics.md b/doc/api/topics.md index 5e9e1b8fc12..538b9af9374 100644 --- a/doc/api/topics.md +++ b/doc/api/topics.md @@ -161,7 +161,7 @@ curl --request PUT \ --data "name=topic1" \ --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/topics/1" - +``` Example response: @@ -188,3 +188,18 @@ curl --request PUT \ "https://gitlab.example.com/api/v4/topics/1" \ --form "avatar=@/tmp/example.png" ``` + +### Remove a topic avatar + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348148) in GitLab 14.6. + +To remove a topic avatar, use a blank value for the `avatar` attribute. + +Example request: + +```shell +curl --request PUT \ + --data "avatar=" \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/topics/1" +``` diff --git a/doc/api/users.md b/doc/api/users.md index d8effc4d38f..292dc411e5b 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -269,7 +269,9 @@ GET /users/:id Parameters: -- `id` (required) - The ID of a user +| Attribute | Type | Required | Description | +|-----------|---------|----------|------------------| +| `id` | integer | yes | The ID of a user | ```json { @@ -303,7 +305,9 @@ GET /users/:id Parameters: -- `id` (required) - The ID of a user +| Attribute | Type | Required | Description | +|-----------|---------|----------|------------------| +| `id` | integer | yes | The ID of a user | Example Responses: @@ -509,8 +513,10 @@ DELETE /users/:id/identities/:provider Parameters: -- `id` (required) - The ID of the user -- `provider` (required) - External provider name +| Attribute | Type | Required | Description | +|------------|---------|----------|------------------------| +| `id` | integer | yes | The ID of a user | +| `provider` | string | yes | External provider name | ## User deletion @@ -523,10 +529,10 @@ DELETE /users/:id Parameters: -- `id` (required) - The ID of the user -- `hard_delete` (optional) - If true, contributions that would usually be - [moved to the ghost user](../user/profile/account/delete_account.md#associated-records) - are deleted instead, as well as groups owned solely by this user. +| Attribute | Type | Required | Description | +|---------------|---------|----------|----------------------------------------------| +| `id` | integer | yes | The ID of a user | +| `hard_delete` | boolean | no | If true, contributions that would usually be [moved to the ghost user](../user/profile/account/delete_account.md#associated-records) are deleted instead, as well as groups owned solely by this user. | ## List current user (for normal users) @@ -576,14 +582,16 @@ GET /user ## List current user (for admins) -Parameters: - -- `sudo` (optional) - the ID of a user to make the call in their place - ```plaintext GET /user ``` +Parameters: + +| Attribute | Type | Required | Description | +|-----------|---------|----------|--------------------------------------------------| +| `sudo` | integer | no | the ID of a user to make the call in their place | + ```json { "id": 1, @@ -936,7 +944,9 @@ GET /user/keys/:key_id Parameters: -- `key_id` (required) - The ID of an SSH key +| Attribute | Type | Required | Description | +|-----------|--------|----------|----------------------| +| `key_id` | string | yes | The ID of an SSH key | ```json { @@ -957,9 +967,11 @@ POST /user/keys Parameters: -- `title` (required) - new SSH key's title -- `key` (required) - new SSH key -- `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) +| Attribute | Type | Required | Description | +|--------------|--------|----------|--------------------------------------------------------------------------------| +| `title` | string | yes | new SSH key's title | +| `key` | string | yes | new SSH key | +| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | ```json { @@ -995,10 +1007,12 @@ POST /users/:id/keys Parameters: -- `id` (required) - ID of specified user -- `title` (required) - new SSH key's title -- `key` (required) - new SSH key -- `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) +| Attribute | Type | Required | Description | +|--------------|---------|----------|--------------------------------------------------------------------------------| +| `id` | integer | yes | ID of specified user | +| `title` | string | yes | new SSH key's title | +| `key` | string | yes | new SSH key | +| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) | NOTE: This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events). **(PREMIUM)** @@ -1014,7 +1028,9 @@ DELETE /user/keys/:key_id Parameters: -- `key_id` (required) - SSH key ID +| Attribute | Type | Required | Description | +|-----------|---------|----------|-------------| +| `key_id` | integer | yes | SSH key ID | ## Delete SSH key for given user @@ -1026,8 +1042,10 @@ DELETE /users/:id/keys/:key_id Parameters: -- `id` (required) - ID of specified user -- `key_id` (required) - SSH key ID +| Attribute | Type | Required | Description | +|-----------|---------|----------|----------------------| +| `id` | integer | yes | ID of specified user | +| `key_id` | integer | yes | SSH key ID | ## List all GPG keys @@ -1092,8 +1110,8 @@ POST /user/gpg_keys Parameters: | Attribute | Type | Required | Description | -| --------- | ------ | -------- | --------------- | -| key | string | yes | The new GPG key | +|-----------|--------|----------|-----------------| +| `key` | string | yes | The new GPG key | ```shell curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \ @@ -1288,7 +1306,9 @@ GET /users/:id/emails Parameters: -- `id` (required) - ID of specified user +| Attribute | Type | Required | Description | +|-----------|---------|----------|----------------------| +| `id` | integer | yes | ID of specified user | ## Single email @@ -1300,7 +1320,9 @@ GET /user/emails/:email_id Parameters: -- `email_id` (required) - email ID +| Attribute | Type | Required | Description | +|------------|---------|----------|-------------| +| `email_id` | integer | yes | Email ID | ```json { @@ -1320,7 +1342,9 @@ POST /user/emails Parameters: -- `email` (required) - email address +| Attribute | Type | Required | Description | +|-----------|--------|----------|-------------| +| `email` | string | yes | Email address | ```json { @@ -1353,9 +1377,11 @@ POST /users/:id/emails Parameters: -- `id` (required) - ID of specified user -- `email` (required) - email address -- `skip_confirmation` (optional) - Skip confirmation and assume email is verified - true or false (default) +| Attribute | Type | Required | Description | +|---------------------|---------|----------|---------------------------------------------------------------------------| +| `id` | string | yes | ID of specified user | +| `email` | string | yes | Email address | +| `skip_confirmation` | boolean | no | Skip confirmation and assume email is verified - true or false (default) | ## Delete email for current user @@ -1368,7 +1394,9 @@ DELETE /user/emails/:email_id Parameters: -- `email_id` (required) - email ID +| Attribute | Type | Required | Description | +|------------|---------|----------|-------------| +| `email_id` | integer | yes | Email ID | ## Delete email for given user @@ -1380,8 +1408,10 @@ DELETE /users/:id/emails/:email_id Parameters: -- `id` (required) - ID of specified user -- `email_id` (required) - email ID +| Attribute | Type | Required | Description | +|------------|---------|----------|----------------------| +| `id` | integer | yes | ID of specified user | +| `email_id` | integer | yes | Email ID | ## Block user @@ -1393,7 +1423,9 @@ POST /users/:id/block Parameters: -- `id` (required) - ID of specified user +| Attribute | Type | Required | Description | +|------------|---------|----------|----------------------| +| `id` | integer | yes | ID of specified user | Returns: @@ -1413,7 +1445,9 @@ POST /users/:id/unblock Parameters: -- `id` (required) - ID of specified user +| Attribute | Type | Required | Description | +|------------|---------|----------|----------------------| +| `id` | integer | yes | ID of specified user | Returns `201 OK` on success, `404 User Not Found` is user cannot be found or `403 Forbidden` when trying to unblock a user blocked by LDAP synchronization. @@ -1430,7 +1464,9 @@ POST /users/:id/deactivate Parameters: -- `id` (required) - ID of specified user +| Attribute | Type | Required | Description | +|------------|---------|----------|----------------------| +| `id` | integer | yes | ID of specified user | Returns: @@ -1453,7 +1489,9 @@ POST /users/:id/activate Parameters: -- `id` (required) - ID of specified user +| Attribute | Type | Required | Description | +|------------|---------|----------|----------------------| +| `id` | integer | yes | ID of specified user | Returns: @@ -1572,7 +1610,9 @@ POST /users/:id/approve Parameters: -- `id` (required) - ID of specified user +| Attribute | Type | Required | Description | +|------------|---------|----------|----------------------| +| `id` | integer | yes | ID of specified user | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/approve" @@ -1583,6 +1623,7 @@ Returns: - `201 Created` on success. - `404 User Not Found` if user cannot be found. - `403 Forbidden` if the user cannot be approved because they are blocked by an administrator or by LDAP synchronization. +- `409 Conflict` if the user has been deactivated. Example Responses: @@ -1731,10 +1772,6 @@ It revokes an impersonation token. DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id ``` -```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1" -``` - Parameters: | Attribute | Type | Required | Description | @@ -1742,6 +1779,10 @@ Parameters: | `user_id` | integer | yes | The ID of the user | | `impersonation_token_id` | integer | yes | The ID of the impersonation token | +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1" +``` + ## Create a personal access token **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17176) in GitLab 13.6. diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 3fba95c1fb3..da269073905 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -11,7 +11,7 @@ The GitLab API v3 was [removed](https://gitlab.com/gitlab-org/gitlab-foss/-/issu For information about the current version of the GitLab API, read the [API documentation](index.md). -## Related links +## Related topics - [GitLab v3 API documentation](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-16-stable/doc/api/index.md) - [Migration guide](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/11-0-stable/doc/api/v3_to_v4.md) from |