diff options
Diffstat (limited to 'doc')
1888 files changed, 21466 insertions, 13691 deletions
diff --git a/doc/.vale/gitlab/Prerequisites.yml b/doc/.vale/gitlab/Prerequisites.yml new file mode 100644 index 00000000000..239f9277c4d --- /dev/null +++ b/doc/.vale/gitlab/Prerequisites.yml @@ -0,0 +1,14 @@ +--- +# Error: gitlab.Prerequisites +# +# The "Prerequisites:" line should always be plural. +# +# For a list of all options, see https://vale.sh/docs/topics/styles/ +extends: existence +message: "Pluralize 'Prerequisites', even if it includes only one item." +link: https://docs.gitlab.com/ee/development/documentation/topic_types/task.html#task-prerequisites +level: warning +nonword: true +scope: text +raw: + - '^Prerequisite:' diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml index 07f0f9d617f..fe15b8fc42c 100644 --- a/doc/.vale/gitlab/SubstitutionWarning.yml +++ b/doc/.vale/gitlab/SubstitutionWarning.yml @@ -28,14 +28,16 @@ swap: e-mail: "email" emojis: "emoji" ex: "for example" - file name: "filename" + filename: "file name" filesystem: "file system" + fullscreen: "full screen" info: "information" installation from source: self-compiled installation installations from source: self-compiled installations it is recommended: "you should" logged in user: "authenticated user" logged-in user: "authenticated user" + machine-learning: "machine learning" modal dialog: "dialog" modal window: "dialog" modal: "dialog" diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 575dc713b51..cc02821b6d6 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -177,6 +177,7 @@ Codecov codenames Codepen CodeSandbox +Codey Cognito Coinbase colocate @@ -883,7 +884,6 @@ sharded sharding SHAs shfmt -Shimo Shippo Shopify Sidekiq diff --git a/doc/administration/admin_area.md b/doc/administration/admin_area.md index a27fc04ff8f..ff18ac8ff3a 100644 --- a/doc/administration/admin_area.md +++ b/doc/administration/admin_area.md @@ -1,15 +1,15 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Admin Area **(FREE SELF)** The Admin Area provides a web UI to manage and configure features of GitLab -self-managed instances. If you are an administrator,to access the Admin Area: +self-managed instances. If you are an administrator, to access the Admin Area: +- In GitLab 16.7 and later: on the left sidebar, at the bottom, select **Admin Area**. - In GitLab 16.1 and later: on the left sidebar, select **Search or go to**, then select **Admin Area**. - In GitLab 16.0 and earlier: on the top bar, select **Main menu > Admin**. @@ -22,8 +22,7 @@ You can administer all projects in the GitLab instance from the Admin Area's Pro To access the Projects page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Projects**. 1. Select the **All**, **Private**, **Internal**, or **Public** tab to list only projects of that criteria. @@ -74,8 +73,7 @@ You can combine the filter options. For example, to list only public projects wi You can administer all users in the GitLab instance from the Admin Area's Users page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. To list users matching a specific criteria, select one of the following tabs on the **Users** page: @@ -119,8 +117,7 @@ This allows the administrator to "see what the user sees," and take actions on b You can impersonate a user in the following ways: - Through the UI: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Impersonate**. @@ -138,8 +135,7 @@ By default, impersonation is enabled. GitLab can be configured to [disable imper When using authentication providers, administrators can see the identities for a user: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Identities**. @@ -185,8 +181,7 @@ GitLab billing is based on the number of [**Billable users**](../subscriptions/s You must be an administrator to manually add emails to users: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Locate the user and select them. 1. Select **Edit**. @@ -202,8 +197,7 @@ The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and By default, users can create top level groups. To prevent a user from creating a top level group: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Locate the user and select them. 1. Select **Edit**. @@ -218,8 +212,7 @@ You can administer all groups in the GitLab instance from the Admin Area's Group To access the Groups page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Groups**. For each group, the page displays their name, description, size, number of projects in the group, @@ -238,22 +231,20 @@ To [Create a new group](../user/group/index.md#create-a-group) select **New grou - > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.4. - > Merging topics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366884) in GitLab 15.5. -[Topics](../user/project/working_with_projects.md#explore-topics) are used to categorize and find similar projects. +[Topics](../user/project/settings/project_features_permissions.md#project-topics) are used to categorize and find similar projects. ### View all topics To view all topics in the GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. For each topic, the page displays its name and the number of projects labeled with the topic. ### Search for topics -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. In the search box, enter your search criteria. The topic search is case-insensitive and applies partial matching. @@ -262,8 +253,7 @@ For each topic, the page displays its name and the number of projects labeled wi To create a topic: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. Select **New topic**. 1. Enter the **Topic slug (name)** and **Topic title**. @@ -282,8 +272,7 @@ Do not include sensitive information in the name of a topic. You can edit a topic's name, title, description, and avatar at any time. To edit a topic: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. Select **Edit** in that topic's row. 1. Edit the topic slug (name), title, description, or avatar. @@ -294,8 +283,7 @@ To edit a topic: If you no longer need a topic, you can permanently remove it. To remove a topic: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. To remove a topic, select **Remove** in that topic's row. @@ -307,8 +295,7 @@ After a merged topic is deleted, you cannot restore it. To merge topics: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Topics**. 1. Select **Merge topics**. 1. From the **Source topic** dropdown list, select the topic you want to merge and remove. @@ -322,8 +309,7 @@ page. For more details, see [Gitaly](gitaly/index.md). To access the **Gitaly Servers** page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Gitaly Servers**. For each Gitaly server, the following details are listed: @@ -347,8 +333,7 @@ You can administer all runners in the GitLab instance from the Admin Area's **Ru To access the **Runners** page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Runners**. #### Search and filter runners @@ -374,8 +359,7 @@ You can also filter runners by status, type, and tag. To filter: You can delete multiple runners at the same time. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Runners**. 1. To the left of the runners you want to delete, select the checkbox. To select all of the runners on the page, select the checkbox above @@ -405,8 +389,7 @@ You can administer all jobs in the GitLab instance from the Admin Area's Jobs pa To access the Jobs page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Jobs**. All jobs are listed, in descending order of job ID. 1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** tab to list only jobs of that status. diff --git a/doc/administration/analytics/dev_ops_reports.md b/doc/administration/analytics/dev_ops_reports.md index a5a3120489d..057dc5d48ee 100644 --- a/doc/administration/analytics/dev_ops_reports.md +++ b/doc/administration/analytics/dev_ops_reports.md @@ -1,19 +1,18 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DevOps Reports **(FREE SELF)** DevOps Reports give you an overview of your entire instance's adoption of -[Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) +[DevOps](https://about.gitlab.com/topics/devops/) from planning to monitoring. To see DevOps Reports: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Analytics > DevOps Reports**. ## DevOps Score diff --git a/doc/administration/analytics/index.md b/doc/administration/analytics/index.md index 5ba14222165..c5431efaf9b 100644 --- a/doc/administration/analytics/index.md +++ b/doc/administration/analytics/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance-level analytics **(FREE SELF)** @@ -12,14 +12,13 @@ Instance-level analytics provide insights into the feature and data usage of you ## View instance-level analytics -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To view instance-level analytics: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Analytics**, then one of the available analytics: - [DevOps Reports](dev_ops_reports.md): Provides an overview of your entire instance's feature usage. diff --git a/doc/administration/analytics/usage_trends.md b/doc/administration/analytics/usage_trends.md index 20b732d028d..52ea20a2954 100644 --- a/doc/administration/analytics/usage_trends.md +++ b/doc/administration/analytics/usage_trends.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Usage Trends **(FREE SELF)** @@ -19,8 +19,7 @@ Usage Trends data refreshes daily. To view Usage Trends: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Analytics > Usage Trends**. ## Total counts diff --git a/doc/administration/appearance.md b/doc/administration/appearance.md index ceb4a4a30e9..3599c444134 100644 --- a/doc/administration/appearance.md +++ b/doc/administration/appearance.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Appearance **(FREE SELF)** @@ -9,8 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Several options are available for customizing the appearance of a self-managed instance of GitLab. To access these settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Appearance**. ## Navigation bar @@ -83,8 +82,7 @@ description, and icon. To configure the PWA settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Appearance**. 1. Scroll to the **Progressive Web App (PWA)** section. 1. Complete the fields. diff --git a/doc/administration/application_settings_cache.md b/doc/administration/application_settings_cache.md index c14562c0e18..91392b2f0d9 100644 --- a/doc/administration/application_settings_cache.md +++ b/doc/administration/application_settings_cache.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application cache interval **(FREE SELF)** diff --git a/doc/administration/audit_event_streaming.md b/doc/administration/audit_event_streaming.md deleted file mode 100644 index d6a6725210d..00000000000 --- a/doc/administration/audit_event_streaming.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'audit_event_streaming/index.md' -remove_date: '2023-09-12' ---- - -This document was moved to [another location](audit_event_streaming/index.md). - -<!-- This redirect file can be deleted after <2023-09-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/administration/audit_event_streaming/audit_event_types.md b/doc/administration/audit_event_streaming/audit_event_types.md index 88212045d8e..28cab04553a 100644 --- a/doc/administration/audit_event_streaming/audit_event_types.md +++ b/doc/administration/audit_event_streaming/audit_event_types.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- <!--- @@ -47,6 +47,7 @@ Audit event types belong to the following product categories. | [`create_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | | [`create_http_namespace_filter`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136047) | Event triggered when a namespace filter for an external audit event destination for a top-level group is created.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.6](https://gitlab.com/gitlab-org/gitlab/-/issues/424176) | | [`create_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123882) | Event triggered when an instance level external audit event destination is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | +| [`delete_http_namespace_filter`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136302) | Event triggered when a namespace filter for an external audit event destination for a top-level group is deleted.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/424177) | | [`destroy_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | | [`destroy_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125846) | Event triggered when an instance level external audit event destination is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | | [`event_type_filters_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113081) | Event triggered when a new audit events streaming event type filter is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.10](https://gitlab.com/gitlab-org/gitlab/-/issues/344848) | @@ -54,12 +55,21 @@ Audit event types belong to the following product categories. | [`google_cloud_logging_configuration_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | | [`google_cloud_logging_configuration_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | | [`google_cloud_logging_configuration_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025) | Triggered when Google Cloud Logging configuration is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/409422) | +| [`instance_amazon_s3_configuration_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137651) | Triggered when instance Amazon S3 configuration for audit events streaming is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/423235) | +| [`instance_amazon_s3_configuration_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138318) | Triggered when instance-level Amazon S3 configuration for audit events streaming is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/423235) | +| [`instance_amazon_s3_configuration_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138310) | Triggered when instance-level Amazon S3 configuration for audit events streaming is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/423235) | | [`instance_google_cloud_logging_configuration_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130663) | Triggered when Instance level Google Cloud Logging configuration is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.4](https://gitlab.com/gitlab-org/gitlab/-/issues/423038) | | [`instance_google_cloud_logging_configuration_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131752) | Triggered when instance level Google Cloud Logging configuration is deleted.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/423040) | | [`instance_google_cloud_logging_configuration_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131790) | Triggered when instance level Google Cloud Logging configuration is updated.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/423039) | | [`update_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74632) | Event triggered when an external audit event destination is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/344664) | | [`update_instance_event_streaming_destination`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125846) | Event triggered when an instance level external audit event destination is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/gitlab/-/issues/404730) | +### Authorization + +| Name | Description | Saved to database | Streamed | Introduced in | +|:-----|:------------|:------------------|:---------|:--------------| +| [`member_role_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137087) | Event triggered when a custom role is created.| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/388934) | + ### Code review | Name | Description | Saved to database | Streamed | Introduced in | @@ -170,6 +180,9 @@ Audit event types belong to the following product categories. | [`ci_group_variable_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a CI variable is created at a group level| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | | [`ci_group_variable_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a group's CI variable is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | | [`ci_group_variable_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a group's CI variable is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | +| [`ci_instance_variable_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131882) | When an instance level CI variable is created| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/8070) | +| [`ci_instance_variable_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131882) | When an instance level CI varialbe is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/8070) | +| [`ci_instance_variable_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131882) | When an instance level CI variable is changed| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.5](https://gitlab.com/gitlab-org/gitlab/-/issues/8070) | | [`ci_variable_created`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a CI variable is created at a project level| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | | [`ci_variable_deleted`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a project's CI variable is deleted| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | | [`ci_variable_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91983) | Triggered when a project's CI variable is updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.2](https://gitlab.com/gitlab-org/gitlab/-/issues/363090) | @@ -305,6 +318,7 @@ Audit event types belong to the following product categories. | Name | Description | Saved to database | Streamed | Introduced in | |:-----|:------------|:------------------|:---------|:--------------| | [`project_feature_model_experiments_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121027) | Model experiments access level was updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.1](https://gitlab.com/gitlab-org/gitlab/-/issues/412384) | +| [`project_feature_model_registry_access_level_updated`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138399) | Model registry access level was updated| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) | ### Not categorized @@ -402,7 +416,7 @@ Audit event types belong to the following product categories. | [`user_access_locked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124169) | Event triggered when user access to the instance is locked| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/244) | | [`user_access_unlocked`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124973) | Event triggered when user access to the instance is unlocked| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [16.2](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/244) | | [`user_disable_two_factor`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89598) | Audit event triggered when user disables two factor authentication| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.1](https://gitlab.com/gitlab-org/gitlab/-/issues/238177) | -| [`user_enable_admin_mode`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104754) | Event triggered on enabling admin mode| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/362101) | +| [`user_enable_admin_mode`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104754) | Event triggered on enabling Admin Mode| **{check-circle}** Yes | **{check-circle}** Yes | GitLab [15.7](https://gitlab.com/gitlab-org/gitlab/-/issues/362101) | ### Team planning diff --git a/doc/administration/audit_event_streaming/examples.md b/doc/administration/audit_event_streaming/examples.md index b0d6190211c..ed7c0d5d97d 100644 --- a/doc/administration/audit_event_streaming/examples.md +++ b/doc/administration/audit_event_streaming/examples.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit event streaming examples @@ -40,7 +40,7 @@ X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN> X-Gitlab-Audit-Event-Type: repository_git_operation ``` -### Example payloads for SSH events +### Example payloads for Git over SSH events Fetch: @@ -106,7 +106,7 @@ Push: } ``` -### Example payloads for SSH events with Deploy Key +### Example payloads for Git over SSH events with Deploy Key > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363876) in GitLab 15.3. @@ -142,7 +142,7 @@ Fetch: } ``` -### Example payloads for HTTP and HTTPS events +### Example payloads for Git over HTTP and HTTPS events Fetch: @@ -208,7 +208,7 @@ Push: } ``` -### Example payloads for HTTP and HTTPS events with Deploy Token +### Example payloads for Git over HTTP and HTTPS events with Deploy Token Fetch: diff --git a/doc/administration/audit_event_streaming/graphql_api.md b/doc/administration/audit_event_streaming/graphql_api.md index 58668902b8e..06cae34b7ef 100644 --- a/doc/administration/audit_event_streaming/graphql_api.md +++ b/doc/administration/audit_event_streaming/graphql_api.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit event streaming GraphQL API **(ULTIMATE ALL)** @@ -378,7 +378,7 @@ Event streaming is enabled if: List all Google Cloud Logging configuration destinations for a top-level group. -Prerequisite: +Prerequisites: - Owner role for a top-level group. @@ -410,7 +410,7 @@ You need the ID values returned by this query for the update and delete mutation Update a Google Cloud Logging configuration destinations for a top-level group. -Prerequisite: +Prerequisites: - Owner role for a top-level group. @@ -446,7 +446,7 @@ Delete streaming destinations for a top-level group. When the last destination is successfully deleted, streaming is disabled for the group. -Prerequisite: +Prerequisites: - Owner role for a top-level group. @@ -786,7 +786,7 @@ Event streaming is enabled if: List all Google Cloud Logging configuration destinations for an instance. -Prerequisite: +Prerequisites: - You have administrator access to the instance. @@ -815,7 +815,7 @@ You need the ID values returned by this query for the update and delete mutation Update the Google Cloud Logging configuration destinations for an instance. -Prerequisite: +Prerequisites: - You have administrator access to the instance. @@ -851,7 +851,7 @@ Delete streaming destinations for an instance. When the last destination is successfully deleted, streaming is disabled for the instance. -Prerequisite: +Prerequisites: - You have administrator access to the instance. diff --git a/doc/administration/audit_event_streaming/index.md b/doc/administration/audit_event_streaming/index.md index 09474db1e08..71ae33b3d87 100644 --- a/doc/administration/audit_event_streaming/index.md +++ b/doc/administration/audit_event_streaming/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit event streaming **(ULTIMATE ALL)** @@ -49,7 +49,7 @@ To add streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **HTTP endpoint** to show the section for adding destinations. 1. In the **Name** and **Destination URL** fields, add a destination name and URL. 1. Optional. Locate the **Custom HTTP headers** table. @@ -68,7 +68,7 @@ To list the streaming destinations for a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand it and see all the custom HTTP headers. #### Update an HTTP destination @@ -81,7 +81,7 @@ To update a streaming destination's name: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. In the **Name** fields, add a destination name to update. 1. Select **Save** to update the streaming destination. @@ -90,7 +90,7 @@ To update a streaming destination's custom HTTP headers: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Locate the **Custom HTTP headers** table. 1. Locate the header that you wish to update. @@ -146,7 +146,7 @@ To list streaming destinations and see the verification tokens: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select the **Streams**. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Locate the **Verification token** input. @@ -169,6 +169,25 @@ To update a streaming destination's event filters: 1. Select the dropdown list and select or clear the required event types. 1. Select **Save** to update the event filters. +#### Update namespace filters + +> Namespace filtering in the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390133) in GitLab 16.7. + +When this feature is enabled for a group, you can permit users to filter streamed audit events per destination. +If the feature is enabled with no filters, the destination receives all audit events. + +A streaming destination that has a namespace filter set has a **filtered** (**{filter}**) label. + +To update a streaming destination's namespace filters: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Secure > Audit events**. +1. On the main area, select the **Streams** tab. +1. Select the stream to expand. +1. Locate the **Filter by groups or projects** dropdown list. +1. Select the dropdown list and select or clear the required namespaces. +1. Select **Save** to update the namespace filter. + #### Override default content type header By default, streaming destinations use a `content-type` header of `application/x-www-form-urlencoded`. However, you @@ -204,7 +223,7 @@ To add Google Cloud Logging streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **Google Cloud Logging** to show the section for adding destinations. 1. Enter a random string to use as a name for the new destination. 1. Enter the Google project ID, Google client email, and Google private key from previously-created Google Cloud service account key to add to the new destination. @@ -221,7 +240,7 @@ To list Google Cloud Logging streaming destinations for a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand and see all the fields. #### Update a Google Cloud Logging destination @@ -236,7 +255,7 @@ To update Google Cloud Logging streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand. 1. Enter a random string to use as a name for the destination. 1. Enter the Google project ID and Google client email from previously-created Google Cloud service account key to update the destination. @@ -261,11 +280,8 @@ To delete Google Cloud Logging streaming destinations to a top-level group: ### AWS S3 destinations -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132603) in GitLab 16.6 [with a flag](../feature_flags.md) named `allow_streaming_audit_events_to_amazon_s3`. Enabled by default. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per group, an administrator can [disable the feature flag](../feature_flags.md) named `allow_streaming_audit_events_to_amazon_s3`. -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132603) in GitLab 16.6 [with a flag](../feature_flags.md) named `allow_streaming_audit_events_to_amazon_s3`. Enabled by default. +> - [Feature flag `allow_streaming_audit_events_to_amazon_s3`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137391) removed in GitLab 16.7. Manage AWS S3 destinations for top-level groups. @@ -287,7 +303,7 @@ To add AWS S3 streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **AWS S3** to show the section for adding destinations. 1. Enter a random string to use as a name for the new destination. 1. Enter the Access Key ID, Secret Access Key, Bucket Name, and AWS Region from previously-created AWS access key and bucket to add to the new destination. @@ -303,7 +319,7 @@ To list AWS S3 streaming destinations for a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the AWS S3 stream to expand and see all the fields. #### Update a AWS S3 destination @@ -316,7 +332,7 @@ To update AWS S3 streaming destinations to a top-level group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Audit events**. -1. On the main area, select **Streams** tab. +1. On the main area, select the **Streams** tab. 1. Select the AWS S3 stream to expand. 1. Enter a random string to use as a name for the destination. 1. Enter the Access Key ID, Secret Access Key, Bucket Name, and AWS Region from previously-created AWS access key and bucket to update the destination. @@ -360,10 +376,9 @@ Prerequisites: To add a streaming destination for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **HTTP endpoint** to show the section for adding destinations. 1. In the **Name** and **Destination URL** fields, add a destination name and URL. 1. Optional. To add custom HTTP headers, select **Add header** to create a new name and value pair, and input their values. Repeat this step for as many name and value pairs are required. You can add up to 20 headers per streaming destination. @@ -380,10 +395,9 @@ Prerequisites: To list the streaming destinations for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand it and see all the custom HTTP headers. #### Update an HTTP destination @@ -394,20 +408,18 @@ Prerequisites: To update a instance streaming destination's name: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. In the **Name** fields, add a destination name to update. 1. Select **Save** to update the streaming destination. To update a instance streaming destination's custom HTTP headers: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Locate the **Custom HTTP headers** table. 1. Locate the header that you wish to update. @@ -427,9 +439,8 @@ Prerequisites: To delete the streaming destinations for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Select **Delete destination**. @@ -437,9 +448,8 @@ To delete the streaming destinations for an instance: To delete only the custom HTTP headers for a streaming destination: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. 1. To the right of the item, **Edit** (**{pencil}**). 1. Locate the **Custom HTTP headers** table. @@ -465,9 +475,8 @@ Prerequisites: To list streaming destinations for an instance and see the verification tokens: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. 1. View the verification token on the right side of each item. @@ -482,9 +491,8 @@ A streaming destination that has an event type filter set has a **filtered** (** To update a streaming destination's event filters: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. On the main area, select the **Streams** tab. 1. Select the stream to expand. 1. Locate the **Filter by audit event type** dropdown list. @@ -524,10 +532,9 @@ Prerequisites: To add Google Cloud Logging streaming destinations to an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select **Add streaming destination** and select **Google Cloud Logging** to show the section for adding destinations. 1. Enter a random string to use as a name for the new destination. 1. Enter the Google project ID, Google client email, and Google private key from previously-created Google Cloud service account key to add to the new destination. @@ -542,10 +549,9 @@ Prerequisites: To list Google Cloud Logging streaming destinations for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand and see all the fields. #### Update a Google Cloud Logging destination @@ -556,10 +562,9 @@ Prerequisites: To update Google Cloud Logging streaming destinations to an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand. 1. Enter a random string to use as a name for the destination. 1. Enter the Google project ID and Google client email from previously-created Google Cloud service account key to update the destination. @@ -575,14 +580,92 @@ Prerequisites: To delete Google Cloud Logging streaming destinations to an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. -1. On the main area, select **Streams** tab. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. 1. Select the Google Cloud Logging stream to expand. 1. Select **Delete destination**. 1. Confirm by selecting **Delete destination** in the dialog. +### AWS S3 destinations + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138245) in GitLab 16.7 [with a flag](../feature_flags.md) named `allow_streaming_instance_audit_events_to_amazon_s3`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To enable the feature, an administrator can [enable the feature flag](../feature_flags.md) named +`allow_streaming_instance_audit_events_to_amazon_s3`. On GitLab.com, this feature is not available. + +Manage AWS S3 destinations for entire instance. + +#### Prerequisites + +Before setting up AWS S3 streaming audit events, you must: + +1. Create a access key for AWS with the appropriate credentials and permissions. This account is used to configure audit log streaming authentication. + For more information, see [Managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html?icmpid=docs_iam_console#Using_CreateAccessKey). +1. Create a AWS S3 bucket. This bucket is used to store audit log streaming data. For more information, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) + +#### Add a new AWS S3 destination + +Prerequisites: + +- Administrator access on the instance. + +To add AWS S3 streaming destinations to an instance: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select **Add streaming destination** and select **AWS S3** to show the section for adding destinations. +1. Enter a random string to use as a name for the new destination. +1. Enter the Access Key ID, Secret Access Key, Bucket Name, and AWS Region from previously-created AWS access key and bucket to add to the new destination. +1. Select **Add** to add the new streaming destination. + +#### List AWS S3 destinations + +Prerequisites: + +- Administrator access on the instance. + +To list AWS S3 streaming destinations for an instance. + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select the AWS S3 stream to expand and see all the fields. + +#### Update an AWS S3 destination + +Prerequisites: + +- Administrator access on the instance. + +To update AWS S3 streaming destinations to an instance: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select the AWS S3 stream to expand. +1. Enter a random string to use as a name for the destination. +1. Enter the Access Key ID, Secret Access Key, Bucket Name, and AWS Region from previously-created AWS access key and bucket to update the destination. +1. Select **Add a new Secret Access Key** and enter a AWS Secret Access Key to update the Secret Access Key. +1. Select **Save** to update the streaming destination. + +#### Delete an AWS S3 streaming destination + +Prerequisites: + +- Administrator access on the instance. + +To delete AWS S3 streaming destinations on an instance: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. +1. On the main area, select the **Streams** tab. +1. Select the AWS S3 stream to expand. +1. Select **Delete destination**. +1. Confirm by selecting **Delete destination** in the dialog. + ## Payload schema > Documentation for an audit event streaming schema was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358149) in GitLab 15.3. diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index ba1a4ca05c4..d40e2c86dc9 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit events **(PREMIUM ALL)** @@ -37,7 +37,7 @@ Audit events can be viewed at the group, project, instance, and sign-in level. E To view a group's audit events: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Audit events**. +1. Select **Secure > Audit events**. 1. Filter the audit events by the member of the project (user) who performed the action and date range. Group audit events can also be accessed using the [Group Audit Events API](../api/audit_events.md#group-audit-events). Group audit event queries are limited to a maximum of 30 days. @@ -45,7 +45,7 @@ Group audit events can also be accessed using the [Group Audit Events API](../ap ### Project audit events 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Secure > Audit events**. +1. Select **Secure > Audit events**. 1. Filter the audit events by the member of the project (user) who performed the action and date range. Project audit events can also be accessed using the [Project Audit Events API](../api/audit_events.md#project-audit-events). Project audit event queries are limited to a maximum of 30 days. @@ -55,9 +55,8 @@ Project audit events can also be accessed using the [Project Audit Events API](. You can view audit events from user actions across an entire GitLab instance. To view instance audit events: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. Filter by the following: - Member of the project (user) who performed the action - Group @@ -82,9 +81,8 @@ After upgrading to a paid tier, you can also see successful sign-in events on au You can export the current view (including filters) of your instance audit events as a CSV(comma-separated values) file. To export the instance audit events to CSV: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Audit Events**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Audit Events**. 1. Select the available search filters. 1. Select **Export as CSV**. diff --git a/doc/administration/audit_reports.md b/doc/administration/audit_reports.md index 84425dd7b89..bfd061eb760 100644 --- a/doc/administration/audit_reports.md +++ b/doc/administration/audit_reports.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to create evidence artifacts typically requested by a 3rd party auditor.' --- diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index 09d68e82782..45475ab7b16 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auditor users **(PREMIUM SELF)** @@ -34,9 +34,8 @@ To create a new user account with auditor access (or change an existing user): To create a user account with auditor access: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. 1. Create a new user or edit an existing one. Set **Access Level** to **Auditor**. 1. If you created a user, select **Create user**. For an existing user, select **Save changes**. diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index cbb9663cfa6..36331799fec 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Atlassian as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index 2e2d9ec3d28..096243419c1 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -1,8 +1,7 @@ --- -type: concepts, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use AWS Cognito as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 574b8967b02..ae9a46650f6 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -1,11 +1,10 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Use Atlassian Crowd as an OAuth 2.0 authentication provider (deprecated) **(FREE SELF)** +# Use Atlassian Crowd as an authentication provider (deprecated) **(FREE SELF)** WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/369117) in GitLab 15.3 and is planned for diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 037a2943b2e..95268f6f39b 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -1,8 +1,7 @@ --- -type: index stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab authentication and authorization **(FREE SELF)** diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 67f72b3344e..f4e7ea09615 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use JWT as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 5b9bddc34c5..8338760ecb5 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Secure LDAP **(FREE SELF)** diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 0c42ce90346..62395ebdcd2 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate LDAP with GitLab **(FREE SELF)** diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 0a96e904f24..9cd306d979f 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting LDAP **(FREE SELF)** @@ -167,9 +166,8 @@ may see the following message: `Access denied for your LDAP account`. We have a workaround, based on toggling the access level of affected users: -1. As an administrator, on the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. 1. Select the name of the affected user. 1. In the upper-right corner, select **Edit**. 1. Change the user's access level from `Regular` to `Administrator` (or vice versa). @@ -225,9 +223,8 @@ field contains no data: To resolve this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, go to **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand both of the following: - **Account and limit**. - **Sign-up restrictions**. @@ -369,8 +366,7 @@ things to debug the situation. - Ensure the correct [LDAP group link is added to the GitLab group](ldap_synchronization.md#add-group-links). - Check that the user has an LDAP identity: 1. Sign in to GitLab as an administrator user. - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Users**. 1. Search for the user. 1. Open the user by selecting their name. Do not select **Edit**. @@ -661,6 +657,25 @@ end You can then [run a UserSync](#sync-all-users) **(PREMIUM SELF)** to sync the latest DN for each of these users. +## Could not authenticate from AzureActivedirectoryV2 because "Invalid grant" + +When converting from LDAP to SAML you might get an error in Azure that states the following: + +```plaintext +Authentication failure! invalid_credentials: OAuth2::Error, invalid_grant. +``` + +This issue occurs when both of the following are true: + +- LDAP identities still exist for users after SAML has been configured for those users. +- You disable LDAP for those users. + +You would receive both LDAP and Azure metadata in the logs, which generates the error in Azure. + +The workaround for a single user is to remove the LDAP identity from the user in **Admin > Identities**. + +To remove multiple LDAP identities, use either of the workarounds for the [`Could not authenticate you from Ldapmain because "Unknown provider"` error](#could-not-authenticate-you-from-ldapmain-because-unknown-provider). + ## `Could not authenticate you from Ldapmain because "Unknown provider"` You can receive the following error when authenticating with an LDAP server: diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index 0a1c0bd9689..75c257c1009 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # LDAP synchronization **(PREMIUM SELF)** @@ -501,10 +501,9 @@ When global group memberships lock is enabled: To enable global group memberships lock: 1. [Configure LDAP](index.md#configure-ldap). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility and access controls** section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Visibility and access controls**. 1. Ensure the **Lock memberships to LDAP synchronization** checkbox is selected. ### Change LDAP group synchronization settings management @@ -514,9 +513,8 @@ By default, group members with the Owner role can manage [LDAP group synchroniza GitLab administrators can remove this permission from group Owners: 1. [Configure LDAP](index.md#configure-ldap). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Ensure the **Allow group owners to manage LDAP-related settings** checkbox is not checked. diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index d3ecd2771e6..d20c9ee4412 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -1,18 +1,17 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use OpenID Connect as an OAuth 2.0 authentication provider **(FREE SELF)** -GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) +You can use GitLab as a client application with [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider. To enable the OpenID Connect OmniAuth provider, you must register your application with an OpenID Connect provider. -The OpenID Connect provides you with a client's details and secret for you to use. +The OpenID Connect provider provides you with a client's details and secret for you to use. 1. On your GitLab server, open the configuration file. diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index f4c64efb7b4..1d4ca87bcc0 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Smartcard authentication **(PREMIUM SELF)** diff --git a/doc/administration/auth/test_oidc_oauth.md b/doc/administration/auth/test_oidc_oauth.md index 49fb27af482..1f30da50dfa 100644 --- a/doc/administration/auth/test_oidc_oauth.md +++ b/doc/administration/auth/test_oidc_oauth.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test OIDC/OAuth in GitLab **(FREE SELF)** diff --git a/doc/administration/backup_restore/backup_gitlab.md b/doc/administration/backup_restore/backup_gitlab.md index 5c0fcbbc4ef..f38358810e3 100644 --- a/doc/administration/backup_restore/backup_gitlab.md +++ b/doc/administration/backup_restore/backup_gitlab.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Back up GitLab **(FREE SELF)** @@ -29,7 +29,7 @@ For more information, see [alternative backup strategies](#alternative-backup-st - [PostgreSQL databases](#postgresql-databases) - [Git repositories](#git-repositories) - [Blobs](#blobs) -- [Container Registry](#container-registry) +- [Container registry](#container-registry) - [Configuration files](#storing-configuration-files) - [Other data](#other-data) @@ -90,9 +90,9 @@ The [backup command](#backup-command) doesn't back up blobs that aren't stored o - [Amazon S3 backups](https://docs.aws.amazon.com/aws-backup/latest/devguide/s3-backups.html) - [Google Cloud Storage Transfer Service](https://cloud.google.com/storage-transfer-service) and [Google Cloud Storage Object Versioning](https://cloud.google.com/storage/docs/object-versioning) -### Container Registry +### Container registry -[GitLab Container Registry](../packages/container_registry.md) storage can be configured in either: +[GitLab container registry](../packages/container_registry.md) storage can be configured in either: - The file system in a specific location. - An [Object Storage](../object_storage.md) solution. Object Storage solutions can be: @@ -172,7 +172,7 @@ including: - CI/CD job artifacts - LFS objects - Terraform states ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331806) in GitLab 14.7) -- Container Registry images +- Container registry images - GitLab Pages content - Packages ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332006) in GitLab 14.7) - Snippets @@ -283,22 +283,11 @@ Dumping database tables: - Dumping table wikis... [DONE] Dumping repositories: - Dumping repository abcd... [DONE] -Creating backup archive: $TIMESTAMP_gitlab_backup.tar [DONE] +Creating backup archive: <backup-id>_gitlab_backup.tar [DONE] Deleting tmp directories...[DONE] Deleting old backups... [SKIPPING] ``` -### Backup timestamp - -The backup archive is saved in `backup_path`, which is specified in the -`config/gitlab.yml` file. The default path is `/var/opt/gitlab/backups`. The filename is `[TIMESTAMP]_gitlab_backup.tar`, -where `TIMESTAMP` identifies the time at which each backup was created, plus -the GitLab version. The timestamp is needed if you need to restore GitLab and -multiple backups are available. - -For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, -the timestamp is `1493107454_2018_04_25_10.6.4-ce`. - ### Backup options The command-line tool GitLab provides to back up your instance can accept more @@ -327,15 +316,14 @@ To use the `copy` strategy instead of the default streaming strategy, specify sudo gitlab-backup create STRATEGY=copy ``` -#### Backup filename +#### Backup file name WARNING: -If you use a custom backup filename, you can't +If you use a custom backup file name, you can't [limit the lifetime of the backups](#limit-backup-lifetime-for-local-files-prune-old-backups). -By default, a backup file is created according to the specification in the -previous [Backup timestamp](#backup-timestamp) section. You can, however, -override the `[TIMESTAMP]` portion of the filename by setting the `BACKUP` +Backup files are created with file names according to [specific defaults](index.md#backup-id). However, you can +override the `<backup-id>` portion of the file name by setting the `BACKUP` environment variable. For example: ```shell @@ -346,11 +334,102 @@ The resulting file is named `dump_gitlab_backup.tar`. This is useful for systems that make use of rsync and incremental backups, and results in considerably faster transfer speeds. +#### Backup compression + +By default, Gzip fast compression is applied during backup of: + +- [PostgreSQL database](#postgresql-databases) dumps. +- [blobs](#blobs), for example uploads, job artifacts, external merge request diffs. + +The default command is `gzip -c -1`. You can override this command with `COMPRESS_CMD`. Similarly, you can override the decompression command with `DECOMPRESS_CMD`. + +Caveats: + +- The compression command is used in a pipeline, so your custom command must output to `stdout`. +- If you specify a command that is not packaged with GitLab, then you must install it yourself. +- The resultant file names will still end in `.gz`. +- The default decompression command, used during restore, is `gzip -cd`. Therefore if you override the compression command to use a format that cannot be decompressed by `gzip -cd`, you must override the decompression command during restore. +- [Do not place environment variables after the backup command](https://gitlab.com/gitlab-org/gitlab/-/issues/433227). For example, `gitlab-backup create COMPRESS_CMD="pigz -c --best"` doesn't work as intended. + +##### Default compression: Gzip with fastest method + +```shell +gitlab-backup create +``` + +##### Gzip with slowest method + +```shell +COMPRESS_CMD="gzip -c --best" gitlab-backup create +``` + +If `gzip` was used for backup, then restore does not require any options: + +```shell +gitlab-backup restore +``` + +##### No compression + +If your backup destination has built-in automatic compression, then you may wish to skip compression. + +The `tee` command pipes `stdin` to `stdout`. + +```shell +COMPRESS_CMD=tee gitlab-backup create +``` + +And on restore: + +```shell +DECOMPRESS_CMD=tee gitlab-backup restore +``` + +##### Parallel compression with `pigz` + +WARNING: +While we support using `COMPRESS_CMD` and `DECOMPRESS_CMD` to override the default Gzip compression library, we currently only test the default Gzip library with default options on a routine basis. You are responsible for testing and validating the viability of your backups. We strongly recommend this as best practice in general for backups, whether overriding the compression command or not. If you encounter issues with another compression library, you should revert back to the default. Troubleshooting and fixing errors with alternative libraries are a lower priority for GitLab. + +NOTE: +`pigz` is not included in the GitLab Linux package. You must install it yourself. + +An example of compressing backups with `pigz` using 4 processes: + +```shell +COMPRESS_CMD="pigz --compress --stdout --fast --processes=4" sudo gitlab-backup create +``` + +Because `pigz` compresses to the `gzip` format, it is not required to use `pigz` to decompress backups which were compressed by `pigz`. However, it can still have a performance benefit over `gzip`. An example of decompressing backups with `pigz`: + +```shell +DECOMPRESS_CMD="pigz --decompress --stdout" sudo gitlab-backup restore +``` + +##### Parallel compression with `zstd` + +WARNING: +While we support using `COMPRESS_CMD` and `DECOMPRESS_CMD` to override the default Gzip compression library, we currently only test the default Gzip library with default options on a routine basis. You are responsible for testing and validating the viability of your backups. We strongly recommend this as best practice in general for backups, whether overriding the compression command or not. If you encounter issues with another compression library, you should revert back to the default. Troubleshooting and fixing errors with alternative libraries are a lower priority for GitLab. + +NOTE: +`zstd` is not included in the GitLab Linux package. You must install it yourself. + +An example of compressing backups with `zstd` using 4 threads: + +```shell +COMPRESS_CMD="zstd --compress --stdout --fast --threads=4" sudo gitlab-backup create +``` + +An example of decompressing backups with `zstd`: + +```shell +DECOMPRESS_CMD="zstd --decompress --stdout" sudo gitlab-backup restore +``` + #### Confirm archive can be transferred To ensure the generated archive is transferable by rsync, you can set the `GZIP_RSYNCABLE=yes` option. This sets the `--rsyncable` option to `gzip`, which is useful only in -combination with setting [the Backup filename option](#backup-filename). +combination with setting [the Backup file name option](#backup-file-name). The `--rsyncable` option in `gzip` isn't guaranteed to be available on all distributions. To verify that it's available in your distribution, run @@ -370,7 +449,7 @@ You can exclude specific directories from the backup by adding the environment v - `artifacts` (CI job artifacts) - `lfs` (LFS objects) - `terraform_state` (Terraform states) -- `registry` (Container Registry images) +- `registry` (Container registry images) - `pages` (Pages content) - `repositories` (Git repositories data) - `packages` (Packages) @@ -523,23 +602,23 @@ Incremental repository backups can be faster than full repository backups becaus The incremental backup archives are not linked to each other: each archive is a self-contained backup of the instance. There must be an existing backup to create an incremental backup from: -- In GitLab 14.9 and 14.10, use the `BACKUP=<timestamp_of_backup>` option to choose the backup to use. The chosen previous backup is overwritten. -- In GitLab 15.0 and later, use the `PREVIOUS_BACKUP=<timestamp_of_backup>` option to choose the backup to use. By default, a backup file is created - as documented in the [Backup timestamp](#backup-timestamp) section. You can override the `[TIMESTAMP]` portion of the filename by setting the - [`BACKUP` environment variable](#backup-filename). +- In GitLab 14.9 and 14.10, use the `BACKUP=<backup-id>` option to choose the backup to use. The chosen previous backup is overwritten. +- In GitLab 15.0 and later, use the `PREVIOUS_BACKUP=<backup-id>` option to choose the backup to use. By default, a backup file is created + as documented in the [Backup ID](index.md#backup-id) section. You can override the `<backup-id>` portion of the file name by setting the + [`BACKUP` environment variable](#backup-file-name). To create an incremental backup, run: - In GitLab 15.0 or later: ```shell - sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=<timestamp_of_backup> + sudo gitlab-backup create INCREMENTAL=yes PREVIOUS_BACKUP=<backup-id> ``` - In GitLab 14.9 and 14.10: ```shell - sudo gitlab-backup create INCREMENTAL=yes BACKUP=<timestamp_of_backup> + sudo gitlab-backup create INCREMENTAL=yes BACKUP=<backup-id> ``` To create an [untarred](#skipping-tar-creation) incremental backup from a tarred backup, use `SKIP=tar`: @@ -1118,7 +1197,7 @@ When troubleshooting backup problems, however, replace `CRON=1` with `--trace` t #### Limit backup lifetime for local files (prune old backups) WARNING: -The process described in this section doesn't work if you used a [custom filename](#backup-filename) +The process described in this section doesn't work if you used a [custom file name](#backup-file-name) for your backups. To prevent regular backups from using all your disk space, you may want to set a limited lifetime @@ -1621,9 +1700,9 @@ You should verify that the secrets are the root cause before deleting any data. TRUNCATE integrations, chat_names, issue_tracker_data, jira_tracker_data, slack_integrations, web_hooks, zentao_tracker_data, web_hook_logs CASCADE; ``` -### Container Registry push failures after restoring from a backup +### Container registry push failures after restoring from a backup -If you use the [Container Registry](../../user/packages/container_registry/index.md), +If you use the [container registry](../../user/packages/container_registry/index.md), pushes to the registry may fail after restoring your backup on a Linux package (Omnibus) instance after restoring the registry data. @@ -1680,16 +1759,16 @@ During backup, you can get the `File name too long` error ([issue #354984](https Problem: <class 'OSError: [Errno 36] File name too long: ``` -This problem stops the backup script from completing. To fix this problem, you must truncate the filenames causing the problem. A maximum of 246 characters, including the file extension, is permitted. +This problem stops the backup script from completing. To fix this problem, you must truncate the file names causing the problem. A maximum of 246 characters, including the file extension, is permitted. WARNING: The steps in this section can potentially lead to **data loss**. All steps must be followed strictly in the order given. Consider opening a [Support Request](https://support.gitlab.com/hc/en-us/requests/new) if you're a Premium or Ultimate customer. -Truncating filenames to resolve the error involves: +Truncating file names to resolve the error involves: - Cleaning up remote uploaded files that aren't tracked in the database. -- Truncating the filenames in the database. +- Truncating the file names in the database. - Rerunning the backup task. #### Clean up remote uploaded files @@ -1713,15 +1792,15 @@ To fix these files, you must clean up all remote uploaded files that are in the bundle exec rake gitlab:cleanup:remote_upload_files RAILS_ENV=production DRY_RUN=false ``` -#### Truncate the filenames referenced by the database +#### Truncate the file names referenced by the database -You must truncate the files referenced by the database that are causing the problem. The filenames referenced by the database are stored: +You must truncate the files referenced by the database that are causing the problem. The file names referenced by the database are stored: - In the `uploads` table. - In the references found. Any reference found from other database tables and columns. - On the file system. -Truncate the filenames in the `uploads` table: +Truncate the file names in the `uploads` table: 1. Enter the database console: @@ -1749,9 +1828,9 @@ Truncate the filenames in the `uploads` table: sudo -u git -H bundle exec rails dbconsole -e production ``` -1. Search the `uploads` table for filenames longer than 246 characters: +1. Search the `uploads` table for file names longer than 246 characters: - The following query selects the `uploads` records with filenames longer than 246 characters in batches of 0 to 10000. This improves the performance on large GitLab instances with tables having thousand of records. + The following query selects the `uploads` records with file names longer than 246 characters in batches of 0 to 10000. This improves the performance on large GitLab instances with tables having thousand of records. ```sql CREATE TEMP TABLE uploads_with_long_filenames AS @@ -1764,9 +1843,9 @@ Truncate the filenames in the `uploads` table: SELECT u.id, u.path, - -- Current filename + -- Current file name (regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1] AS current_filename, - -- New filename + -- New file name CONCAT( LEFT(SPLIT_PART((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1], '.', 1), 242), COALESCE(SUBSTRING((regexp_match(u.path, '[^\\/:*?"<>|\r\n]+$'))[1] FROM '\.(?:.(?!\.))+$')) @@ -1796,13 +1875,13 @@ Truncate the filenames in the `uploads` table: Where: - - `current_filename`: a filename that is currently more than 246 characters long. - - `new_filename`: a filename that has been truncated to 246 characters maximum. + - `current_filename`: a file name that is currently more than 246 characters long. + - `new_filename`: a file name that has been truncated to 246 characters maximum. - `new_path`: new path considering the `new_filename` (truncated). After you validate the batch results, you must change the batch size (`row_id`) using the following sequence of numbers (10000 to 20000). Repeat this process until you reach the last record in the `uploads` table. -1. Rename the files found in the `uploads` table from long filenames to new truncated filenames. The following query rolls back the update so you can check the results safely in a transaction wrapper: +1. Rename the files found in the `uploads` table from long file names to new truncated file names. The following query rolls back the update so you can check the results safely in a transaction wrapper: ```sql CREATE TEMP TABLE uploads_with_long_filenames AS @@ -1837,7 +1916,7 @@ Truncate the filenames in the `uploads` table: After you validate the batch update results, you must change the batch size (`row_id`) using the following sequence of numbers (10000 to 20000). Repeat this process until you reach the last record in the `uploads` table. -1. Validate that the new filenames from the previous query are the expected ones. If you are sure you want to truncate the records found in the previous step to 246 characters, run the following: +1. Validate that the new file names from the previous query are the expected ones. If you are sure you want to truncate the records found in the previous step to 246 characters, run the following: WARNING: The following action is **irreversible**. @@ -1869,9 +1948,9 @@ Truncate the filenames in the `uploads` table: After you finish the batch update, you must change the batch size (`updatable_uploads.row_id`) using the following sequence of numbers (10000 to 20000). Repeat this process until you reach the last record in the `uploads` table. -Truncate the filenames in the references found: +Truncate the file names in the references found: -1. Check if those records are referenced somewhere. One way to do this is to dump the database and search for the parent directory name and filename: +1. Check if those records are referenced somewhere. One way to do this is to dump the database and search for the parent directory name and file name: 1. To dump your database, you can use the following command as an example: @@ -1879,15 +1958,15 @@ Truncate the filenames in the references found: pg_dump -h /var/opt/gitlab/postgresql/ -d gitlabhq_production > gitlab-dump.tmp ``` - 1. Then you can search for the references using the `grep` command. Combining the parent directory and the filename can be a good idea. For example: + 1. Then you can search for the references using the `grep` command. Combining the parent directory and the file name can be a good idea. For example: ```shell grep public/alongfilenamehere.txt gitlab-dump.tmp ``` -1. Replace those long filenames using the new filenames obtained from querying the `uploads` table. +1. Replace those long file names using the new file names obtained from querying the `uploads` table. -Truncate the filenames on the file system. You must manually rename the files in your file system to the new filenames obtained from querying the `uploads` table. +Truncate the file names on the file system. You must manually rename the files in your file system to the new file names obtained from querying the `uploads` table. #### Re-run the backup task diff --git a/doc/administration/backup_restore/backup_large_reference_architectures.md b/doc/administration/backup_restore/backup_large_reference_architectures.md index 4e11a707052..64d7b2168f5 100644 --- a/doc/administration/backup_restore/backup_large_reference_architectures.md +++ b/doc/administration/backup_restore/backup_large_reference_architectures.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Back up and restore large reference architectures **(FREE SELF)** @@ -17,7 +17,7 @@ This document is intended for environments using: - [Linux package (Omnibus) and cloud-native hybrid reference architectures 3,000 users and up](../reference_architectures/index.md) - [Amazon RDS](https://aws.amazon.com/rds/) for PostgreSQL data - [Amazon S3](https://aws.amazon.com/s3/) for object storage -- [Object storage](../object_storage.md) to store everything possible, including [blobs](backup_gitlab.md#blobs) and [Container Registry](backup_gitlab.md#container-registry) +- [Object storage](../object_storage.md) to store everything possible, including [blobs](backup_gitlab.md#blobs) and [container registry](backup_gitlab.md#container-registry) ## Configure daily backups @@ -48,7 +48,38 @@ There is a feature proposal to add the ability to back up repositories directly 1. Spin up a VM with 8 vCPU and 7.2 GB memory. This node will be used to back up Git repositories. Note that [a Praefect node cannot be used to back up Git data](https://gitlab.com/gitlab-org/gitlab/-/issues/396343#note_1385950340). - 1. Configure the node as another **GitLab Rails** node as defined in your [reference architecture](../reference_architectures/index.md). As with other GitLab Rails nodes, this node must have access to your main Postgres database as well as to Gitaly Cluster. + 1. Configure the node as another **GitLab Rails** node as defined in your [reference architecture](../reference_architectures/index.md). + As with other GitLab Rails nodes, this node must have access to your main PostgreSQL database, Redis, object storage, and Gitaly Cluster. + 1. Ensure the GitLab application isn't running on this node by disabling most services: + + 1. Edit `/etc/gitlab/gitlab.rb` to ensure the following services are disabled. + `roles(['application_role'])` disables Redis, PostgreSQL, and Consul, and + is the basis of the reference architecture Rails node definition. + + ```ruby + roles(['application_role']) + gitlab_workhorse['enable'] = false + puma['enable'] = false + sidekiq['enable'] = false + gitlab_kas['enable'] = false + gitaly['enable'] = false + prometheus_monitoring['enable'] = false + ``` + + 1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + + 1. The only service that should be left is `logrotate`, you can verify with: + + ```shell + gitlab-ctl status + ``` + + There is [a feature request](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6823) for a role in the Linux package + that meets these requirements. To back up the Git repositories: @@ -65,12 +96,12 @@ To back up the Git repositories: sudo gitlab-backup create SKIP=db ``` - The resulting tar file will include only the Git repositories and some metadata. Blobs such as uploads, artifacts, and LFS do not need to be explicitly skipped, because the command does not back up object storage by default. The tar file will be created in the [`/var/opt/gitlab/backups` directory](https://docs.gitlab.com/omnibus/settings/backups.html#creating-an-application-backup) and [the filename will end in `_gitlab_backup.tar`](backup_gitlab.md#backup-timestamp). + The resulting tar file will include only the Git repositories and some metadata. Blobs such as uploads, artifacts, and LFS do not need to be explicitly skipped, because the command does not back up object storage by default. The tar file will be created in the [`/var/opt/gitlab/backups` directory](https://docs.gitlab.com/omnibus/settings/backups.html#creating-an-application-backup) and [the file name will end in `_gitlab_backup.tar`](index.md#backup-id). Since we configured uploading backups to remote cloud storage, the tar file will be uploaded to the remote region and deleted from disk. -1. Note the [timestamp](backup_gitlab.md#backup-timestamp) of the backup file for the next step. For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, the timestamp is `1493107454_2018_04_25_10.6.4-ce`. -1. Run the [backup command](backup_gitlab.md#backup-command) again, this time specifying [incremental backup of Git repositories](backup_gitlab.md#incremental-repository-backups), and the timestamp of the source backup file. Using the example timestamp from the previous step, the command is: +1. Note the [backup ID](index.md#backup-id) of the backup file for the next step. For example, if the backup archive name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, the backup ID is `1493107454_2018_04_25_10.6.4-ce`. +1. Run the [backup command](backup_gitlab.md#backup-command) again, this time specifying [incremental backup of Git repositories](backup_gitlab.md#incremental-repository-backups), and the backup ID of the source backup file. Using the example ID from the previous step, the command is: ```shell sudo gitlab-backup create SKIP=db INCREMENTAL=yes PREVIOUS_BACKUP=1493107454_2018_04_25_10.6.4-ce @@ -246,7 +277,7 @@ To restore Git repositories: sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar ``` -1. Restore the backup, specifying the timestamp of the backup you wish to restore: +1. Restore the backup, specifying the ID of the backup you wish to restore: WARNING: The restore command requires diff --git a/doc/administration/backup_restore/index.md b/doc/administration/backup_restore/index.md index 8c78e26db2a..d6e67ad4229 100644 --- a/doc/administration/backup_restore/index.md +++ b/doc/administration/backup_restore/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Back up and restore GitLab **(FREE SELF)** @@ -25,196 +25,8 @@ For detailed information on restoring GitLab, see [Restore GitLab](restore_gitla ## Migrate to a new server -<!-- some details borrowed from GitLab.com move from Azure to GCP detailed at https://gitlab.com/gitlab-com/migration/-/blob/master/.gitlab/issue_templates/failover.md --> - -You can use GitLab backup and restore to migrate your instance to a new server. This section outlines a typical procedure for a GitLab deployment running on a single server. -If you're running GitLab Geo, an alternative option is [Geo disaster recovery for planned failover](../geo/disaster_recovery/planned_failover.md). - -WARNING: -Avoid uncoordinated data processing by both the new and old servers, where multiple -servers could connect concurrently and process the same data. For example, when using -[incoming email](../incoming_email.md), if both GitLab instances are -processing email at the same time, then both instances miss some data. -This type of problem can occur with other services as well, such as a -[non-packaged database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server), -a non-packaged Redis instance, or non-packaged Sidekiq. - -Prerequisites: - -- Some time before your migration, consider notifying your users of upcoming - scheduled maintenance with a [broadcast message banner](../broadcast_messages.md). -- Ensure your backups are complete and current. Create a complete system-level backup, or - take a snapshot of all servers involved in the migration, in case destructive commands - (like `rm`) are run incorrectly. - -### Prepare the new server - -To prepare the new server: - -1. Copy the - [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) - from the old server to avoid man-in-the-middle attack warnings. - See [Manually replicate the primary site's SSH host keys](../geo/replication/configuration.md#step-2-manually-replicate-the-primary-sites-ssh-host-keys) for example steps. -1. [Install and configure GitLab](https://about.gitlab.com/install/) except - [incoming email](../incoming_email.md): - 1. Install GitLab. - 1. Configure by copying `/etc/gitlab` files from the old server to the new server, and update as necessary. - Read the - [Linux package installation backup and restore instructions](https://docs.gitlab.com/omnibus/settings/backups.html) for more detail. - 1. If applicable, disable [incoming email](../incoming_email.md). - 1. Block new CI/CD jobs from starting upon initial startup after the backup and restore. - Edit `/etc/gitlab/gitlab.rb` and set the following: - - ```ruby - nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" - ``` - - 1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Stop GitLab to avoid any potential unnecessary and unintentional data processing: - - ```shell - sudo gitlab-ctl stop - ``` - -1. Configure the new server to allow receiving the Redis database and GitLab backup files: - - ```shell - sudo rm -f /var/opt/gitlab/redis/dump.rdb - sudo chown <your-linux-username> /var/opt/gitlab/redis /var/opt/gitlab/backups - ``` - -### Prepare and transfer content from the old server - -1. Ensure you have an up-to-date system-level backup or snapshot of the old server. -1. Enable [maintenance mode](../maintenance_mode/index.md), - if supported by your GitLab edition. -1. Block new CI/CD jobs from starting: - 1. Edit `/etc/gitlab/gitlab.rb`, and set the following: - - ```ruby - nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" - ``` - - 1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Disable periodic background jobs: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. - 1. On the left sidebar, select **Monitoring > Background Jobs**. - 1. Under the Sidekiq dashboard, select **Cron** tab and then - **Disable All**. -1. Wait for the currently running CI/CD jobs to finish, or accept that jobs that have not completed may be lost. - To view jobs currently running, on the left sidebar, select **Overviews > Jobs**, - and then select **Running**. -1. Wait for Sidekiq jobs to finish: - 1. On the left sidebar, select **Monitoring > Background Jobs**. - 1. Under the Sidekiq dashboard, select **Queues** and then **Live Poll**. - Wait for **Busy** and **Enqueued** to drop to 0. - These queues contain work that has been submitted by your users; - shutting down before these jobs complete may cause the work to be lost. - Make note of the numbers shown in the Sidekiq dashboard for post-migration verification. -1. Flush the Redis database to disk, and stop GitLab other than the services needed for migration: - - ```shell - sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket save && sudo gitlab-ctl stop && sudo gitlab-ctl start postgresql && sudo gitlab-ctl start gitaly - ``` - -1. Create a GitLab backup: - - ```shell - sudo gitlab-backup create - ``` - -1. Disable the following GitLab services and prevent unintentional restarts by adding the following to the bottom of `/etc/gitlab/gitlab.rb`: - - ```ruby - alertmanager['enable'] = false - gitlab_exporter['enable'] = false - gitlab_pages['enable'] = false - gitlab_workhorse['enable'] = false - grafana['enable'] = false - logrotate['enable'] = false - gitlab_rails['incoming_email_enabled'] = false - nginx['enable'] = false - node_exporter['enable'] = false - postgres_exporter['enable'] = false - postgresql['enable'] = false - prometheus['enable'] = false - puma['enable'] = false - redis['enable'] = false - redis_exporter['enable'] = false - registry['enable'] = false - sidekiq['enable'] = false - ``` - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Verify everything is stopped, and confirm no services are running: - - ```shell - sudo gitlab-ctl status - ``` - -1. Transfer the Redis database and GitLab backups to the new server: - - ```shell - sudo scp /var/opt/gitlab/redis/dump.rdb <your-linux-username>@new-server:/var/opt/gitlab/redis - sudo scp /var/opt/gitlab/backups/your-backup.tar <your-linux-username>@new-server:/var/opt/gitlab/backups - ``` - -### Restore data on the new server - -1. Restore appropriate file system permissions: - - ```shell - sudo chown gitlab-redis /var/opt/gitlab/redis - sudo chown gitlab-redis:gitlab-redis /var/opt/gitlab/redis/dump.rdb - sudo chown git:root /var/opt/gitlab/backups - sudo chown git:git /var/opt/gitlab/backups/your-backup.tar - ``` - -1. [Restore the GitLab backup](#restore-gitlab). -1. Verify that the Redis database restored correctly: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. - 1. On the left sidebar, select **Monitoring > Background Jobs**. - 1. Under the Sidekiq dashboard, verify that the numbers - match with what was shown on the old server. - 1. While still under the Sidekiq dashboard, select **Cron** and then **Enable All** - to re-enable periodic background jobs. -1. Test that read-only operations on the GitLab instance work as expected. For example, browse through project repository files, merge requests, and issues. -1. Disable [Maintenance Mode](../maintenance_mode/index.md), if previously enabled. -1. Test that the GitLab instance is working as expected. -1. If applicable, re-enable [incoming email](../incoming_email.md) and test it is working as expected. -1. Update your DNS or load balancer to point at the new server. -1. Unblock new CI/CD jobs from starting by removing the custom NGINX configuration - you added previously: - - ```ruby - # The following line must be removed - nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" - ``` - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -1. Remove the scheduled maintenance [broadcast message banner](../broadcast_messages.md). +For detailed information on using back up and restore to migrate to a new server, see +[Migrate to a new server](migrate_to_new_server.md). ## Additional notes @@ -224,6 +36,187 @@ methods to export or back up your data yourself from GitLab.com. Issues are stored in the database, and can't be stored in Git itself. +## GitLab backup archive creation process + +When working with GitLab backups, you might need to know how GitLab creates backup archives. To create backup archives, GitLab: + +1. If creating an incremental backup, extracts the previous backup archive and read its `backup_information.yml` file. +1. Updates or generates the `backup_information.yml` file. +1. Runs all backup sub-tasks: + - `db` to backup the GitLab PostgreSQL database (not Gitaly Cluster). + - `repositories` to back up Git repositories. + - `uploads` to back up attachments. + - `builds` to back up CI job output logs. + - `artifacts` to back up CI job artifacts. + - `pages` to back up page content. + - `lfs` to back up LFS objects. + - `terraform_state` to back up Terraform states. + - `registry` to back up container registry images. + - `packages` to back up packages. + - `ci_secure_files` to back up project-level secure files. +1. Archives the backup staging area into a tar file. +1. Optional. Uploads the new backup archive to object-storage. +1. Cleans up backup staging directory files that are now archived. + +## Backup ID + +Backup IDs identify individual backup archives. You need the backup ID of a backup archive if you need to restore GitLab and multiple backup archives are available. + +Backup archives are saved in a directory set in `backup_path`, which is specified in the `config/gitlab.yml` file. + +- By default, backup archives are stored in `/var/opt/gitlab/backups`. +- By default, backup archive file names are `<backup-id>_gitlab_backup.tar` where `<backup-id>` identifies the time when the + backup archive was created, the GitLab version, and the GitLab edition. + +For example, if the archive file name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, +the backup ID is `1493107454_2018_04_25_10.6.4-ce`. + +## Backup staging directory + +The backup staging directory is a place to temporarily: + +- Store backup artifacts on disk before the GitLab backup archive is created. +- Extract backup archives on disk before restoring a backup or creating an incremental backup. + +This directory is the same directory where completed GitLab backup archives are created. When creating an untarred backup, the backup artifacts are left in this directory and no +archive is created. + +Example backup staging directory with untarred backup: + +```plaintext +backups/ +├── 1701728344_2023_12_04_16.7.0-pre_gitlab_backup.tar +├── 1701728447_2023_12_04_16.7.0-pre_gitlab_backup.tar +├── artifacts.tar.gz +├── backup_information.yml +├── builds.tar.gz +├── ci_secure_files.tar.gz +├── db +│ ├── ci_database.sql.gz +│ └── database.sql.gz +├── lfs.tar.gz +├── packages.tar.gz +├── pages.tar.gz +├── repositories +│ ├── manifests/ +│ ├── @hashed/ +│ └── @snippets/ +├── terraform_state.tar.gz +└── uploads.tar.gz +``` + +## `backup_information.yml` file + +The `backup_information.yml` file saves all backup inputs that are not included in the backup itself. It includes information such as: + +- The time the backup was created. +- The version of GitLab that generated the backup. +- Any options that were specified, such as skipped sub-tasks. + +This information is used by some sub-tasks to determine how: + +- To restore. +- To link data in the backup with external services (such as server-side repository backups). + +This file is saved into the backup staging directory. + +## Database backups + +Database backups are created and restored by a GitLab backup sub-task called `db`. The database sub-task uses `pg_dump` to create [a SQL dump](https://www.postgresql.org/docs/14/backup-dump.html). The output of `pg_dump` is piped through `gzip` in order to create a compressed SQL file. This file is saved to the backup staging directory. + +## Repository backups + +Repository backups are created and restored by a GitLab backup sub-task called `repositories`. The repositories sub-task uses a Gitaly command +[`gitaly-backup`](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/gitaly-backup.md) to create Git repository backups: + +- GitLab uses its database to tell `gitaly-backup` which repositories to back up. +- `gitaly-backup` then calls a series of RPCs on Gitaly to collect the repository backup data for each repository. This data is streamed into a directory structure in the GitLab backup staging directory. + +```mermaid +sequenceDiagram + box Backup host + participant Repositories sub-task + participant gitaly-backup + end + + Repositories sub-task->>+gitaly-backup: List of repositories + + loop Each repository + gitaly-backup->>+Gitaly: ListRefs request + Gitaly->>-gitaly-backup: List of Git references + + gitaly-backup->>+Gitaly: CreateBundleFromRefList request + Gitaly->>-gitaly-backup: Git bundle file + + gitaly-backup->>+Gitaly: GetCustomHooks request + Gitaly->>-gitaly-backup: Custom hooks archive + end + + gitaly-backup->>-Repositories sub-task: Success/failure +``` + +Storages configured to Gitaly Cluster are backed up the same as standalone Gitaly. When Gitaly Cluster receives the RPC calls from `gitaly-backup`, it is responsible for +rebuilding its own database. This means that there is no need to backup the Gitaly Cluster database separately. Because backups operate through RPCs, each repository is only backed +up once no matter the replication factor. + +### Server-side repository backups + +You can configure repository backups as server-side repository backups. When specified, `gitaly-backup` makes a single RPC call for each repository to create the backup. This RPC +does not transmit any repository data. Instead, the RPC triggers the Gitaly node that stores that physical repository to upload the backup data directly to object-storage. Because +the data is no longer transmitted through RPCs from Gitaly, server-side backups require much less network transfer and require no disk storage on the machine that is running the +backup Rake task. The backups stored on object-storage are linked to the created backup archive by [the backup ID](#backup-id). + +```mermaid +sequenceDiagram + box Backup host + participant Repositories sub-task + participant gitaly-backup + end + + Repositories sub-task->>+gitaly-backup: List of repositories + + loop Each repository + gitaly-backup->>+Gitaly: BackupRepository request + + Gitaly->>+Object-storage: Git references file + Object-storage->>-Gitaly: Success/failure + + Gitaly->>+Object-storage: Git bundle file + Object-storage->>-Gitaly: Success/failure + + Gitaly->>+Object-storage: Custom hooks archive + Object-storage->>-Gitaly: Success/failure + + Gitaly->>+Object-storage: Backup manifest file + Object-storage->>-Gitaly: Success/failure + + Gitaly->>-gitaly-backup: Success/failure + end + + gitaly-backup->>-Repositories sub-task: Success/failure +``` + +## File backups + +The following GitLab backup sub-tasks back up files: + +- `uploads` +- `builds` +- `artifacts` +- `pages` +- `lfs` +- `terraform_state` +- `registry` +- `packages` +- `ci_secure_files` + +These file sub-tasks determine a set of files within a directory specific to the task. This set of files is then passed to `tar` +to create an archive. This archive is piped (not saved to disk) through `gzip` to save a compressed tar file to the backup staging directory. + +Because backups are created from live instances, the files that tar is trying to archive can sometimes be modified while creating the backup. In this case, an alternate "copy" +strategy can be used. When this strategy is used, `rsync` is first used to create a copy of the files to back up. Then, these copies are passed to `tar` as usual. In this case, +the machine running the backup Rake task must have enough storage for the copied files and the compressed archive. + ## Related features - [Geo](../geo/index.md) diff --git a/doc/administration/backup_restore/migrate_to_new_server.md b/doc/administration/backup_restore/migrate_to_new_server.md new file mode 100644 index 00000000000..7b04861cc7c --- /dev/null +++ b/doc/administration/backup_restore/migrate_to_new_server.md @@ -0,0 +1,208 @@ +--- +stage: Systems +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Migrate to a new server + +<!-- some details borrowed from GitLab.com move from Azure to GCP detailed at https://gitlab.com/gitlab-com/migration/-/blob/master/.gitlab/issue_templates/failover.md --> + +You can use GitLab backup and restore to migrate your instance to a new server. This section outlines a typical procedure for a GitLab deployment running on a single server. +If you're running GitLab Geo, an alternative option is [Geo disaster recovery for planned failover](../geo/disaster_recovery/planned_failover.md). + +WARNING: +Avoid uncoordinated data processing by both the new and old servers, where multiple +servers could connect concurrently and process the same data. For example, when using +[incoming email](../incoming_email.md), if both GitLab instances are +processing email at the same time, then both instances miss some data. +This type of problem can occur with other services as well, such as a +[non-packaged database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server), +a non-packaged Redis instance, or non-packaged Sidekiq. + +Prerequisites: + +- Some time before your migration, consider notifying your users of upcoming + scheduled maintenance with a [broadcast message banner](../broadcast_messages.md). +- Ensure your backups are complete and current. Create a complete system-level backup, or + take a snapshot of all servers involved in the migration, in case destructive commands + (like `rm`) are run incorrectly. + +## Prepare the new server + +To prepare the new server: + +1. Copy the + [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) + from the old server to avoid man-in-the-middle attack warnings. + See [Manually replicate the primary site's SSH host keys](../geo/replication/configuration.md#step-2-manually-replicate-the-primary-sites-ssh-host-keys) for example steps. +1. [Install and configure GitLab](https://about.gitlab.com/install/) except + [incoming email](../incoming_email.md): + 1. Install GitLab. + 1. Configure by copying `/etc/gitlab` files from the old server to the new server, and update as necessary. + Read the + [Linux package installation backup and restore instructions](https://docs.gitlab.com/omnibus/settings/backups.html) for more detail. + 1. If applicable, disable [incoming email](../incoming_email.md). + 1. Block new CI/CD jobs from starting upon initial startup after the backup and restore. + Edit `/etc/gitlab/gitlab.rb` and set the following: + + ```ruby + nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" + ``` + + 1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Stop GitLab to avoid any potential unnecessary and unintentional data processing: + + ```shell + sudo gitlab-ctl stop + ``` + +1. Configure the new server to allow receiving the Redis database and GitLab backup files: + + ```shell + sudo rm -f /var/opt/gitlab/redis/dump.rdb + sudo chown <your-linux-username> /var/opt/gitlab/redis /var/opt/gitlab/backups + ``` + +## Prepare and transfer content from the old server + +1. Ensure you have an up-to-date system-level backup or snapshot of the old server. +1. Enable [maintenance mode](../maintenance_mode/index.md), + if supported by your GitLab edition. +1. Block new CI/CD jobs from starting: + 1. Edit `/etc/gitlab/gitlab.rb`, and set the following: + + ```ruby + nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" + ``` + + 1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Disable periodic background jobs: + 1. On the left sidebar, at the bottom, select **Admin Area**. + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, select **Cron** tab and then + **Disable All**. +1. Wait for the currently running CI/CD jobs to finish, or accept that jobs that have not completed may be lost. + To view jobs currently running, on the left sidebar, select **Overviews > Jobs**, + and then select **Running**. +1. Wait for Sidekiq jobs to finish: + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, select **Queues** and then **Live Poll**. + Wait for **Busy** and **Enqueued** to drop to 0. + These queues contain work that has been submitted by your users; + shutting down before these jobs complete may cause the work to be lost. + Make note of the numbers shown in the Sidekiq dashboard for post-migration verification. +1. Flush the Redis database to disk, and stop GitLab other than the services needed for migration: + + ```shell + sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket save && sudo gitlab-ctl stop && sudo gitlab-ctl start postgresql && sudo gitlab-ctl start gitaly + ``` + +1. Create a GitLab backup: + + ```shell + sudo gitlab-backup create + ``` + +1. Disable the following GitLab services and prevent unintentional restarts by adding the following to the bottom of `/etc/gitlab/gitlab.rb`: + + ```ruby + alertmanager['enable'] = false + gitlab_exporter['enable'] = false + gitlab_pages['enable'] = false + gitlab_workhorse['enable'] = false + grafana['enable'] = false + logrotate['enable'] = false + gitlab_rails['incoming_email_enabled'] = false + nginx['enable'] = false + node_exporter['enable'] = false + postgres_exporter['enable'] = false + postgresql['enable'] = false + prometheus['enable'] = false + puma['enable'] = false + redis['enable'] = false + redis_exporter['enable'] = false + registry['enable'] = false + sidekiq['enable'] = false + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Verify everything is stopped, and confirm no services are running: + + ```shell + sudo gitlab-ctl status + ``` + +1. Stop Redis on the **new server** before transferring the Redis database backup: + + ```shell + sudo gitlab-ctl stop redis + ``` + +1. Transfer the Redis database and GitLab backups to the new server: + + ```shell + sudo scp /var/opt/gitlab/redis/dump.rdb <your-linux-username>@new-server:/var/opt/gitlab/redis + sudo scp /var/opt/gitlab/backups/your-backup.tar <your-linux-username>@new-server:/var/opt/gitlab/backups + ``` + +## Restore data on the new server + +1. Restore appropriate file system permissions: + + ```shell + sudo chown gitlab-redis /var/opt/gitlab/redis + sudo chown gitlab-redis:gitlab-redis /var/opt/gitlab/redis/dump.rdb + sudo chown git:root /var/opt/gitlab/backups + sudo chown git:git /var/opt/gitlab/backups/your-backup.tar + ``` + +1. Start Redis: + + ```shell + sudo gitlab-ctl start redis + ``` + +1. [Restore the GitLab backup](restore_gitlab.md). +1. Verify that the Redis database restored correctly: + 1. On the left sidebar, at the bottom, select **Admin Area**. + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, verify that the numbers + match with what was shown on the old server. + 1. While still under the Sidekiq dashboard, select **Cron** and then **Enable All** + to re-enable periodic background jobs. +1. Test that read-only operations on the GitLab instance work as expected. For example, browse through project repository files, merge requests, and issues. +1. Disable [Maintenance Mode](../maintenance_mode/index.md), if previously enabled. +1. Test that the GitLab instance is working as expected. +1. If applicable, re-enable [incoming email](../incoming_email.md) and test it is working as expected. +1. Update your DNS or load balancer to point at the new server. +1. Unblock new CI/CD jobs from starting by removing the custom NGINX configuration + you added previously: + + ```ruby + # The following line must be removed + nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n }\n" + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Remove the scheduled maintenance [broadcast message banner](../broadcast_messages.md). diff --git a/doc/administration/backup_restore/restore_gitlab.md b/doc/administration/backup_restore/restore_gitlab.md index 9b6c6eb557a..2dd85602f99 100644 --- a/doc/administration/backup_restore/restore_gitlab.md +++ b/doc/administration/backup_restore/restore_gitlab.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Restore GitLab **(FREE SELF)** @@ -100,7 +100,7 @@ sudo gitlab-ctl status Next, ensure you have completed the [restore prerequisites](#restore-prerequisites) steps and have run `gitlab-ctl reconfigure` after copying over the GitLab secrets file from the original installation. -Next, restore the backup, specifying the timestamp of the backup you wish to +Next, restore the backup, specifying the ID of the backup you wish to restore: ```shell @@ -301,8 +301,8 @@ options. ### Specify backup to restore when there are more than one -By default, backup files use a naming scheme [starting with a timestamp](backup_gitlab.md#backup-timestamp). When more than one backup exists, you must specify which -`*_gitlab_backup.tar` file to restore by setting the environment variable `BACKUP=timestamp_of_backup`. +Backup files use a naming scheme [starting with a backup ID](index.md#backup-id). When more than one backup exists, you must specify which +`<backup-id>_gitlab_backup.tar` file to restore by setting the environment variable `BACKUP=<backup-id>`. ### Disable prompts during restore @@ -340,7 +340,7 @@ You can exclude specific tasks on restore by adding the environment variable `SK - `artifacts` (CI job artifacts) - `lfs` (LFS objects) - `terraform_state` (Terraform states) -- `registry` (Container Registry images) +- `registry` (Container registry images) - `pages` (Pages content) - `repositories` (Git repositories data) - `packages` (Packages) @@ -350,13 +350,13 @@ To exclude specific tasks: - Linux package installations: ```shell - sudo gitlab-backup restore BACKUP=timestamp_of_backup SKIP=db,uploads + sudo gitlab-backup restore BACKUP=<backup-id> SKIP=db,uploads ``` - Self-compiled installations: ```shell - sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup SKIP=db,uploads RAILS_ENV=production + sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> SKIP=db,uploads RAILS_ENV=production ``` ### Restore specific repository storages @@ -373,13 +373,13 @@ For example: - Linux package installations: ```shell - sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2 + sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2 ``` - Self-compiled installations: ```shell - sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_STORAGES=storage1,storage2 + sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2 ``` ### Restore specific repositories @@ -397,19 +397,19 @@ and skip the **Project D** in **Group A** (`group-a/project-d`): - Linux package installations: ```shell - sudo gitlab-backup restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d + sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d ``` - Self-compiled installations: ```shell - sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=timestamp_of_backup REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d + sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d ``` ### Restore untarred backups If an [untarred backup](backup_gitlab.md#skipping-tar-creation) (made with `SKIP=tar`) is found, -and no backup is chosen with `BACKUP=<timestamp>`, the untarred backup is used. +and no backup is chosen with `BACKUP=<backup-id>`, the untarred backup is used. For example: @@ -471,7 +471,7 @@ While restoring from backup, you can encounter an error when the following are t The error looks like: ```plaintext -{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupTimestamp>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"} +{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupID>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"} ``` To resolve this, you can update the Git [server hooks](../server_hooks.md) for GitLab version 15.11 and later, and create a new backup. diff --git a/doc/administration/broadcast_messages.md b/doc/administration/broadcast_messages.md index 4ed80010220..5a1cb88e876 100644 --- a/doc/administration/broadcast_messages.md +++ b/doc/administration/broadcast_messages.md @@ -1,8 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Broadcast messages **(FREE SELF)** @@ -57,8 +56,7 @@ To display messages to users on your GitLab instance, add a broadcast message. To add a broadcast message: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Messages**. 1. Select **Add new message**. 1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. @@ -86,8 +84,7 @@ If you must make changes to a broadcast message, you can edit it. To edit a broadcast message: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Messages**. 1. From the list of broadcast messages, select the edit button for the message. 1. After making the required changes, select **Update broadcast message**. @@ -101,8 +98,7 @@ You can delete a broadcast message while it's active. To delete a broadcast message: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Messages**. 1. From the list of broadcast messages, select the delete button for the message. diff --git a/doc/administration/cicd.md b/doc/administration/cicd.md index 10bc60fe399..4fd11041e91 100644 --- a/doc/administration/cicd.md +++ b/doc/administration/cicd.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD instance configuration **(FREE SELF)** diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index a6d20327802..9c87576aa80 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install the GitLab agent server for Kubernetes (KAS) **(FREE SELF)** diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 3f4d781e2a2..73583856cb0 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance features **(FREE SELF)** diff --git a/doc/administration/configure.md b/doc/administration/configure.md index 8ff2ae5aa9d..8b4f8a9abc6 100644 --- a/doc/administration/configure.md +++ b/doc/administration/configure.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure your GitLab installation **(FREE SELF)** diff --git a/doc/administration/consul.md b/doc/administration/consul.md index a65b2100237..0740c27dc7c 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to set up Consul **(PREMIUM SELF)** diff --git a/doc/administration/credentials_inventory.md b/doc/administration/credentials_inventory.md index d7b67dfd703..1bd4ce75891 100644 --- a/doc/administration/credentials_inventory.md +++ b/doc/administration/credentials_inventory.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Credentials inventory **(ULTIMATE SELF)** @@ -37,8 +36,7 @@ You can also [revoke](#revoke-a-users-personal-access-token), [delete](#delete-a You can revoke a user's personal access token. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Credentials**. 1. By the personal access token, select **Revoke**. @@ -58,8 +56,7 @@ When a PAT is revoked from the credentials inventory, the instance notifies the > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243833) in GitLab 14.8. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Credentials**. 1. Select the **Project Access Tokens** tab. 1. By the project access token, select **Revoke**. @@ -72,8 +69,7 @@ The project access token is revoked and a background worker is queued to delete > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225248) in GitLab 13.5. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Credentials**. 1. Select the **SSH Keys** tab. 1. By the SSH key, select **Delete**. diff --git a/doc/administration/custom_project_templates.md b/doc/administration/custom_project_templates.md index 239ec09de86..3c3319c80f9 100644 --- a/doc/administration/custom_project_templates.md +++ b/doc/administration/custom_project_templates.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom instance-level project templates **(PREMIUM SELF)** @@ -24,9 +24,8 @@ might modify the template projects without understanding the side effects. To select the group to manage the project templates for your instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Templates**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Templates**. 1. Expand **Custom project templates**. 1. Select a group to use. 1. Select **Save changes**. @@ -51,7 +50,7 @@ Prerequisites: - **Public** and **Internal** projects can be selected by any authenticated user. - **Private** projects can be selected only by members of that project. 1. Review the project's - [feature settings](../user/project/settings/index.md#configure-project-features-and-permissions). + [feature settings](../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions). All enabled project features should be set to **Everyone With Access**, except **GitLab Pages** and **Security and Compliance**. diff --git a/doc/administration/dedicated/index.md b/doc/administration/dedicated/index.md index 16efc353c84..ef9e53c8fb7 100644 --- a/doc/administration/dedicated/index.md +++ b/doc/administration/dedicated/index.md @@ -1,7 +1,7 @@ --- stage: SaaS Platforms group: GitLab Dedicated -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" description: 'Learn how to configure your GitLab Dedicated instance.' --- @@ -60,7 +60,7 @@ It can take up to 3 hours to create the GitLab Dedicated tenant. When the setup Available scheduled maintenance windows, performed outside standard working hours: - APAC: Wednesday 1 PM - 5 PM UTC -- EU: Tuesday 1 AM - 5 AM UTC +- EMEA: Tuesday 1 AM - 5 AM UTC - AMER Option 1: Tuesday 7 AM - 11 AM UTC - AMER Option 2: Sunday 9 PM - Monday 1 AM UTC @@ -214,11 +214,33 @@ Make sure the AWS KMS keys are replicated to your desired primary, secondary and ## Configuration changes +### Configuration change policy + +Configuration changes requested with a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) are batched up and applied during your environment's weekly four-hour maintenance window. + +This policy does not apply to configuration changes made by a GitLab Dedicated tenant admin [using Switchboard](#configuration-changes-in-switchboard). + +To have a change considered for an upcoming weekly maintenance window, all required information +must be submitted in full two business days before the start of the window. + +A configuration change might not be applied during an upcoming weekly maintenance window, even if +it meets the minimum lead time. If GitLab needs to perform high-priority maintenance tasks that +run beyond the maintenance window, configuration changes will be postponed to the following week. + +Changes requested with a support ticket cannot be applied outside of a weekly maintenance window unless it qualifies for +[emergency support](https://about.gitlab.com/support/#how-to-engage-emergency-support). + +### Configuration changes in Switchboard + Switchboard empowers the user to make limited configuration changes to their Dedicated Tenant Instance. As Switchboard matures further configuration changes will be made available. -To change or update the configuration of your GitLab Dedicated instance, use Switchboard following the instructions in the relevant section or open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with your request. You can request configuration changes for the options originally specified during onboarding, or for any of the following optional features. +To change or update the configuration of your GitLab Dedicated instance, use Switchboard following the instructions in the relevant section or open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with your request. + +You can request configuration changes for some of the options originally specified during onboarding, or for any of the following optional features. + +Configuration changes made with Switchboard can be applied immediately or deferred until your next scheduled weekly [maintenance window](#maintenance-window). -The turnaround time to process configuration change requests is [documented in the GitLab handbook](https://about.gitlab.com/handbook/engineering/infrastructure/team/gitlab-dedicated/#handling-configuration-changes-for-tenant-environments). +When applied immediately, changes may take up to 90 minutes to be deployed to your environment. Individual changes are applied in the order they are saved, or you may choose to save several changes at once before applying them in one batch. ### Inbound Private Link @@ -226,7 +248,7 @@ The turnaround time to process configuration change requests is [documented in t To enable the Inbound Private Link: -1. In the body of your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650), include the IAM Principal for the AWS user or role in your own AWS Organization that's establishing the VPC endpoint in your AWS account. GitLab Dedicated uses this IAM Principal for access-control. This IAM principal is the only one able to set up an endpoint to the service. +1. Open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). In the body of your support ticket, include the IAM principal for the AWS user or role in your AWS organization that's establishing the VPC endpoint in your AWS account. The IAM principal must be an [IAM role principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-roles) or [IAM user principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#principal-users). GitLab Dedicated uses this IAM Principal for access-control. This IAM principal is the only one able to set up an endpoint to the service. 1. After your IAM Principal has been allowlisted, GitLab [creates the Endpoint Service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) and communicates the `Service Endpoint Name` on the support ticket. The service name is generated by AWS upon creation of the service endpoint. - GitLab handles the domain verification for the Private DNS name, so that DNS resolution of the tenant instance domain name in your VPC resolves to the PrivateLink endpoint. - GitLab makes the Endpoint Service available in the Availability Zones you specified during the initial onboarding. If you did not specify any Availability Zones, GitLab randomly selects the Availability Zones IDs. @@ -304,7 +326,9 @@ GitLab Dedicated limits the number of reverse PrivateLink connections to 10. ### IP allowlist -GitLab Dedicated allows you to control which IP addresses can access your instance through an IP allowlist. +GitLab Dedicated allows you to control which IP addresses can access your instance through an IP allowlist. Once the IP allowlist has been enabled, when an IP not on the allowlist tries to access your instance an `HTTP 403 Forbidden` response is returned. + +IP addresses that have been added to your IP allowlist can be viewed on the Configuration page in Switchboard. You can add or remove IP addresses from your allowlist with Switchboard or a support request. #### Add an IP to the allowlist with Switchboard @@ -315,11 +339,11 @@ GitLab Dedicated allows you to control which IP addresses can access your instan 1. Select **Add Item**. 1. Enter the IP address and description. To add another IP address, repeat steps 5 and 6. 1. Select **Save**. -1. Scroll up to the top of the page and select whether to apply the changes immediately or during the next maintenance window. +1. Scroll up to the top of the page and select whether to apply the changes immediately or during the next maintenance window. After the changes are applied, the IP addresses are added to the IP allowlist for your instance. #### Add an IP to the allowlist with a Support Request -Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). After the configuration has been applied, when an IP not on the allowlist tries to access your instance, the connection is refused. +Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). The IP addresses are then added to the IP allowlist for your instance. ### SAML @@ -410,6 +434,23 @@ To enable group sync: 1. Add the [required elements](../../user/group/saml_sso/group_sync.md#configure-saml-group-sync) to the SAML configuration block you provide in your [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650). 1. Configure the [Group Links](../../user/group/saml_sso/group_sync.md#configure-saml-group-links). +### Add users to a tenant instance + +Tenant administrators can add Switchboard users to their tenant instance. There are two types of users: + +- **Read only**: Users can only view tenant data. +- **Admin**: Users can edit the tenant configuration and manage users. + +To add a new user to your GitLab Dedicated instance: + +1. From the **Tenants** page, select **Manage** next to the tenant instance. +1. From the top of the page, select **Users**. +1. Select **New user**. +1. Enter the **Email** and select a **Role** for the user. +1. Select **Create**. + +An invitation to use Switchboard is sent to the user. + ### Access to application logs GitLab [application logs](../../administration/logs/index.md) are delivered to an S3 bucket in the GitLab tenant account, which can be shared with you. Logs stored in the S3 bucket are retained indefinitely, until the 1 year retention policy is fully enforced. GitLab team members can view more information in this confidential issue: @@ -419,3 +460,11 @@ To gain read only access to this bucket: 1. Open a [support ticket](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=4414917877650) with the title "Customer Log Access". In the body of the ticket, include a list of IAM Principal ARNs (users or roles) that are fetching the logs from S3. 1. GitLab then informs you of the name of the S3 bucket. Your nominated users/roles are then able to list and get all objects in the S3 bucket. + +You can use the [AWS CLI](https://aws.amazon.com/cli/) to verify that access to the S3 bucket works as expected. + +#### Bucket contents and structure + +The S3 bucket contains a combination of **infrastructure logs** and **application logs** from the GitLab [log system](../../administration/logs/index.md). The logs in the bucket are encrypted using an AWS KMS key that is managed by GitLab. If you choose to enable [BYOK](#encrypted-data-at-rest-byok), the application logs are not encrypted with the key you provide. + +The logs in the S3 bucket are organized by date in `YYYY/MM/DD/HH` format. For example, there would be a directory like `2023/10/12/13`. That directory would contain the logs from October 12, 2023 at 1300 UTC. The logs are streamed into the bucket with [Amazon Kinesis Data Firehose](https://aws.amazon.com/kinesis/data-firehose/). diff --git a/doc/administration/diff_limits.md b/doc/administration/diff_limits.md index dcf5a2b1b32..66a1e86b025 100644 --- a/doc/administration/diff_limits.md +++ b/doc/administration/diff_limits.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Diff limits administration **(FREE SELF)** @@ -33,8 +32,7 @@ set values are presented as **Too large** are cannot be expanded in the UI. To configure these values: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for the diff limit. diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index 1eecc139d1f..5b9bfe82294 100644 --- a/doc/administration/docs_self_host.md +++ b/doc/administration/docs_self_host.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Host the GitLab product documentation **(FREE SELF)** @@ -82,7 +82,7 @@ To run the GitLab product documentation website in a Docker container: You can use GitLab Pages to host the GitLab product documentation. -Prerequisite: +Prerequisites: - Ensure the Pages site URL does not use a subfolder. Because of the way the site is pre-compiled, the CSS and JavaScript files are relative to the diff --git a/doc/administration/email_from_gitlab.md b/doc/administration/email_from_gitlab.md index ec231d25da2..0fe07c63169 100644 --- a/doc/administration/email_from_gitlab.md +++ b/doc/administration/email_from_gitlab.md @@ -1,43 +1,35 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Email from GitLab **(PREMIUM SELF)** -GitLab provides a tool to administrators for emailing all users, or users of -a chosen group or project, right from the Admin Area. Users receive the email -at their primary email address. +Administrators can email all users, or users of a chosen group or project. +Users receive the email at their primary email address. -For information about email notifications originating from GitLab, read -[GitLab notification emails](../user/profile/notifications.md). +You might use this functionality to notify your users: -## Use-cases +- About a new project, a new feature, or a new product launch. +- About a new deployment, or that downtime is expected. -- Notify your users about a new project, a new feature, or a new product launch. -- Notify your users about a new deployment, or that downtime is expected - for a particular reason. +For information about email notifications originating from GitLab, read +[GitLab notification emails](../user/profile/notifications.md). ## Sending emails to users from GitLab -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. Select **Overview > Users**. -1. Select **Send email to users**. - -  +You can send email notifications to all users, or only to users in a specific group or project. +You can send email notifications once every 10 minutes. -1. Compose an email and choose where to send it (all users or users of a - chosen group or project). The email body only supports plain text messages. - HTML, Markdown, and other rich text formats are not supported, and is - sent as plain text to users. +To send an email: -  - -NOTE: -[Starting with GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/31509), email notifications can be sent only once every 10 minutes. This helps minimize performance issues. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. +1. In the upper-right corner, select **Send email to users** (**{mail}**). +1. Complete the fields. The email body supports only plain text and does not support HTML, Markdown, or other rich text formats. +1. From the **Select group or project** dropdown list, select the recipient. +1. Select **Send message**. ## Unsubscribing from emails diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index 4ffb1495ec8..1346786446c 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Encrypted Configuration **(FREE SELF)** diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index 260095d12ac..c3bc4b0bc1f 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Environment variables **(FREE SELF)** @@ -39,6 +38,8 @@ You can use the following environment variables to override certain values: | `RAILS_ENV` | string | The Rails environment; can be one of `production`, `development`, `staging`, or `test`. | | `GITLAB_RAILS_CACHE_DEFAULT_TTL_SECONDS` | integer | The default TTL used for entries stored in the Rails-cache. Default is `28800`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95042) in 15.3. | | `GITLAB_CI_CONFIG_FETCH_TIMEOUT_SECONDS` | integer | Timeout for resolving remote includes in CI config in seconds. Must be between `0` and `60`. Default is `30`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116383) in 15.11. | +| `GITLAB_LFS_MAX_OID_TO_FETCH` | integer | Sets the maximum number of LFS objects to link. Default is `100,000`. | +| `SIDEKIQ_SEMI_RELIABLE_FETCH_TIMEOUT` | integer | Sets the timeout for Sidekiq semi-reliable fetch. Default is `5`. [Before GitLab 16.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139583), default was `3`. If you experience high Redis CPU consumption on GitLab 16.6 and earlier, or if you have customized this variable, you should update this variable to `5`. | ## Adding more variables diff --git a/doc/administration/external_pipeline_validation.md b/doc/administration/external_pipeline_validation.md index 9d182a95fc9..5442bc74125 100644 --- a/doc/administration/external_pipeline_validation.md +++ b/doc/administration/external_pipeline_validation.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External pipeline validation **(FREE SELF)** diff --git a/doc/administration/external_users.md b/doc/administration/external_users.md index 5c3f3ae26b1..d8951631b72 100644 --- a/doc/administration/external_users.md +++ b/doc/administration/external_users.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External users **(FREE SELF)** @@ -30,7 +30,7 @@ For example, if an external user is added as Guest, and your project is internal private, they do not have access to the code; you need to grant the external user access at the Reporter level or above if you want them to have access to the code. You should always take into account the -[project's visibility](../user/public_access.md#change-project-visibility) and [permissions settings](../user/project/settings/index.md#configure-project-features-and-permissions) +[project's visibility](../user/public_access.md#change-project-visibility) and [permissions settings](../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions) as well as the permission level of the user. NOTE: @@ -40,8 +40,7 @@ An administrator can flag a user as external by either of the following methods: - [Through the API](../api/users.md#user-modification). - Using the GitLab UI: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. There, you can find the option to flag the user as external. @@ -56,8 +55,7 @@ Additionally, users can be set as external users using: By default, new users are not set as external users. This behavior can be changed by an administrator: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index 76bcc8c699e..b40334fe507 100644 --- a/doc/administration/feature_flags.md +++ b/doc/administration/feature_flags.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "GitLab administrator: enable and disable GitLab features deployed behind feature flags" --- diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index d1b46a9fec1..a16e1c2fde9 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.md @@ -1,8 +1,7 @@ --- stage: Manage group: Import and Integrate -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # File hooks **(FREE SELF)** diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index 8aec77d9d88..a927450d80f 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Automatic background verification **(PREMIUM SELF)** @@ -27,9 +27,8 @@ the site more time before scheduling a planned failover. On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Expand **Verification information** tab for that site to view automatic checksumming status for repositories and wikis. Successes are shown in green, pending work in gray, and failures in red. @@ -38,9 +37,8 @@ On the **primary** site: On the **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Expand **Verification information** tab for that site to view automatic checksumming status for repositories and wikis. Successes are shown in green, pending work in gray, and failures in red. @@ -67,9 +65,8 @@ increase load and vice versa. On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Select **Edit** for the **primary** site to customize the minimum re-verification interval: @@ -101,8 +98,7 @@ sudo gitlab-rake geo:verification:wiki:reset If the **primary** and **secondary** sites have a checksum verification mismatch, the cause may not be apparent. To find the cause of a checksum mismatch: 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Projects**. 1. Find the project that you want to check the checksum differences and select its name. diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index 5f2cbd4d03b..be4f4d3f6a4 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Bring a demoted primary site back online **(PREMIUM SELF)** diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 2f636dc6ba4..f97c892c3eb 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Disaster Recovery (Geo) **(PREMIUM SELF)** diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index cdc52b55c3e..01e5c33a726 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Disaster recovery for planned failover **(PREMIUM SELF)** @@ -45,7 +44,7 @@ be adapted for use with any other file-based data. ### Container registry By default, the container registry is not automatically replicated to secondary -sites and this needs to be manually configured, see [Container Registry for a secondary site](../replication/container_registry.md). +sites and this needs to be manually configured, see [container registry for a secondary site](../replication/container_registry.md). If you are using local storage on your current primary site for the container registry, you can `rsync` the container registry objects to the secondary @@ -154,9 +153,8 @@ ensure these processes are close to 100% as possible during active use. On the **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. Replicated objects (shown in green) should be close to 100%, and there should be no failures (shown in red). If a large proportion of objects aren't yet replicated (shown in gray), consider giving the site more @@ -183,9 +181,8 @@ This [content was moved to another location](background_verification.md). On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Messages**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Messages**. 1. Add a message notifying users on the maintenance window. You can check under **Geo > Sites** to estimate how long it takes to finish syncing. @@ -197,9 +194,8 @@ To ensure that all data is replicated to a secondary site, updates (write reques be disabled on the **primary** site: 1. Enable [maintenance mode](../../maintenance_mode/index.md) on the **primary** site. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Background Jobs**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Cron**. 1. Select `Disable All` to disable non-Geo periodic background jobs. 1. Select `Enable` for the `geo_sidekiq_cron_config_worker` cron job. @@ -211,8 +207,7 @@ be disabled on the **primary** site: 1. If you are manually replicating any data not managed by Geo, trigger the final replication process now. 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -227,8 +222,7 @@ be disabled on the **primary** site: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md index 787e7c4669e..f24d2bba2a3 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- WARNING: @@ -65,9 +64,8 @@ promote a Geo replica and perform a failover. On the **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites** to see its status. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites** to see its status. Replicated objects (shown in green) should be close to 100%, and there should be no failures (shown in red). If a large proportion of objects aren't replicated (shown in gray), consider giving the site more @@ -105,8 +103,7 @@ follow these steps to avoid unnecessary data loss: [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), trigger the final replication process now. 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -121,8 +118,7 @@ follow these steps to avoid unnecessary data loss: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md index e29b19ca040..0afd669e797 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- WARNING: @@ -115,8 +114,7 @@ follow these steps to avoid unnecessary data loss: connection. 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**.. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Cron**. 1. Select `Disable All` to disable any non-Geo periodic background jobs. @@ -134,8 +132,7 @@ follow these steps to avoid unnecessary data loss: [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), trigger the final replication process now. 1. On the **primary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -150,8 +147,7 @@ follow these steps to avoid unnecessary data loss: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** site: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/glossary.md b/doc/administration/geo/glossary.md index d0f94ba39f5..138bf6c444c 100644 --- a/doc/administration/geo/glossary.md +++ b/doc/administration/geo/glossary.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index e8b2cb38563..6609bbed5a6 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo **(PREMIUM SELF)** @@ -115,15 +115,16 @@ The following are required to run Geo: The following operating systems are known to ship with a current version of OpenSSH: - [CentOS](https://www.centos.org) 7.4 or later - [Ubuntu](https://ubuntu.com) 16.04 or later -- PostgreSQL 12 or 13 with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication) +- [Supported PostgreSQL versions](https://about.gitlab.com/handbook/engineering/development/enablement/data_stores/database/postgresql-upgrade-cadence.html) for your GitLab releases with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication). - Note,[PostgreSQL 12 is deprecated](../../update/deprecations.md#postgresql-12-deprecated) and is removed in GitLab 16.0. +- All sites must run [the same PostgreSQL versions](setup/database.md#postgresql-replication). + - Where possible, you should also use the same operating system version on all + Geo sites. If using different operating system versions between Geo sites, you + **must** [check OS locale data compatibility](replication/troubleshooting.md#check-os-locale-data-compatibility) + across Geo sites to avoid silent corruption of database indexes. - Git 2.9 or later - Git-lfs 2.4.2 or later on the user side when using LFS - All sites must run the same GitLab version. -- All sites must run [the same PostgreSQL versions](setup/database.md#postgresql-replication). - - If using different operating system versions between Geo sites, - [check OS locale data compatibility](replication/troubleshooting.md#check-os-locale-data-compatibility) - across Geo sites to avoid silent corruption of database indexes. - All sites must define the same [repository storages](../repository_storage_paths.md). Additionally, check the GitLab [minimum requirements](../../install/requirements.md), @@ -159,9 +160,8 @@ public URL of the primary site is used. To update the internal URL of the primary Geo site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Select **Edit** on the primary site. 1. Change the **Internal URL**, then select **Save changes**. @@ -245,17 +245,29 @@ Linux package-managed database. External databases are not supported. In some circumstances, like during [upgrades](replication/upgrading_the_geo_sites.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. -Pausing and resuming replication is done through a command-line tool from the node in the secondary site where the `postgresql` service is enabled. +If you plan to allow user activity on your secondary sites during the upgrade, +do not pause replication for a [zero downtime upgrade](../../update/zero_downtime.md). While paused, the secondary site gets more and more out-of-date. +One known effect is that more and more Git fetches get redirected or proxied to the primary site. There may be additional unknown effects. + +Pausing and resuming replication is done through a command-line tool from a specific node in the secondary site. Depending on your database architecture, +this will target either the `postgresql` or `patroni` service: + +- If you are using a single node for all services on your secondary site, you must run the commands on this single node. +- If you have a standalone PostgreSQL node on your secondary site, you must run the commands on this standalone PostgreSQL node. +- If your secondary site is using a Patroni cluster, you must run these commands on the secondary Patroni standby leader node. + +If you aren't using a single node for all services on your secondary site, ensure that the `/etc/gitlab/gitlab.rb` on your PostgreSQL or Patroni nodes +contains the configuration line `gitlab_rails['geo_node_name'] = 'node_name'`, where `node_name` is the same as the `geo_node_name` on the application node. -If `postgresql` is on a standalone database node, ensure that `gitlab.rb` on that node contains the configuration line `gitlab_rails['geo_node_name'] = 'node_name'`, where `node_name` is the same as the `geo_node_name` on the application node. +**To Pause: (from secondary site)** -**To Pause: (from secondary)** +Also, be aware that if PostgreSQL is restarted after pausing replication (either by restarting the VM or restarting the service with `gitlab-ctl restart postgresql`), PostgreSQL automatically resumes replication, which is something you wouldn't want during an upgrade or in a planned failover scenario. ```shell gitlab-ctl geo-replication-pause ``` -**To Resume: (from secondary)** +**To Resume: (from secondary site)** ```shell gitlab-ctl geo-replication-resume @@ -273,9 +285,9 @@ For information on configuring Geo with Object storage, see [Geo with Object sto For information on using Geo in disaster recovery situations to mitigate data-loss and restore services, see [Disaster Recovery](disaster_recovery/index.md). -### Replicating the Container Registry +### Replicating the container registry -For more information on how to replicate the Container Registry, see [Container Registry for a **secondary** site](replication/container_registry.md). +For more information on how to replicate the container registry, see [Container registry for a **secondary** site](replication/container_registry.md). ### Geo secondary proxy diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 8722ab574c3..b50f86dcf47 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo configuration **(PREMIUM SELF)** @@ -217,8 +216,7 @@ In the following steps, replace `<ssh_host_key_path>` with the one you're using: ``` 1. Navigate to the Primary Node GitLab Instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Geo > Sites**. 1. Select **Add site**.  @@ -327,9 +325,8 @@ method to be enabled. This is enabled by default, but if converting an existing On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. If using Git over SSH, then: 1. Ensure "Enabled Git access protocols" is set to "Both SSH and HTTP(S)". @@ -341,9 +338,8 @@ On the **primary** site: You can sign in to the **secondary** site with the same credentials you used with the **primary** site. After you sign in: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Verify that it's correctly identified as a **secondary** Geo site, and that Geo is enabled. diff --git a/doc/administration/geo/replication/container_registry.md b/doc/administration/geo/replication/container_registry.md index 65ecba0d04a..b9bee753089 100644 --- a/doc/administration/geo/replication/container_registry.md +++ b/doc/administration/geo/replication/container_registry.md @@ -1,17 +1,16 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Container Registry for a secondary site **(PREMIUM SELF)** +# Container registry for a secondary site **(PREMIUM SELF)** -You can set up a Container Registry on your **secondary** Geo site that mirrors the one on the **primary** Geo site. +You can set up a container registry on your **secondary** Geo site that mirrors the one on the **primary** Geo site. NOTE: -The Container Registry replication is used only for disaster recovery purposes. We do not recommend -pulling the Container Registry data from the secondary. For a feature proposal to implement it in the +The container registry replication is used only for disaster recovery purposes. We do not recommend +pulling the container registry data from the secondary. For a feature proposal to implement it in the future, see [Geo: Accelerate container images by serving read request from secondary site](https://gitlab.com/gitlab-org/gitlab/-/issues/365864) for details. ## Supported container registries @@ -40,7 +39,7 @@ For more information on supported registry storage drivers see Read the [Load balancing considerations](https://docs.docker.com/registry/deploying/#load-balancing-considerations) when deploying the Registry, and how to set up the storage driver for the GitLab integrated -[Container Registry](../../packages/container_registry.md#use-object-storage). +[container registry](../../packages/container_registry.md#use-object-storage). ### Registries that support OCI artifacts @@ -55,26 +54,26 @@ The following registries support OCI artifacts: For more information, see the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec). -## Configure Container Registry replication +## Configure container registry replication You can enable a storage-agnostic replication so it can be used for cloud or local storage. Whenever a new image is pushed to the **primary** site, each **secondary** site pulls it to its own container repository. -To configure Container Registry replication: +To configure container registry replication: 1. Configure the [**primary** site](#configure-primary-site). 1. Configure the [**secondary** site](#configure-secondary-site). -1. Verify Container Registry [replication](#verify-replication). +1. Verify container registry [replication](#verify-replication). ### Configure **primary** site -Make sure that you have Container Registry set up and working on +Make sure that you have container registry set up and working on the **primary** site before following the next steps. -To be able to replicate new container images, the Container Registry must send notification events to the -**primary** site for every push. The token shared between the Container Registry and the web nodes on the +To be able to replicate new container images, the container registry must send notification events to the +**primary** site for every push. The token shared between the container registry and the web nodes on the **primary** is used to make communication more secure. 1. SSH into your GitLab **primary** server and login as root (for GitLab HA, you only need a Registry node): @@ -124,17 +123,17 @@ To be able to replicate new container images, the Container Registry must send n ### Configure **secondary** site -Make sure you have Container Registry set up and working on +Make sure you have container registry set up and working on the **secondary** site before following the next steps. The following steps should be done on each **secondary** site you're expecting to see the container images replicated. Because we need to allow the **secondary** site to communicate securely with -the **primary** site Container Registry, we need to have a single key +the **primary** site container registry, we need to have a single key pair for all the sites. The **secondary** site uses this key to generate a short-lived JWT that is pull-only-capable to access the -**primary** site Container Registry. +**primary** site container registry. For each application and Sidekiq node on the **secondary** site: @@ -164,11 +163,10 @@ For each application and Sidekiq node on the **secondary** site: ### Verify replication -To verify Container Registry replication is working, on the **secondary** site: +To verify container registry replication is working, on the **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Nodes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Nodes**. The initial replication, or "backfill", is probably still in progress. You can monitor the synchronization process on each Geo site from the **primary** site's **Geo Nodes** dashboard in your browser. diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 896501128f7..634a524e6f0 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported Geo data types **(PREMIUM SELF)** @@ -190,7 +189,7 @@ successfully, you must replicate their data using some other means. |Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | GitLab-managed object storage replication (added in GitLab version) | GitLab-managed object storage verification (added in GitLab version) | Notes | |:--------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------|:---------------------------------------------------------------------------|:--------------------------------------------------------------------|:----------------------------------------------------------------|:------| |[Application data in PostgreSQL](../../postgresql/index.md) | **Yes** (10.2) | **Yes** (10.2) | Not applicable | Not applicable | | -|[Project repository](../../../user/project/repository/index.md) | **Yes** (10.2) | **Yes** (10.7) | Not applicable | Not applicable | Migrated to [self-service framework](../../../development/geo/framework.md) in 16.2. See GitLab issue [#367925](https://gitlab.com/gitlab-org/gitlab/-/issues/367925) for more details.<br /><br />Behind feature flag `geo_project_repository_replication`, enabled by default in (16.3).<br /><br /> All projects, including [archived projects](../../../user/project/settings/index.md#archive-a-project), are replicated. | +|[Project repository](../../../user/project/repository/index.md) | **Yes** (10.2) | **Yes** (10.7) | Not applicable | Not applicable | Migrated to [self-service framework](../../../development/geo/framework.md) in 16.2. See GitLab issue [#367925](https://gitlab.com/gitlab-org/gitlab/-/issues/367925) for more details.<br /><br />Behind feature flag `geo_project_repository_replication`, enabled by default in (16.3).<br /><br /> All projects, including [archived projects](../../../user/project/settings/migrate_projects.md#archive-a-project), are replicated. | |[Project wiki repository](../../../user/project/wiki/index.md) | **Yes** (10.2)<sup>2</sup> | **Yes** (10.7)<sup>2</sup> | Not applicable | Not applicable | Migrated to [self-service framework](../../../development/geo/framework.md) in 15.11. See GitLab issue [#367925](https://gitlab.com/gitlab-org/gitlab/-/issues/367925) for more details.<br /><br />Behind feature flag `geo_project_wiki_repository_replication`, enabled by default in (15.11). | |[Group wiki repository](../../../user/project/wiki/group.md) | [**Yes** (13.10)](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | [**Yes** (16.3)](https://gitlab.com/gitlab-org/gitlab/-/issues/323897) | Not applicable | Not applicable | Behind feature flag `geo_group_wiki_repository_replication`, enabled by default. | |[Uploads](../../uploads.md) | **Yes** (10.2) | **Yes** (14.6) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Replication is behind the feature flag `geo_upload_replication`, enabled by default. Verification was behind the feature flag `geo_upload_verification`, removed in 14.8. | @@ -200,10 +199,10 @@ successfully, you must replicate their data using some other means. |[CI job artifacts](../../../ci/jobs/job_artifacts.md) | **Yes** (10.4) | **Yes** (14.10) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Verification is behind the feature flag `geo_job_artifact_replication`, enabled by default in 14.10. | |[CI Pipeline Artifacts](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/pipeline_artifact.rb) | [**Yes** (13.11)](https://gitlab.com/gitlab-org/gitlab/-/issues/238464) | [**Yes** (13.11)](https://gitlab.com/gitlab-org/gitlab/-/issues/238464) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Persists additional artifacts after a pipeline completes. | |[CI Secure Files](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/secure_file.rb) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [**Yes** (16.4)](object_storage.md) | Verification is behind the feature flag `geo_ci_secure_file_replication`, enabled by default in 15.3. | -|[Container Registry](../../packages/container_registry.md) | **Yes** (12.3)<sup>1</sup> | **Yes** (15.10) | **Yes** (12.3)<sup>1</sup> | **Yes** (15.10) | See [instructions](container_registry.md) to set up the Container Registry replication. | +|[Container registry](../../packages/container_registry.md) | **Yes** (12.3)<sup>1</sup> | **Yes** (15.10) | **Yes** (12.3)<sup>1</sup> | **Yes** (15.10) | See [instructions](container_registry.md) to set up the container registry replication. | |[Terraform Module Registry](../../../user/packages/terraform_module_registry/index.md) | **Yes** (14.0) | **Yes** (14.0) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | **Yes** (16.1) | Not applicable | Not applicable | Designs also require replication of LFS objects and Uploads. | -|[Package Registry](../../../user/packages/package_registry/index.md) | **Yes** (13.2) | **Yes** (13.10) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Behind feature flag `geo_package_file_replication`, enabled by default. | +|[Package registry](../../../user/packages/package_registry/index.md) | **Yes** (13.2) | **Yes** (13.10) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Versioned Terraform State](../../terraform_state.md) | **Yes** (13.5) | **Yes** (13.12) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Replication is behind the feature flag `geo_terraform_state_version_replication`, enabled by default. Verification was behind the feature flag `geo_terraform_state_version_verification`, which was removed in 14.0. | |[External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | **Yes** (14.6) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [**Yes** (16.4)](object_storage.md) | Replication is behind the feature flag `geo_merge_request_diff_replication`, enabled by default. Verification was behind the feature flag `geo_merge_request_diff_verification`, removed in 14.7.| |[Versioned snippets](../../../user/snippets.md#versioned-snippets) | [**Yes** (13.7)](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [**Yes** (14.2)](https://gitlab.com/groups/gitlab-org/-/epics/2810) | Not applicable | Not applicable | Verification was implemented behind the feature flag `geo_snippet_repository_verification` in 13.11, and the feature flag was removed in 14.2. | @@ -215,6 +214,7 @@ successfully, you must replicate their data using some other means. |[Elasticsearch integration](../../../integration/advanced_search/elasticsearch.md) | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | No | No | Not planned because further product discovery is required and Elasticsearch (ES) clusters can be rebuilt. Secondaries use the same ES cluster as the primary. | |[Dependency Proxy Images](../../../user/packages/dependency_proxy/index.md) | [**Yes** (15.7)](https://gitlab.com/groups/gitlab-org/-/epics/8833) | [**Yes** (15.7)](https://gitlab.com/groups/gitlab-org/-/epics/8833) | [**Yes** (15.7)](https://gitlab.com/groups/gitlab-org/-/epics/8833) | [**Yes** (16.4)](object_storage.md) | | |[Vulnerability Export](../../../user/application_security/vulnerability_report/index.md#export-vulnerability-details) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/3111) | No | No | No | Not planned because they are ephemeral and sensitive information. They can be regenerated on demand. | +|Packages NPM metadata cache | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/408278) | No | No | No | Not planned because it would not notably improve disaster recovery capabilities nor response times at secondary sites. | <sup>1</sup> Migrated to [self-service framework](../../../development/geo/framework.md) in 15.5. See GitLab issue [#337436](https://gitlab.com/gitlab-org/gitlab/-/issues/337436) for more details. diff --git a/doc/administration/geo/replication/disable_geo.md b/doc/administration/geo/replication/disable_geo.md index 42c37a79ec2..597bb08c188 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Disabling Geo **(PREMIUM SELF)** @@ -36,9 +35,8 @@ to do that. To remove the **primary** site: 1. [Remove all secondary Geo sites](remove_geo_site.md) -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Nodes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Nodes**. 1. Select **Remove** for the **primary** node. 1. Confirm by selecting **Remove** when the prompt appears. diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index 311cdeee5b9..f29d7967feb 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo Frequently Asked Questions **(PREMIUM SELF)** @@ -65,9 +65,9 @@ connectivity between your sites, and your hardware. That's totally fine. We use HTTP(s) to fetch repository changes from the **primary** site to all **secondary** sites. -## Is this possible to set up a Container Registry for a **secondary** site that mirrors the one on the **primary** site? +## Is this possible to set up a container registry for a **secondary** site that mirrors the one on the **primary** site? -Yes. See [Container Registry for a **secondary** site](container_registry.md). +Yes. See [container registry for a **secondary** site](container_registry.md). ## Can you sign in to a secondary site? diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index 7897635e78f..b4f4374fd9b 100644 --- a/doc/administration/geo/replication/geo_validation_tests.md +++ b/doc/administration/geo/replication/geo_validation_tests.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo validation tests **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/location_aware_git_url.md b/doc/administration/geo/replication/location_aware_git_url.md index a3abc945288..6849a648991 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Location-aware Git remote URL with AWS Route53 **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index 786030736f6..850ab9f0707 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo for multiple nodes **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index 3b6b214d9e3..9d1cb4387a0 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo with Object storage **(PREMIUM SELF)** @@ -43,9 +42,8 @@ whether they are stored on the local file system or in object storage. To enable GitLab replication: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Nodes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Nodes**. 1. Select **Edit** on the **secondary** site. 1. In the **Synchronization Settings** section, find the **Allow this secondary node to replicate content on Object Storage** checkbox to enable it. diff --git a/doc/administration/geo/replication/remove_geo_site.md b/doc/administration/geo/replication/remove_geo_site.md index a55c05050a0..4787b949e2e 100644 --- a/doc/administration/geo/replication/remove_geo_site.md +++ b/doc/administration/geo/replication/remove_geo_site.md @@ -1,17 +1,15 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Removing secondary Geo sites **(PREMIUM SELF)** **Secondary** sites can be removed from the Geo cluster using the Geo administration page of the **primary** site. To remove a **secondary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Nodes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Nodes**. 1. For the **secondary** site you want to remove, select **Remove**. 1. Confirm by selecting **Remove** when the prompt appears. diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index e099c2b2e9d..a267ac23779 100644 --- a/doc/administration/geo/replication/security_review.md +++ b/doc/administration/geo/replication/security_review.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo security review (Q&A) **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/single_sign_on.md b/doc/administration/geo/replication/single_sign_on.md index 15e24cdcefb..f8ca6209524 100644 --- a/doc/administration/geo/replication/single_sign_on.md +++ b/doc/administration/geo/replication/single_sign_on.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo with Single Sign On (SSO) **(PREMIUM SELF)** @@ -15,7 +14,7 @@ This documentation only discusses Geo-specific SSO considerations and configurat [Instance-wide SAML](../../../integration/saml.md) must be working on your primary Geo site. -You only configure SAML on the primary site. Configuring `gitlab_rails['omniauth_providers']` in `gitlab.rb` in a secondary site has no effect. +You only configure SAML on the primary site. Configuring `gitlab_rails['omniauth_providers']` in `gitlab.rb` in a secondary site has no effect. The secondary site authenticates against the SAML provider configured on the primary site. Depending on the [URL type](#determine-the-type-of-url-your-secondary-site-uses) of the secondary site, [additional configuration](#saml-with-separate-url-with-proxying-enabled) might be needed on the primary site. ### Determine the type of URL your secondary site uses diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index dd021695800..6e60ae34a22 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Geo **(PREMIUM SELF)** @@ -27,9 +27,8 @@ Before attempting more advanced troubleshooting: On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. We perform the following health checks on each **secondary** site to help identify if something is wrong: @@ -199,7 +198,7 @@ http://secondary.example.com/ Last status report was: 1 minute ago ``` -There are up to three statuses for each item. For example, for `Project Repositories`, you see the following lines: +Each item can have up to three statuses. For example, for `Project Repositories`, you see the following lines: ```plaintext Project Repositories: succeeded 12345 / total 12345 (100%) @@ -466,9 +465,9 @@ For more information about recommended site names in the description of the Name ### Check OS locale data compatibility -If different operating systems or different operating system versions are deployed across Geo sites, you should perform a locale data compatibility check before setting up Geo. +If different operating systems or different operating system versions are deployed across Geo sites, you **must** perform a locale data compatibility check before setting up Geo. -Geo uses PostgreSQL and Streaming Replication to replicate data across Geo sites. PostgreSQL uses locale data provided by the operating system's C library for sorting text. If the locale data in the C library is incompatible across Geo sites, it can cause erroneous query results that lead to [incorrect behavior on secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/360723). +Geo uses PostgreSQL and Streaming Replication to replicate data across Geo sites. PostgreSQL uses locale data provided by the operating system's C library for sorting text. If the locale data in the C library is incompatible across Geo sites, it causes erroneous query results that lead to [incorrect behavior on secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/360723). For example, Ubuntu 18.04 (and earlier) and RHEL/Centos7 (and earlier) are incompatible with their later releases. See the [PostgreSQL wiki for more details](https://wiki.postgresql.org/wiki/Locale_data_changes). @@ -493,9 +492,9 @@ or the reverse order: 1-1 ``` -If the output is identical on all hosts, then they running compatible versions of locale data. +If the output is **identical** on all hosts, then they running compatible versions of locale data and you may proceed with Geo configuration. -If the output differs on some hosts, PostgreSQL replication does not work properly: indexes are corrupted on the database replicas. You should select operating system versions that are compatible. +If the output **differs** on any hosts, PostgreSQL replication will not work properly: indexes will become corrupted on the database replicas. You **must** select operating system versions that are compatible. A full index rebuild is required if the on-disk data is transferred 'at rest' to an operating system with an incompatible locale, or through replication. @@ -682,6 +681,19 @@ In GitLab 13.4, a seed project is added when GitLab is first installed. This mak on a new Geo secondary site. There is an [issue to account for seed projects](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5618) when checking the database. +### Message: `FATAL: could not map anonymous shared memory: Cannot allocate memory` + +If you see this message, it means that the secondary site's PostgreSQL tries to request memory that is higher than the available memory. There is an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/381585) that tracks this problem. + +Example error message in Patroni logs (located at `/var/log/gitlab/patroni/current` for Linux package installations): + +```plaintext +2023-11-21_23:55:18.63727 FATAL: could not map anonymous shared memory: Cannot allocate memory +2023-11-21_23:55:18.63729 HINT: This error usually means that PostgreSQL's request for a shared memory segment exceeded available memory, swap space, or huge pages. To reduce the request size (currently 17035526144 bytes), reduce PostgreSQL's shared memory usage, perhaps by reducing shared_buffers or max_connections. +``` + +The workaround is to increase the memory available to the secondary site's PostgreSQL nodes to match the memory requirements of the primary site's PostgreSQL nodes. + ## Synchronization errors ### Reverify all uploads (or any SSF data type which is verified) @@ -726,16 +738,75 @@ If large repositories are affected by this problem, their resync may take a long time and cause significant load on your Geo sites, storage and network systems. -If you see the error message `Synchronization failed - Error syncing repository` along with `fatal: fsck error in packed object`, this indicates -a consistency check error when syncing the repository. +The following error message indicates a consistency check error when syncing the repository: + +```plaintext +Synchronization failed - Error syncing repository [..] fatal: fsck error in packed object +``` + +Several issues can trigger this error. For example, problems with email addresses: + +```plaintext +Error syncing repository: 13:fetch remote: "error: object <SHA>: badEmail: invalid author/committer line - bad email + fatal: fsck error in packed object + fatal: fetch-pack: invalid index-pack output +``` + +Another issue that can trigger this error is `object <SHA>: hasDotgit: contains '.git'`. Check the specific errors because you might have more than one problem across all +your repositories. + +A second synchronization error can also be caused by repository check issues: + +```plaintext +Error syncing repository: 13:Received RST_STREAM with error code 2. +``` + +These errors can be observed by [immediately syncing all failed repositories](#sync-all-failed-repositories-now). + +Removing the malformed objects causing consistency errors involves rewriting the repository history, which is usually not an option. + +To ignore these consistency checks, reconfigure Gitaly **on the secondary Geo sites** to ignore these `git fsck` issues. +The following configuration example: + +- [Uses the new configuration structure](../../../update/versions/gitlab_16_changes.md#gitaly-configuration-structure-change) required from GitLab 16.0. +- Ignores five common check failures. + +[The Gitaly documentation has more details](../../gitaly/configure_gitaly.md#repository-consistency-checks) +about other Git check failures and older versions of GitLab. + +```ruby +gitaly['configuration'] = { + git: { + config: [ + { key: "fsck.duplicateEntries", value: "ignore" }, + { key: "fsck.badFilemode", value: "ignore" }, + { key: "fsck.missingEmail", value: "ignore" }, + { key: "fsck.badEmail", value: "ignore" }, + { key: "fsck.hasDotgit", value: "ignore" }, + { key: "fetch.fsck.duplicateEntries", value: "ignore" }, + { key: "fetch.fsck.badFilemode", value: "ignore" }, + { key: "fetch.fsck.missingEmail", value: "ignore" }, + { key: "fetch.fsck.badEmail", value: "ignore" }, + { key: "fetch.fsck.hasDotgit", value: "ignore" }, + { key: "receive.fsck.duplicateEntries", value: "ignore" }, + { key: "receive.fsck.badFilemode", value: "ignore" }, + { key: "receive.fsck.missingEmail", value: "ignore" }, + { key: "receive.fsck.badEmail", value: "ignore" }, + { key: "receive.fsck.hasDotgit", value: "ignore" }, + ], + }, +} +``` + +GitLab 16.1 and later [include an enhancement](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5879) that might resolve some of these issues. -One example of a consistency error is: `error: object f4a87a3be694fbbd6e50a668a31a8513caeaafe3: hasDotgit: contains '.git`. +[Gitaly issue 5625](https://gitlab.com/gitlab-org/gitaly/-/issues/5625) proposes to ensure that Geo replicates repositories even if the source repository contains +problematic commits. -Removing the malformed objects causing consistency errors require rewriting the repository history, which is not always an option. However, -it's possible to override the consistency checks instead. To do that, follow -[the instructions in the Gitaly docs](../../gitaly/configure_gitaly.md#repository-consistency-checks). +#### Related error `does not appear to be a git repository` -You can also get the error message `Synchronization failed - Error syncing repository` along with the following log messages, this indicates that the expected `geo` remote is not present in the `.git/config` file +You can also get the error message `Synchronization failed - Error syncing repository` along with the following log messages. +This error indicates that the expected Geo remote is not present in the `.git/config` file of a repository on the secondary Geo site's file system: ```json @@ -839,7 +910,7 @@ This behavior affects only the following data types through GitLab 14.6: | Data type | From version | | ------------------------ | ------------ | -| Package Registry | 13.10 | +| Package registry | 13.10 | | CI Pipeline Artifacts | 13.11 | | Terraform State Versions | 13.12 | | Infrastructure Registry (renamed to Terraform Module Registry in GitLab 15.11) | 14.0 | @@ -953,6 +1024,11 @@ The following script: - Displays the project details and the reasons for the last failure. - Attempts to resync the repository. - Reports back if a failure occurs, and why. +- Might take some time to complete. Each repository check must complete + before reporting back the result. If your session times out, take measures + to allow the process to continue running such as starting a `screen` session, + or running it using [Rails runner](../../operations/rails_console.md#using-the-rails-runner) + and `nohup`. ```ruby Geo::ProjectRegistry.sync_failed('repository').find_each do |p| @@ -1450,9 +1526,8 @@ If you have updated the value of `external_url` in `/etc/gitlab/gitlab.rb` for t In this case, make sure to update the changed URL on all your sites: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Change the URL and save the change. ### Message: `ERROR: canceling statement due to conflict with recovery` during backup @@ -1556,9 +1631,8 @@ site's URL matches its external URL. On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Find the affected **secondary** site and select **Edit**. 1. Ensure the **URL** field matches the value found in `/etc/gitlab/gitlab.rb` in `external_url "https://gitlab.example.com"` on the **Rails nodes of the secondary** site. diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index 3a4366cfd63..c02571e21a8 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tuning Geo **(PREMIUM SELF)** @@ -14,9 +13,8 @@ in the background. On the **primary** site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Geo > Sites**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Geo > Sites**. 1. Select **Edit** of the secondary site you want to tune. 1. Under **Tuning settings**, there are several variables that can be tuned to improve the performance of Geo: diff --git a/doc/administration/geo/replication/upgrading_the_geo_sites.md b/doc/administration/geo/replication/upgrading_the_geo_sites.md index 6f02ef29f99..aae35d45bde 100644 --- a/doc/administration/geo/replication/upgrading_the_geo_sites.md +++ b/doc/administration/geo/replication/upgrading_the_geo_sites.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading the Geo sites **(PREMIUM SELF)** diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md index cfaa02e1a17..0594709b23d 100644 --- a/doc/administration/geo/replication/usage.md +++ b/doc/administration/geo/replication/usage.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- Please update EE::GitLab::GeoGitAccess::GEO_SERVER_DOCS_URL if this file is moved) --> @@ -41,5 +41,5 @@ Go modules can be pulled from secondary sites, with a number of limitations: - Git configuration (using `insteadOf`) is needed to fetch data from the Geo secondary site. - For private projects, authentication details need to be specified in `~/.netrc`. -Read more in the -[working with projects `go get` documentation](../../../user/project/working_with_projects.md#fetch-go-modules-from-geo-secondary-sites). +For more information, see +[Using a project as a Go package](../../../user/project/use_project_as_go_package.md#fetch-go-modules-from-geo-secondary-sites). diff --git a/doc/administration/geo/secondary_proxy/index.md b/doc/administration/geo/secondary_proxy/index.md index f6572ded4a9..22bb7dd721d 100644 --- a/doc/administration/geo/secondary_proxy/index.md +++ b/doc/administration/geo/secondary_proxy/index.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo proxying for secondary sites **(PREMIUM SELF)** @@ -115,7 +114,7 @@ for details. - Non-Rails requests are not proxied, so other services may need to use a separate, non-unified URL to ensure requests are always sent to the primary. These services include: - - GitLab Container Registry - [can be configured to use a separate domain](../../packages/container_registry.md#configure-container-registry-under-its-own-domain). + - GitLab container registry - [can be configured to use a separate domain](../../packages/container_registry.md#configure-container-registry-under-its-own-domain). - GitLab Pages - should always use a separate domain, as part of [the prerequisites for running GitLab Pages](../../pages/index.md#prerequisites). - With a unified URL, Let's Encrypt can't generate certificates unless it can reach both IPs through the same domain. diff --git a/doc/administration/geo/secondary_proxy/location_aware_external_url.md b/doc/administration/geo/secondary_proxy/location_aware_external_url.md index ae701bb8482..4ff349d8741 100644 --- a/doc/administration/geo/secondary_proxy/location_aware_external_url.md +++ b/doc/administration/geo/secondary_proxy/location_aware_external_url.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Location-aware public URL **(PREMIUM SELF)** diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 471bae72c5b..13615825a14 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo database replication **(PREMIUM SELF)** @@ -763,7 +762,7 @@ defaults default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions frontend internal-postgresql-tcp-in - bind *:5000 + bind *:5432 mode tcp option tcplog @@ -900,6 +899,10 @@ For each node running a Patroni instance on the secondary site: gitlab_rails['auto_migrate'] = false ``` + When configuring `patroni['standby_cluster']['host']` and `patroni['standby_cluster']['port']`: + - `INTERNAL_LOAD_BALANCER_PRIMARY_IP` must point to the primary internal load balancer IP. + - `INTERNAL_LOAD_BALANCER_PRIMARY_PORT` must point to the frontend port [configured for the primary Patroni cluster leader](#step-2-configure-the-internal-load-balancer-on-the-primary-site). **Do not** use the PgBouncer frontend port. + 1. Reconfigure GitLab for the changes to take effect. This step is required to bootstrap PostgreSQL users and settings. @@ -952,8 +955,7 @@ If you want to run the Geo tracking database on a single node, see [Configure th A production-ready and secure setup for the tracking PostgreSQL DB requires at least three Consul nodes: two Patroni nodes, and one PgBouncer node on the secondary site. -Because of [issue 6587](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6587), Consul can't track multiple -services, so these must be different than the nodes used for the Standby Cluster database. +Consul can track multiple services, so you can choose to reuse the nodes used for the Standby Cluster database, though the instructions below do not show how to combine configurations when reusing Consul nodes. Be sure to use [password credentials](../../postgresql/replication_and_failover.md#database-authorization-for-patroni) and other database best practices. diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index 6083d7331b6..2d0e9e45197 100644 --- a/doc/administration/geo/setup/external_database.md +++ b/doc/administration/geo/setup/external_database.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo with external PostgreSQL instances **(PREMIUM SELF)** diff --git a/doc/administration/geo/setup/index.md b/doc/administration/geo/setup/index.md index f59dec17f8b..1868902cfcf 100644 --- a/doc/administration/geo/setup/index.md +++ b/doc/administration/geo/setup/index.md @@ -1,8 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Setting up Geo **(PREMIUM SELF)** @@ -33,14 +32,14 @@ If both Geo sites are based on the [1K reference architecture](../../reference_a If using external PostgreSQL services, for example Amazon RDS, follow [Set up Geo for two single-node sites (with external PostgreSQL services)](two_single_node_external_services.md). -Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the Container Registry might be required. +Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the container registry might be required. ### Multi-node Geo sites If one or more of your sites is using the [2K reference architecture](../../reference_architectures/2k_users.md) or larger, see [Configure Geo for multiple nodes](../replication/multiple_servers.md). -Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the Container Registry might be required. +Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the container registry might be required. ### General steps for reference @@ -50,7 +49,7 @@ Depending on your GitLab deployment, [additional configuration](#additional-conf 1. [Configure GitLab](../replication/configuration.md) to set the **primary** and **secondary** sites. 1. Follow the [Using a Geo Site](../replication/usage.md) guide. -Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the Container Registry might be required. +Depending on your GitLab deployment, [additional configuration](#additional-configuration) for LDAP, object storage, and the container registry might be required. ### Additional configuration @@ -59,7 +58,7 @@ Depending on how you use GitLab, the following configuration might be required: - If the **primary** site uses object storage, [configure object storage replication](../replication/object_storage.md) for the **secondary** sites. - If you use LDAP, [configure a secondary LDAP server](../../auth/ldap/index.md) for the **secondary** sites. For more information, see [LDAP with Geo](../replication/single_sign_on.md#ldap). -- If you use the Container Registry, [configure the Container Registry for replication](../replication/container_registry.md) on the **primary** and **secondary** sites. +- If you use the container registry, [configure the container registry for replication](../replication/container_registry.md) on the **primary** and **secondary** sites. You should [configure unified URLs](../secondary_proxy/index.md#set-up-a-unified-url-for-geo-sites) to use a single, unified URL for all Geo sites. diff --git a/doc/administration/geo/setup/two_single_node_external_services.md b/doc/administration/geo/setup/two_single_node_external_services.md index 405a791fedc..a77bacb0587 100644 --- a/doc/administration/geo/setup/two_single_node_external_services.md +++ b/doc/administration/geo/setup/two_single_node_external_services.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up Geo for two single-node sites (with external PostgreSQL services) **(PREMIUM SELF)** @@ -38,7 +38,7 @@ Prerequisites: ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` @@ -292,7 +292,7 @@ secondary site is a read-only copy. ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<secondary_site_name_here>' ``` @@ -306,8 +306,7 @@ secondary site is a read-only copy. ``` 1. Go to the primary node GitLab instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**.. 1. Select **Geo > Sites**. 1. Select **Add site**. @@ -362,8 +361,7 @@ If you convert an existing site to Geo, you should check that the clone method i On the primary site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. If you use Git over SSH: @@ -378,8 +376,7 @@ the primary site. After you sign in: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. 1. Verify that the site is correctly identified as a secondary Geo site, and that Geo is enabled. diff --git a/doc/administration/geo/setup/two_single_node_sites.md b/doc/administration/geo/setup/two_single_node_sites.md index da7ec455c6a..edcb2f467ff 100644 --- a/doc/administration/geo/setup/two_single_node_sites.md +++ b/doc/administration/geo/setup/two_single_node_sites.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up Geo for two single-node sites **(PREMIUM SELF)** @@ -38,7 +38,7 @@ Prerequisites: ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` @@ -538,7 +538,7 @@ You must manually replicate the secret file across all of your secondary sites, ```ruby ## ## The unique identifier for the Geo site. See - ## https://docs.gitlab.com/ee/user/admin_area/geo_nodes.html#common-settings + ## https://docs.gitlab.com/ee/administration/geo_sites.html#common-settings ## gitlab_rails['geo_node_name'] = '<site_name_here>' ``` @@ -552,8 +552,7 @@ You must manually replicate the secret file across all of your secondary sites, ``` 1. Navigate to the primary node GitLab instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. 1. Select **Add site**. @@ -608,8 +607,7 @@ If you convert an existing site to Geo, you should check that the clone method i On the primary site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. If you use Git over SSH: @@ -624,8 +622,7 @@ the primary site. After you sign in: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. 1. Verify that the site is correctly identified as a secondary Geo site, and that Geo is enabled. diff --git a/doc/administration/geo_sites.md b/doc/administration/geo_sites.md index f0c3e24f643..fa650bade47 100644 --- a/doc/administration/geo_sites.md +++ b/doc/administration/geo_sites.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo sites Admin Area **(PREMIUM SELF)** @@ -11,8 +11,7 @@ You can configure various settings for GitLab Geo sites. For more information, s On either the primary or secondary site: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. ## Common settings @@ -72,8 +71,7 @@ the primary uses the secondary's internal URL to contact it directly. The internal URL defaults to external URL. To change it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Geo > Sites**. 1. Select **Edit** on the site you want to customize. 1. Edit the internal URL. diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index 978ea519305..336ed743a47 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -1,5 +1,5 @@ --- -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: Tutorials --- diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 7fb241b8d1f..7ff676e3512 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Set and configure Git protocol v2" --- diff --git a/doc/administration/gitaly/concurrency_limiting.md b/doc/administration/gitaly/concurrency_limiting.md new file mode 100644 index 00000000000..321bb9efe20 --- /dev/null +++ b/doc/administration/gitaly/concurrency_limiting.md @@ -0,0 +1,244 @@ +--- +stage: Systems +group: Gitaly +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Concurrency limiting + +To avoid overwhelming the servers running Gitaly, you can limit concurrency of: + +- RPCs. +- Pack objects. + +These limits can be fixed, or set as adaptive. + +WARNING: +Enabling limits on your environment should be done with caution and only +in select circumstances, such as to protect against unexpected traffic. +When reached, limits _do_ result in disconnects that negatively impact users. +For consistent and stable performance, you should first explore other options such as +adjusting node specifications, and [reviewing large repositories](../../user/project/repository/managing_large_repositories.md) or workloads. + +## Limit RPC concurrency + +When cloning or pulling repositories, various RPCs run in the background. In particular, the Git pack RPCs: + +- `SSHUploadPackWithSidechannel` (for Git SSH). +- `PostUploadPackWithSidechannel` (for Git HTTP). + +These RPCs can consume a large amount of resources, which can have a significant impact in situations such as: + +- Unexpectedly high traffic. +- Running against [large repositories](../../user/project/repository/managing_large_repositories.md) that don't follow best practices. + +You can limit these processes from overwhelming your Gitaly server in these scenarios using the concurrency limits in the Gitaly configuration file. For +example: + +```ruby +# in /etc/gitlab/gitlab.rb +gitaly['configuration'] = { + # ... + concurrency: [ + { + rpc: '/gitaly.SmartHTTPService/PostUploadPackWithSidechannel', + max_per_repo: 20, + max_queue_wait: '1s', + max_queue_size: 10, + }, + { + rpc: '/gitaly.SSHService/SSHUploadPackWithSidechannel', + max_per_repo: 20, + max_queue_wait: '1s', + max_queue_size: 10, + }, + ], +} +``` + +- `rpc` is the name of the RPC to set a concurrency limit for per repository. +- `max_per_repo` is the maximum number of in-flight RPC calls for the given RPC per repository. +- `max_queue_wait` is the maximum amount of time a request can wait in the concurrency queue to + be picked up by Gitaly. +- `max_queue_size` is the maximum size the concurrency queue (per RPC method) can grow to before requests are rejected by + Gitaly. + +This limits the number of in-flight RPC calls for the given RPCs. The limit is applied per +repository. In the example above: + +- Each repository served by the Gitaly server can have at most 20 simultaneous `PostUploadPackWithSidechannel` and + `SSHUploadPackWithSidechannel` RPC calls in flight. +- If another request comes in for a repository that has used up its 20 slots, that request gets + queued. +- If a request waits in the queue for more than 1 second, it is rejected with an error. +- If the queue grows beyond 10, subsequent requests are rejected with an error. + +NOTE: +When these limits are reached, users are disconnected. + +You can observe the behavior of this queue using the Gitaly logs and Prometheus. For more +information, see the [relevant documentation](monitoring.md#monitor-gitaly-concurrency-limiting). + +## Limit pack-objects concurrency + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7891) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `gitaly_pack_objects_limiting_remote_ip`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5772) in GitLab 16.0. Feature flag `gitaly_pack_objects_limiting_remote_ip` removed. + +Gitaly triggers `git-pack-objects` processes when handling both SSH and HTTPS traffic to clone or pull repositories. These processes generate a `pack-file` and can +consume a significant amount of resources, especially in situations such as unexpectedly high traffic or concurrent pulls from a large repository. On GitLab.com, we also +observe problems with clients that have slow internet connections. + +You can limit these processes from overwhelming your Gitaly server by setting pack-objects concurrency limits in the Gitaly configuration file. This setting limits the +number of in-flight pack-object processes per remote IP address. + +WARNING: +Only enable these limits on your environment with caution and only in select circumstances, such as to protect against unexpected traffic. When reached, these limits +disconnect users. For consistent and stable performance, you should first explore other options such as adjusting node specifications, and +[reviewing large repositories](../../user/project/repository/managing_large_repositories.md) or workloads. + +Example configuration: + +```ruby +# in /etc/gitlab/gitlab.rb +gitaly['pack_objects_limiting'] = { + 'max_concurrency' => 15, + 'max_queue_length' => 200, + 'max_queue_wait' => '60s', +} +``` + +- `max_concurrency` is the maximum number of in-flight pack-object processes per key. +- `max_queue_length` is the maximum size the concurrency queue (per key) can grow to before requests are rejected by Gitaly. +- `max_queue_wait` is the maximum amount of time a request can wait in the concurrency queue to be picked up by Gitaly. + +In the example above: + +- Each remote IP can have at most 15 simultaneous pack-object processes in flight on a Gitaly node. +- If another request comes in from an IP that has used up its 15 slots, that request gets queued. +- If a request waits in the queue for more than 1 minute, it is rejected with an error. +- If the queue grows beyond 200, subsequent requests are rejected with an error. + +When the pack-object cache is enabled, pack-objects limiting kicks in only if the cache is missed. For more, see [Pack-objects cache](configure_gitaly.md#pack-objects-cache). + +You can observe the behavior of this queue using Gitaly logs and Prometheus. For more information, see +[Monitor Gitaly pack-objects concurrency limiting](monitoring.md#monitor-gitaly-pack-objects-concurrency-limiting). + +## Adaptive concurrency limiting + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6. + +Gitaly supports two concurrency limits: + +- An [RPC concurrency limit](#limit-rpc-concurrency), which allow you to configure a maximum number of simultaneous in-flight requests for each + Gitaly RPC. The limit is scoped by RPC and repository. +- A [Pack-objects concurrency limit](#limit-pack-objects-concurrency), which restricts the number of concurrent Git data transfer request by IP. + +If this limit is exceeded, either: + +- The request is put in a queue. +- The request is rejected if the queue is full or if the request remains in the queue for too long. + +Both of these concurrency limits can be configured statically. Though static limits can yield good protection results, they have some drawbacks: + +- Static limits are not good for all usage patterns. There is no one-size-fits-all value. If the limit is too low, big repositories are + negatively impacted. If the limit is too high, the protection is essentially lost. +- It's tedious to maintain a sane value for the concurrency limit, especially when the workload of each repository changes over time. +- A request can be rejected even though the server is idle because the rate doesn't factor in the load on the server. + +You can overcome all of these drawbacks and keep the benefits of concurrency limiting by configuring adaptive concurrency limits. Adaptive +concurrency limits are optional and build on the two concurrency limiting types. It uses Additive Increase/Multiplicative Decrease (AIMD) +algorithm. Each adaptive limit: + +- Gradually increases up to a certain upper limit during typical process functioning. +- Quickly decreases when the host machine has a resource problem. + +This mechanism provides some headroom for the machine to "breathe" and speeds up current inflight requests. + + + +The adaptive limiter calibrates the limits every 30 seconds and: + +- Increases the limits by one until reaching the upper limit. +- Decreases the limits by half when the top-level cgroup has either memory usage that exceeds 90%, excluding highly-evictable page caches, + or CPU throttled for 50% or more of the observation time. + +Otherwise, the limits increase by one until reaching the upper bound. For more information about technical implementation +of this system, refer to [this blueprint](../../architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md). + +Adaptive limiting is enabled for each RPC or pack-objects cache individually. However, limits are calibrated at the same time. + +### Enable adaptiveness for RPC concurrency + +Prerequisites: + +- Because adaptive limiting depends on [control groups](configure_gitaly.md#control-groups), control groups must be enabled before using adaptive limiting. + +The following is an example to configure an adaptive limit for RPC concurrency: + +```ruby +# in /etc/gitlab/gitlab.rb +gitaly['configuration'] = { + # ... + concurrency: [ + { + rpc: '/gitaly.SmartHTTPService/PostUploadPackWithSidechannel', + max_queue_wait: '1s', + max_queue_size: 10, + adaptive: true, + min_limit: 10, + initial_limit: 20, + max_limit: 40 + }, + { + rpc: '/gitaly.SSHService/SSHUploadPackWithSidechannel', + max_queue_wait: '10s', + max_queue_size: 20, + adaptive: true, + min_limit: 10, + initial_limit: 50, + max_limit: 100 + }, + ], +} +``` + +In this example: + +- `adaptive` sets whether the adaptiveness is enabled. If set, the `max_per_repo` value is ignored in favor of the following configuration. +- `initial_limit` is the per-repository concurrency limit to use when Gitaly starts. +- `max_limit` is the minimum per-repository concurrency limit of the configured RPC. Gitaly increases the current limit + until it reaches this number. +- `min_limit` is the is the minimum per-repository concurrency limit of the configured RPC. When the host machine has a resource problem, + Gitaly quickly reduces the limit until reaching this value. + +For more information, see [RPC concurrency](#limit-rpc-concurrency). + +### Enable adaptiveness for pack-objects concurrency + +Prerequisites: + +- Because adaptive limiting depends on [control groups](configure_gitaly.md#control-groups), control groups must be enabled before using adaptive limiting. + +The following is an example to configure an adaptive limit for pack-objects concurrency: + +```ruby +# in /etc/gitlab/gitlab.rb +gitaly['pack_objects_limiting'] = { + 'max_queue_length' => 200, + 'max_queue_wait' => '60s', + 'adaptive' => true, + 'min_limit' => 10, + 'initial_limit' => 20, + 'max_limit' => 40 +} +``` + +In this example: + +- `adaptive` sets whether the adaptiveness is enabled. If set, the value of `max_concurrency` is ignored in favor of the following configuration. +- `initial_limit` is the per-IP concurrency limit to use when Gitaly starts. +- `max_limit` is the minimum per-IP concurrency limit for pack-objects. Gitaly increases the current limit until it reaches this number. +- `min_limit` is the is the minimum per-IP concurrency limit for pack-objects. When the host machine has a resources problem, Gitaly quickly + reduces the limit until it reaches this value. + +For more information, see [pack-objects concurrency](#limit-pack-objects-concurrency). diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index 15ace9c4ed9..d89413b2cf4 100644 --- a/doc/administration/gitaly/configure_gitaly.md +++ b/doc/administration/gitaly/configure_gitaly.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Gitaly **(FREE SELF)** @@ -25,9 +25,9 @@ Configure Gitaly in one of two ways: The following configuration options are also available: -- Enabling [TLS support](#enable-tls-support). -- Limiting [RPC concurrency](#limit-rpc-concurrency). -- Limiting [pack-objects concurrency](#limit-pack-objects-concurrency). +- Enabling [TLS support](tls_support.md). +- Limiting [RPC concurrency](concurrency_limiting.md#limit-rpc-concurrency). +- Limiting [pack-objects concurrency](concurrency_limiting.md#limit-pack-objects-concurrency). ## About the Gitaly token @@ -95,7 +95,7 @@ the default ports for HTTP and HTTPs communication. WARNING: Gitaly servers must not be exposed to the public internet as Gitaly network traffic is unencrypted by default. The use of firewall is highly recommended to restrict access to the Gitaly server. -Another option is to [use TLS](#enable-tls-support). +Another option is to [use TLS](tls_support.md). In the following sections, we describe how to configure two Gitaly servers with secret token `abc123secret`: @@ -441,22 +441,14 @@ Configure Gitaly clients in one of two ways: default: gitaly_address: tcp://gitaly1.internal:8075 gitaly_token: AUTH_TOKEN_1 - path: /some/local/path storage1: gitaly_address: tcp://gitaly1.internal:8075 gitaly_token: AUTH_TOKEN_1 - path: /some/local/path storage2: gitaly_address: tcp://gitaly2.internal:8075 gitaly_token: AUTH_TOKEN_2 - path: /some/local/path ``` - NOTE: - `/some/local/path` should be set to a local folder that exists, however no data is stored in - this folder. This requirement is scheduled to be removed when - [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. - 1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Run `sudo -u git -H bundle exec rake gitlab:gitaly:check RAILS_ENV=production` to confirm the Gitaly client can connect to Gitaly servers. @@ -575,457 +567,6 @@ Disable Gitaly on a GitLab server in one of two ways: ::EndTabs -## Enable TLS support - -Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure -connections, use the `tls://` URL scheme in the `gitaly_address` of the corresponding -storage entry in the GitLab configuration. - -Gitaly provides the same server certificates as client certificates in TLS -connections to GitLab. This can be used as part of a mutual TLS authentication strategy -when combined with reverse proxies (for example, NGINX) that validate client certificate -to grant access to GitLab. - -You must supply your own certificates as this isn't provided automatically. The certificate -corresponding to each Gitaly server must be installed on that Gitaly server. - -Additionally, the certificate (or its certificate authority) must be installed on all: - -- Gitaly servers. -- Gitaly clients that communicate with it. - -If you use a load balancer, it must be able to negotiate HTTP/2 using the ALPN TLS extension. - -### Certificate requirements - -- The certificate must specify the address you use to access the Gitaly server. You must add the hostname or IP address as a Subject Alternative Name to the certificate. -- You can configure Gitaly servers with both an unencrypted listening address `listen_addr` and an - encrypted listening address `tls_listen_addr` at the same time. This allows you to gradually - transition from unencrypted to encrypted traffic if necessary. -- The certificate's Common Name field is ignored. - -### Configure Gitaly with TLS - -Configure Gitaly with TLS in one of two ways: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -1. Create certificates for Gitaly servers. -1. On the Gitaly clients, copy the certificates (or their certificate authority) into - `/etc/gitlab/trusted-certs`: - - ```shell - sudo cp cert.pem /etc/gitlab/trusted-certs/ - ``` - -1. On the Gitaly clients, edit `git_data_dirs` in `/etc/gitlab/gitlab.rb` as follows: - - ```ruby - git_data_dirs({ - 'default' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, - 'storage1' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, - 'storage2' => { 'gitaly_address' => 'tls://gitaly2.internal:9999' }, - }) - ``` - -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). -1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate - there: - - ```shell - sudo mkdir -p /etc/gitlab/ssl - sudo chmod 755 /etc/gitlab/ssl - sudo cp key.pem cert.pem /etc/gitlab/ssl/ - sudo chmod 644 key.pem cert.pem - ``` - -1. Copy all Gitaly server certificates (or their certificate authority) to - `/etc/gitlab/trusted-certs` on all Gitaly servers and clients - so that Gitaly servers and clients trust the certificate when calling into themselves - or other Gitaly servers: - - ```shell - sudo cp cert1.pem cert2.pem /etc/gitlab/trusted-certs/ - ``` - -1. Edit `/etc/gitlab/gitlab.rb` and add: - - <!-- Updates to following example must also be made at https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab --> - - ```ruby - gitaly['configuration'] = { - # ... - tls_listen_addr: '0.0.0.0:9999', - tls: { - certificate_path: '/etc/gitlab/ssl/cert.pem', - key_path: '/etc/gitlab/ssl/key.pem', - }, - } - ``` - -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). -1. Run `sudo gitlab-rake gitlab:gitaly:check` on the Gitaly client (for example, the - Rails application) to confirm it can connect to Gitaly servers. -1. Verify Gitaly traffic is being served over TLS by - [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). -1. Optional. Improve security by: - 1. Disabling non-TLS connections by commenting out or deleting `gitaly['configuration'][:listen_addr]` in - `/etc/gitlab/gitlab.rb`. - 1. Saving the file. - 1. [Reconfiguring GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). - -:::TabTitle Self-compiled (source) - -1. Create certificates for Gitaly servers. -1. On the Gitaly clients, copy the certificates into the system trusted certificates: - - ```shell - sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt - sudo update-ca-certificates - ``` - -1. On the Gitaly clients, edit `storages` in `/home/git/gitlab/config/gitlab.yml` as follows: - - ```yaml - gitlab: - repositories: - storages: - default: - gitaly_address: tls://gitaly1.internal:9999 - path: /some/local/path - storage1: - gitaly_address: tls://gitaly1.internal:9999 - path: /some/local/path - storage2: - gitaly_address: tls://gitaly2.internal:9999 - path: /some/local/path - ``` - - NOTE: - `/some/local/path` should be set to a local folder that exists, however no data is stored - in this folder. This requirement is scheduled to be removed when - [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. - -1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). -1. On the Gitaly servers, create or edit `/etc/default/gitlab` and add: - - ```shell - export SSL_CERT_DIR=/etc/gitlab/ssl - ``` - -1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate there: - - ```shell - sudo mkdir -p /etc/gitlab/ssl - sudo chmod 755 /etc/gitlab/ssl - sudo cp key.pem cert.pem /etc/gitlab/ssl/ - sudo chmod 644 key.pem cert.pem - ``` - -1. Copy all Gitaly server certificates (or their certificate authority) to the system trusted - certificates folder so Gitaly server trusts the certificate when calling into itself or other Gitaly - servers. - - ```shell - sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt - sudo update-ca-certificates - ``` - -1. Edit `/home/git/gitaly/config.toml` and add: - - ```toml - tls_listen_addr = '0.0.0.0:9999' - - [tls] - certificate_path = '/etc/gitlab/ssl/cert.pem' - key_path = '/etc/gitlab/ssl/key.pem' - ``` - -1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). -1. Verify Gitaly traffic is being served over TLS by - [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). -1. Optional. Improve security by: - 1. Disabling non-TLS connections by commenting out or deleting `listen_addr` in - `/home/git/gitaly/config.toml`. - 1. Saving the file. - 1. [Restarting GitLab](../restart_gitlab.md#self-compiled-installations). - -::EndTabs - -#### Update the certificates - -To update the Gitaly certificates after initial configuration: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, but no configuration changes have been made to -`/etc/gitlab/gitlab.rb`, then reconfiguring GitLab doesn’t affect Gitaly. Instead, you must restart Gitaly manually for the certificates to be loaded -by the Gitaly process: - -```shell -sudo gitlab-ctl restart gitaly -``` - -If you change or update the certificates in `/etc/gitlab/trusted-certs` without making changes to the `/etc/gitlab/gitlab.rb` file, you must: - -1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) so the symlinks for the trusted certificates are updated. -1. Restart Gitaly manually for the certificates to be loaded by the Gitaly process: - - ```shell - sudo gitlab-ctl restart gitaly - ``` - -:::TabTitle Self-compiled (source) - -If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, you must -[restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process. - -If you change or update the certificates in `/usr/local/share/ca-certificates`, you must: - -1. Run `sudo update-ca-certificates` to update the system's trusted store. -1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process. - -::EndTabs - -### Observe type of Gitaly connections - -For information on observing the type of Gitaly connections being served, see the -[relevant documentation](monitoring.md#queries). - -## Limit RPC concurrency - -WARNING: -Enabling limits on your environment should be done with caution and only -in select circumstances, such as to protect against unexpected traffic. -When reached, limits _do_ result in disconnects that negatively impact users. -For consistent and stable performance, you should first explore other options such as -adjusting node specifications, and [reviewing large repositories](../../user/project/repository/managing_large_repositories.md) or workloads. - -When cloning or pulling repositories, various RPCs run in the background. In particular, the Git pack RPCs: - -- `SSHUploadPackWithSidechannel` (for Git SSH). -- `PostUploadPackWithSidechannel` (for Git HTTP). - -These RPCs can consume a large amount of resources, which can have a significant impact in situations such as: - -- Unexpectedly high traffic. -- Running against [large repositories](../../user/project/repository/managing_large_repositories.md) that don't follow best practices. - -You can limit these processes from overwhelming your Gitaly server in these scenarios using the concurrency limits in the Gitaly configuration file. For -example: - -```ruby -# in /etc/gitlab/gitlab.rb -gitaly['configuration'] = { - # ... - concurrency: [ - { - rpc: '/gitaly.SmartHTTPService/PostUploadPackWithSidechannel', - max_per_repo: 20, - max_queue_wait: '1s', - max_queue_size: 10, - }, - { - rpc: '/gitaly.SSHService/SSHUploadPackWithSidechannel', - max_per_repo: 20, - max_queue_wait: '1s', - max_queue_size: 10, - }, - ], -} -``` - -- `rpc` is the name of the RPC to set a concurrency limit for per repository. -- `max_per_repo` is the maximum number of in-flight RPC calls for the given RPC per repository. -- `max_queue_wait` is the maximum amount of time a request can wait in the concurrency queue to - be picked up by Gitaly. -- `max_queue_size` is the maximum size the concurrency queue (per RPC method) can grow to before requests are rejected by - Gitaly. - -This limits the number of in-flight RPC calls for the given RPCs. The limit is applied per -repository. In the example above: - -- Each repository served by the Gitaly server can have at most 20 simultaneous `PostUploadPackWithSidechannel` and - `SSHUploadPackWithSidechannel` RPC calls in flight. -- If another request comes in for a repository that has used up its 20 slots, that request gets - queued. -- If a request waits in the queue for more than 1 second, it is rejected with an error. -- If the queue grows beyond 10, subsequent requests are rejected with an error. - -NOTE: -When these limits are reached, users are disconnected. - -You can observe the behavior of this queue using the Gitaly logs and Prometheus. For more -information, see the [relevant documentation](monitoring.md#monitor-gitaly-concurrency-limiting). - -## Limit pack-objects concurrency - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7891) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `gitaly_pack_objects_limiting_remote_ip`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5772) in GitLab 16.0. Feature flag `gitaly_pack_objects_limiting_remote_ip` removed. - -Gitaly triggers `git-pack-objects` processes when handling both SSH and HTTPS traffic to clone or pull repositories. These processes generate a `pack-file` and can -consume a significant amount of resources, especially in situations such as unexpectedly high traffic or concurrent pulls from a large repository. On GitLab.com, we also -observe problems with clients that have slow internet connections. - -You can limit these processes from overwhelming your Gitaly server by setting pack-objects concurrency limits in the Gitaly configuration file. This setting limits the -number of in-flight pack-object processes per remote IP address. - -WARNING: -Only enable these limits on your environment with caution and only in select circumstances, such as to protect against unexpected traffic. When reached, these limits -disconnect users. For consistent and stable performance, you should first explore other options such as adjusting node specifications, and -[reviewing large repositories](../../user/project/repository/managing_large_repositories.md) or workloads. - -Example configuration: - -```ruby -# in /etc/gitlab/gitlab.rb -gitaly['pack_objects_limiting'] = { - 'max_concurrency' => 15, - 'max_queue_length' => 200, - 'max_queue_wait' => '60s', -} -``` - -- `max_concurrency` is the maximum number of in-flight pack-object processes per key. -- `max_queue_length` is the maximum size the concurrency queue (per key) can grow to before requests are rejected by Gitaly. -- `max_queue_wait` is the maximum amount of time a request can wait in the concurrency queue to be picked up by Gitaly. - -In the example above: - -- Each remote IP can have at most 15 simultaneous pack-object processes in flight on a Gitaly node. -- If another request comes in from an IP that has used up its 15 slots, that request gets queued. -- If a request waits in the queue for more than 1 minute, it is rejected with an error. -- If the queue grows beyond 200, subsequent requests are rejected with an error. - -When the pack-object cache is enabled, pack-objects limiting kicks in only if the cache is missed. For more, see [Pack-objects cache](#pack-objects-cache). - -You can observe the behavior of this queue using Gitaly logs and Prometheus. For more information, see -[Monitor Gitaly pack-objects concurrency limiting](monitoring.md#monitor-gitaly-pack-objects-concurrency-limiting). - -## Adaptive concurrency limiting - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6. - -Gitaly supports two concurrency limits: - -- An [RPC concurrency limit](#limit-rpc-concurrency), which allow you to configure a maximum number of simultaneous in-flight requests for each - Gitaly RPC. The limit is scoped by RPC and repository. -- A [Pack-objects concurrency limit](#limit-pack-objects-concurrency), which restricts the number of concurrent Git data transfer request by IP. - -If this limit is exceeded, either: - -- The request is put in a queue. -- The request is rejected if the queue is full or if the request remains in the queue for too long. - -Both of these concurrency limits can be configured statically. Though static limits can yield good protection results, they have some drawbacks: - -- Static limits are not good for all usage patterns. There is no one-size-fits-all value. If the limit is too low, big repositories are - negatively impacted. If the limit is too high, the protection is essentially lost. -- It's tedious to maintain a sane value for the concurrency limit, especially when the workload of each repository changes over time. -- A request can be rejected even though the server is idle because the rate doesn't factor in the load on the server. - -You can overcome all of these drawbacks and keep the benefits of concurrency limiting by configuring adaptive concurrency limits. Adaptive -concurrency limits are optional and build on the two concurrency limiting types. It uses Additive Increase/Multiplicative Decrease (AIMD) -algorithm. Each adaptive limit: - -- Gradually increases up to a certain upper limit during typical process functioning. -- Quickly decreases when the host machine has a resource problem. - -This mechanism provides some headroom for the machine to "breathe" and speeds up current inflight requests. - - - -The adaptive limiter calibrates the limits every 30 seconds and: - -- Increases the limits by one until reaching the upper limit. -- Decreases the limits by half when the top-level cgroup has either memory usage that exceeds 90%, excluding highly-evictable page caches, - or CPU throttled for 50% or more of the observation time. - -Otherwise, the limits increase by one until reaching the upper bound. For more information about technical implementation -of this system, please refer to [this blueprint](../../architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md). - -Adaptive limiting is enabled for each RPC or pack-objects cache individually. However, limits are calibrated at the same time. - -### Enable adaptiveness for RPC concurrency - -Prerequisites: - -- Because adaptive limiting depends on [control groups](#control-groups), control groups must be enabled before using adaptive limiting. - -The following is an example to configure an adaptive limit for RPC concurrency: - -```ruby -# in /etc/gitlab/gitlab.rb -gitaly['configuration'] = { - # ... - concurrency: [ - { - rpc: '/gitaly.SmartHTTPService/PostUploadPackWithSidechannel', - max_queue_wait: '1s', - max_queue_size: 10, - adaptive: true, - min_limit: 10, - initial_limit: 20, - max_limit: 40 - }, - { - rpc: '/gitaly.SSHService/SSHUploadPackWithSidechannel', - max_queue_wait: '10s', - max_queue_size: 20, - adaptive: true, - min_limit: 10, - initial_limit: 50, - max_limit: 100 - }, - ], -} -``` - -In this example: - -- `adaptive` sets whether the adaptiveness is enabled. If set, the `max_per_repo` value is ignored in favor of the following configuration. -- `initial_limit` is the per-repository concurrency limit to use when Gitaly starts. -- `max_limit` is the minimum per-repository concurrency limit of the configured RPC. Gitaly increases the current limit - until it reaches this number. -- `min_limit` is the is the minimum per-repository concurrency limit of the configured RPC. When the host machine has a resource problem, - Gitaly quickly reduces the limit until reaching this value. - -For more information, see [RPC concurrency](#limit-rpc-concurrency). - -### Enable adaptiveness for pack-objects concurrency - -Prerequisites: - -- Because adaptive limiting depends on [control groups](#control-groups), control groups must be enabled before using adaptive limiting. - -The following is an example to configure an adaptive limit for pack-objects concurrency: - -```ruby -# in /etc/gitlab/gitlab.rb -gitaly['pack_objects_limiting'] = { - 'max_queue_length' => 200, - 'max_queue_wait' => '60s', - 'adaptive' => true, - 'min_limit' => 10, - 'initial_limit' => 20, - 'max_limit' => 40 -} -``` - -In this example: - -- `adaptive` sets whether the adaptiveness is enabled. If set, the value of `max_concurrency` is ignored in favor of the following configuration. -- `initial_limit` is the per-IP concurrency limit to use when Gitaly starts. -- `max_limit` is the minimum per-IP concurrency limit for pack-objects. Gitaly increases the current limit until it reaches this number. -- `min_limit` is the is the minimum per-IP concurrency limit for pack-objects. When the host machine has a resources problem, Gitaly quickly - reduces the limit until it reaches this value. - -For more information, see [pack-objects concurrency](#limit-pack-objects-concurrency). - ## Control groups WARNING: @@ -1430,7 +971,7 @@ By default, the cache storage directory is set to a subdirectory of the first Gi defined in the configuration file. Multiple Gitaly processes can use the same directory for cache storage. Each Gitaly process -uses a unique random string as part of the cache filenames it creates. This means: +uses a unique random string as part of the cache file names it creates. This means: - They do not collide. - They do not reuse another process's files. @@ -1708,8 +1249,15 @@ By default, Gitaly doesn't sign commits made using GitLab UI. For example, commi - Web IDE. - Merge requests. -You can configure Gitaly to sign commits made with the GitLab UI. The commits show as unverified and signed by an unknown -user. Support for improvements is proposed in [issue 19185](https://gitlab.com/gitlab-org/gitlab/-/issues/19185). +You can configure Gitaly to sign commits made with the GitLab UI. + +By default, Gitaly sets the author of a commit as the committer. In this case, +it is harder to [Verify commits locally](../../user/project/repository/signed_commits/ssh.md#verify-commits-locally) +because the signature belongs to neither the author nor the committer of the commit. + +You can configure Gitaly to reflect that a commit has been committed by your instance by +setting `committer_email` and `committer_name`. For example, on GitLab.com these configuration options are +set to `noreply@gitlab.com` and `GitLab`. Configure Gitaly to sign commits made with the GitLab UI in one of two ways: @@ -1740,7 +1288,10 @@ Configure Gitaly to sign commits made with the GitLab UI in one of two ways: # ... git: { # ... + committer_name: 'Your Instance', + committer_email: 'noreply@yourinstance.com', signing_key: '/etc/gitlab/gitaly/signing_key.gpg', + # ... }, } ``` @@ -1769,6 +1320,8 @@ Configure Gitaly to sign commits made with the GitLab UI in one of two ways: ```toml [git] + committer_name = "Your Instance" + committer_email = "noreply@yourinstance.com" signing_key = "/etc/gitlab/gitaly/signing_key.gpg" ``` @@ -2001,50 +1554,3 @@ go_cloud_url = "s3://gitaly-backups?region=minio&endpoint=my.minio.local:8080&di ``` ::EndTabs - -## Configure negotiation timeouts - -> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5574) in GitLab 16.5. - -Gitaly supports configurable negotiation timeouts. - -Negotiation timeouts can be configured for the `git-upload-pack(1)` and `git-upload-archive(1)` -operations, which are invoked by a Gitaly node when you execute the `git fetch` and -`git archive --remote` commands respectively. You might need to increase the negotiation timeout: - -- For particularly large repositories. -- When performing these commands in parallel. - -These timeouts affect only the [negotiation phase](https://git-scm.com/docs/pack-protocol/2.2.3#_packfile_negotiation) of -remote Git operations, not the entire transfer. - -Valid values for timeouts follow the format of [`ParseDuration`](https://pkg.go.dev/time#ParseDuration) in Go. - -How you configure negotiation timeouts depends on the type of installation you have: - -::Tabs - -:::TabTitle Linux package (Omnibus) - -Edit `/etc/gitlab/gitlab.rb`: - -```ruby -gitaly['configuration'] = { - timeout: { - upload_pack_negotiation: '10m', # 10 minutes - upload_archive_negotiation: '20m', # 20 minutes - } -} -``` - -:::TabTitle Self-compiled (source) - -Edit `/home/git/gitaly/config.toml`: - -```toml -[timeout] -upload_pack_negotiation = "10m" -upload_archive_negotiation = "20m" -``` - -::EndTabs diff --git a/doc/administration/gitaly/gitaly_geo_capabilities.md b/doc/administration/gitaly/gitaly_geo_capabilities.md index a98477318f2..7fee435ee36 100644 --- a/doc/administration/gitaly/gitaly_geo_capabilities.md +++ b/doc/administration/gitaly/gitaly_geo_capabilities.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly and Geo capabilities diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 6784ff4d970..4744959ce13 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly and Gitaly Cluster **(FREE SELF)** @@ -171,6 +171,17 @@ Gitaly comes pre-configured with a Linux package installation, which is a config GitLab installations for more than 2000 active users performing daily Git write operation may be best suited by using Gitaly Cluster. +### Gitaly CLI + +The `gitaly` command is a command-line interface that provides additional subcommands for Gitaly administrators. For example, +the Gitaly CLI is used to: + +- [Configure custom Git hooks](../server_hooks.md) for a repository. +- Validate Gitaly configuration files. +- Verify the internal Gitaly API is accessible. + +For more information on the other subcommands, run `gitaly --help`. + ### Backing up repositories When backing up or syncing repositories using tools other than GitLab, you must [prevent writes](../../administration/backup_restore/backup_gitlab.md#prevent-writes-and-copy-the-git-repository-data) diff --git a/doc/administration/gitaly/monitoring.md b/doc/administration/gitaly/monitoring.md index 5d8de42666b..83d843971d7 100644 --- a/doc/administration/gitaly/monitoring.md +++ b/doc/administration/gitaly/monitoring.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring Gitaly and Gitaly Cluster @@ -31,7 +31,7 @@ of requests dropped due to request limiting. The `reason` label indicates why a ## Monitor Gitaly concurrency limiting -You can observe specific behavior of [concurrency-queued requests](configure_gitaly.md#limit-rpc-concurrency) using Gitaly logs and Prometheus. +You can observe specific behavior of [concurrency-queued requests](concurrency_limiting.md#limit-rpc-concurrency) using Gitaly logs and Prometheus. In the [Gitaly logs](../logs/index.md#gitaly-logs), you can identify logs related to the pack-objects concurrency limiting with entries such as: @@ -62,7 +62,7 @@ In Prometheus, look for the following metrics: ## Monitor Gitaly pack-objects concurrency limiting -You can observe specific behavior of [pack-objects limiting](configure_gitaly.md#limit-pack-objects-concurrency) using Gitaly logs and Prometheus. +You can observe specific behavior of [pack-objects limiting](concurrency_limiting.md#limit-pack-objects-concurrency) using Gitaly logs and Prometheus. In the [Gitaly logs](../logs/index.md#gitaly-logs), you can identify logs related to the pack-objects concurrency limiting with entries such as: @@ -94,7 +94,7 @@ In Prometheus, look for the following metrics: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10734) in GitLab 16.6. -You can observe specific behavior of [adaptive concurrency limiting](configure_gitaly.md#adaptive-concurrency-limiting) using Gitaly logs and Prometheus. +You can observe specific behavior of [adaptive concurrency limiting](concurrency_limiting.md#adaptive-concurrency-limiting) using Gitaly logs and Prometheus. In the [Gitaly logs](../logs/index.md#gitaly-logs), you can identify logs related to the adaptive concurrency limiting when the current limits are adjusted. You can filter the content of the logs (`msg`) for "Multiplicative decrease" and "Additive increase" messages. @@ -176,12 +176,26 @@ gitaly_streamcache_filestore_removed_total{dir="/var/opt/gitlab/git-data/reposit gitaly_streamcache_index_entries{dir="/var/opt/gitlab/git-data/repositories/+gitaly/PackObjectsCache"} 1 ``` +## Monitor Gitaly server-side backups + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5358) in GitLab 16.7. + +Monitor [server-side repository backups](configure_gitaly.md#configure-server-side-backups) with the following metrics: + +- `gitaly_backup_latency_seconds`, a histogram measuring the amount of time in seconds that each phase of a server-side + backup takes. The different phases are `refs`, `bundle`, and `custom_hooks` and represent the type of data being + processed at each stage. +- `gitaly_backup_bundle_bytes`, a histogram measuring the upload data rate of Git bundles being pushed to object + storage by the Gitaly backup service. + +Use these metrics especially if your GitLab instance contains large repositories. + ## Queries The following are some queries for monitoring Gitaly: - Use the following Prometheus query to observe the - [type of connections](configure_gitaly.md#enable-tls-support) Gitaly is serving a production + [type of connections](tls_support.md) Gitaly is serving a production environment: ```prometheus @@ -189,7 +203,7 @@ The following are some queries for monitoring Gitaly: ``` - Use the following Prometheus query to monitor the - [authentication behavior](configure_gitaly.md#observe-type-of-gitaly-connections) of your GitLab + [authentication behavior](tls_support.md#observe-type-of-gitaly-connections) of your GitLab installation: ```prometheus diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 0297f295e6f..66e220dacc2 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Gitaly Cluster **(FREE SELF)** @@ -50,7 +50,7 @@ default value. The default value depends on the GitLab version. Network latency for Gitaly Cluster should ideally be measurable in single-digit milliseconds. Latency is particularly important for: -- Gitaly node health checks. Nodes must be able to respond 1 second or faster. +- Gitaly node health checks. Nodes must be able to respond within 1 second. - Reference transactions that enforce [strong consistency](index.md#strong-consistency). Lower latencies mean Gitaly nodes can agree on changes faster. @@ -278,6 +278,7 @@ praefect['configuration'] = { database: { # ... host: POSTGRESQL_HOST, + user: 'praefect', port: 5432, password: PRAEFECT_SQL_PASSWORD, dbname: 'praefect_production', @@ -725,7 +726,7 @@ Updates to example must be made at: Praefect supports TLS encryption. To communicate with a Praefect instance that listens for secure connections, you must: -- Ensure Gitaly is [configured for TLS](configure_gitaly.md#enable-tls-support) and use a `tls://` URL scheme in the `gitaly_address` +- Ensure Gitaly is [configured for TLS](tls_support.md) and use a `tls://` URL scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. - Bring your own certificates because this isn't provided automatically. The certificate corresponding to each Praefect server must be installed on that Praefect server. @@ -739,7 +740,7 @@ Note the following: - The certificate must specify the address you use to access the Praefect server. You must add the hostname or IP address as a Subject Alternative Name to the certificate. - When running Praefect sub-commands such as `dial-nodes` and `list-untracked-repositories` from the command line with - [Gitaly TLS enabled](configure_gitaly.md#enable-tls-support), you must set the `SSL_CERT_DIR` or `SSL_CERT_FILE` + [Gitaly TLS enabled](tls_support.md), you must set the `SSL_CERT_DIR` or `SSL_CERT_FILE` environment variable so that the Gitaly certificate is trusted. For example: ```shell @@ -843,14 +844,8 @@ For self-compiled installations: storages: default: gitaly_address: tls://PRAEFECT_LOADBALANCER_HOST:3305 - path: /some/local/path ``` - NOTE: - `/some/local/path` should be set to a local folder that exists, however no - data is stored in this folder. This requirement is scheduled to be removed when - [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. - 1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). 1. Copy all Praefect server certificates, or their certificate authority, to the system trusted certificates on each Gitaly server so the Praefect server trusts the @@ -980,14 +975,8 @@ with Praefect service discovery address, such as `praefect.service.consul`. storages: default: gitaly_address: dns:PRAEFECT_SERVICE_DISCOVERY_ADDRESS:2305 - path: /some/local/path ``` - NOTE: - `/some/local/path` should be set to a local folder that exists, however no - data is stored in this folder. [Issue 375254](https://gitlab.com/gitlab-org/gitlab/-/issues/375254) - proposes to remove this requirement. - 1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). ::EndTabs @@ -1337,8 +1326,7 @@ Particular attention should be shown to: 1. Check that the Praefect storage is configured to store new repositories: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand the **Repository storage** section. diff --git a/doc/administration/gitaly/recovery.md b/doc/administration/gitaly/recovery.md index 6779823c941..78e7cc6995d 100644 --- a/doc/administration/gitaly/recovery.md +++ b/doc/administration/gitaly/recovery.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly Cluster recovery options and tools diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 5b26c93cea8..946be6c8af3 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly reference **(FREE SELF)** @@ -89,7 +89,7 @@ certificate_path = '/home/git/cert.cert' key_path = '/home/git/key.pem' ``` -[Read more](configure_gitaly.md#enable-tls-support) about TLS in Gitaly. +[Read more](tls_support.md) about TLS in Gitaly. ### Storage diff --git a/doc/administration/gitaly/tls_support.md b/doc/administration/gitaly/tls_support.md new file mode 100644 index 00000000000..90a1a6bd2fe --- /dev/null +++ b/doc/administration/gitaly/tls_support.md @@ -0,0 +1,228 @@ +--- +stage: Systems +group: Gitaly +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Gitaly TLS support + +Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure +connections, use the `tls://` URL scheme in the `gitaly_address` of the corresponding +storage entry in the GitLab configuration. + +Gitaly provides the same server certificates as client certificates in TLS +connections to GitLab. This can be used as part of a mutual TLS authentication strategy +when combined with reverse proxies (for example, NGINX) that validate client certificate +to grant access to GitLab. + +You must supply your own certificates as this isn't provided automatically. The certificate +corresponding to each Gitaly server must be installed on that Gitaly server. + +Additionally, the certificate (or its certificate authority) must be installed on all: + +- Gitaly servers. +- Gitaly clients that communicate with it. + +If you use a load balancer, it must be able to negotiate HTTP/2 using the ALPN TLS extension. + +## Certificate requirements + +- The certificate must specify the address you use to access the Gitaly server. You must add the hostname or IP address as a Subject Alternative Name to the certificate. +- You can configure Gitaly servers with both an unencrypted listening address `listen_addr` and an + encrypted listening address `tls_listen_addr` at the same time. This allows you to gradually + transition from unencrypted to encrypted traffic if necessary. +- The certificate's Common Name field is ignored. + +## Configure Gitaly with TLS + +[Configure Gitaly](configure_gitaly.md) before configuring TLS support. + +The process for configuring TLS support depends on your installation type. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Create certificates for Gitaly servers. +1. On the Gitaly clients, copy the certificates (or their certificate authority) into + `/etc/gitlab/trusted-certs`: + + ```shell + sudo cp cert.pem /etc/gitlab/trusted-certs/ + ``` + +1. On the Gitaly clients, edit `git_data_dirs` in `/etc/gitlab/gitlab.rb` as follows: + + ```ruby + git_data_dirs({ + 'default' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, + 'storage1' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, + 'storage2' => { 'gitaly_address' => 'tls://gitaly2.internal:9999' }, + }) + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). +1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate + there: + + ```shell + sudo mkdir -p /etc/gitlab/ssl + sudo chmod 755 /etc/gitlab/ssl + sudo cp key.pem cert.pem /etc/gitlab/ssl/ + sudo chmod 644 key.pem cert.pem + ``` + +1. Copy all Gitaly server certificates (or their certificate authority) to + `/etc/gitlab/trusted-certs` on all Gitaly servers and clients + so that Gitaly servers and clients trust the certificate when calling into themselves + or other Gitaly servers: + + ```shell + sudo cp cert1.pem cert2.pem /etc/gitlab/trusted-certs/ + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and add: + + <!-- Updates to following example must also be made at https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab --> + + ```ruby + gitaly['configuration'] = { + # ... + tls_listen_addr: '0.0.0.0:9999', + tls: { + certificate_path: '/etc/gitlab/ssl/cert.pem', + key_path: '/etc/gitlab/ssl/key.pem', + }, + } + ``` + +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). +1. Run `sudo gitlab-rake gitlab:gitaly:check` on the Gitaly client (for example, the + Rails application) to confirm it can connect to Gitaly servers. +1. Verify Gitaly traffic is being served over TLS by + [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). +1. Optional. Improve security by: + 1. Disabling non-TLS connections by commenting out or deleting `gitaly['configuration'][:listen_addr]` in + `/etc/gitlab/gitlab.rb`. + 1. Saving the file. + 1. [Reconfiguring GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). + +:::TabTitle Self-compiled (source) + +1. Create certificates for Gitaly servers. +1. On the Gitaly clients, copy the certificates into the system trusted certificates: + + ```shell + sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt + sudo update-ca-certificates + ``` + +1. On the Gitaly clients, edit `storages` in `/home/git/gitlab/config/gitlab.yml` as follows: + + ```yaml + gitlab: + repositories: + storages: + default: + gitaly_address: tls://gitaly1.internal:9999 + path: /some/local/path + storage1: + gitaly_address: tls://gitaly1.internal:9999 + path: /some/local/path + storage2: + gitaly_address: tls://gitaly2.internal:9999 + path: /some/local/path + ``` + + NOTE: + `/some/local/path` should be set to a local folder that exists, however no data is stored + in this folder. This requirement is scheduled to be removed when + [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. + +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). +1. On the Gitaly servers, create or edit `/etc/default/gitlab` and add: + + ```shell + export SSL_CERT_DIR=/etc/gitlab/ssl + ``` + +1. On the Gitaly servers, create the `/etc/gitlab/ssl` directory and copy your key and certificate there: + + ```shell + sudo mkdir -p /etc/gitlab/ssl + sudo chmod 755 /etc/gitlab/ssl + sudo cp key.pem cert.pem /etc/gitlab/ssl/ + sudo chmod 644 key.pem cert.pem + ``` + +1. Copy all Gitaly server certificates (or their certificate authority) to the system trusted + certificates folder so Gitaly server trusts the certificate when calling into itself or other Gitaly + servers. + + ```shell + sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt + sudo update-ca-certificates + ``` + +1. Edit `/home/git/gitaly/config.toml` and add: + + ```toml + tls_listen_addr = '0.0.0.0:9999' + + [tls] + certificate_path = '/etc/gitlab/ssl/cert.pem' + key_path = '/etc/gitlab/ssl/key.pem' + ``` + +1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations). +1. Verify Gitaly traffic is being served over TLS by + [observing the types of Gitaly connections](#observe-type-of-gitaly-connections). +1. Optional. Improve security by: + 1. Disabling non-TLS connections by commenting out or deleting `listen_addr` in + `/home/git/gitaly/config.toml`. + 1. Saving the file. + 1. [Restarting GitLab](../restart_gitlab.md#self-compiled-installations). + +::EndTabs + +### Update the certificates + +To update the Gitaly certificates after initial configuration: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, but no configuration changes have been made to +`/etc/gitlab/gitlab.rb`, then reconfiguring GitLab doesn’t affect Gitaly. Instead, you must restart Gitaly manually for the certificates to be loaded +by the Gitaly process: + +```shell +sudo gitlab-ctl restart gitaly +``` + +If you change or update the certificates in `/etc/gitlab/trusted-certs` without making changes to the `/etc/gitlab/gitlab.rb` file, you must: + +1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) so the symlinks for the trusted certificates are updated. +1. Restart Gitaly manually for the certificates to be loaded by the Gitaly process: + + ```shell + sudo gitlab-ctl restart gitaly + ``` + +:::TabTitle Self-compiled (source) + +If the content of your SSL certificates under the `/etc/gitlab/ssl` directory have been updated, you must +[restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process. + +If you change or update the certificates in `/usr/local/share/ca-certificates`, you must: + +1. Run `sudo update-ca-certificates` to update the system's trusted store. +1. [Restart GitLab](../restart_gitlab.md#self-compiled-installations) for the certificates to be loaded by the Gitaly process. + +::EndTabs + +## Observe type of Gitaly connections + +For information on observing the type of Gitaly connections being served, see the +[relevant documentation](monitoring.md#queries). diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md index 17687cbb181..7d0255a3efb 100644 --- a/doc/administration/gitaly/troubleshooting.md +++ b/doc/administration/gitaly/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Gitaly and Gitaly Cluster **(FREE SELF)** @@ -20,9 +20,8 @@ and our advice on [parsing the `gitaly/current` file](../logs/log_parsing.md#par When using standalone Gitaly servers, you must make sure they are the same version as GitLab to ensure full compatibility: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Gitaly Servers**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Gitaly Servers**. 1. Confirm all Gitaly servers indicate that they are up to date. ### Find storage resource details @@ -89,7 +88,7 @@ Check whether `Verify return code` field indicates a [known Linux package installation configuration problem](https://docs.gitlab.com/omnibus/settings/ssl/index.html). If `openssl` succeeds but `gitlab-rake gitlab:gitaly:check` fails, -check [certificate requirements](configure_gitaly.md#certificate-requirements) for Gitaly. +check [certificate requirements](tls_support.md#certificate-requirements) for Gitaly. ### Server side gRPC logs @@ -389,7 +388,7 @@ One way to resolve this is to make sure the entry is correct for the GitLab inte ### Changes (diffs) don't load for new merge requests when using Gitaly TLS -After enabling [Gitaly with TLS](configure_gitaly.md#enable-tls-support), changes (diffs) for new merge requests are not generated +After enabling [Gitaly with TLS](tls_support.md), changes (diffs) for new merge requests are not generated and you see the following message in GitLab: ```plaintext @@ -424,7 +423,7 @@ and: 1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) so the certificates are symlinked 1. Restart Gitaly manually `sudo gitlab-ctl restart gitaly` for the certificates to be loaded by the Gitaly process. -## Gitaly fails to fork processes stored on `noexec` file systems +### Gitaly fails to fork processes stored on `noexec` file systems Because of changes [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5999) in GitLab 14.10, applying the `noexec` option to a mount point (for example, `/var`) causes Gitaly to throw `permission denied` errors related to forking processes. For example: @@ -577,7 +576,7 @@ To determine the primary node of a repository: Praefect node: ```shell - curl localhost:9652/metrics | grep gitaly_praefect_primaries` + curl localhost:9652/metrics | grep gitaly_praefect_primaries ``` ### View repository metadata @@ -684,8 +683,8 @@ The documented examples specify `-virtual-storage default`. Check the Praefect s ### Check that repositories are in sync Is [some cases](index.md#known-issues) the Praefect database can get out of sync with the underlying Gitaly nodes. To check that -a given repository is fully synced on all nodes, run the [`gitlab:praefect:replicas` Rake task](../raketasks/praefect.md#replica-checksums) -that checksums the repository on all Gitaly nodes. +a given repository is fully synced on all nodes, run the [`gitlab:praefect:replicas` Rake task](../raketasks/praefect.md#replica-checksums) on your Rails node. +This Rake task checksums the repository on all Gitaly nodes. The [Praefect `dataloss`](recovery.md#check-for-data-loss) command only checks the state of the repository in the Praefect database, and cannot be relied to detect sync problems in this scenario. diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index f4815e0f04f..7ee29035de4 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Housekeeping **(FREE SELF)** @@ -76,9 +76,8 @@ frequently. You can change how often Gitaly is asked to optimize a repository. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand **Repository maintenance**. 1. In the **Housekeeping** section, configure the housekeeping options. 1. Select **Save changes**. @@ -110,7 +109,7 @@ housekeeping tasks. The manual trigger can be useful when either: To trigger housekeeping tasks manually: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. Select **Run housekeeping**. @@ -137,7 +136,7 @@ reduce the likelihood of such race conditions. To trigger a manual prune of unreachable objects: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Advanced**. 1. Select **Run housekeeping**. 1. Wait 30 minutes for the operation to complete. diff --git a/doc/administration/img/email1.png b/doc/administration/img/email1.png Binary files differdeleted file mode 100644 index e79ccc3e9a9..00000000000 --- a/doc/administration/img/email1.png +++ /dev/null diff --git a/doc/administration/img/email2.png b/doc/administration/img/email2.png Binary files differdeleted file mode 100644 index d073c0e42da..00000000000 --- a/doc/administration/img/email2.png +++ /dev/null diff --git a/doc/administration/inactive_project_deletion.md b/doc/administration/inactive_project_deletion.md index 7ccd3455011..3c340448cee 100644 --- a/doc/administration/inactive_project_deletion.md +++ b/doc/administration/inactive_project_deletion.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Inactive project deletion **(FREE SELF)** @@ -23,9 +23,8 @@ For the default setting on GitLab.com, see the [GitLab.com settings page](../use To configure deletion of inactive projects: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. 1. Expand **Repository maintenance**. 1. In the **Inactive project deletion** section, select **Delete inactive projects**. 1. Configure the settings. @@ -35,7 +34,7 @@ To configure deletion of inactive projects: Inactive projects that meet the criteria are scheduled for deletion and a warning email is sent. If the projects remain inactive, they are deleted after the specified duration. These projects are deleted even if -[the project is archived](../user/project/settings/index.md#archive-a-project). +[the project is archived](../user/project/settings/migrate_projects.md#archive-a-project). ### Configuration example diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 33afaf19220..2d2d9d34019 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incoming email **(FREE SELF)** @@ -995,3 +995,35 @@ read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secre ``` ::EndTabs + +## Troubleshooting + +### Email ingestion doesn't work in 16.6.0 + +GitLab self-managed `16.6.0` introduced a regression that prevents `mail_room` (email ingestion) from starting. +Service Desk and other reply-by-email features don't work. +[Issue 432257](https://gitlab.com/gitlab-org/gitlab/-/issues/432257) tracks fixing this problem. + +The workaround is to run the following commands in your GitLab installation +to patch the affected files: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff" +patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch +gitlab-ctl restart mailroom +``` + +:::TabTitle Docker + +```shell +curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff" +cd /opt/gitlab/embedded/service/gitlab-rails +patch -p1 < /tmp/mailroom.patch +gitlab-ctl restart mailroom +``` + +::EndTabs diff --git a/doc/administration/index.md b/doc/administration/index.md index ded6eabdba7..fcda1c4b413 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" description: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index d5855e3c832..259a0c961d2 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab application limits **(FREE SELF)** @@ -21,7 +20,7 @@ Depending on which limits you have configured, you can see: - SSH host keys information - CI/CD limits - GitLab Pages limits -- Package Registry limits +- Package registry limits - Rate limits - Size limits @@ -88,10 +87,10 @@ Read more about [protected path rate limits](settings/protected_paths.md). - **Default rate limit**: After 10 requests, the client must wait 60 seconds before trying again. -### Package Registry +### Package registry This setting limits the request rate on the Packages API per user or IP. For more information, see -[Package Registry Rate Limits](settings/package_registry_rate_limits.md). +[package registry rate limits](settings/package_registry_rate_limits.md). - **Default rate limit**: Disabled by default. @@ -202,7 +201,7 @@ Read more about [pipeline creation rate limits](settings/rate_limit_on_pipelines Clone traffic can put a large strain on your Gitaly service. To prevent such workloads from overwhelming your Gitaly server, you can set concurrency limits in the Gitaly configuration file. -Read more about [Gitaly concurrency limits](gitaly/configure_gitaly.md#limit-rpc-concurrency). +Read more about [Gitaly concurrency limits](gitaly/concurrency_limiting.md#limit-rpc-concurrency). - **Default rate limit**: Disabled. @@ -436,7 +435,7 @@ You can change the maximum time a job can run before it times out: - At the project-level in the [project's CI/CD settings](../ci/pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) for a given project. This limit must be between 10 minutes and 1 month. -- At the [runner level](../ci/runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). +- At the [runner level](../ci/runners/configure_runners.md#set-the-maximum-job-timeout). This limit must be 10 minutes or longer. ### Maximum number of deployment jobs in a pipeline @@ -961,7 +960,7 @@ Reports that go over the 20 MB limit aren't loaded. Affected reports: ### Maximum file size indexed You can set a limit on the content of repository files that are indexed in -Elasticsearch. Any files larger than this limit only index the filename. +Elasticsearch. Any files larger than this limit only index the file name. The file content is neither indexed nor searchable. Setting a limit helps reduce the memory usage of the indexing processes and @@ -1052,11 +1051,11 @@ individual push events or a bulk push event are created. More information can be found in the [Push event activities limit and bulk push events documentation](settings/push_event_activities_limit.md). -## Package Registry Limits +## Package registry limits -### File Size Limits +### File size limits -The default maximum file size for a package that's uploaded to the [GitLab Package Registry](../user/packages/package_registry/index.md) varies by format: +The default maximum file size for a package that's uploaded to the [GitLab package registry](../user/packages/package_registry/index.md) varies by format: - Conan: 3 GB - Generic: 5 GB @@ -1105,7 +1104,7 @@ Set the limit to `0` to allow any file size. ### Package versions returned -When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 versions. +When asking for versions of a given NuGet package name, the GitLab package registry returns a maximum of 300 versions. ## Dependency Proxy Limits @@ -1134,7 +1133,7 @@ In addition to application-based limits, GitLab.com is configured to use Cloudfl ## Container Repository tag deletion limit -Container repository tags are in the Container Registry and, as such, each tag deletion triggers network requests to the Container Registry. Because of this, we limit the number of tags that a single API call can delete to 20. +Container repository tags are in the container registry and, as such, each tag deletion triggers network requests to the container registry. Because of this, we limit the number of tags that a single API call can delete to 20. ## Project-level Secure Files API limits diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index 6a2ead82538..a33bf0f70b1 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance review **(FREE SELF)** diff --git a/doc/administration/integration/diagrams_net.md b/doc/administration/integration/diagrams_net.md index 13be572d524..42286428bb1 100644 --- a/doc/administration/integration/diagrams_net.md +++ b/doc/administration/integration/diagrams_net.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Diagrams.net **(FREE SELF)** @@ -46,9 +45,8 @@ For more information, see [Run your own diagrams.net server with Docker](https:/ ## Enable Diagrams.net integration 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Diagrams.net**. 1. Select the **Enable Diagrams.net** checkbox. 1. Enter the Diagrams.net URL. To connect to: diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index 926833cfa1a..b3c55e6f772 100644 --- a/doc/administration/integration/kroki.md +++ b/doc/administration/integration/kroki.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Kroki **(FREE SELF)** @@ -61,8 +61,7 @@ read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images You need to enable Kroki integration from Settings under Admin Area. To do that, sign in with an administrator account and follow these steps: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Go to **Settings > General**. 1. Expand the **Kroki** section. 1. Select **Enable Kroki** checkbox. diff --git a/doc/administration/integration/mailgun.md b/doc/administration/integration/mailgun.md index 4fe846e99a6..a4e8c826ef7 100644 --- a/doc/administration/integration/mailgun.md +++ b/doc/administration/integration/mailgun.md @@ -1,8 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mailgun **(FREE SELF)** @@ -43,8 +42,7 @@ After configuring your Mailgun domain for the webhook endpoints, you're ready to enable the Mailgun integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, go to **Settings > General** and expand the **Mailgun** section. 1. Select the **Enable Mailgun** checkbox. 1. Enter the Mailgun HTTP webhook signing key as described in diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index dae400ff755..fbd3e636123 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # PlantUML **(FREE SELF)** @@ -316,8 +315,7 @@ stop; After configuring your local PlantUML server, you're ready to enable the PlantUML integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, go to **Settings > General** and expand the **PlantUML** section. 1. Select the **Enable PlantUML** checkbox. 1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`, diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index baeabdc6964..cb7d51f882a 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web terminals (deprecated) **(FREE SELF)** @@ -112,7 +112,6 @@ they receive a `Connection failed` message. By default, terminal sessions do not expire. To limit the terminal session lifetime in your GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Web terminal**. 1. Set a `max session time`. diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md index 5db08075449..e58d56b2aed 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.md @@ -1,8 +1,7 @@ --- stage: Plan group: Project Management -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Markdown cache **(FREE SELF)** diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index d179b77530a..cf61b930800 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Issue closing pattern **(FREE SELF)** diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 442e9638d86..33dc2020331 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs artifacts administration **(FREE SELF)** diff --git a/doc/administration/job_artifacts_troubleshooting.md b/doc/administration/job_artifacts_troubleshooting.md index c2be485a9ad..138803a2675 100644 --- a/doc/administration/job_artifacts_troubleshooting.md +++ b/doc/administration/job_artifacts_troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Job artifact troubleshooting for administrators diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index c8702260ccb..364927b4726 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Job logs **(FREE SELF)** diff --git a/doc/administration/labels.md b/doc/administration/labels.md index adc621a2982..25a86b8c2fc 100644 --- a/doc/administration/labels.md +++ b/doc/administration/labels.md @@ -1,13 +1,12 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Labels administration **(FREE SELF)** -To manage labels for the GitLab instance, select **Labels** (**{labels}**) from the Admin Area sidebar. For more details on how to manage labels, see [Labels](../user/project/labels.md). +To manage labels for the GitLab instance, in the Admin Area, on the left sidebar, select **Labels**. For more details on how to manage labels, see [Labels](../user/project/labels.md). Labels created in the Admin Area are automatically added to new projects. They are not available to new groups. diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index 26034ce1d01..5eccbf9e951 100644 --- a/doc/administration/lfs/index.md +++ b/doc/administration/lfs/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # GitLab Git Large File Storage (LFS) Administration **(FREE SELF)** diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md index 899269fb9d1..d91f286c633 100644 --- a/doc/administration/libravatar.md +++ b/doc/administration/libravatar.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using the Libravatar service with GitLab **(FREE SELF)** diff --git a/doc/administration/license.md b/doc/administration/license.md index 05b60955ed9..1dc39d9ac23 100644 --- a/doc/administration/license.md +++ b/doc/administration/license.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Provision -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Activate GitLab Enterprise Edition (EE) **(PREMIUM SELF)** @@ -15,7 +15,7 @@ your instance with an activation code. In GitLab Enterprise Edition 14.1 and later, you need an activation code to activate your instance. -Prerequisite: +Prerequisites: - You must [purchase a subscription](https://about.gitlab.com/pricing/). - You must be running GitLab Enterprise Edition (EE). @@ -28,8 +28,7 @@ To activate your instance with an activation code: - Your subscription confirmation email. - The [Customers Portal](https://customers.gitlab.com/customers/sign_in), on the **Manage Purchases** page. 1. Sign in to your GitLab self-managed instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. 1. Paste the activation code in **Activation code**. 1. Read and accept the terms of service. diff --git a/doc/administration/license_file.md b/doc/administration/license_file.md index 2086e4888a7..fc1de38bb11 100644 --- a/doc/administration/license_file.md +++ b/doc/administration/license_file.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Provision -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- To promote the workflow described in license.md, this page is not included in global left nav. --> @@ -18,8 +18,7 @@ link to the **Add license** page should be displayed. Otherwise, to add your license: 1. Sign in to GitLab as an administrator. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. In the **Add License** area, add a license by either uploading the file or entering the key. 1. Select the **Terms of Service** checkbox. @@ -45,7 +44,7 @@ If you have a license, you can also import it when you install GitLab. - For self-compiled installations: - Place the `Gitlab.gitlab-license` file in the `config/` directory. - - To specify a custom location and filename for the license, set the + - To specify a custom location and file name for the license, set the `GITLAB_LICENSE_FILE` environment variable with the path to the file: ```shell @@ -54,7 +53,7 @@ If you have a license, you can also import it when you install GitLab. - For Linux package installations: - Place the `Gitlab.gitlab-license` file in the `/etc/gitlab/` directory. - - To specify a custom location and filename for the license, add this entry to `gitlab.rb`: + - To specify a custom location and file name for the license, add this entry to `gitlab.rb`: ```ruby gitlab_rails['initial_license_file'] = "/path/to/license/file" @@ -96,8 +95,7 @@ To go back to Free features, [delete all expired licenses](#remove-a-license). To remove a license from a self-managed instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. 1. Select **Remove license**. @@ -107,8 +105,7 @@ Repeat these steps to remove all licenses, including those applied in the past. To view your license details: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. You can add and view more than one license, but only the latest license in diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index 1662febc8cc..d58b70865df 100644 --- a/doc/administration/load_balancer.md +++ b/doc/administration/load_balancer.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Load Balancer for multi-node GitLab **(FREE SELF)** diff --git a/doc/administration/logs/index.md b/doc/administration/logs/index.md index 3bb26681fae..1b1591a36d9 100644 --- a/doc/administration/logs/index.md +++ b/doc/administration/logs/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Log system **(FREE SELF)** @@ -985,8 +985,15 @@ For example: ## `geo.log` **(PREMIUM SELF)** -Geo stores structured log messages in a `geo.log` file. For Linux package -installations, this file is at `/var/log/gitlab/gitlab-rails/geo.log`. +Geo stores structured log messages in a `geo.log` file. For Linux package installations, +this file is at `/var/log/gitlab/gitlab-rails/geo.log`. + +For Helm chart installations, it's stored in the Sidekiq pod, at `/var/log/gitlab/geo.log`. +It can be read by either directly accessing the file, or by using `kubectl` to fetch the Sidekiq logs, and subsequently filtering the results by `"subcomponent"=="geo"`. The example below uses `jq` to grab only Geo logs: + +```shell +kubectl logs -l app=sidekiq --max-log-requests=50 | jq 'select(."subcomponent"=="geo")' +``` This file contains information about when Geo attempts to sync repositories and files. Each line in the file contains a separate JSON entry that can be @@ -1037,7 +1044,7 @@ This file is located at: ## Registry logs -For Linux package installations, Container Registry logs are in `/var/log/gitlab/registry/current`. +For Linux package installations, container registry logs are in `/var/log/gitlab/registry/current`. ## NGINX logs @@ -1047,8 +1054,8 @@ For Linux package installations, NGINX logs are in: - `/var/log/gitlab/nginx/gitlab_error.log`: A log of NGINX errors for GitLab - `/var/log/gitlab/nginx/gitlab_pages_access.log`: A log of requests made to Pages static sites - `/var/log/gitlab/nginx/gitlab_pages_error.log`: A log of NGINX errors for Pages static sites -- `/var/log/gitlab/nginx/gitlab_registry_access.log`: A log of requests made to the Container Registry -- `/var/log/gitlab/nginx/gitlab_registry_error.log`: A log of NGINX errors for the Container Registry +- `/var/log/gitlab/nginx/gitlab_registry_access.log`: A log of requests made to the container registry +- `/var/log/gitlab/nginx/gitlab_registry_error.log`: A log of NGINX errors for the container registry - `/var/log/gitlab/nginx/gitlab_mattermost_access.log`: A log of requests made to Mattermost - `/var/log/gitlab/nginx/gitlab_mattermost_error.log`: A log of NGINX errors for Mattermost diff --git a/doc/administration/logs/log_parsing.md b/doc/administration/logs/log_parsing.md index b281620fcf3..3ac24fbb9ab 100644 --- a/doc/administration/logs/log_parsing.md +++ b/doc/administration/logs/log_parsing.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Parsing GitLab logs with `jq` **(FREE SELF)** @@ -24,7 +24,7 @@ include use cases targeted for parsing GitLab log files. ## Parsing Logs The examples listed below address their respective log files by -their relative Linux package installation paths and default filenames. +their relative Linux package installation paths and default file names. Find the respective full paths in the [GitLab logs sections](../logs/index.md#production_jsonlog). ### General Commands diff --git a/doc/administration/logs/tracing_correlation_id.md b/doc/administration/logs/tracing_correlation_id.md index 79c8dcf4d81..f6b341ff114 100644 --- a/doc/administration/logs/tracing_correlation_id.md +++ b/doc/administration/logs/tracing_correlation_id.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Find relevant log entries with a correlation ID **(FREE SELF)** diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md index 36c702bbda1..f4823ce9af1 100644 --- a/doc/administration/maintenance_mode/index.md +++ b/doc/administration/maintenance_mode/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Maintenance Mode **(PREMIUM SELF)** @@ -21,8 +21,7 @@ Maintenance Mode allows most external actions that do not change internal state. Enable Maintenance Mode as an administrator in one of these ways: - **Web UI**: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. You can optionally add a message for the banner as well. @@ -46,8 +45,7 @@ Enable Maintenance Mode as an administrator in one of these ways: Disable Maintenance Mode in one of three ways: - **Web UI**: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. You can optionally add a message for the banner as well. @@ -162,13 +160,13 @@ You should disable auto deploys during Maintenance Mode, and enable them when it Terraform integration depends on running CI pipelines, hence it is blocked. -### Container Registry +### Container registry `docker push` fails with this error: `denied: requested access to the resource is denied`, but `docker pull` works. -### Package Registry +### Package registry -Package Registry allows you to install but not publish packages. +Package registry allows you to install but not publish packages. ### Background jobs @@ -181,9 +179,8 @@ you should disable all cron jobs except for those related to Geo. To monitor queues and disable jobs: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Background Jobs**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Background Jobs**. 1. In the Sidekiq dashboard, select **Cron** and disable jobs individually or all at once by selecting **Disable All**. ### Incident management diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 9c4ddcdc094..a3874091f34 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request diffs storage **(FREE SELF)** diff --git a/doc/administration/merge_requests_approvals.md b/doc/administration/merge_requests_approvals.md index 8c554b00048..9e766633d56 100644 --- a/doc/administration/merge_requests_approvals.md +++ b/doc/administration/merge_requests_approvals.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request approvals **(PREMIUM SELF)** @@ -19,8 +18,7 @@ and can no longer be changed: To enable merge request approval settings for an instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Push Rules**. 1. Expand **Merge request approvals**. 1. Choose the required options. diff --git a/doc/administration/moderate_users.md b/doc/administration/moderate_users.md index c12eb2b9a95..c2c3491b6fc 100644 --- a/doc/administration/moderate_users.md +++ b/doc/administration/moderate_users.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moderate users (administration) **(FREE SELF)** @@ -42,8 +41,7 @@ sign in. To view user sign ups pending approval: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Pending approval** tab. @@ -53,8 +51,7 @@ A user sign up pending approval can be approved or rejected from the Admin Area. To approve or reject a user sign up: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Pending approval** tab. 1. For the user sign up you want to approve or reject, select the vertical ellipsis (**{ellipsis_v}**), then **Approve** or **Reject**. @@ -68,34 +65,37 @@ Approving a user: ## Block and unblock users GitLab administrators can block and unblock users. +You should block a user when you don't want them to access the instance, but you want to retain their data. + +A blocked user: + +- Cannot sign in or access any repositories. The blocked user's data remains in those repositories. +- Cannot use slash commands. For more information, see [slash commands](../user/project/integrations/gitlab_slack_application.md#slash-commands). +- Does not occupy a seat. For more information, see [billable users](../subscriptions/self_managed/index.md#billable-users). ### Block a user -Prerequisite: +Prerequisites: - You must be an administrator for the instance. -You can block a user's access to the instance. When you block a user, they receive an email notification that their account has been blocked. After this email, they no longer receive notifications. A blocked user: - -- Cannot sign in or access any repositories, but all of their data remains in those repositories. -- Cannot use slash commands. For more information, see [slash commands](../user/project/integrations/gitlab_slack_application.md#slash-commands). -- Does not occupy a seat. For more information, see [billable users](../subscriptions/self_managed/index.md#billable-users). +You can block a user's access to the instance. To block a user: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to block, select the vertical ellipsis (**{ellipsis_v}**), then **Block**. +The user receives an email notification that their account has been blocked. After this email, they no longer receive notifications. + To report abuse from other users, see [report abuse](../user/report_abuse.md). For more information on abuse reports in the Admin area, see [resolving abuse reports](../administration/review_abuse_reports.md#resolving-abuse-reports). ### Unblock a user A blocked user can be unblocked from the Admin Area. To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Blocked** tab. 1. For the user you want to unblock, select the vertical ellipsis (**{ellipsis_v}**), then **Unblock**. @@ -109,8 +109,7 @@ Users can also be unblocked using the [GitLab API](../api/users.md#unblock-user) The unblock option may be unavailable for LDAP users. To enable the unblock option, the LDAP identity first needs to be deleted: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Blocked** tab. 1. Select a user. @@ -120,30 +119,35 @@ the LDAP identity first needs to be deleted: ## Activate and deactivate users GitLab administrators can deactivate and activate users. +You should deactivate a user if they have no recent activity, and you don't want them to occupy a seat on the instance. -### Deactivate a user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. - -You can temporarily deactivate a user who has no recent activity. - -The user you deactivate must be dormant. When you deactivate a user, their projects, group, and history remain. A deactivated user: +A deactivated user: +- Can sign in to GitLab. + - If a deactivated user signs in, they are automatically activated. - Cannot access repositories or the API. - Cannot use slash commands. For more information, see [slash commands](../user/project/integrations/gitlab_slack_application.md#slash-commands). - Does not occupy a seat. For more information, see [billable users](../subscriptions/self_managed/index.md#billable-users). -Deactivation is similar to blocking, but there are a few important differences. Deactivating a user does not prohibit the user from signing into the GitLab UI. A deactivated user can become active again by signing in. +When you deactivate a user, their projects, groups, and history remain. + +### Deactivate a user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. + +Prerequisites: + +- The user has had no activity in the last 90 days. -To deactivate a user from the Admin Area: +To deactivate a user: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to deactivate, select the vertical ellipsis (**{ellipsis_v}**) and then **Deactivate**. 1. On the dialog, select **Deactivate**. -Email notifications stop after deactivation. GitLab sends email notifications to users when their account has been deactivated. For more information about this feature, see [user deactivation emails](../administration/settings/email.md#user-deactivation-emails). +The user receives an email notification that their account has been deactivated. After this email, they no longer receive notifications. +For more information, see [user deactivation emails](../administration/settings/email.md#user-deactivation-emails). To deactivate users with the GitLab API, see [deactivate user](../api/users.md#deactivate-user). For information about permanent user restrictions, see [block and unblock users](#block-and-unblock-users). @@ -161,8 +165,7 @@ Administrators can enable automatic deactivation of users who either: To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Under **Dormant users**, check **Deactivate dormant users after a period of inactivity**. @@ -212,8 +215,7 @@ A deactivated user can be activated from the Admin Area. To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Deactivated** tab. 1. For the user you want to activate, select the vertical ellipsis (**{ellipsis_v}**), then **Activate**. @@ -233,7 +235,13 @@ Users can also be activated using the [GitLab API](../api/users.md#activate-user > - Hiding comments of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112973) in GitLab 15.11 [with a flag](../administration/feature_flags.md) named `hidden_notes`. Disabled by default. > - Hiding projects of banned users [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121488) in GitLab 16.2 [with a flag](../administration/feature_flags.md) named `hide_projects_of_banned_users`. Disabled by default. -GitLab administrators can ban and unban users. Banned users are blocked, and their projects, issues, merge requests, and comments are hidden. +GitLab administrators can ban and unban users. +You should ban a user when you want to block them and hide their activity from the instance. + +A banned user: + +- Is blocked from the instance. The banned user's projects, issues, merge requests, and comments are hidden. +- Does not occupy a [seat](../subscriptions/self_managed/index.md#billable-users). ### Ban a user @@ -241,19 +249,15 @@ To block a user and hide their contributions, administrators can ban the user. Users can be banned using the Admin Area. To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to ban, select the vertical ellipsis (**{ellipsis_v}**), then **Ban user**. -The banned user does not consume a [seat](../subscriptions/self_managed/index.md#billable-users). - ### Unban a user A banned user can be unbanned using the Admin Area. To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Banned** tab. 1. For the user you want to unban, select the vertical ellipsis (**{ellipsis_v}**), then **Unban user**. @@ -265,8 +269,7 @@ The user's state is set to active and they consume a Use the Admin Area to delete users. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to delete, select the vertical ellipsis (**{ellipsis_v}**), then **Delete user**. 1. Type the username. @@ -277,8 +280,7 @@ You can only delete a user if there are inherited or direct owners of a group. Y You can also delete a user and their contributions, such as merge requests, issues, and groups of which they are the only group owner. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. For the user you want to delete, select the vertical ellipsis (**{ellipsis_v}**), then **Delete user and contributions**. 1. Type the username. @@ -295,7 +297,7 @@ You can trust and untrust users from the Admin Area. By default, a user is not trusted and is blocked from creating issues, notes, and snippets considered to be spam. When you trust a user, they can create issues, notes, and snippets without being blocked. -Prerequisite: +Prerequisites: - You must be an administrator. @@ -303,8 +305,7 @@ Prerequisite: :::TabTitle Trust a user -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select a user. 1. From the **User administration** dropdown list, select **Trust user**. @@ -314,8 +315,7 @@ The user is trusted. :::TabTitle Untrust a user -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Trusted** tab. 1. Select a user. diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md index 74e584db3a0..28dbc3d8209 100644 --- a/doc/administration/monitoring/github_imports.md +++ b/doc/administration/monitoring/github_imports.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitHub imports **(FREE SELF)** diff --git a/doc/administration/monitoring/health_check.md b/doc/administration/monitoring/health_check.md index 4dbbdf6f3c9..b688387ded6 100644 --- a/doc/administration/monitoring/health_check.md +++ b/doc/administration/monitoring/health_check.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Health Check **(FREE SELF)** diff --git a/doc/administration/monitoring/index.md b/doc/administration/monitoring/index.md index 622a772a638..10fe1486484 100644 --- a/doc/administration/monitoring/index.md +++ b/doc/administration/monitoring/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitLab **(FREE SELF)** diff --git a/doc/administration/monitoring/ip_allowlist.md b/doc/administration/monitoring/ip_allowlist.md index b3ddc05776c..d861a24ba2d 100644 --- a/doc/administration/monitoring/ip_allowlist.md +++ b/doc/administration/monitoring/ip_allowlist.md @@ -1,15 +1,15 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# IP whitelist **(FREE SELF)** +# IP allowlist **(FREE SELF)** GitLab provides some [monitoring endpoints](health_check.md) that provide health check information when probed. -To control access to those endpoints via IP whitelisting, you can add single +To control access to those endpoints through IP allowlisting, you can add single hosts or use IP ranges: ::Tabs @@ -32,7 +32,7 @@ You can set the required IPs under the `gitlab.webservice.monitoring.ipWhitelist gitlab: webservice: monitoring: - # Monitoring IP whitelist + # Monitoring IP allowlist ipWhitelist: - 0.0.0.0/0 # Default ``` diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index a32a38a11e5..7dc4f34e514 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Configuration **(FREE SELF)** @@ -9,10 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab Performance Monitoring is disabled by default. To enable it and change any of its settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling** - (`/admin/application_settings/metrics_and_profiling`). +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. 1. Add the necessary configuration changes. 1. Restart all GitLab for the changes to take effect: diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index a69eb67e77e..0d264972073 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Grafana **(FREE SELF)** @@ -34,10 +34,9 @@ see the [GitLab Grafana dashboards](https://gitlab.com/gitlab-org/grafana-dashbo After setting up Grafana, you can enable a link to access it from the GitLab sidebar: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling** - and expand **Metrics - Grafana**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. +1. Expand **Metrics - Grafana**. 1. Select the **Add a link to Grafana** checkbox. 1. Configure the **Grafana URL**. Enter the full URL of the Grafana instance. 1. Select **Save changes**. diff --git a/doc/administration/monitoring/performance/index.md b/doc/administration/monitoring/performance/index.md index 935ee4719c5..88faf071cfe 100644 --- a/doc/administration/monitoring/performance/index.md +++ b/doc/administration/monitoring/performance/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Performance Monitoring **(FREE SELF)** diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 95717f0c54f..a8bf39761ed 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performance bar **(FREE SELF)** @@ -107,11 +107,9 @@ The performance bar is disabled by default for non-administrators. To enable it for a given group: 1. Sign in as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling** - (`admin/application_settings/metrics_and_profiling`), and expand - **Profiling - Performance bar**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. +1. Expand **Profiling - Performance bar**. 1. Select **Allow non-administrators access to the performance bar**. 1. In the **Allow access to members of the following group** field, provide the full path of the group allowed to access the performance. diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 75400535e60..96f666db0ed 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 2eb482cae69..80121c7c235 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -1,7 +1,7 @@ --- stage: Shared responsibility based on functional area group: Shared responsibility based on functional area -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Prometheus metrics **(FREE SELF)** @@ -9,9 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w To enable the GitLab Prometheus metrics: 1. Log in to GitLab as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. 1. Find the **Metrics - Prometheus** section, and select **Enable GitLab Prometheus metrics endpoint**. 1. [Restart GitLab](../../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. @@ -178,6 +177,9 @@ The following metrics are available: | `gitlab_ci_queue_iteration_duration_seconds` | Histogram | 16.3 | Time it takes to find a build in CI/CD queue | | `gitlab_ci_queue_retrieval_duration_seconds` | Histogram | 16.3 | Time it takes to execute a SQL query to retrieve builds queue | | `gitlab_ci_queue_active_runners_total` | Histogram | 16.3 | The amount of active runners that can process queue in a project | +| `gitlab_connection_pool_size` | Gauge | 16.7 | Size of connection pool | +| `gitlab_connection_pool_available_count` | Gauge | 16.7 | Number of available connections in the pool | +| `gitlab_security_policies_scan_result_process_duration_seconds` | Histogram | 16.7 | The amount of time to process scan result policies | ## Metrics controlled by a feature flag diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 01b1851ab7f..bd3f2a20006 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitLab with Prometheus **(FREE SELF)** @@ -42,10 +42,14 @@ monitoring target for Prometheus, unless individually disabled. To disable Prometheus and all of its exporters, as well as any added in the future: 1. Edit `/etc/gitlab/gitlab.rb` -1. Add or find and uncomment the following line, making sure it's set to `false`: +1. Add or find and uncomment the following lines, making sure they are set to `false`: ```ruby prometheus_monitoring['enable'] = false + sidekiq['metrics_enabled'] = false + + # Already set to `false` by default, but you can explicitly disable it to be sure + puma['exporter_enabled'] = false ``` 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to @@ -98,7 +102,7 @@ prometheus['scrape_configs'] = [ 'metrics_path': '/probe', 'params' => { 'param_a' => ['test'], - 'param_b' => ['additional_test'] + 'param_b' => ['additional_test'], }, 'static_configs' => [ 'targets' => ['1.1.1.1:8060'], @@ -212,7 +216,7 @@ To use an external Prometheus server: 1. Install and set up a dedicated Prometheus instance, if necessary, using the [official installation instructions](https://prometheus.io/docs/prometheus/latest/installation/). -1. On **all** GitLab Rails(Puma, Sidekiq) servers, set the Prometheus server IP address and listen port. For example: +1. On **all** GitLab Rails (Puma, Sidekiq) servers, set the Prometheus server IP address and listen port. For example: ```ruby gitlab_rails['prometheus_address'] = '192.168.0.1:9090' @@ -236,7 +240,7 @@ To use an external Prometheus server: nginx['status']['options'] = { "server_tokens" => "off", "access_log" => "off", - "allow" => ["192.168.0.1", "192.168.0.2"] + "allow" => ["192.168.0.1", "192.168.0.2"], "deny" => "all", } ``` diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index 4de05034fff..6b395f77ce2 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -1,7 +1,7 @@ --- stage: Shared responsibility based on functional area group: Shared responsibility based on functional area -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Node exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index 6f925cb7fb6..e1773301047 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PgBouncer exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md index 20cfb078994..fe04ae3f797 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL Server Exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index 25c76fac743..fde07c68c0a 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -1,7 +1,7 @@ --- stage: Shared responsibility based on functional area group: Shared responsibility based on functional area -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md index 1c46224f7b3..8dde7086d79 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Registry exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/web_exporter.md b/doc/administration/monitoring/prometheus/web_exporter.md index fbf4a109813..2831ca17c81 100644 --- a/doc/administration/monitoring/prometheus/web_exporter.md +++ b/doc/administration/monitoring/prometheus/web_exporter.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web exporter (dedicated metrics server) **(FREE SELF)** diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index 119f757bfbc..5f12c141540 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using NFS with GitLab **(FREE SELF)** @@ -258,7 +257,6 @@ following are the 4 locations need to be shared: | Location | Description | Default configuration | | -------- | ----------- | --------------------- | -| `/var/opt/gitlab/git-data` | Git repository data. This accounts for a large portion of your data | `git_data_dirs({"default" => { "path" => "/var/opt/gitlab/git-data"} })` | `/var/opt/gitlab/gitlab-rails/uploads` | User uploaded attachments | `gitlab_rails['uploads_directory'] = '/var/opt/gitlab/gitlab-rails/uploads'` | `/var/opt/gitlab/gitlab-rails/shared` | Objects such as build artifacts, GitLab Pages, LFS objects, and temp files. If you're using LFS this may also account for a large portion of your data | `gitlab_rails['shared_path'] = '/var/opt/gitlab/gitlab-rails/shared'` | `/var/opt/gitlab/gitlab-ci/builds` | GitLab CI/CD build traces | `gitlab_ci['builds_directory'] = '/var/opt/gitlab/gitlab-ci/builds'` diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index 0b12d41eb4e..9a9b2811cf0 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Object storage **(FREE SELF)** @@ -157,13 +157,13 @@ For the storage-specific form, because it does not require a shared folder. For configuring object storage in GitLab 13.1 and earlier, _or_ for storage types not -For storage types not supported by the consolidated form, refer to the following guides: +supported by the consolidated form, refer to the following guides: | Object storage type | Supported by consolidated form? | |---------------------|------------------------------------------| | [Secure Files](secure_files.md#using-object-storage) | **{dotted-circle}** No | | [Backups](../administration/backup_restore/backup_gitlab.md#upload-backups-to-a-remote-cloud-storage) | **{dotted-circle}** No | -| [Container Registry](packages/container_registry.md#use-object-storage) (optional feature) | **{dotted-circle}** No | +| [Container registry](packages/container_registry.md#use-object-storage) (optional feature) | **{dotted-circle}** No | | [Mattermost](https://docs.mattermost.com/configure/file-storage-configuration-settings.html)| **{dotted-circle}** No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | **{dotted-circle}** No | | [Job artifacts](job_artifacts.md#using-object-storage) including archived job logs | **{check-circle}** Yes | @@ -814,7 +814,7 @@ or add fault tolerance and redundancy, you may be looking at removing dependencies on block or network file systems. See the following additional guides: -1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#moving-the-home-directory-for-a-user) is on local disk. +1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#move-the-home-directory-for-a-user) is on local disk. 1. Configure [database lookup of SSH keys](operations/fast_ssh_key_lookup.md) to eliminate the need for a shared `authorized_keys` file. 1. [Prevent local disk usage for job logs](job_logs.md#prevent-local-disk-usage). diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 888ec79d4b6..2170abf8700 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Fast lookup of authorized SSH keys in the database **(FREE SELF)** @@ -121,9 +121,8 @@ users as long as a large file exists. To disable writes to the `authorized_keys` file: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Performance optimization**. 1. Clear the **Use authorized_keys file to authenticate SSH keys** checkbox. 1. Select **Save changes**. @@ -141,8 +140,7 @@ This overview is brief. Refer to the above instructions for more context. 1. [Rebuild the `authorized_keys` file](../raketasks/maintenance.md#rebuild-authorized_keys-file). 1. Enable writes to the `authorized_keys` file. - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Performance optimization**. 1. Select the **Use authorized_keys file to authenticate SSH keys** checkbox. diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md index bd37bd4b1a8..7b0bb012624 100644 --- a/doc/administration/operations/filesystem_benchmarking.md +++ b/doc/administration/operations/filesystem_benchmarking.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File system performance benchmarking **(FREE SELF)** diff --git a/doc/administration/operations/gitlab_sshd.md b/doc/administration/operations/gitlab_sshd.md index 43ca6251a0e..86c6d9d7fba 100644 --- a/doc/administration/operations/gitlab_sshd.md +++ b/doc/administration/operations/gitlab_sshd.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # `gitlab-sshd` **(FREE SELF)** diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index be90b0a073f..33f407b2dbf 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maintain your GitLab installation **(FREE SELF)** diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 49746c7cc72..2c2762d92b7 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moving repositories managed by GitLab **(FREE SELF)** diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index 89f1574697f..ec236f52c5b 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the bundled Puma instance of the GitLab package **(FREE SELF)** diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index b3e7a97428a..f15fdd32c90 100644 --- a/doc/administration/operations/rails_console.md +++ b/doc/administration/operations/rails_console.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rails console **(FREE SELF)** @@ -108,13 +108,24 @@ Notify.test_email(u.email, "Test email for #{u.name}", 'Test email').deliver_now ## Disable database statement timeout You can disable the PostgreSQL statement timeout for the current Rails console -session by running: +session. + +In GitLab 15.11 and earlier, to disable the database statement timeout, run: + +```ruby +ActiveRecord::Base.connection.execute('SET statement_timeout TO 0') +``` + +In GitLab 16.0 and later, [GitLab uses two database connections by default](../../update/versions/gitlab_16_changes.md#1600). To disable the database statement timeout, run: ```ruby ActiveRecord::Base.connection.execute('SET statement_timeout TO 0') +Ci::ApplicationRecord.connection.execute('SET statement_timeout TO 0') ``` -This change only affects the current Rails console session and is +Instances running GitLab 16.0 and later reconfigured to use a single database connection should disable the database statement timeout using the code for GitLab 15.11 and earlier. + +Disabling the database statement timeout affects only the current Rails console session and is not persisted in the GitLab production environment or in the next Rails console session. @@ -707,7 +718,7 @@ irb(#<Project>)> web_url The `gitlab-rails` command executes Rails Runner using a non-root account and group, by default: `git:git`. -If the non-root account cannot find the Ruby script filename passed to `gitlab-rails runner` +If the non-root account cannot find the Ruby script file name passed to `gitlab-rails runner` you may get a syntax error, not an error that the file couldn't be accessed. A common reason for this is that the script has been put in the root account's home directory. diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index bdd1045f7a7..ca24b2e0721 100644 --- a/doc/administration/operations/ssh_certificates.md +++ b/doc/administration/operations/ssh_certificates.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User lookup via OpenSSH's AuthorizedPrincipalsCommand **(FREE SELF)** diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md index f85ada3c782..93f01d71879 100644 --- a/doc/administration/package_information/defaults.md +++ b/doc/administration/package_information/defaults.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package defaults **(FREE SELF)** diff --git a/doc/administration/package_information/deprecation_policy.md b/doc/administration/package_information/deprecation_policy.md index f2d23da2b7e..7cc589990db 100644 --- a/doc/administration/package_information/deprecation_policy.md +++ b/doc/administration/package_information/deprecation_policy.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linux package deprecation policy **(FREE SELF)** diff --git a/doc/administration/package_information/index.md b/doc/administration/package_information/index.md index 503fdfe3ba8..59086579965 100644 --- a/doc/administration/package_information/index.md +++ b/doc/administration/package_information/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package information **(FREE SELF)** diff --git a/doc/administration/package_information/licensing.md b/doc/administration/package_information/licensing.md index cad9c0e6075..2f907ba9df3 100644 --- a/doc/administration/package_information/licensing.md +++ b/doc/administration/package_information/licensing.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Licensing **(FREE SELF)** diff --git a/doc/administration/package_information/omnibus_packages.md b/doc/administration/package_information/omnibus_packages.md index d16783034dc..8f8fa0097f7 100644 --- a/doc/administration/package_information/omnibus_packages.md +++ b/doc/administration/package_information/omnibus_packages.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Packages and images from the Linux package **(FREE SELF)** diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md index 3a499be43b3..5140d795892 100644 --- a/doc/administration/package_information/postgresql_versions.md +++ b/doc/administration/package_information/postgresql_versions.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL versions shipped with the Linux package **(FREE SELF)** @@ -29,19 +29,21 @@ The lowest supported PostgreSQL versions are listed in the Read more about update policies and warnings in the PostgreSQL [upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). -| GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes | +| First GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes | | -------------- | ------------------- | ---------------------------------- | ---------------------------- | ----- | -| 16.2.0 | 13.11, 14.8 | 13.11 | 13.11 | For upgrades, users can manually upgrade to 14.8 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-162-and-later). | +| 16.7.0 | 13.12, 14.9 | 14.9 | 14.9 | | +| 16.4.3, 16.5.3, 16.6.1 | 13.12, 14.9 | 13.12 | 13.12 | For upgrades, you can manually upgrade to 14.9 following the [upgrade documentation](../../update/versions/gitlab_16_changes.md#linux-package-installations-2). | +| 16.2.0 | 13.11, 14.8 | 13.11 | 13.11 | For upgrades, you can manually upgrade to 14.8 following the [upgrade documentation](../../update/versions/gitlab_16_changes.md#linux-package-installations-2). | | 16.0.2 | 13.11 | 13.11 | 13.11 | | | 16.0.0 | 13.8 | 13.8 | 13.8 | | | 15.11.7 | 13.11 | 13.11 | 12.12 | | | 15.10.8 | 13.11 | 13.11 | 12.12 | | -| 15.6 | 12.12, 13.8 | 13.8 | 12.12 | For upgrades, users can manually upgrade to 13.8 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-150-and-later). | -| 15.0 | 12.10, 13.6 | 13.6 | 12.10 | For upgrades, users can manually upgrade to 13.6 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-150-and-later). | +| 15.6 | 12.12, 13.8 | 13.8 | 12.12 | For upgrades, you can manually upgrade to 13.8 following the [upgrade documentation](../../update/versions/gitlab_15_changes.md#linux-package-installations-2). | +| 15.0 | 12.10, 13.6 | 13.6 | 12.10 | For upgrades, you can manually upgrade to 13.6 following the [upgrade documentation](../../update/versions/gitlab_15_changes.md#linux-package-installations-2). | | 14.1 | 12.7, 13.3 | 12.7 | 12.7 | PostgreSQL 13 available for fresh installations if not using [Geo](../geo/index.md#requirements-for-running-geo) or [Patroni](../postgresql/index.md#postgresql-replication-and-failover-for-linux-package-installations). | 14.0 | 12.7 | 12.7 | 12.7 | HA installations with repmgr are no longer supported and are prevented from upgrading to Linux package 14.0 | | 13.8 | 11.9, 12.4 | 12.4 | 12.4 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or HA cluster. | -| 13.7 | 11.9, 12.4 | 12.4 | 11.9 | For upgrades users can manually upgrade to 12.4 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-133-and-later). | +| 13.7 | 11.9, 12.4 | 12.4 | 11.9 | For upgrades users can manually upgrade to 12.4 following the [upgrade documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). | | 13.4 | 11.9, 12.4 | 11.9 | 11.9 | Package upgrades aborted if users not running PostgreSQL 11 already | | 13.3 | 11.7, 12.3 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already | | 13.0 | 11.7 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already | diff --git a/doc/administration/package_information/signed_packages.md b/doc/administration/package_information/signed_packages.md index b2aab96e52c..22ac472c590 100644 --- a/doc/administration/package_information/signed_packages.md +++ b/doc/administration/package_information/signed_packages.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Signatures **(FREE SELF)** diff --git a/doc/administration/package_information/supported_os.md b/doc/administration/package_information/supported_os.md index ab579ca93c6..89b2f78f6d9 100644 --- a/doc/administration/package_information/supported_os.md +++ b/doc/administration/package_information/supported_os.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported operating systems **(FREE SELF)** diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 74dd71c19bf..bfeca7c56b9 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -1,12 +1,12 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Container Registry administration **(FREE SELF)** +# GitLab container registry administration **(FREE SELF)** -With the GitLab Container Registry, every project can have its +With the GitLab container registry, every project can have its own space to store Docker images. For more details about the Distribution Registry: @@ -18,24 +18,24 @@ For more details about the Distribution Registry: This document is the administrator's guide. To learn how to use the GitLab Container Registry, see the [user documentation](../../user/packages/container_registry/index.md). -## Enable the Container Registry +## Enable the container registry -The process for enabling the Container Registry depends on the type of installation you use. +The process for enabling the container registry depends on the type of installation you use. ### Linux package installations -If you installed GitLab by using the Linux package, the Container Registry +If you installed GitLab by using the Linux package, the container registry may or may not be available by default. -The Container Registry is automatically enabled and available on your GitLab domain, port 5050 if +The container registry is automatically enabled and available on your GitLab domain, port 5050 if you're using the built-in [Let's Encrypt integration](https://docs.gitlab.com/omnibus/settings/ssl/index.html#enable-the-lets-encrypt-integration). -Otherwise, the Container Registry is not enabled. To enable it: +Otherwise, the container registry is not enabled. To enable it: - You can configure it for your [GitLab domain](#configure-container-registry-under-an-existing-gitlab-domain), or - You can configure it for [a different domain](#configure-container-registry-under-its-own-domain). -The Container Registry works under HTTPS by default. You can use HTTP +The container registry works under HTTPS by default. You can use HTTP but it's not recommended and is beyond the scope of this document. ### Self-compiled installations @@ -96,7 +96,7 @@ auth: WARNING: If `auth` is not set up, users can pull Docker images without authentication. -## Container Registry domain configuration +## Container registry domain configuration You can configure the Registry's external domain in either of these ways: @@ -105,19 +105,19 @@ You can configure the Registry's external domain in either of these ways: - [Use a completely separate domain](#configure-container-registry-under-its-own-domain) with a new TLS certificate for that domain. -Because the Container Registry requires a TLS certificate, cost may be a factor. +Because the container registry requires a TLS certificate, cost may be a factor. -Take this into consideration before configuring the Container Registry +Take this into consideration before configuring the container registry for the first time. -### Configure Container Registry under an existing GitLab domain +### Configure container registry under an existing GitLab domain -If the Container Registry is configured to use the existing GitLab domain, you can -expose the Container Registry on a port. This way you can reuse the existing GitLab TLS +If the container registry is configured to use the existing GitLab domain, you can +expose the container registry on a port. This way you can reuse the existing GitLab TLS certificate. If the GitLab domain is `https://gitlab.example.com` and the port to the outside world is `5050`, -to configure the Container Registry: +to configure the container registry: - Edit `gitlab.rb` if you are using a Linux package installation. - Edit `gitlab.yml` if you are using a self-compiled installation. @@ -194,14 +194,14 @@ registry_nginx['listen_port'] = 5678 ::EndTabs -Users should now be able to sign in to the Container Registry with their GitLab +Users should now be able to sign in to the container registry with their GitLab credentials using: ```shell docker login gitlab.example.com:5050 ``` -### Configure Container Registry under its own domain +### Configure container registry under its own domain When the Registry is configured to use its own domain, you need a TLS certificate for that specific domain (for example, `registry.example.com`). You might need @@ -212,7 +212,7 @@ and is distinct from `*.example.com`. As well as manually generated SSL certificates (explained here), certificates automatically generated by Let's Encrypt are also [supported in Linux package installations](https://docs.gitlab.com/omnibus/settings/ssl/index.html). -Let's assume that you want the container Registry to be accessible at +Let's assume that you want the container registry to be accessible at `https://registry.gitlab.example.com`. ::Tabs @@ -263,14 +263,14 @@ registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key" ::EndTabs -Users should now be able to sign in to the Container Registry using their GitLab +Users should now be able to sign in to the container registry using their GitLab credentials: ```shell docker login registry.gitlab.example.com ``` -## Disable Container Registry site-wide +## Disable container registry site-wide When you disable the Registry by following these steps, you do not remove any existing Docker images. Docker image removal is handled by the @@ -302,11 +302,11 @@ Registry application itself. ::EndTabs -## Disable Container Registry for new projects site-wide +## Disable container registry for new projects site-wide -If the Container Registry is enabled, then it should be available on all new +If the container registry is enabled, then it should be available on all new projects. To disable this function and let the owners of a project to enable -the Container Registry by themselves, follow the steps below. +the container registry by themselves, follow the steps below. ::Tabs @@ -342,17 +342,16 @@ the Container Registry by themselves, follow the steps below. ### Increase token duration -In GitLab, tokens for the Container Registry expire every five minutes. +In GitLab, tokens for the container registry expire every five minutes. To increase the token duration: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Container Registry**. 1. For the **Authorization token duration (minutes)**, update the value. 1. Select **Save changes**. -## Configure storage for the Container Registry +## Configure storage for the container registry NOTE: For storage backends that support it, you can use object versioning to preserve, retrieve, and @@ -367,8 +366,8 @@ you should configure an object lifecycle policy with your storage provider. WARNING: Do not directly modify the files or objects stored by the container registry. Anything other than the registry writing or deleting these entries can lead to instance-wide data consistency and instability issues from which recovery may not be possible. -You can configure the Container Registry to use various storage backends by -configuring a storage driver. By default the GitLab Container Registry +You can configure the container registry to use various storage backends by +configuring a storage driver. By default the GitLab container registry is configured to use the [file system driver](#use-file-system) configuration. @@ -380,19 +379,32 @@ The different supported drivers are: | `azure` | Microsoft Azure Blob Storage | | `gcs` | Google Cloud Storage | | `s3` | Amazon Simple Storage Service. Be sure to configure your storage bucket with the correct [S3 Permission Scopes](https://docs.docker.com/registry/storage-drivers/s3/#s3-permission-scopes). | -| `swift` | OpenStack Swift Object Storage | -| `oss` | Aliyun OSS | -Although most S3 compatible services (like [MinIO](https://min.io/)) should work with the Container Registry, we only guarantee support for AWS S3. Because we cannot assert the correctness of third-party S3 implementations, we can debug issues, but we cannot patch the registry unless an issue is reproducible against an AWS S3 bucket. +Although most S3 compatible services (like [MinIO](https://min.io/)) should work with the container registry, +we only guarantee support for AWS S3. Because we cannot assert the correctness of third-party S3 implementations, +we can debug issues, but we cannot patch the registry unless an issue is reproducible against an AWS S3 bucket. + +<!--- start_remove The following content will be removed on remove_date: '2024-05-16' --> + +WARNING: +Support for the following drivers was [deprecated](https://gitlab.com/gitlab-org/container-registry/-/issues/1141) +in GitLab 16.6, and is planned for removal in 17.0. This change is a breaking change. + +| Driver | Description | +|---------|-------------| +| `swift` | OpenStack Swift Object Storage | +| `oss` | Aliyun OSS | + +<!--- end_remove --> ### Use file system If you want to store your images on the file system, you can change the storage -path for the Container Registry, follow the steps below. +path for the container registry, follow the steps below. This path is accessible to: -- The user running the Container Registry daemon. +- The user running the container registry daemon. - The user running GitLab. All GitLab, Registry, and web server users must @@ -433,7 +445,7 @@ The default location where images are stored in self-compiled installations is ### Use object storage If you want to store your images on object storage, you can change the storage -driver for the Container Registry. +driver for the container registry. [Read more about using object storage with GitLab](../object_storage.md). @@ -566,15 +578,15 @@ to copy the registry data to or between S3 buckets creates invalid metadata obje For additional details, see [Tags with an empty name](#tags-with-an-empty-name). To move data to and between S3 buckets, the AWS CLI `sync` operation is recommended. -To migrate storage without stopping the Container Registry, set the Container Registry -to read-only mode. On large instances, this may require the Container Registry +To migrate storage without stopping the container registry, set the container registry +to read-only mode. On large instances, this may require the container registry to be in read-only mode for a while. During this time, -you can pull from the Container Registry, but you cannot push. +you can pull from the container registry, but you cannot push. 1. Optional: To reduce the amount of data to be migrated, run the [garbage collection tool without downtime](#performing-garbage-collection-without-downtime). 1. This example uses the `aws` CLI. If you haven't configured the CLI before, you have to configure your credentials by running `sudo aws configure`. - Because a non-administrator user likely can't access the Container Registry folder, + Because a non-administrator user likely can't access the container registry folder, ensure you use `sudo`. To check your credential configuration, run [`ls`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/ls.html) to list all buckets. @@ -598,7 +610,7 @@ you can pull from the Container Registry, but you cannot push. [running parallel sync operations](https://repost.aws/knowledge-center/s3-improve-transfer-sync-command). 1. To perform the final data sync, - [put the Container Registry in `read-only` mode](#performing-garbage-collection-without-downtime) and + [put the container registry in `read-only` mode](#performing-garbage-collection-without-downtime) and [reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). 1. Sync any changes dating from after the initial data load to your S3 bucket, and delete files that exist in the destination bucket but not in the source: @@ -615,7 +627,7 @@ you can pull from the Container Registry, but you cannot push. flag deletes files that exist in the destination but not in the source. If you swap the source and destination, all data in the Registry is deleted. -1. Verify all Container Registry files have been uploaded to object storage +1. Verify all container registry files have been uploaded to object storage by looking at the file count returned by these two commands: ```shell @@ -635,11 +647,6 @@ you can pull from the Container Registry, but you cannot push. > The default configuration for the storage driver is scheduled to be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0. -<!--- start_remove The following content will be removed on remove_date: '2023-10-22' --> -WARNING: -The default configuration for the storage driver is scheduled to be [changed](https://gitlab.com/gitlab-org/container-registry/-/issues/854) in GitLab 16.0. The storage driver will use `/` as the default root directory. You can add `trimlegacyrootprefix: false` to your current configuration now to avoid any disruptions. For more information, see the [Container Registry configuration](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/upstream-differences.md#azure-storage-driver) documentation. -<!--- end_remove --> - When moving from an existing file system or another object storage provider to Azure Object Storage, you must configure the registry to use the standard root directory. Configure it by setting [`trimlegacyrootprefix: true`](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/upstream-differences.md#azure-storage-driver) in the Azure storage driver section of the registry configuration. Without this configuration, the Azure storage driver uses `//` instead of `/` as the first section of the root path, rendering the migrated images inaccessible. @@ -819,17 +826,17 @@ In the examples below we set the Registry's port to `5010`. ::EndTabs -## Disable Container Registry per project +## Disable container registry per project If Registry is enabled in your GitLab instance, but you don't need it for your -project, you can [disable it from your project's settings](../../user/project/settings/index.md#configure-project-features-and-permissions). +project, you can [disable it from your project's settings](../../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions). ## Use an external container registry with GitLab as an auth endpoint WARNING: Using external container registries in GitLab is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/376217) in GitLab 15.8 and the end of support is scheduled for GitLab 16.0. -If you need to use external container registries instead of the GitLab Container Registry, +If you need to use external container registries instead of the GitLab container registry, tell us about your use cases in [feedback issue 958](https://gitlab.com/gitlab-org/container-registry/-/issues/958). If you use an external container registry, some features associated with the @@ -870,8 +877,8 @@ You can use GitLab as an auth endpoint with an external container registry. ``` - `gitlab_rails['registry_enabled'] = true` is needed to enable GitLab - Container Registry features and authentication endpoint. The GitLab bundled - Container Registry service does not start, even with this enabled. + container registry features and authentication endpoint. The GitLab bundled + container registry service does not start, even with this enabled. - `gitlab_rails['registry_api_url'] = "http://<external_registry_host>:5000"` must be changed to match the host where Registry is installed. It must also specify `https` if the external registry is @@ -916,7 +923,7 @@ You can use GitLab as an auth endpoint with an external container registry. 1. Open `/home/git/gitlab/config/gitlab.yml`, and edit the configuration settings under `registry`: ```yaml - ## Container Registry + ## Container registry registry: enabled: true @@ -932,15 +939,15 @@ You can use GitLab as an auth endpoint with an external container registry. 1. Save the file and [restart GitLab](../restart_gitlab.md#self-compiled-installations) for the changes to take effect. -## Configure Container Registry notifications +## Configure container registry notifications -You can configure the Container Registry to send webhook notifications in +You can configure the container registry to send webhook notifications in response to events happening in the registry. -Read more about the Container Registry notifications configuration options in the +Read more about the container registry notifications configuration options in the [Docker Registry notifications documentation](https://docs.docker.com/registry/notifications/). -You can configure multiple endpoints for the Container Registry. +You can configure multiple endpoints for the container registry. ::Tabs @@ -1062,7 +1069,7 @@ end You can also [run cleanup on a schedule](../../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy). -## Container Registry garbage collection +## Container registry garbage collection NOTE: Retention policies in your object storage provider, such as Amazon S3 Lifecycle, may prevent @@ -1073,17 +1080,17 @@ The container registry can use considerable amounts of storage space, and you mi Among the listed options, deleting tags is the most effective option. However, tag deletion alone does not delete image layers, it only leaves the underlying image manifests untagged. -To more effectively free up space, the Container Registry has a garbage collector that can +To more effectively free up space, the container registry has a garbage collector that can delete unreferenced layers and (optionally) untagged manifests. To start the garbage collector, use the `registry-garbage-collect` command provided by `gitlab-ctl`. WARNING: -This command shuts down the Container Registry prior to the garbage collection and +This command shuts down the container registry prior to the garbage collection and only starts it again after garbage collection completes. If you prefer to avoid downtime, -you can manually set the Container Registry to [read-only mode and bypass `gitlab-ctl`](#performing-garbage-collection-without-downtime). +you can manually set the container registry to [read-only mode and bypass `gitlab-ctl`](#performing-garbage-collection-without-downtime). -The time required to perform garbage collection is proportional to the Container Registry data size. +The time required to perform garbage collection is proportional to the container registry data size. Prerequisites: @@ -1115,9 +1122,9 @@ no longer directly accessible via the `:latest` tag. ### Remove unreferenced layers -Image layers are the bulk of the Container Registry storage. A layer is considered +Image layers are the bulk of the container registry storage. A layer is considered unreferenced when no image manifest references it. Unreferenced layers are the -default target of the Container Registry garbage collector. +default target of the container registry garbage collector. If you did not change the default location of the configuration file, run: @@ -1125,7 +1132,7 @@ If you did not change the default location of the configuration file, run: sudo gitlab-ctl registry-garbage-collect ``` -If you changed the location of the Container Registry `config.yml`: +If you changed the location of the container registry `config.yml`: ```shell sudo gitlab-ctl registry-garbage-collect /path/to/config.yml @@ -1136,7 +1143,7 @@ to recover additional space. ### Removing untagged manifests and unreferenced layers -By default the Container Registry garbage collector ignores images that are untagged, +By default the container registry garbage collector ignores images that are untagged, and users can keep pulling untagged images by digest. Users can also re-tag images in the future, making them visible again in the GitLab UI and API. @@ -1151,11 +1158,11 @@ If you are unsure about deleting untagged images, back up your registry data bef ### Performing garbage collection without downtime -To do garbage collection while keeping the Container Registry online, put the registry +To do garbage collection while keeping the container registry online, put the registry in read-only mode and bypass the built-in `gitlab-ctl registry-garbage-collect` command. -You can pull but not push images while the Container Registry is in read-only mode. The Container -Registry must remain in read-only for the full duration of the garbage collection. +You can pull but not push images while the container registry is in read-only mode. The container +registry must remain in read-only for the full duration of the garbage collection. By default, the [registry storage path](#configure-storage-for-the-container-registry) is `/var/opt/gitlab/gitlab-rails/shared/registry`. @@ -1183,7 +1190,7 @@ To enable the read-only mode: sudo gitlab-ctl reconfigure ``` - This command sets the Container Registry into the read-only mode. + This command sets the container registry into the read-only mode. 1. Next, trigger one of the garbage collect commands: @@ -1298,7 +1305,7 @@ for GitLab to run separately from Registry: Registry side. - `gitlab_rails['internal_key']`, contents of the key that GitLab uses to sign the tokens. -## Architecture of GitLab Container Registry +## Architecture of GitLab container registry The GitLab registry is what users use to store their own Docker images. Because of that the Registry is client facing, meaning that we expose it directly @@ -1342,10 +1349,10 @@ in GitLab 15.8 and the end of support occurred in GitLab 16.0. See the [deprecat The integration is not disabled in GitLab 16.0, but support for debugging and fixing issues is no longer provided. Additionally, the integration is no longer being developed or enhanced with new features. Third-party registry functionality might be completely removed -after the new GitLab Container Registry version is available for self-managed (see epic [5521](https://gitlab.com/groups/gitlab-org/-/epics/5521)). Only the GitLab Container Registry is planned to be supported. +after the new GitLab container registry version is available for self-managed (see epic [5521](https://gitlab.com/groups/gitlab-org/-/epics/5521)). Only the GitLab container registry is planned to be supported. This section has guidance for administrators migrating from third-party registries -to the GitLab Container Registry. If the third-party container registry you are using is not listed here, +to the GitLab container registry. If the third-party container registry you are using is not listed here, you can describe your use cases in [the feedback issue](https://gitlab.com/gitlab-org/container-registry/-/issues/958). For all of the instructions provided below, you should try them first on a test environment. @@ -1355,11 +1362,11 @@ Make sure everything continues to work as expected before replicating it in prod The [Docker Distribution Registry](https://docs.docker.com/registry/) was donated to the CNCF and is now known as the [Distribution Registry](https://github.com/distribution/distribution). -This registry is the open source implementation that the GitLab Container Registry is based on. -The GitLab Container Registry is compatible with the basic functionality provided by the Distribution Registry, -including all the supported storage backends. To migrate to the GitLab Container Registry +This registry is the open source implementation that the GitLab container registry is based on. +The GitLab container registry is compatible with the basic functionality provided by the Distribution Registry, +including all the supported storage backends. To migrate to the GitLab container registry you can follow the instructions on this page, and use the same storage backend as the Distribution Registry. -The GitLab Container Registry should accept the same configuration that you are using for the Distribution Registry. +The GitLab container registry should accept the same configuration that you are using for the Distribution Registry. ## Use a PostgreSQL database for metadata **(FREE SELF BETA)** @@ -1413,9 +1420,9 @@ Before diving in to the following sections, here's some basic troubleshooting: for errors (for example `/var/log/gitlab/gitlab-rails/production.log`). You may be able to find clues there. -### Using self-signed certificates with Container Registry +### Using self-signed certificates with container registry -If you're using a self-signed certificate with your Container Registry, you +If you're using a self-signed certificate with your container registry, you might encounter issues during the CI jobs like the following: ```plaintext @@ -1467,7 +1474,7 @@ Check which files are in use: - `grep -A6 'auth:' /var/opt/gitlab/registry/config.yml` ```yaml - ## Container Registry Certificate + ## Container registry certificate auth: token: realm: https://gitlab.my.net/jwt/auth @@ -1480,7 +1487,7 @@ Check which files are in use: - `grep -A9 'Container Registry' /var/opt/gitlab/gitlab-rails/etc/gitlab.yml` ```yaml - ## Container Registry Key + ## Container registry key registry: enabled: true host: gitlab.company.com @@ -1600,7 +1607,7 @@ project or branch name. Special characters can include: - Double hyphen/dash To get around this, you can [change the group path](../../user/group/manage.md#change-a-groups-path), -[change the project path](../../user/project/settings/index.md#rename-a-repository) or change the +[change the project path](../../user/project/working_with_projects.md#rename-a-repository) or change the branch name. Another option is to create a [push rule](../../user/project/repository/push_rules.md) to prevent this at the instance level. @@ -1643,7 +1650,7 @@ and a simple solution would be to enable relative URLs in the Registry. ### Enable the Registry debug server -You can use the Container Registry debug server to diagnose problems. The debug endpoint can monitor metrics and health, as well as do profiling. +You can use the container registry debug server to diagnose problems. The debug endpoint can monitor metrics and health, as well as do profiling. WARNING: Sensitive information may be available from the debug endpoint. @@ -1674,9 +1681,9 @@ was: - [Deprecated in GitLab 13.7](https://about.gitlab.com/releases/2020/12/22/gitlab-13-7-released/#deprecate-pulls-that-use-v1-of-the-docker-registry-api) - [Removed in GitLab 13.9](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#deprecate-pulls-that-use-v1-of-the-docker-registry-api) -It's no longer possible to push or pull v1 images from the GitLab Container Registry. +It's no longer possible to push or pull v1 images from the GitLab container registry. -If you had v1 images in the GitLab Container Registry, but you did not upgrade them (following the +If you had v1 images in the GitLab container registry, but you did not upgrade them (following the [steps Docker recommends](https://docs.docker.com/registry/spec/deprecated-schema-v1/)) ahead of the GitLab 13.9 upgrade, these images are no longer accessible. If you try to pull them, this error appears: @@ -1684,12 +1691,12 @@ this error appears: - `Error response from daemon: manifest invalid: Schema 1 manifest not supported` For self-managed GitLab instances, you can regain access to these images by temporarily downgrading -the GitLab Container Registry to a version lower than `v3.0.0-gitlab`. Follow these steps to regain +the GitLab container registry to a version lower than `v3.0.0-gitlab`. Follow these steps to regain access to these images: -1. Downgrade the Container Registry to [`v2.13.1-gitlab`](https://gitlab.com/gitlab-org/container-registry/-/releases/v2.13.1-gitlab). +1. Downgrade the container registry to [`v2.13.1-gitlab`](https://gitlab.com/gitlab-org/container-registry/-/releases/v2.13.1-gitlab). 1. Upgrade any v1 images. -1. Revert the Container Registry downgrade. +1. Revert the container registry downgrade. There's no need to put the registry in read-only mode during the image upgrade process. Ensure that you are not relying on any new feature introduced since `v3.0.0-gitlab`. Such features are @@ -1936,7 +1943,7 @@ Once the right permissions were set, the error goes away. ### Missing `gitlab-registry.key` prevents container repository deletion -If you disable your GitLab instance's Container Registry and try to remove a project that has +If you disable your GitLab instance's container registry and try to remove a project that has container repositories, the following error occurs: ```plaintext @@ -1945,7 +1952,7 @@ Errno::ENOENT: No such file or directory @ rb_sysopen - /var/opt/gitlab/gitlab-r In this case, follow these steps: -1. Temporarily enable the instance-wide setting for the Container Registry in your `gitlab.rb`: +1. Temporarily enable the instance-wide setting for the container registry in your `gitlab.rb`: ```ruby gitlab_rails['registry_enabled'] = true diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index f84703b63e7..8098ed2e95b 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Dependency Proxy administration **(FREE SELF)** diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 2eb3da4b5d7..51641bf06ea 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -1,18 +1,18 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Package Registry administration **(FREE SELF)** +# GitLab package registry administration **(FREE SELF)** -To use GitLab as a private repository for a variety of common package managers, use the Package Registry. +To use GitLab as a private repository for a variety of common package managers, use the package registry. You can build and publish packages, which can be consumed as dependencies in downstream projects. ## Supported formats -The Package Registry supports the following formats: +The package registry supports the following formats: | Package type | GitLab version | |-------------------------------------------------------------------|----------------| @@ -55,11 +55,11 @@ guides you through the process. When downloading packages as dependencies in downstream projects, many requests are made through the Packages API. You may therefore reach enforced user and IP rate limits. To address this issue, you -can define specific rate limits for the Packages API. For more details, see [Package Registry Rate Limits](../settings/package_registry_rate_limits.md). +can define specific rate limits for the Packages API. For more details, see [package registry rate limits](../settings/package_registry_rate_limits.md). -## Enable or disable the Package Registry +## Enable or disable the package registry -The Package Registry is enabled by default. To disable it: +The package registry is enabled by default. To disable it: ::Tabs diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 97acbf717fe..0594c4b93bd 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages administration **(FREE SELF)** @@ -93,6 +93,41 @@ Where `example.io` is the domain GitLab Pages is served from, `192.0.2.1` is the IPv4 address of your GitLab instance, and `2001:db8::1` is the IPv6 address. If you don't have IPv6, you can omit the `AAAA` record. +#### For namespace in URL path, without wildcard DNS **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Prerequisites: + +- Your instance must use the Linux package installation method. + +If you need support for namespace in the URL path to remove the requirement for wildcard DNS: + +1. Enable the GitLab Pages flag for this feature by adding + `gitlab_pages["namespace_in_path"] = true` to `/etc/gitlab/gitlab.rb`. +1. In your DNS provider, add entries for `example.com` and `projects.example.com`. + In both lines, replace `example.com` with your domain name, and `192.0.0.0` with + the IPv4 version of your IP address. The entries look like this: + + ```plaintext + example.com 1800 IN A 192.0.0.0 + projects.example.com 1800 IN A 192.0.0.0 + ``` + +1. Optional. If your GitLab instance has an IPv6 address, add entries for it. + In both lines, replace `example.com` with your domain name, and `2001:db8::1` with + the IPv6 version of your IP address. The entries look like this: + + ```plaintext + example.com 1800 IN AAAA 2001:db8::1 + projects.example.com 1800 IN AAAA 2001:db8::1 + ``` + #### DNS configuration for custom domains If support for custom domains is needed, all subdomains of the Pages root domain should point to the @@ -149,6 +184,46 @@ The Pages daemon doesn't listen to the outside world. Watch the [video tutorial](https://youtu.be/dD8c7WNcc6s) for this configuration. +### Pages domain without wildcard DNS **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +This configuration is the minimum setup for GitLab Pages. It is the base for all +other configurations. In this configuration, NGINX proxies all requests to the daemon, +because the GitLab Pages daemon doesn't listen to the outside world. + +Prerequisites: + +- Your instance must use the Linux package installation method. +- You have configured DNS setup + [without a wildcard](#for-namespace-in-url-path-without-wildcard-dns). + +1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages, and enable + the feature flag: + + ```ruby + # External_url here is only for reference + external_url "http://example.com" + pages_external_url 'http://example.io' + + pages_nginx['enable'] = true + + # Set this flag to enable this feature + gitlab_pages["namespace_in_path"] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). + +NGINX uses the custom proxy header `X-Gitlab-Namespace-In-Path` +to send the namespace to the GitLab Pages daemon. + +The resulting URL scheme is `http://example.io/<namespace>/<project_slug>`. + ### Wildcard domains with TLS support **Requirements:** @@ -163,7 +238,7 @@ URL scheme: `https://<namespace>.example.io/<project_slug>` NGINX proxies all requests to the daemon. Pages daemon doesn't listen to the outside world. -1. Place the wildcard LTS certificate for `*.example.io` and the key inside `/etc/gitlab/ssl`. +1. Place the wildcard TLS certificate for `*.example.io` and the key inside `/etc/gitlab/ssl`. 1. In `/etc/gitlab/gitlab.rb` specify the following configuration: ```ruby @@ -195,6 +270,68 @@ Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitl then run `gitlab-ctl reconfigure`. For more information, read [GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). +### Pages domain with TLS support, without wildcard DNS **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17584) in GitLab 16.7. This feature is an [Experiment](../../policy/experiment-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is available. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Prerequisites: + +- Your instance must use the Linux package installation method. +- You have configured DNS setup + [without a wildcard](#for-namespace-in-url-path-without-wildcard-dns). +- You have a single TLS certificate that covers your domain (like `example.com`) + and the `projects.*` version of your domain, like `projects.example.com`. + +In this configuration, NGINX proxies all requests to the daemon. The GitLab Pages +daemon doesn't listen to the outside world: + +1. Add your TLS certificate and key as mentioned in the prerequisites into `/etc/gitlab/ssl`. +1. In `/etc/gitlab/gitlab.rb`, set the external URL for GitLab Pages, and enable + the feature flag: + + ```ruby + # The external_url field is here only for reference. + external_url "https://example.com" + pages_external_url 'https://example.io' + + pages_nginx['enable'] = true + pages_nginx['redirect_http_to_https'] = true + + # Set this flag to enable this feature + gitlab_pages["namespace_in_path"] = true + ``` + +1. If your TLS certificate and key don't match the name of your domain, like + `example.io.crt` and `example.io.key`, + add the full paths for the certificate and key files to `/etc/gitlab/gitlab.rb`: + + ```ruby + pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt" + pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key" + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation). + + WARNING: + GitLab Pages does not update the OAuth application if changes are made to the redirect URI. + Before you reconfigure, remove the `gitlab_pages` section from `/etc/gitlab/gitlab-secrets.json`, + then run `gitlab-ctl reconfigure`. For more information, see + [GitLab Pages does not regenerate OAuth](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3947). + +1. If you're using [Pages Access Control](#access-control), update the redirect URI in the GitLab Pages + [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application) + to use the HTTPS protocol. + +NGINX uses the custom proxy header `X-Gitlab-Namespace-In-Path` +to send the namespace to the GitLab Pages daemon. + +The resulting URL scheme is `https://example.io/<namespace>/<project_slug>`. + ### Wildcard domains with TLS-terminating Load Balancer **Requirements:** @@ -258,6 +395,7 @@ control over how the Pages daemon runs and serves content in your environment. | `gitlab_id` | The OAuth application public ID. Leave blank to automatically fill when Pages authenticates with GitLab. | | `gitlab_secret` | The OAuth application secret. Leave blank to automatically fill when Pages authenticates with GitLab. | | `auth_scope` | The OAuth application scope to use for authentication. Must match GitLab Pages OAuth application settings. Leave blank to use `api` scope by default. | +| `auth_timeout` | GitLab application client timeout for authentication in seconds (default: `5s`). A value of `0` means no timeout. | | `auth_cookie_session_timeout` | Authentication cookie session timeout in seconds (default: `10m`). A value of `0` means the cookie is deleted after the browser session ends. | | `gitlab_server` | Server to use for authentication when access control is enabled; defaults to GitLab `external_url`. | | `headers` | Specify any additional http headers that should be sent to the client with each response. Multiple headers can be given as an array, header and value as one string, for example `['my-header: myvalue', 'my-other-header: my-other-value']` | @@ -268,6 +406,7 @@ control over how the Pages daemon runs and serves content in your environment. | `log_directory` | Absolute path to a log directory. | | `log_format` | The log output format: `text` or `json`. | | `log_verbose` | Verbose logging, true/false. | +| `namespace_in_path` | (Experimental) Enable or disable namespace in the URL path. This requires `pages_nginx[enable] = true`. Sets `rewrite` configuration in NGINX to support [without wildcard DNS setup](#for-namespace-in-url-path-without-wildcard-dns). Default: `false` | | `propagate_correlation_id` | Set to true (false by default) to re-use existing Correlation ID from the incoming request header `X-Request-ID` if present. If a reverse proxy sets this header, the value is propagated in the request chain. | | `max_connections` | Limit on the number of concurrent connections to the HTTP, HTTPS or proxy listeners. | | `max_uri_length` | The maximum length of URIs accepted by GitLab Pages. Set to 0 for unlimited length. [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5729) in GitLab 14.5. @@ -292,7 +431,7 @@ control over how the Pages daemon runs and serves content in your environment. | `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`. | | **`pages_nginx[]`** | | | `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains). | -| `FF_CONFIGURABLE_ROOT_DIR` | Feature flag to [customize the default folder](../../user/project/pages/introduction.md#customize-the-default-folder) (enabled by default). | +| `FF_CONFIGURABLE_ROOT_DIR` | Feature flag to [customize the default folder](../../user/project/pages/introduction.md#customize-the-default-folder) (enabled by default). | | `FF_ENABLE_PLACEHOLDERS` | Feature flag for rewrites (enabled by default). See [Rewrites](../../user/project/pages/redirects.md#rewrites) for more information. | | `use_legacy_storage` | Temporarily-introduced parameter allowing to use legacy domain configuration source and storage. [Removed in 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166). | | `rate_limit_source_ip` | Rate limit per source IP in number of requests per second. Set to `0` to disable this feature. | @@ -406,9 +545,8 @@ domain as a custom domain to their project. If your user base is private or otherwise trusted, you can disable the verification requirement: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. Clear the **Require users to prove ownership of custom domains** checkbox. This setting is enabled by default. @@ -424,9 +562,8 @@ sites served under a custom domain. To enable it: 1. Choose an email address on which you want to receive notifications about expiring domains. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. Enter the email address for receiving notifications and accept Let's Encrypt's Terms of Service. 1. Select **Save changes**. @@ -478,9 +615,8 @@ pre-existing applications must modify the GitLab Pages OAuth application. Follow this: 1. Enable [access control](#access-control). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Applications**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Applications**. 1. Expand **GitLab Pages**. 1. Clear the `api` scope's checkbox and select the desired scope's checkbox (for example, `read_api`). @@ -498,13 +634,15 @@ This can be helpful to restrict information published with Pages websites to the of your instance only. To do that: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. Select the **Disable public access to Pages sites** checkbox. 1. Select **Save changes**. +NOTE: +You must enable [Access Control](#access-control) first for the setting to show in the Admin Area. + ### Running behind a proxy Like the rest of GitLab, Pages can be used in those environments where external @@ -683,57 +821,56 @@ Follow the steps below to configure the proxy listener of GitLab Pages. ## Set global maximum size of each GitLab Pages site **(FREE SELF)** -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To set the global maximum pages size for a project: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. In **Maximum size of pages**, enter a value. The default is `100`. 1. Select **Save changes**. ## Set maximum size of each GitLab Pages site in a group **(PREMIUM SELF)** -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To set the maximum size of each GitLab Pages site in a group, overriding the inherited setting: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Pages**. 1. Enter a value under **Maximum size** in MB. 1. Select **Save changes**. ## Set maximum size of GitLab Pages site in a project **(PREMIUM SELF)** -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To set the maximum size of GitLab Pages site in a project, overriding the inherited setting: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. In **Maximum size of pages**, enter the size in MB. 1. Select **Save changes**. ## Set maximum number of GitLab Pages custom domains for a project -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To set the maximum number of GitLab Pages custom domains for a project: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**, and expand **Pages**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. +1. Expand **Pages**. 1. Enter a value for **Maximum number of custom domains per project**. Use `0` for unlimited domains. 1. Select **Save changes**. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index fcbc04ed0c3..4e88d4aa4f3 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages administration for self-compiled installations **(FREE SELF)** @@ -479,9 +479,8 @@ The default for the maximum size of unpacked archives per project is 100 MB. To change this value: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Pages**. 1. Update the value for **Maximum size of pages (MB)**. diff --git a/doc/administration/pages/troubleshooting.md b/doc/administration/pages/troubleshooting.md index be5b8ba27ee..7a93c8a0f76 100644 --- a/doc/administration/pages/troubleshooting.md +++ b/doc/administration/pages/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting GitLab Pages administration **(FREE SELF)** @@ -170,9 +170,8 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Applications > GitLab Pages**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Applications > GitLab Pages**. 1. Edit the application. 1. Under **Scopes**, ensure that the `api` scope is selected. 1. Save your changes. @@ -184,7 +183,7 @@ this setting needs to be configured on the main GitLab server. If the wildcard DNS [prerequisite](index.md#prerequisites) can't be met, you can still use GitLab Pages in a limited fashion: -1. [Move](../../user/project/settings/index.md#transfer-a-project-to-another-namespace) +1. [Move](../../user/project/settings/migrate_projects.md#transfer-a-project-to-another-namespace) all projects you need to use Pages with into a single group namespace, for example `pages`. 1. Configure a [DNS entry](index.md#dns-configuration) without the `*.`-wildcard, for example `pages.example.io`. 1. Configure `pages_external_url http://example.io/` in your `gitlab.rb` file. @@ -214,8 +213,7 @@ You may see this error if `pages_external_url` was updated at some point of time 1. Check the [System OAuth application](../../integration/oauth_provider.md#create-an-instance-wide-application): - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Applications** and then **Add new application**. 1. Ensure the **Callback URL/Redirect URI** is using the protocol (HTTP or HTTPS) that `pages_external_url` is configured to use. diff --git a/doc/administration/polling.md b/doc/administration/polling.md index b27613663da..5edba91165f 100644 --- a/doc/administration/polling.md +++ b/doc/administration/polling.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Polling interval multiplier **(FREE SELF)** @@ -26,9 +26,8 @@ The default value (`1`) is recommended for the majority of GitLab installations. To adjust the polling interval multiplier: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **Polling interval multiplier**. 1. Set a value for the polling interval multiplier. This multiplier is applied to all resources at once. diff --git a/doc/administration/postgresql/database_load_balancing.md b/doc/administration/postgresql/database_load_balancing.md index d640dbe9341..7ef4e2cbcd2 100644 --- a/doc/administration/postgresql/database_load_balancing.md +++ b/doc/administration/postgresql/database_load_balancing.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database Load Balancing **(FREE SELF)** diff --git a/doc/administration/postgresql/external.md b/doc/administration/postgresql/external.md index b9bfda80b83..5b425075b9e 100644 --- a/doc/administration/postgresql/external.md +++ b/doc/administration/postgresql/external.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure GitLab using an external PostgreSQL service **(FREE SELF)** @@ -51,6 +51,12 @@ If you use a cloud-managed service, or provide your own PostgreSQL instance: sudo gitlab-ctl reconfigure ``` +1. Restart PostgreSQL to enable the TCP port: + + ```shell + sudo gitlab-ctl restart + ``` + ## Troubleshooting ### Resolve `SSL SYSCALL error: EOF detected` error diff --git a/doc/administration/postgresql/external_metrics.md b/doc/administration/postgresql/external_metrics.md index fc4c5652a18..8b849bc4e71 100644 --- a/doc/administration/postgresql/external_metrics.md +++ b/doc/administration/postgresql/external_metrics.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring and logging setup for external databases diff --git a/doc/administration/postgresql/external_upgrade.md b/doc/administration/postgresql/external_upgrade.md index 3e2c3b09853..97e1c5e2cb9 100644 --- a/doc/administration/postgresql/external_upgrade.md +++ b/doc/administration/postgresql/external_upgrade.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading external PostgreSQL databases diff --git a/doc/administration/postgresql/index.md b/doc/administration/postgresql/index.md index 4d73ba49846..07de9bcdcf1 100644 --- a/doc/administration/postgresql/index.md +++ b/doc/administration/postgresql/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring PostgreSQL for scaling **(FREE SELF)** diff --git a/doc/administration/postgresql/moving.md b/doc/administration/postgresql/moving.md index 7c18297a175..f1d6ffb29f6 100644 --- a/doc/administration/postgresql/moving.md +++ b/doc/administration/postgresql/moving.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moving GitLab databases to a different PostgreSQL instance **(FREE SELF)** diff --git a/doc/administration/postgresql/multiple_databases.md b/doc/administration/postgresql/multiple_databases.md index 80f2f369428..2caa4f147c4 100644 --- a/doc/administration/postgresql/multiple_databases.md +++ b/doc/administration/postgresql/multiple_databases.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple Databases **(FREE SELF)** diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index 7e46933113b..6bda0522b54 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Working with the bundled PgBouncer service **(FREE SELF)** diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 8403177952a..f4ed9d99b45 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL replication and failover for Linux package installations **(PREMIUM SELF)** @@ -275,7 +275,7 @@ gitlab_rails['auto_migrate'] = false consul['services'] = %w(postgresql) # START user configuration -# Please set the real values as explained in Required Information section +# Set the real values as explained in Required Information section # # Replace PGBOUNCER_PASSWORD_HASH with a generated md5 value postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH' @@ -427,7 +427,7 @@ authentication mode (`patroni['tls_client_mode']`), must each have the same valu consul['watchers'] = %w(postgresql) # START user configuration - # Please set the real values as explained in Required Information section + # Set the real values as explained in Required Information section # Replace CONSUL_PASSWORD_HASH with with a generated md5 value # Replace PGBOUNCER_PASSWORD_HASH with with a generated md5 value pgbouncer['users'] = { @@ -898,6 +898,12 @@ Stopping or restarting the Patroni service on the leader node triggers an automa ### Manual failover procedure for Patroni +WARNING: +In GitLab 16.5 and earlier, PgBouncer nodes do not automatically fail over alongside +Patroni nodes. PgBouncer services +[must be restarted manually](#pgbouncer-errors-error-running-command-gitlabctlerrorsexecutionerror-and-error-database-gitlabhq_production-is-not-paused) +for a successful switchover. + While Patroni supports automatic failover, you also have the ability to perform a manual one, where you have two slightly different options: @@ -920,7 +926,7 @@ For further details on this subject, see the #### Geo secondary site considerations -When a Geo secondary site is replicating from a primary site that uses `Patroni` and `PgBouncer`, [replicating through PgBouncer is not supported](https://github.com/pgbouncer/pgbouncer/issues/382#issuecomment-517911529). The secondary *must* replicate directly from the leader node in the `Patroni` cluster. When there is an automatic or manual failover in the `Patroni` cluster, you can manually re-point your secondary site to replicate from the new leader with: +When a Geo secondary site is replicating from a primary site that uses `Patroni` and `PgBouncer`, [replicating through PgBouncer is not supported](https://github.com/pgbouncer/pgbouncer/issues/382#issuecomment-517911529). The secondary _must_ replicate directly from the leader node in the `Patroni` cluster. When there is an automatic or manual failover in the `Patroni` cluster, you can manually re-point your secondary site to replicate from the new leader with: ```shell sudo gitlab-ctl replicate-geo-database --host=<new_leader_ip> --replication-slot=<slot_name> @@ -957,7 +963,7 @@ For further details, see [Patroni documentation on this subject](https://patroni ### Switching from repmgr to Patroni WARNING: -Switching from repmgr to Patroni is straightforward, the other way around is *not*. Rolling back from Patroni to repmgr can be complicated and may involve deletion of data directory. If you need to do that, contact GitLab support. +Switching from repmgr to Patroni is straightforward, the other way around is _not_. Rolling back from Patroni to repmgr can be complicated and may involve deletion of data directory. If you need to do that, contact GitLab support. You can switch an exiting database cluster to use Patroni instead of repmgr with the following steps: @@ -1011,7 +1017,7 @@ Here are a few key facts that you must consider before upgrading PostgreSQL: GitLab deployment is down for the duration of database upgrade or, at least, as long as your leader node is upgraded. This can be **a significant downtime depending on the size of your database**. -- Upgrading PostgreSQL creates a new data directory with a new control data. From the perspective of Petroni, this is a new cluster that needs to be bootstrapped again. Therefore, as part of the upgrade procedure, the cluster state (stored in Consul) is wiped out. After the upgrade is complete, Patroni bootstraps a new cluster. **This changes your _cluster ID_**. +- Upgrading PostgreSQL creates a new data directory with a new control data. From the perspective of Patroni, this is a new cluster that needs to be bootstrapped again. Therefore, as part of the upgrade procedure, the cluster state (stored in Consul) is wiped out. After the upgrade is complete, Patroni bootstraps a new cluster. **This changes your _cluster ID_**. - The procedures for upgrading leader and replicas are not the same. That is why it is important to use the right procedure on each node. @@ -1309,6 +1315,27 @@ postgresql['trust_auth_cidr_addresses'] = %w(123.123.123.123/32 <other_cidrs>) [Reconfigure GitLab](../restart_gitlab.md#reconfigure-a-linux-package-installation) for the changes to take effect. +### PgBouncer errors `Error running command: GitlabCtl::Errors::ExecutionError` and `ERROR: database gitlabhq_production is not paused` + +Due to a [known issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/8166) that +affects versions of GitLab prior to 16.5.0, the automatic failover of PgBouncer nodes does not +happen after a [Patroni switchover](#manual-failover-procedure-for-patroni). In this +example, GitLab failed to detect a paused database, then attempted to `RESUME` a +not-paused database: + +```plaintext +INFO -- : Running: gitlab-ctl pgb-notify --pg-database gitlabhq_production --newhost database7.example.com --user pgbouncer --hostuser gitlab-consul +ERROR -- : STDERR: Error running command: GitlabCtl::Errors::ExecutionError +ERROR -- : STDERR: ERROR: ERROR: database gitlabhq_production is not paused +``` + +To ensure a [Patroni switchover](#manual-failover-procedure-for-patroni) succeeds, +you must manually restart the PgBouncer service on all PgBouncer nodes with this command: + +```shell +gitlab-ctl restart pgbouncer +``` + ### Reinitialize a replica If a replica cannot start or rejoin the cluster, or when it lags behind and cannot catch up, it might be necessary to reinitialize the replica: diff --git a/doc/administration/postgresql/standalone.md b/doc/administration/postgresql/standalone.md index d6f3460e255..b609400e91d 100644 --- a/doc/administration/postgresql/standalone.md +++ b/doc/administration/postgresql/standalone.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Standalone PostgreSQL for Linux package installations **(FREE SELF)** diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index ec28b6bee67..207dbc7b509 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrity check Rake task **(FREE SELF)** diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md index a4b14b132db..f0cbd66c719 100644 --- a/doc/administration/raketasks/geo.md +++ b/doc/administration/raketasks/geo.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments remove_date: '2024-02-06' redirect_to: '../../update/deprecations.md#geo-housekeeping-rake-tasks' --- diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index a4d52899f21..3b9b7bdfa7a 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitHub import Rake task (deprecated) **(FREE SELF)** @@ -25,7 +25,7 @@ before/after the brackets. Also, some shells (for example, Zsh) can interpret th You can only import repositories that are in the namespace of the owner of the GitHub personal access token being used to import. For more information, see [issue 424105](https://gitlab.com/gitlab-org/gitlab/-/issues/424105). -Prerequisite: +Prerequisites: - At least the Maintainer role on the destination group to import to. diff --git a/doc/administration/raketasks/incoming_email.md b/doc/administration/raketasks/incoming_email.md index 6b9c27ed144..abd5f0e0a4d 100644 --- a/doc/administration/raketasks/incoming_email.md +++ b/doc/administration/raketasks/incoming_email.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incoming email Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index d8909440ceb..0db18ca6460 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # LDAP Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 724dcc2046a..3a136e773d9 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maintenance Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md index ba2a135cb01..95db4544f43 100644 --- a/doc/administration/raketasks/praefect.md +++ b/doc/administration/raketasks/praefect.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Praefect Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 36013803999..001d8ec6f1d 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project import and export Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/service_desk_email.md b/doc/administration/raketasks/service_desk_email.md index 21b4050a93b..9e18d2fe6c8 100644 --- a/doc/administration/raketasks/service_desk_email.md +++ b/doc/administration/raketasks/service_desk_email.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Desk email Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/smtp.md b/doc/administration/raketasks/smtp.md index 3cb161345cb..46df6b7a720 100644 --- a/doc/administration/raketasks/smtp.md +++ b/doc/administration/raketasks/smtp.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SMTP Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index a1826d3e5df..d5f998e35db 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads migrate Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index f86b4406a9e..225e65fae76 100644 --- a/doc/administration/raketasks/uploads/sanitize.md +++ b/doc/administration/raketasks/uploads/sanitize.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads sanitize Rake tasks **(FREE SELF)** diff --git a/doc/administration/read_only_gitlab.md b/doc/administration/read_only_gitlab.md index adc6f42271c..f70e1379958 100644 --- a/doc/administration/read_only_gitlab.md +++ b/doc/administration/read_only_gitlab.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Place GitLab into a read-only state **(FREE SELF)** diff --git a/doc/administration/redis/index.md b/doc/administration/redis/index.md index ad5aca37830..1ba51c588fe 100644 --- a/doc/administration/redis/index.md +++ b/doc/administration/redis/index.md @@ -1,8 +1,7 @@ --- -type: index stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring Redis for scaling **(FREE SELF)** diff --git a/doc/administration/redis/replication_and_failover.md b/doc/administration/redis/replication_and_failover.md index 82b9a33d2c6..b33db6ce957 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -1,8 +1,7 @@ --- -type: howto stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis replication and failover with the Linux package **(PREMIUM SELF)** diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index cfe5a3157d9..48a5fa8e20f 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -1,8 +1,7 @@ --- -type: howto stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis replication and failover providing your own instance **(FREE SELF)** diff --git a/doc/administration/redis/standalone.md b/doc/administration/redis/standalone.md index b9d00b92f95..9b66d3a81af 100644 --- a/doc/administration/redis/standalone.md +++ b/doc/administration/redis/standalone.md @@ -1,8 +1,7 @@ --- -type: howto stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Standalone Redis using the Linux package **(FREE SELF)** diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md index 5f0be709d78..0dcb19c1999 100644 --- a/doc/administration/redis/troubleshooting.md +++ b/doc/administration/redis/troubleshooting.md @@ -1,8 +1,7 @@ --- -type: reference stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Redis **(FREE SELF)** @@ -78,6 +77,11 @@ repl_backlog_first_byte_offset:0 repl_backlog_histlen:0 ``` +## High CPU usage on Redis instance + +High CPU usage on Redis instance can be cause by Sidekiq `BRPOP` calls. The `BRPOP` command is expensive and increases CPU usage on Redis. +Increase the [`SIDEKIQ_SEMI_RELIABLE_FETCH_TIMEOUT` environment variable](../environment_variables.md) to improve CPU usage on Redis. + ## Troubleshooting Sentinel If you get an error like: `Redis::CannotConnectError: No sentinels available.`, diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 2203f4b3a02..defc74b7e9e 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 10,000 users **(PREMIUM SELF)** @@ -168,6 +168,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 10,000 users: @@ -234,16 +236,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. +traffic to the application servers. + +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 362da0bd7c6..1296111a974 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 1,000 users **(FREE SELF)** diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index a5d44edf877..6520f63957b 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 25,000 users **(PREMIUM SELF)** @@ -168,6 +168,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 25,000 users: @@ -236,25 +238,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. - -The next question is how you will handle SSL in your environment. -There are several different options: +traffic to the application servers. -- [The application node terminates SSL](#application-node-terminates-ssl). -- [The load balancer terminates SSL without backend SSL](#load-balancer-terminates-ssl-without-backend-ssl) - and communication is not secure between the load balancer and the application node. -- [The load balancer terminates SSL with backend SSL](#load-balancer-terminates-ssl-with-backend-ssl) - and communication is *secure* between the load balancer and the application node. +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index fb8b9d8de45..d3f53ce3e14 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 2,000 users **(FREE SELF)** @@ -101,6 +101,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 2,000 users: @@ -124,25 +126,12 @@ To set up GitLab and its components to accommodate up to 2,000 users: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. +traffic to the application servers. -The next question is how you will handle SSL in your environment. There are -several different options: - -- [The application node terminates SSL](#application-node-terminates-ssl). -- [The load balancer terminates SSL without backend SSL](#load-balancer-terminates-ssl-without-backend-ssl) - and communication is not secure between the load balancer and the application node. -- [The load balancer terminates SSL with backend SSL](#load-balancer-terminates-ssl-with-backend-ssl) - and communication is *secure* between the load balancer and the application node. +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 73b0291ab95..c01564a3e7a 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 3,000 users **(PREMIUM SELF)** @@ -163,6 +163,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 3,000 users: @@ -224,25 +226,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. - -The next question is how you will handle SSL in your environment. -There are several different options: +traffic to the application servers. -- [The application node terminates SSL](#application-node-terminates-ssl). -- [The load balancer terminates SSL without backend SSL](#load-balancer-terminates-ssl-without-backend-ssl) - and communication is not secure between the load balancer and the application node. -- [The load balancer terminates SSL with backend SSL](#load-balancer-terminates-ssl-with-backend-ssl) - and communication is *secure* between the load balancer and the application node. +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm @@ -441,7 +430,8 @@ topology with a [Redis Sentinel](https://redis.io/docs/manual/sentinel/) service start the failover procedure. NOTE: -Redis clusters must each be deployed in an odd number of 3 nodes or more. This is to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, such as a cloud provider service. +Multi-node Redis must be deployed in an odd number of 3 nodes or more to ensure Redis Sentinel can take votes as part of a quorum. This does not apply when configuring Redis externally, +such as a cloud provider service. Redis requires authentication if used with Sentinel. See [Redis Security](https://redis.io/docs/manual/security/) documentation for more @@ -463,7 +453,7 @@ to be used with GitLab. The following IPs will be used as an example: You can optionally use a [third party external service for the Redis instance](../redis/replication_and_failover_external.md#redis-as-a-managed-service-in-a-cloud-provider) with the following guidance: - A reputable provider or solution should be used for this. [Google Memorystore](https://cloud.google.com/memorystore/docs/redis/redis-overview) and [AWS ElastiCache](https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/WhatIs.html) are known to work. -- Redis Cluster mode is specifically not supported, but Redis Standalone with HA is. +- Redis Cluster mode is specifically not supported, but Redis Standalone with HA (Redis Sentinel) **is** supported. For more information, see [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services). diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index ca39468a76e..92421a35273 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 50,000 users **(PREMIUM SELF)** @@ -168,6 +168,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 50,000 users: @@ -243,16 +245,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. +traffic to the application servers. + +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index e908565e27e..16a92944984 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 5,000 users **(PREMIUM SELF)** @@ -163,6 +163,8 @@ If this applies to you, we strongly recommended referring to the linked document Testing is done regularly via our [GitLab Performance Tool (GPT)](https://gitlab.com/gitlab-org/quality/performance) and its dataset, which is available for anyone to use. The results of this testing are [available publicly on the GPT wiki](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest). For more information on our testing strategy [refer to this section of the documentation](index.md#validation-and-test-results). +The load balancers used for testing were HAProxy for Linux package environments or equivalent Cloud Provider services via NGINX Ingress for Cloud Native Hybrids. Note that these selections do not represent a specific requirement or recommendation as most [reputable load balancers are expected to work](#configure-the-external-load-balancer). + ## Setup components To set up GitLab and its components to accommodate up to 5,000 users: @@ -224,25 +226,12 @@ The following list includes descriptions of each server and its assigned IP: ## Configure the external load balancer In a multi-node GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or its exact configuration is beyond the scope of GitLab documentation. We assume -that if you're managing multi-node systems like GitLab, you already have a load -balancer of choice. Some load balancer examples include HAProxy (open-source), -F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and -protocols needed for use with GitLab. - -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) -as the load balancer. Although other load balancers with similar feature sets -could also be used, those load balancers have not been validated. - -The next question is how you handle SSL in your environment. -There are several different options: +traffic to the application servers. -- [The application node terminates SSL](#application-node-terminates-ssl). -- [The load balancer terminates SSL without backend SSL](#load-balancer-terminates-ssl-without-backend-ssl) - and communication is not secure between the load balancer and the application node. -- [The load balancer terminates SSL with backend SSL](#load-balancer-terminates-ssl-with-backend-ssl) - and communication is *secure* between the load balancer and the application node. +The specifics on which load balancer to use, or its exact configuration +is beyond the scope of GitLab documentation. It is expected however that any +reputable load balancer should work and as such this section will focus on the specifics of +what to configure for your load balancer of choice. ### Balancing algorithm diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index fcbfaf46009..c4827695716 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -1,8 +1,7 @@ --- -type: reference, concepts stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architectures **(FREE SELF)** @@ -19,7 +18,7 @@ the _total_ load that comes with such a user count based on real data along with However, it should be noted that in some cases, known heavy scenarios such as [large monorepos](#large-monorepos) or notable [additional workloads](#additional-workloads) may require adjustments to be made. -For each Reference Architecture, the details of what they have been tested against can be found respectively in the "Testing Methodology" section of each page. +For details about what each Reference Architecture has been tested against, see the "Testing Methodology" section of each page. ### GitLab package (Omnibus) @@ -73,7 +72,7 @@ load of what each architecture has been tested against under the "Testing Method comparing those values with what load you are expecting against your existing GitLab environment to help select the right Reference Architecture size. -Load is given in terms of Requests per Section (RPS) for each endpoint type (API, Web, Git). This information on your existing infrastructure +Load is given in terms of Requests per Second (RPS) for each endpoint type (API, Web, Git). This information on your existing infrastructure can typically be surfaced by most reputable monitoring solutions or in some other ways such as load balancer metrics. For example, on existing GitLab environments, [Prometheus metrics](../monitoring/prometheus/gitlab_metrics.md) such as `gitlab_transaction_duration_seconds` can be used to see this data. @@ -88,7 +87,7 @@ With standalone setups, especially single node environments, there are [various ### High Availability (HA) -High Availability ensures every component in the GitLab setup can handle failures through various mechanisms. However, to achieve this is complex and the environments required can be sizable. +High Availability ensures every component in the GitLab setup can handle failures through various mechanisms. However, to achieve this is complex, and the environments required can be sizable. For environments serving 3,000 or more users we generally recommend that a HA strategy is used as at this level outages have a bigger impact against more users. All the architectures in this range have HA built in by design for this reason. @@ -206,7 +205,7 @@ Before implementing a reference architecture, refer to the following requirement These reference architectures were built and tested on Google Cloud Platform (GCP) using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) -CPU platform as a lowest common denominator baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). +CPU platform as the lowest common denominator baseline ([Sysbench benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks)). Newer, similarly-sized CPUs are supported and may have improved performance as a result. ARM CPUs are supported for Linux package environments as well as for any [Cloud Provider services](#cloud-provider-services) where applicable. @@ -216,7 +215,7 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### Supported disk types -As a general guidance, most standard disk types are expected to work for GitLab, but be aware of the following specific call outs: +As a general guidance, most standard disk types are expected to work for GitLab, but be aware of the following specific call-outs: - [Gitaly](../gitaly/index.md#disk-requirements) requires at least 8,000 input/output operations per second (IOPS) for read operations, and 2,000 IOPS for write operations. - We don't recommend the use of any disk types that are "burstable" due to inconsistent performance. @@ -226,7 +225,7 @@ Outside the above standard, disk types are expected to work for GitLab and the c ### Supported infrastructure As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP, Azure) and -their services, or self managed (ESXi) that meet both: +their services, or self-managed (ESXi) that meet both: - The specifications detailed in each reference architecture. - Any requirements in this section. @@ -431,7 +430,7 @@ While we endeavour to try and have a good range of support for GitLab environmen [Running stateful components in Kubernetes, such as Gitaly Cluster, is not supported](https://docs.gitlab.com/charts/installation/#configure-the-helm-chart-to-use-external-stateful-data). -Gitaly Cluster is only supported on conventional virtual machines. Kubernetes enforces strict memory restrictions but Git memory usage is unpredictable, which +Gitaly Cluster is only supported on conventional virtual machines. Kubernetes enforces strict memory restrictions, but Git memory usage is unpredictable, which can cause sporadic OOM termination of Gitaly pods, leading to significant disruptions and potential data loss. For this reason and others, Gitaly is not tested or supported in Kubernetes. For more information, see [epic 6127](https://gitlab.com/groups/gitlab-org/-/epics/6127). @@ -709,6 +708,141 @@ scaling downwards. You should take an iterative approach when scaling downwards, ### Monitoring -There are numerous options available to monitor your infrastructure, as well as [GitLab itself](../monitoring/index.md), and you should refer to your chosen monitoring solution's documentation for more information. +There are numerous options available to monitor your infrastructure, as well as [GitLab itself](../monitoring/index.md), and you should refer to your selected monitoring solution's documentation for more information. Of note, the GitLab application is bundled with [Prometheus as well as various Prometheus compatible exporters](../monitoring/prometheus/index.md) that could be hooked into your solution. + +## Update history + +Below is a history of notable updates for the Reference Architectures (2021-01-01 onward, ascending order), which we aim to keep updated at least once per quarter. + +You can find a full history of changes [on the GitLab project](https://gitlab.com/gitlab-org/gitlab/-/merge_requests?scope=all&state=merged&label_name%5B%5D=Reference%20Architecture&label_name%5B%5D=documentation). + +**2023:** + +- [2023-12-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133457): Updated notes on Load Balancers to be more reflective that any reputable offering is expected to work. +- [2023-11-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133457): Expanded details on what each Reference Architecture is designed for, the testing methodology used as well as added details on how to scale environments. +- [2023-11-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134518): Added expanded notes on disk types, object storage and monitoring. +- [2023-10-25](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134518): Adjusted Sidekiq configuration example to use Linux Package role. +- [2023-10-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133835): Adjusted the Sidekiq recommendations to include a separate node for 2k and tweaks to instance type and counts for 3k and 5k. +- [2023-10-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132270): Added more expanded notes throughout to warn about the use of Large Monorepos and their impacts for increased awareness. +- [2023-10-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133258): Updated name of Task Runner pod to its new name of Toolbox. +- [2023-10-02](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132961): Expanded guidance on using an external service for Redis further, in particular for separated Cache and Persistent services with 10k and up. +- [2023-09-21](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132289): Expanded details on the challenges of running Gitaly in Kubernetes. +- [2023-09-20](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132275): Removed references to Grafana after deprecation and removal. +- [2023-08-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130470): Expanded section on Geo under the Decision Tree. +- [2023-08-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128529): Switch config example to use the Sidekiq role for Linux package. +- [2023-08-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128374): Fixed an AWS Machine type typo for the 50k architecture. +- [2023-11-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133457): Expand details on what each Reference Architecture is designed for, the testing methodology used as well as added details on how to scale environments. +- [2023-11-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134518): Add expanded notes on disk types, object storage and monitoring. +- [2023-10-25](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134518): Adjust Sidekiq configuration example to use Linux Package role. +- [2023-10-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133835): Adjust the Sidekiq recommendations to include a separate node for 2k and tweaks to instance type and counts for 3k and 5k. +- [2023-10-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132270): Add more expanded notes throughout to warn about the use of Large Monorepos and their impacts for increased awareness. +- [2023-10-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133258): Update name of Task Runner pod to its new name of Toolbox. +- [2023-10-02](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132961): Expand guidance on using an external service for Redis further, in particular for separated Cache and Persistent services with 10k and up. +- [2023-09-21](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132289): Expand details on the challenges of running Gitaly in Kubernetes. +- [2023-09-20](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132275): Remove references to Grafana after deprecation and removal. +- [2023-08-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130470): Expand section on Geo under the Decision Tree. +- [2023-08-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128529): Switch configuration example to use the Sidekiq role for Linux package. +- [2023-08-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128374): Fix an AWS Machine type typo for the 50k architecture. +- [2023-06-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125017): Update PostgreSQL configuration examples to remove a now unneeded setting to instead use the Linux package default. +- [2023-06-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125017): Add explicit example on main page that reflects Google Memorystore is recommended. +- [2023-06-11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122063): Fix IP examples for the 3k and 5k architectures. +- [2023-05-25](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121545): Expand notes on usage of external Cloud Provider Services and the recommendation of separated Redis servers for 10k environments and up. +- [2023-05-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119224): Update documentation to reflect correct requirement of Redis 6 instead of 5. +- [2023-04-28](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114877): Add a note that the Azure Active Directory authentication method is not supported for use with Azure PostgreSQL Flexible service. +- [2023-03-23](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114877): Add more details about known unsupported designs. +- [2023-03-16](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114872): Update Redis configuration examples for multi-node to have correct config to ensure all components can connect. +- [2023-03-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110784): Update Gitaly configuration examples to the new format. +- [2023-03-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114495): Update cost estimates to no longer include NFS VMs. +- [2023-02-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110379): Update Praefect configuration examples to the new format. +- [2023-02-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109798): Add examples of what automations may be considered additional workloads. +- [2023-02-13](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111018): Add a new 'Before you Start' section that gives more context about what's involved with running production software self-managed. Also added more details for Standalone setups and Cloud Provider services in the Decision Tree section. +- [2023-02-01](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110641): Switch to use more common "complex" terminology instead of less known "involved". +- [2023-01-31](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110328): Expand and centralize the requirements' section on the main page. +- [2023-01-26](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110183): Add notes on migrating Git Data from NFS, that object data is still supported on NFS and handling SSH keys correctly across multiple Rails nodes. + +**2022:** + +- [2022-12-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105451): Remove guidance for using NFS for Git data as support for this is now ended with `15.6` onwards. +- [2022-12-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106826): Add note to clarify difference between Amazon RDS Multi-AZ DB _cluster_ and _instance_, with the latter being supported. Also increase PostgreSQL max connections setting to new default of `500`. +- [2022-12-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106695): Update Sidekiq max concurrency configuration to match new default of `20`. +- [2022-11-16](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104236): Correct guidance for Praefect and Gitaly in reduced 3k architecture section that an odd number quorum is required. +- [2022-11-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103623): Add guidance on how to handle GitLab Secrets in Cloud Native Hybrids and further links to the GitLab Charts documentation. +- [2022-11-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103767): Fix a typo with Sidekiq configuration for the 10k architecture. +- [2022-11-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102746): Add guidance on large monorepos and additional workloads impact on performance. Also expanded Load Balancer guidance around SSL and a recommendation for least connection based routing methods. +- [2022-10-18](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100826): Adjust Object Storage guidance to make it clearer it's recommended over NFS. +- [2022-10-11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100305): Update guidance for Azure to recommend up to 2k only due to performance issues. +- [2022-09-27](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98204): Add Decision Tree section to help users better decide what architecture to use. +- [2022-09-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98263): Add explicit step to enable Incremental Logging when only Object Storage is being used. +- [2022-09-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98184): Expand guidance on recommended cloud providers and services. +- [2022-09-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97245): Expand Object Storage guidance and updated that NFS support for Git data ends with `15.6`. +- [2022-08-24](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96150): Add clearer note that Gitaly Cluster is not supported in Kubernetes. +- [2022-08-24](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96021): Add section on supported CPUs and types. +- [2022-08-18](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95713): Update architecture tables to be clearer for Object Storage support. +- [2022-08-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95185): Increase Cloud Native Hybrid pool specs for 2k architecture to ensure enough resources present for pods. Also increased Sidekiq worker count. +- [2022-08-02](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93493): Add note to use newer Gitaly check command from GitLab 15 and later. +- [2022-07-25](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93141): Move troubleshooting section to a more general location. +- [2022-07-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92144): Add guidance that Amazon Aurora is no longer compatible and not supported from GitLab 14.4.0 and later. +- [2022-07-07](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91943): Add call out not to remove the `default` section from Gitaly storages config as it's required. +- [2022-06-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86812): Move Incremental Logging guidance to separate section. +- [2022-04-29](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85856): Expand testing results' section with new regular pipelines. +- [2022-04-26](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85833): Update Praefect configuration to reflect setting name changes. +- [2022-04-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85231): Add missing setting to enable Object Storage correctly. +- [2022-04-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85107): Expand Cloud Native Hybrid guidance with AWS machine types. +- [2022-04-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84389): Add cost estimates for AWS and Azure. +- [2022-04-06](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84483): Update configuration examples for most components to be correctly included for Prometheus monitoring auto discovery. +- [2022-03-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81538): Expand validation and testing result's section with more clearly language and more detail. +- [2022-03-21](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83019): Add note that additional specs may be needed for Gitaly in some scenarios. +- [2022-03-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82087): Add guidance for preventing the GitLab KAS service running on nodes where not required. +- [2022-03-01](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81814): Fix a typo for Praefect TLS port in configuration examples. +- [2022-02-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81247): Add guidance to enable the Gitaly Pack-objects cache. +- [2022-02-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80892): Add a general section on recommended Cloud Providers and services. +- [2022-02-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80521): Link to blog post about GPT testing added. +- [2022-01-26](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78705): Merge testing process and cost estimates into one section with expanded details. +- [2022-01-13](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77968): Expand guidance on recommended Kubernetes platforms. + +**2021:** + +- [2021-12-31](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77437): Fix typo for 25k Redis AWS machine size. +- [2021-12-28](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77243): Add Cloud Provider breakdowns to testing process & results section. +- [2021-12-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77039): Add more detail to testing process and results section. +- [2021-12-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77002): Add note on Database Load Balancing requirements when using a modified 3k architecture. +- [2021-12-17](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76236): Add diagram for 1k architecture (single node). +- [2021-12-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76748): Add sections on estimated costs (GCP), testing process and results and further Cloud Provider service details. +- [2021-12-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76226): Expand external database service guidance for components and what Cloud Provider services are recommended. +- [2021-11-24](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74612): Add recommendations for Database Load Balancing. +- [2021-11-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73634): Add more detail about testing targets used for the architectures. +- [2021-10-13](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72052): Add guidance around optionally enabling Incremental Logging via Redis. +- [2021-10-07](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71784): Update Sidekiq config to include required `external_url` setting. +- [2021-10-02](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71576): Expand guidance around Gitaly Cluster and Gitaly Sharded. +- [2021-09-29](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70625): Add note on what Cloud Native Hybrid architecture to use with small user counts. +- [2021-09-27](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70602): Change guidance to now co-locate Redis Sentinel beside Redis on the same node. +- [2021-08-18](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67778): Add 2k Cloud Native Hybrid architecture. +- [2021-08-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67463): Add links to performance test results for each architecture. +- [2021-07-30](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67231): Fix the replication settings in PostgreSQL configuration examples to have correct values. +- [2021-07-22](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66185): Add 3k Cloud Native Hybrid architecture. +- [2021-07-16](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66278): Update architecture diagrams to correctly reflect no direct connection between Rails and Sidekiq. +- [2021-07-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65373): Update Patroni configuration to include Rest API authentication settings. +- [2021-07-15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65992): Add 5k Cloud Native Hybrid architecture. +- [2021-07-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65154): Add 25k Cloud Native Hybrid architecture. +- [2021-06-29](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64711): Add 50k Cloud Native Hybrid architecture. +- [2021-06-23](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64612): Make additions to main page for Cloud Native Hybrid and reduce 3k architecture. +- [2021-06-16](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63580): Update PostgreSQL steps and configuration to use the latest roles and prep for any Geo replication. +- [2021-06-14](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63857): Update configuration examples for Monitoring node to follow latest. +- [2021-06-11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62316): Expand notes on external services with more detail. +- [2021-06-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63504): Add additional guidance and expand on how to correctly manage GitLab secrets and database migrations. +- [2021-06-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63443): Update Praefect configuration examples to follow the new storages format. +- [2021-06-03](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61923): Removed references for the Unicorn webserver, which has been replaced by Puma. +- [2021-04-23](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59471): Update Sidekiq configuration examples to show how to correctly configure multiple workers on each node. +- [2021-04-23](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59283): Add initial guidance on how to modify the 3k Reference Architecture for lower user counts. +- [2021-04-13](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59259): Add further clarification on using external services (PostgreSQL, Redis). +- [2021-04-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59139): Add additional guidance on using Load Balancers and their routing methods. +- [2021-04-08](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58885): Add additional guidance on how to correctly configure only one node to do database migrations for Praefect. +- [2021-04-06](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57476): Expand 10k Cloud Native Hybrid documentation with more details and clear naming. +- [2021-03-04](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54454): Expand Gitaly Cluster documentation to all other applicable Reference Architecture sizes. +- [2021-02-19](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54244): Add additional Object Storage guidance of using separated buckets for different data types as per recommendations. +- [2021-02-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50852): Add documentation for setting up Object Storage with Rails and Sidekiq. +- [2021-02-12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51928): Add documentation for setting up Gitaly Cluster for the 10k Reference Architecture. +- [2021-02-09](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52249): Add the first iteration of the 10k Cloud Native Hybrid reference architecture. +- [2021-01-07](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50573): Add documentation for using Patroni as PostgreSQL replication manager. diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index b632108b103..d6c1f74fda8 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reply by email **(FREE SELF)** diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index ef6fd82a460..99cfbd59c49 100644 --- a/doc/administration/reply_by_email_postfix_setup.md +++ b/doc/administration/reply_by_email_postfix_setup.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up Postfix for incoming email **(FREE SELF)** diff --git a/doc/administration/reporting/git_abuse_rate_limit.md b/doc/administration/reporting/git_abuse_rate_limit.md index 7e2c340f20d..19818a818ac 100644 --- a/doc/administration/reporting/git_abuse_rate_limit.md +++ b/doc/administration/reporting/git_abuse_rate_limit.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git abuse rate limit (administration) **(ULTIMATE SELF)** @@ -21,8 +21,7 @@ GitLab team members can view more information in this confidential epic: ## Configure Git abuse rate limiting -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Reporting**. 1. Expand **Git abuse rate limit**. 1. Update the Git abuse rate limit settings: @@ -41,8 +40,7 @@ If automatic banning is enabled, an email notification is sent when a user is ab ## Unban a user -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Banned** tab and search for the account you want to unban. 1. From the **User administration** dropdown list select **Unban user**. diff --git a/doc/administration/reporting/ip_addr_restrictions.md b/doc/administration/reporting/ip_addr_restrictions.md index 2e152b0b176..434052344d8 100644 --- a/doc/administration/reporting/ip_addr_restrictions.md +++ b/doc/administration/reporting/ip_addr_restrictions.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # IP address restrictions **(FREE SELF)** @@ -19,8 +19,7 @@ unique IP addresses. Therefore, the IP addresses per user limit should take into ## Configure IP address restrictions -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. Update the IP address restrictions settings: diff --git a/doc/administration/reporting/spamcheck.md b/doc/administration/reporting/spamcheck.md index c92336a39b9..4ba36e33abb 100644 --- a/doc/administration/reporting/spamcheck.md +++ b/doc/administration/reporting/spamcheck.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Spamcheck anti-spam service **(FREE SELF)** @@ -40,8 +40,7 @@ Spamcheck is only available for package-based installations: ## Configure GitLab to use Spamcheck -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. Update the Spam Check settings: diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 241f88793ff..85a74199022 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository checks **(FREE SELF)** @@ -20,9 +20,8 @@ committed to a repository. GitLab administrators can: To check a project's repository using GitLab UI: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Projects**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Projects**. 1. Select the project to check. 1. In the **Repository check** section, select **Trigger repository check**. @@ -33,10 +32,9 @@ project page in the Admin Area. If the checks fail, see [what to do](#what-to-do Instead of checking repositories manually, GitLab can be configured to run the checks periodically: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`). -1. Expand the **Repository maintenance** section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. +1. Expand **Repository maintenance**. 1. Enable **Enable repository checks**. When enabled, GitLab periodically runs a repository check on all project repositories and wiki @@ -87,10 +85,9 @@ If a repository check fails, locate the error in the [`repocheck.log` file](logs If periodic repository checks cause false alarms, you can clear all repository check states: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`). -1. Expand the **Repository maintenance** section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. +1. Expand **Repository maintenance**. 1. Select **Clear all repository checks**. ## Troubleshooting diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index a3e0158fd24..efa719d103b 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository storage **(FREE SELF)** @@ -66,9 +66,8 @@ Administrators can look up a project's hashed path from its name or ID using: To look up a project's hash path in the Admin Area: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Projects** and select the project. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Projects** and select the project. 1. Locate the **Relative path** field. The value is similar to: ```plaintext @@ -180,7 +179,7 @@ Files stored in an S3-compatible endpoint can have the same advantages as #### Avatars Each file is stored in a directory that matches the `id` assigned to it in the database. The -filename is always `avatar.png` for user avatars. When an avatar is replaced, the `Upload` model is +file name is always `avatar.png` for user avatars. When an avatar is replaced, the `Upload` model is destroyed and a new one takes place with a different `id`. #### CI/CD artifacts @@ -205,10 +204,9 @@ LFS objects are also [S3-compatible](lfs/index.md#storing-lfs-objects-in-remote- After you configure multiple repository storages, you can choose where new repositories are stored: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository** and expand the **Repository storage** - section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. +1. Expand **Repository storage**. 1. Enter values in the **Storage nodes for new repositories** fields. 1. Select **Save changes**. diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index d0e4beccb3a..6cd9af0731a 100644 --- a/doc/administration/restart_gitlab.md +++ b/doc/administration/restart_gitlab.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to restart GitLab **(FREE SELF)** diff --git a/doc/administration/review_abuse_reports.md b/doc/administration/review_abuse_reports.md index 84bb7ab219f..86953f6d984 100644 --- a/doc/administration/review_abuse_reports.md +++ b/doc/administration/review_abuse_reports.md @@ -1,8 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review abuse reports **(FREE SELF)** @@ -16,8 +15,7 @@ reports in the Admin Area. To receive notifications of new abuse reports by email: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Reporting**. 1. Expand the **Abuse reports** section. 1. Provide an email address and select **Save changes**. @@ -36,8 +34,7 @@ To find out more about reporting abuse, see To access abuse reports: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Abuse Reports**. There are four ways to resolve an abuse report, with a button for each method: diff --git a/doc/administration/review_spam_logs.md b/doc/administration/review_spam_logs.md index e3b96cdae95..67f6080b3bc 100644 --- a/doc/administration/review_spam_logs.md +++ b/doc/administration/review_spam_logs.md @@ -1,8 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review spam logs **(FREE SELF)** @@ -19,8 +18,7 @@ View and resolve spam logs to moderate user activity in your instance. To view spam logs: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Spam Logs**. 1. Optional. To resolve a spam log, select a log and then select **Remove user**, **Block user**, **Remove log**, or **Trust user**. diff --git a/doc/administration/secure_files.md b/doc/administration/secure_files.md index 6c61c390655..d3dfe4fdf4c 100644 --- a/doc/administration/secure_files.md +++ b/doc/administration/secure_files.md @@ -1,7 +1,7 @@ --- stage: Mobile group: Mobile DevOps -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure Files administration **(FREE SELF)** @@ -30,7 +30,7 @@ Secure Files to reduce disk space, or to remove access to the feature. To disable Secure Files, follow the steps below according to your installation. -Prerequisite: +Prerequisites: - You must be an administrator. diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 4d8377b4117..562c8547d90 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git server hooks **(FREE SELF)** @@ -18,8 +18,13 @@ on the GitLab server. You can use them to run Git-related tasks such as: Git server hooks use `pre-receive`, `post-receive`, and `update` [Git server-side hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_server_side_hooks). -GitLab administrators configure server hooks on the file system of the GitLab server. If you don't have file system access, -alternatives to server hooks include: +GitLab administrators configure server hooks using the `gitaly` command, which also: + +- Is used to launch a Gitaly server. +- Provides several subcommands. +- Connects to the Gitaly gRPC API. + +If you don't have access to the `gitaly` command, alternatives to server hooks include: - [Webhooks](../user/project/integrations/webhooks.md). - [GitLab CI/CD](../ci/index.md). @@ -49,7 +54,7 @@ To set server hooks for a repository: example, if the script is in Ruby the shebang is probably `#!/usr/bin/env ruby`. - To create a single server hook, create a file with a name that matches the hook type. For example, for a - `pre-receive` server hook, the filename should be `pre-receive` with no extension. + `pre-receive` server hook, the file name should be `pre-receive` with no extension. - To create many server hooks, create a directory for the hooks that matches the hook type. For example, for a `pre-receive` server hook, the directory name should be `pre-receive.d`. Put the files for the hook in that directory. @@ -71,8 +76,7 @@ If you implemented the server hook code correctly, it should execute when the Gi To create server hooks for a repository: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Go to **Overview > Projects** and select the project you want to add a server hook to. 1. On the page that appears, locate the value of **Relative path**. This path is where server hooks must be located. @@ -85,7 +89,7 @@ To create server hooks for a repository: 1. On the file system, create a new directory in the correct location called `custom_hooks`. 1. In the new `custom_hooks` directory: - To create a single server hook, create a file with a name that matches the hook type. For example, for a - `pre-receive` server hook, the filename should be `pre-receive` with no extension. + `pre-receive` server hook, the file name should be `pre-receive` with no extension. - To create many server hooks, create a directory for the hooks that matches the hook type. For example, for a `pre-receive` server hook, the directory name should be `pre-receive.d`. Put the files for the hook in that directory. 1. **Make the server hook files executable** and ensure that they are owned by the Git user. @@ -156,7 +160,7 @@ To create a global server hook for all repositories: 1. Make the hook file executable, ensure that it's owned by the Git user, and ensure it does not match the backup file pattern (`*~`). -If the server hook code is properly implemented, it should execute when the Git hook is next triggered. Hooks are executed in alphabetical order by filename in the hook type +If the server hook code is properly implemented, it should execute when the Git hook is next triggered. Hooks are executed in alphabetical order by file name in the hook type subdirectories. ## Remove server hooks for a repository diff --git a/doc/administration/settings/account_and_limit_settings.md b/doc/administration/settings/account_and_limit_settings.md index b33ceb2c4e5..d8e2ca38627 100644 --- a/doc/administration/settings/account_and_limit_settings.md +++ b/doc/administration/settings/account_and_limit_settings.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Account and limit settings **(FREE SELF)** @@ -16,8 +15,7 @@ the [project limits for existing users](#projects-limit-for-a-user). To configure the maximum number of projects in personal namespaces for new users: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Increase or decrease that **Default projects limit** value. @@ -30,8 +28,7 @@ in their users personal namespace. However, projects can still be created in a g You can edit a specific user, and change the maximum number of projects this user can create in their personal namespace: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview** > **Users**. 1. From the list of users, select a user. 1. Select **Edit**. @@ -44,8 +41,7 @@ can create in their personal namespace: The maximum file size for attachments in GitLab comments and replies is 100 MB. To change the maximum attachment size: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum attachment size (MiB)**. @@ -60,8 +56,7 @@ For GitLab.com repository size limits, read [accounts and limit settings](../../ You can change the maximum push size for your instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum push size (MiB)**. @@ -92,8 +87,7 @@ The default prefix is `glpat-` but administrators can change it. To change the default global prefix: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Personal Access Token prefix** field. @@ -139,8 +133,7 @@ These settings can be found in: 1. Fill in the **Repository size limit (MiB)** field in the **Naming, visibility** section. 1. Select **Save changes**. - GitLab global settings: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Size limit per repository (MiB)** field. @@ -162,8 +155,7 @@ For details on manually purging files, see [reducing the repository size using G You can change how long users can remain signed in without activity. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. The set duration is in **Session duration (minutes)**. @@ -177,8 +169,7 @@ For details, see [cookies used for sign-in](../../user/profile/index.md#cookies- Users can select the **Remember me** checkbox on sign-in, and their session will remain active for an indefinite period of time when accessed from that specific browser. You can turn off this setting if you need sessions to expire for security or compliance purposes. Turning off this setting will ensure users' sessions expire after the number of minutes of inactivity set when you [customize your session duration](#customize-the-default-session-duration). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Select or clear the **Remember me** checkbox to turn this setting on or off. @@ -195,8 +186,7 @@ GitLab administrators can choose to customize the session duration (in minutes) To set a limit on how long these sessions are valid: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. @@ -223,8 +213,7 @@ there are no restrictions. To set a lifetime on how long SSH keys are valid: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for SSH keys (days)** field. @@ -260,8 +249,7 @@ there are no restrictions. To set a lifetime on how long access tokens are valid: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for access tokens (days)** field. @@ -283,8 +271,7 @@ To maintain integrity of user details in [Audit Events](../../administration/aud To do this: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Select the **Prevent users from changing their profile name** checkbox. @@ -294,6 +281,20 @@ When this ability is disabled, GitLab administrators can still use the [Admin Area](../../administration/admin_area.md#administering-users) or the [API](../../api/users.md#user-modification) to update usernames. +## Prevent users from creating organizations **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423302) in GitLab 16.7 [with a flag](../feature_flags.md) named `ui_for_organizations`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../feature_flags.md) named `ui_for_organizations`. On GitLab.com, this feature is not available. This feature is not ready for production use. + +By default, users can create organizations. GitLab administrators can prevent users from creating organizations. + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Account and limit**. +1. Clear the **Allow users to create organizations** checkbox. + ## Prevent new users from creating top-level groups > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. @@ -305,8 +306,7 @@ By default, new users can create top-level groups. GitLab administrators can pre - The [application setting API](../../api/settings.md#change-application-settings). - In GitLab 15.4 and earlier, a [configuration file](../../administration/user_settings.md#use-configuration-files-to-prevent-new-users-from-creating-top-level-groups). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Clear the **Allow new users to create top-level groups** checkbox. @@ -317,8 +317,7 @@ By default, new users can create top-level groups. GitLab administrators can pre By default, newly created users have a public profile. GitLab administrators can set new users to have a private profile by default: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Select the **Make new users' profiles private by default** checkbox. @@ -330,8 +329,7 @@ By default, newly created users have a public profile. GitLab administrators can By default, users can delete their own accounts. GitLab administrators can prevent users from deleting their own accounts: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Clear the **Allows users to delete their own accounts** checkbox. diff --git a/doc/administration/settings/continuous_integration.md b/doc/administration/settings/continuous_integration.md index 0e2a512302d..8164c63b9b9 100644 --- a/doc/administration/settings/continuous_integration.md +++ b/doc/administration/settings/continuous_integration.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Continuous Integration and Deployment Admin Area settings **(FREE SELF)** @@ -15,8 +14,7 @@ job artifacts. To enable (or disable) [Auto DevOps](../../topics/autodevops/index.md) for all projects: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**. 1. Optionally, set up the [Auto DevOps base domain](../../topics/autodevops/requirements.md#auto-devops-base-domain) @@ -33,8 +31,7 @@ If you want to disable it for a specific project, you can do so in You can set all new projects to have the instance's shared runners available by default. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Select the **Enable shared runners for new projects** checkbox. @@ -53,8 +50,7 @@ you can assign that runner to other projects. To enable a project runner for more than one project: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. From the left sidebar, select **CI/CD > Runners**. 1. Select the runner you want to edit. 1. In the upper-right corner, select **Edit** (**{pencil}**). @@ -67,8 +63,7 @@ To enable a project runner for more than one project: To display details about the instance's shared runners in all projects' runner settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Enter text, including Markdown if you want, in the **Shared runner details** field. For example: @@ -97,8 +92,7 @@ The value is in MB, and the default is 100 MB per job. An administrator can chan - Instance level: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > CI/CD > Continuous Integration and Deployment**. 1. Change the value of **Maximum artifacts size (MB)**. 1. Select **Save changes** for the changes to take effect. @@ -112,7 +106,7 @@ The value is in MB, and the default is 100 MB per job. An administrator can chan - Project level (this overrides the instance and group settings): 1. Go to the project's **Settings > CI/CD > General Pipelines**. - 1. Change the value of **maximum artifacts size** (in MB). + 1. Change the value of **Maximum artifacts size** (in MB). 1. Select **Save changes** for the changes to take effect. ## Default artifacts expiration @@ -122,8 +116,7 @@ can be set in the Admin Area of your GitLab instance. The syntax of duration is described in [`artifacts:expire_in`](../../ci/yaml/index.md#artifactsexpire_in) and the default value is `30 days`. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Change the value of default expiration time. 1. Select **Save changes** for the changes to take effect. @@ -154,8 +147,7 @@ If disabled at the instance level, you cannot enable this per-project. To disable the setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. @@ -178,8 +170,7 @@ blueprint for more details. To set the duration for which the jobs are considered as old and expired: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. Set the value of **Archive jobs**. @@ -196,8 +187,7 @@ For the value set for GitLab.com, see [Scheduled job archiving](../../user/gitla To set all new [CI/CD variables](../../ci/variables/index.md) as [protected](../../ci/variables/index.md#protect-a-cicd-variable) by default: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Select **Protect CI/CD variables by default**. @@ -208,8 +198,7 @@ To set all new [CI/CD variables](../../ci/variables/index.md) as The maximum number of [includes](../../ci/yaml/includes.md) per pipeline can be set at the instance level. The default is `150`. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Change the value of **Maximum includes**. 1. Select **Save changes** for the changes to take effect. @@ -221,8 +210,7 @@ The default is `150`. The default CI/CD configuration file and path for new projects can be set in the Admin Area of your GitLab instance (`.gitlab-ci.yml` if not set): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Input the new file and path in the **Default CI/CD configuration file** field. 1. Select **Save changes** for the changes to take effect. @@ -237,8 +225,7 @@ It is also possible to specify a [custom CI/CD configuration file for a specific You can configure some [CI/CD limits](../../administration/instance_limits.md#cicd-limits) from the Admin Area: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. In the **CI/CD limits** section, you can set the following limits: @@ -260,8 +247,7 @@ walkthrough on how to add one. To enable or disable the banner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Select or clear the **Enable pipeline suggestion banner** checkbox. 1. Select **Save changes**. @@ -276,8 +262,7 @@ malicious user-generated content, as described in Self-managed administrators can disable the external redirect warning page, so you can view job artifact pages directly: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Deselect **Enable the external redirect page for job artifacts**. @@ -313,14 +298,13 @@ in the pipeline editor. To select a CI/CD template for the required pipeline configuration: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Required pipeline configuration** section. 1. Select a CI/CD template from the dropdown list. 1. Select **Save changes**. -## Package Registry configuration +## Package registry configuration ### Maven Forwarding **(PREMIUM SELF)** @@ -328,8 +312,7 @@ GitLab administrators can disable the forwarding of Maven requests to [Maven Cen To disable forwarding Maven requests: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward Maven package requests to the Maven Registry if the packages are not found in the GitLab Package Registry**. @@ -341,8 +324,7 @@ GitLab administrators can disable the forwarding of npm requests to [npmjs.com]( To disable it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward npm package requests to the npm Registry if the packages are not found in the GitLab Package Registry**. @@ -354,8 +336,7 @@ GitLab administrators can disable the forwarding of PyPI requests to [pypi.org]( To disable it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Clear the checkbox **Forward PyPI package requests to the PyPI Registry if the packages are not found in the GitLab Package Registry**. @@ -367,8 +348,7 @@ GitLab administrators can adjust the maximum allowed file size for each package To set the maximum file size: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Find the package type you would like to adjust. @@ -388,8 +368,7 @@ By default, all members of a project and group are able to register runners. To restrict all users in an instance from registering runners: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. In the **Runner registration** section, clear the **Members of the project can register runners** and @@ -411,8 +390,7 @@ GitLab administrators can adjust group permissions to restrict runner registrati To restrict runner registration by members in a specific group: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Groups** and find your group. 1. Select **Edit**. 1. Clear the **New group runners can be registered** checkbox if you want to disable runner registration by all members in the group. If the setting is read-only, you must enable runner registration for the [instance](#restrict-runner-registration-by-all-users-in-an-instance). @@ -426,8 +404,7 @@ By default, GitLab instances periodically fetch official runner version data fro To disable your instance fetching this data: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. 1. In the **Runner version management** section, clear the **Fetch GitLab Runner release version data from GitLab.com** checkbox. @@ -435,11 +412,16 @@ To disable your instance fetching this data: ## Troubleshooting -### 413 Request Entity Too Large +### `413 Request Entity Too Large` error -When build jobs fail with the following error, -increase the [maximum artifacts size](#maximum-artifacts-size). +If the artifacts are too large, the job might fail with the following error: ```plaintext Uploading artifacts as "archive" to coordinator... too large archive <job-id> responseStatus=413 Request Entity Too Large status=413" at end of a build job on pipeline when trying to store artifacts to <object-storage>. ``` + +You might need to: + +- Increase the [maximum artifacts size](#maximum-artifacts-size). +- If you are using NGINX as a proxy server, increase the file upload size limit which is limited to 1 MB by default. + Set a higher value for `client-max-body-size` in the NGINX configuration file. diff --git a/doc/administration/settings/deprecated_api_rate_limits.md b/doc/administration/settings/deprecated_api_rate_limits.md index 21385a6779d..2ef4d49ff0a 100644 --- a/doc/administration/settings/deprecated_api_rate_limits.md +++ b/doc/administration/settings/deprecated_api_rate_limits.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deprecated API rate limits **(FREE SELF)** @@ -28,14 +27,13 @@ the general user and IP rate limits for requests to deprecated endpoints. You ca and IP rate limits already in place, and increase or decrease the rate limits for deprecated API endpoints. No other new features are provided by this override. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To override the general user and IP rate limits for requests to deprecated API endpoints: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Deprecated API Rate Limits**. 1. Select the checkboxes for the types of rate limits you want to enable: diff --git a/doc/administration/settings/email.md b/doc/administration/settings/email.md index bcf4bab6fc5..cc80b082139 100644 --- a/doc/administration/settings/email.md +++ b/doc/administration/settings/email.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Email **(FREE SELF)** @@ -21,8 +20,7 @@ address in the body of the email instead. To include the author's email address in the email body: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Select the **Include author name in email notification email body** checkbox. @@ -34,8 +32,7 @@ GitLab can send email in multipart format (HTML and plain text) or plain text on To enable multipart email: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Select **Enable multipart email**. @@ -50,8 +47,7 @@ This configuration option sets the email hostname for [private commit emails](.. To change the hostname used in private commit emails: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field. @@ -69,8 +65,7 @@ can be used for legal, auditing, or compliance reasons, for example. To add additional text to emails: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter your text in the **Additional text** field. @@ -82,8 +77,7 @@ GitLab sends email notifications to users when their account has been deactivate To disable these notifications: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Clear the **Enable user deactivation emails** checkbox. @@ -106,8 +100,7 @@ setting. To add additional text to deactivation emails: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Email**. 1. Enter your text in the **Additional text for deactivation email** field. diff --git a/doc/administration/settings/external_authorization.md b/doc/administration/settings/external_authorization.md index 3ddebeb983c..95ce7963bb7 100644 --- a/doc/administration/settings/external_authorization.md +++ b/doc/administration/settings/external_authorization.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External authorization control **(FREE SELF)** @@ -45,8 +45,7 @@ Alternatively, learn where to install custom certificates by using The external authorization service can be enabled by an administrator: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **External authorization**. 1. Complete the fields. @@ -66,8 +65,7 @@ Prerequisites: To allow authorization with deploy tokens and keys: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **External authorization**, and: - Leave the service URL field empty. diff --git a/doc/administration/settings/files_api_rate_limits.md b/doc/administration/settings/files_api_rate_limits.md index 025f8c86993..4764341b932 100644 --- a/doc/administration/settings/files_api_rate_limits.md +++ b/doc/administration/settings/files_api_rate_limits.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Repository files API **(FREE SELF)** @@ -24,14 +23,13 @@ the general user and IP rate limits for requests to the and IP rate limits already in place, and increase or decrease the rate limits for the Files API. No other new features are provided by this override. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To override the general user and IP rate limits for requests to the Repository files API: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Files API Rate Limits**. 1. Select the checkboxes for the types of rate limits you want to enable: diff --git a/doc/administration/settings/floc.md b/doc/administration/settings/floc.md index f461472bfe7..499b1d9c82f 100644 --- a/doc/administration/settings/floc.md +++ b/doc/administration/settings/floc.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Federated Learning of Cohorts (FLoC) **(FREE SELF)** @@ -22,8 +22,7 @@ Permissions-Policy: interest-cohort=() To enable it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Federated Learning of Cohorts (FLoC)**. 1. Select the **Participate in FLoC** checkbox. diff --git a/doc/administration/settings/git_lfs_rate_limits.md b/doc/administration/settings/git_lfs_rate_limits.md index acd3945750f..4e096e52f41 100644 --- a/doc/administration/settings/git_lfs_rate_limits.md +++ b/doc/administration/settings/git_lfs_rate_limits.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Git LFS **(FREE SELF)** @@ -21,8 +20,7 @@ rate limits. Git LFS rate limits are disabled by default. If enabled and configured, these limits supersede the [general user and IP rate limits](../settings/user_and_ip_rate_limits.md): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Git LFS Rate Limits**. 1. Select **Enable authenticated Git LFS request rate limit**. diff --git a/doc/administration/settings/gitaly_timeouts.md b/doc/administration/settings/gitaly_timeouts.md index 1cab1e9fd01..b35ee32a3e9 100644 --- a/doc/administration/settings/gitaly_timeouts.md +++ b/doc/administration/settings/gitaly_timeouts.md @@ -1,29 +1,80 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly timeouts **(FREE SELF)** -[Gitaly](../gitaly/index.md) timeouts are configurable. The timeouts can be -configured to make sure that long-running Gitaly calls don't needlessly take up resources. +[Gitaly](../gitaly/index.md) provides two types of configurable timeouts: -To access Gitaly timeout settings: +- Call timeouts, configured by using the GitLab UI. +- Negotiation timeouts, configured by using Gitaly configuration files. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +## Configure the call timeouts + +Configure the following call timeouts to make sure that long-running Gitaly calls don't needlessly take up resources. To +configure the call timeouts: + +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand the **Gitaly timeouts** section. +1. Set each timeout as required. -## Available timeouts +### Available call timeouts -The following timeouts are available. +Different call timeouts are available for different Gitaly operations. | Timeout | Default | Description | |:--------|:-----------|:------------| -| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the [worker timeout](../operations/puma.md#change-the-worker-timeout) that can be configured for [Puma](../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | -| Fast | 10 seconds | Timeout for fast Gitaly operations used within requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance. | -| Medium | 30 seconds | Timeout for Gitaly operations that should be fast (possibly within requests) but preferably not used multiple times within a request. For example, loading blobs. Timeout that should be set between Default and Fast. | +| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made in a web request cannot exceed the entire request timeout. It should be shorter than the [worker timeout](../operations/puma.md#change-the-worker-timeout) that can be configured for [Puma](../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | +| Fast | 10 seconds | Timeout for fast Gitaly operations used in requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance. | +| Medium | 30 seconds | Timeout for Gitaly operations that should be fast (possibly in requests) but preferably not used multiple times in a request. For example, loading blobs. Timeout that should be set between Default and Fast. | + +## Configure the negotiation timeouts + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/5574) in GitLab 16.5. + +You might need to increase the negotiation timeout: + +- For particularly large repositories. +- When performing these commands in parallel. + +You can configure negotiation timeouts for: + +- `git-upload-pack(1)`, which is invoked by a Gitaly node when you execute `git fetch`. +- `git-upload-archive(1)`, which is invoked by a Gitaly node when you execute `git archive --remote`. + +To configure these timeouts: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +Edit `/etc/gitlab/gitlab.rb`: + +```ruby +gitaly['configuration'] = { + timeout: { + upload_pack_negotiation: '10m', # 10 minutes + upload_archive_negotiation: '20m', # 20 minutes + } +} +``` + +:::TabTitle Self-compiled (source) + +Edit `/home/git/gitaly/config.toml`: + +```toml +[timeout] +upload_pack_negotiation = "10m" +upload_archive_negotiation = "20m" +``` + +::EndTabs + +For the values, use the format of [`ParseDuration`](https://pkg.go.dev/time#ParseDuration) in Go. -You can also [configure negotiation timeouts](../gitaly/configure_gitaly.md#configure-negotiation-timeouts). +These timeouts affect only the [negotiation phase](https://git-scm.com/docs/pack-protocol/2.2.3#_packfile_negotiation) of +remote Git operations, not the entire transfer. diff --git a/doc/administration/settings/help_page.md b/doc/administration/settings/help_page.md index 23ca7d55cde..1077bbec316 100644 --- a/doc/administration/settings/help_page.md +++ b/doc/administration/settings/help_page.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customize the Help and sign-in page messages **(FREE SELF)** @@ -16,8 +15,7 @@ the GitLab sign-in page. You can add a help message, which is shown at the top of the GitLab `/help` page (for example, <https://gitlab.com/help>): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the Help page**, enter the information you want to display on `/help`. @@ -34,8 +32,7 @@ is restricted, `/help` is visible only to authenticated users. You can add a help message, which is shown on the GitLab sign-in page. The message appears on the sign-in page: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In **Additional text to show on the sign-in page**, enter the information you want to @@ -48,8 +45,7 @@ You can now see the message on the sign-in page. GitLab marketing-related entries are occasionally shown on the Help page. To hide these entries: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. Select the **Hide marketing-related entries from the Help page** checkbox. @@ -62,8 +58,7 @@ You can specify a custom URL to which users are directed when they: - Select **Support** from the Help dropdown list. - Select **See our website for help** on the Help page. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Support page URL** field, enter the URL. @@ -77,8 +72,7 @@ You can specify a custom URL to which users are directed when they: You can redirect all `/help` links to a destination that meets the [necessary requirements](#destination-requirements). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sign-in and Help page**. 1. In the **Documentation pages URL** field, enter the URL. diff --git a/doc/administration/settings/import_and_export_settings.md b/doc/administration/settings/import_and_export_settings.md index 8d191ea661c..ddb31e49483 100644 --- a/doc/administration/settings/import_and_export_settings.md +++ b/doc/administration/settings/import_and_export_settings.md @@ -1,8 +1,7 @@ --- stage: Manage group: Import and Integrate -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Import and export settings **(FREE SELF)** @@ -15,8 +14,7 @@ Before you can import projects from other systems, you must enable the [import source](../../user/gitlab_com/index.md#default-import-sources) for that system. 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Import and export settings** section. 1. Select each of **Import sources** to allow. @@ -28,8 +26,7 @@ To enable the export of [projects and their data](../../user/project/settings/import_export.md#export-a-project-and-its-data): 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Import and export settings** section. 1. Scroll to **Project export**. @@ -51,8 +48,7 @@ Migration of groups and projects by direct transfer is disabled by default. To enable migration of groups and projects by direct transfer: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Import and export settings** section. 1. Scroll to **Allow migrating GitLab groups and projects by direct transfer**. @@ -69,8 +65,7 @@ The same setting To modify the maximum file size for exports in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**, then expand **Import and export settings**. 1. Increase or decrease by changing the value in **Maximum export size (MiB)**. @@ -80,8 +75,7 @@ To modify the maximum file size for exports in GitLab: To modify the maximum file size for imports in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Increase or decrease by changing the value in **Maximum import size (MiB)**. @@ -103,8 +97,7 @@ By default, the maximum remote file size for imports from external object storag To modify this setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Increase or decrease by changing the value in **Maximum import remote file size (MiB)**. Set to `0` to set no file size limit. @@ -117,8 +110,7 @@ By default, the maximum download file size for imports by direct transfer is 5 G To modify this setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Increase or decrease by changing the value in **Direct transfer maximum download file size (MiB)**. Set to `0` to set no download file size limit. @@ -141,8 +133,7 @@ Decompressed archive size validation failed. To modify this setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Set another value for **Maximum decompressed file size for archives from imports (MiB)**. @@ -155,8 +146,7 @@ When you [import a project](../../user/project/settings/import_export.md), you c To modify the maximum decompressed file size for imports in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Import and export settings**. 1. Set another value for **Timeout for decompressing archived files (seconds)**. diff --git a/doc/administration/settings/import_export_rate_limits.md b/doc/administration/settings/import_export_rate_limits.md index dad72ffdf44..b261efd751b 100644 --- a/doc/administration/settings/import_export_rate_limits.md +++ b/doc/administration/settings/import_export_rate_limits.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits for imports and exports of project and groups **(FREE SELF)** @@ -12,8 +12,7 @@ You can configure the rate limits for imports and exports of projects and groups To change a rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Import and export rate limits**. 1. Change the value of any rate limit. The rate limits are per minute per user, not per IP address. diff --git a/doc/administration/settings/incident_management_rate_limits.md b/doc/administration/settings/incident_management_rate_limits.md index 5a8b1b96c6d..57005682f15 100644 --- a/doc/administration/settings/incident_management_rate_limits.md +++ b/doc/administration/settings/incident_management_rate_limits.md @@ -1,8 +1,7 @@ --- -type: reference -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incident management rate limits **(ULTIMATE SELF)** @@ -30,8 +29,7 @@ Requests that exceed the limit are logged into `auth.log`. To set inbound incident management alert limits: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Incident Management Limits**. 1. Select the **Enable Incident Management inbound alert limit** checkbox. diff --git a/doc/administration/settings/index.md b/doc/administration/settings/index.md index 1c601df7814..531073887c5 100644 --- a/doc/administration/settings/index.md +++ b/doc/administration/settings/index.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Update your Admin Area settings **(FREE SELF)** @@ -17,5 +16,4 @@ Use **Settings** to control settings across the instance. To access the **Admin Area**: 1. Sign in to your GitLab instance as an administrator. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. diff --git a/doc/administration/settings/instance_template_repository.md b/doc/administration/settings/instance_template_repository.md index 510c88e7738..3d95172ae24 100644 --- a/doc/administration/settings/instance_template_repository.md +++ b/doc/administration/settings/instance_template_repository.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Instance template repository **(PREMIUM SELF)** @@ -20,8 +19,7 @@ while the project remains secure. To select a project to serve as the custom template repository: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Templates**. 1. Expand **Templates** 1. From the dropdown list, select the project to use as the template repository. diff --git a/doc/administration/settings/jira_cloud_app.md b/doc/administration/settings/jira_cloud_app.md index 8ff2a9acdb8..c87c7c62a3a 100644 --- a/doc/administration/settings/jira_cloud_app.md +++ b/doc/administration/settings/jira_cloud_app.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab for Jira Cloud app administration **(FREE SELF)** @@ -18,6 +18,10 @@ To set up the GitLab for Jira Cloud app on your self-managed instance, do one of - [Connect the GitLab for Jira Cloud app](#connect-the-gitlab-for-jira-cloud-app) (GitLab 15.7 and later). - [Install the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually). +After you set up the app, you can use the [project toolchain](https://support.atlassian.com/jira-software-cloud/docs/what-is-the-project-toolchain-in-jira) +developed and maintained by Atlassian to [link GitLab repositories to Jira projects](https://support.atlassian.com/jira-software-cloud/docs/link-repositories-to-a-project/#Link-repositories-using-the-toolchain-feature). +The project toolchain does not affect how development information is synced between GitLab and Jira Cloud. + For Jira Data Center or Jira Server, use the [Jira DVCS connector](../../integration/jira/dvcs/index.md) developed and maintained by Atlassian. ## Set up OAuth authentication @@ -29,9 +33,8 @@ You must set up OAuth authentication to: To create an OAuth application on your self-managed instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Applications**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Applications**. 1. Select **New application**. 1. In **Redirect URI**: - If you're installing the app from the official marketplace listing, enter `https://gitlab.com/-/jira_connect/oauth_callbacks`. @@ -109,9 +112,8 @@ With this method: To set up your self-managed instance for the GitLab for Jira Cloud app in GitLab 15.7 and later: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. In **Jira Connect Proxy URL**, enter `https://gitlab.com`. 1. Select **Save changes**. @@ -231,9 +233,8 @@ You might want to use a proxy if you're managing multiple GitLab instances but o To configure your GitLab instance to serve as a proxy: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **GitLab for Jira App**. 1. Select **Enable public key storage**. 1. Select **Save changes**. @@ -248,6 +249,16 @@ Other GitLab instances that use the proxy must configure the following settings The GitLab for Jira Cloud app connects GitLab and Jira. Data must be shared between the two applications, and access must be granted in both directions. +### Using GitLab.com as a proxy + +When you use [GitLab.com as a proxy](#configure-your-gitlab-instance-to-serve-as-a-proxy), +the Jira access token is shared with GitLab.com. + +The Jira access token is stored on GitLab.com because the token must be used to verify +incoming requests from Jira before the requests are sent to your self-managed instance. +The token is encrypted and is not used to access data in Jira. +Any data from your self-managed instance is sent directly to Jira. + ### Access to GitLab through OAuth GitLab does not share an access token with Jira. However, users must authenticate through OAuth to configure the app. @@ -263,161 +274,3 @@ However, the GitLab for Jira Cloud app only uses this access to: - Link groups. Access through OAuth is only needed for the time a user configures the GitLab for Jira Cloud app. For more information, see [Access token expiration](../../integration/oauth_provider.md#access-token-expiration). - -## Troubleshooting - -When administering the GitLab for Jira Cloud app for self-managed instances, you might encounter the following issues. - -For GitLab.com, see [GitLab for Jira Cloud app](../../integration/jira/connect-app.md#troubleshooting). - -### Browser displays a sign-in message when already signed in - -You might get the following message prompting you to sign in to GitLab.com -when you're already signed in: - -```plaintext -You need to sign in or sign up before continuing. -``` - -The GitLab for Jira Cloud app uses an iframe to add groups on the -settings page. Some browsers block cross-site cookies, which can lead to this issue. - -To resolve this issue, set up [OAuth authentication](#set-up-oauth-authentication). - -### Manual installation fails - -You might get an error if you have installed the GitLab for Jira Cloud app from the official marketplace listing and replaced it with [manual installation](#install-the-gitlab-for-jira-cloud-app-manually): - -```plaintext -The app "gitlab-jira-connect-gitlab.com" could not be installed as a local app as it has previously been installed from Atlassian Marketplace -``` - -To resolve this issue, disable the **Jira Connect Proxy URL** setting. - -- In GitLab 15.7: - - 1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). - 1. Execute `ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)`. - -- In GitLab 15.8 and later: - - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. - 1. On the left sidebar, select **Settings > General**. - 1. Expand **GitLab for Jira App**. - 1. Clear the **Jira Connect Proxy URL** text box. - 1. Select **Save changes**. - -### Data sync fails with `Invalid JWT` error - -If the GitLab for Jira Cloud app continuously fails to sync data, it may be due to an outdated secret token. Atlassian can send new secret tokens that must be processed and stored by GitLab. -If GitLab fails to store the token or misses the new token request, an `Invalid JWT` error occurs. - -To resolve this issue on GitLab self-managed, follow one of the solutions below, depending on your app installation method. - -- If you installed the app from the official marketplace listing: - - 1. Open the GitLab for Jira Cloud app on Jira. - 1. Select **Change GitLab version**. - 1. Select **GitLab.com (SaaS)**. - 1. Select **Change GitLab version** again. - 1. Select **GitLab (self-managed)**. - 1. Enter your **GitLab instance URL**. - 1. Select **Save**. - -- If you [installed the GitLab for Jira Cloud app manually](#install-the-gitlab-for-jira-cloud-app-manually): - - - In GitLab 14.9 and later: - - Contact the [Jira Software Cloud support](https://support.atlassian.com/jira-software-cloud/) and ask to trigger a new installed lifecycle event for the GitLab for Jira Cloud app in your group. - - In all GitLab versions: - - Re-install the GitLab for Jira Cloud app. This method might remove all synced data from the [Jira development panel](../../integration/jira/development_panel.md). - -### `Failed to update the GitLab instance` - -When you set up the GitLab for Jira Cloud app, you might get a `Failed to update the GitLab instance` error after you enter your self-managed instance URL. - -To resolve this issue, ensure all prerequisites for your installation method have been met: - -- [Prerequisites for connecting the GitLab for Jira Cloud app](#prerequisites) -- [Prerequisites for installing the GitLab for Jira Cloud app manually](#prerequisites-1) - -If you have configured a Jira Connect Proxy URL and the problem persists after checking the prerequisites, review [Debugging Jira Connect Proxy issues](#debugging-jira-connect-proxy-issues). - -If you're using GitLab 15.8 and earlier and have previously enabled both the `jira_connect_oauth_self_managed` -and the `jira_connect_oauth` feature flags, you must disable the `jira_connect_oauth_self_managed` flag -due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388943). To check for these flags: - -1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). -1. Execute the following code: - - ```ruby - # Check if both feature flags are enabled. - # If the flags are enabled, these commands return `true`. - Feature.enabled?(:jira_connect_oauth) - Feature.enabled?(:jira_connect_oauth_self_managed) - - # If both flags are enabled, disable the `jira_connect_oauth_self_managed` flag. - Feature.disable(:jira_connect_oauth_self_managed) - ``` - -#### Debugging Jira Connect Proxy issues - -If you are using a self-managed GitLab instance and you have configured `https://gitlab.com` for the Jira Connect Proxy URL when -[setting up the OAuth authentication](#set-up-oauth-authentication), you can inspect the network traffic in your browser's development -tools while reproducing the `Failed to update the GitLab instance` error to see a more precise error. - -You should see a `GET` request to `https://gitlab.com/-/jira_connect/installations`. - -This request should return a `200` status code, but it can return a `422` status code if there was a problem. The response body can be checked for the error. - -If you cannot resolve the problem and you are a GitLab customer, contact [GitLab Support](https://about.gitlab.com/support/) for assistance. Provide -GitLab Support with: - -1. Your GitLab self-managed instance URL. -1. Your GitLab.com username. -1. If possible, the `X-Request-Id` response header for the failed `GET` request to `https://gitlab.com/-/jira_connect/installations`. -1. Optional. [A HAR file that captured the problem](https://support.zendesk.com/hc/en-us/articles/4408828867098-Generating-a-HAR-file-for-troubleshooting). - -The GitLab Support team can then look up why this is failing in the GitLab.com server logs. - -##### Process for GitLab Support - -NOTE: -These steps can only be completed by GitLab Support. - -In Kibana, the logs should be filtered for `json.meta.caller_id: JiraConnect::InstallationsController#update` and `NOT json.status: 200`. -If you have been provided the `X-Request-Id` value, you can use that against `json.correlation_id` to narrow down the results. - -Each `GET` request to the Jira Connect Proxy URL `https://gitlab.com/-/jira_connect/installations` generates two log entries. - -For the first log: - -- `json.status` is `422`. -- `json.params.value` should match the GitLab self-managed URL `[[FILTERED], {"instance_url"=>"https://gitlab.example.com"}]`. - -For the second log: - -- `json.message` is `Proxy lifecycle event received error response` or similar. -- `json.jira_status_code` and `json.jira_body` might contain details on why GitLab.com wasn't able to connect back to the self-managed instance. - -### `Failed to link group` - -After you connect the GitLab for Jira Cloud app for self-managed instances, you might get one of these errors: - -```plaintext -Failed to load Jira Connect Application ID. Please try again. -``` - -```plaintext -Failed to link group. Please try again. -``` - -When you check the browser console, you might see the following message: - -```plaintext -Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://gitlab.example.com/-/jira_connect/oauth_application_id. (Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 403. -``` - -`403` status code is returned if the user information cannot be fetched from Jira because of insufficient permissions. - -To resolve this issue, ensure that the Jira user that installs and configures the GitLab for Jira Cloud app meets certain [requirements](#jira-user-requirements). diff --git a/doc/administration/settings/jira_cloud_app_troubleshooting.md b/doc/administration/settings/jira_cloud_app_troubleshooting.md new file mode 100644 index 00000000000..1b6f88d43ae --- /dev/null +++ b/doc/administration/settings/jira_cloud_app_troubleshooting.md @@ -0,0 +1,164 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting GitLab for Jira Cloud app administration **(FREE SELF)** + +When administering the GitLab for Jira Cloud app for self-managed instances, you might encounter the following issues. + +For GitLab.com, see [GitLab for Jira Cloud app](../../integration/jira/connect-app.md#troubleshooting). + +## Browser displays a sign-in message when already signed in + +You might get the following message prompting you to sign in to GitLab.com +when you're already signed in: + +```plaintext +You need to sign in or sign up before continuing. +``` + +The GitLab for Jira Cloud app uses an iframe to add groups on the +settings page. Some browsers block cross-site cookies, which can lead to this issue. + +To resolve this issue, set up [OAuth authentication](jira_cloud_app.md#set-up-oauth-authentication). + +## Manual installation fails + +You might get an error if you have installed the GitLab for Jira Cloud app from the official marketplace listing and replaced it with [manual installation](jira_cloud_app.md#install-the-gitlab-for-jira-cloud-app-manually): + +```plaintext +The app "gitlab-jira-connect-gitlab.com" could not be installed as a local app as it has previously been installed from Atlassian Marketplace +``` + +To resolve this issue, disable the **Jira Connect Proxy URL** setting. + +- In GitLab 15.7: + + 1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). + 1. Execute `ApplicationSetting.current_without_cache.update(jira_connect_proxy_url: nil)`. + +- In GitLab 15.8 and later: + + 1. On the left sidebar, at the bottom, select **Admin Area**. + 1. On the left sidebar, select **Settings > General**. + 1. Expand **GitLab for Jira App**. + 1. Clear the **Jira Connect Proxy URL** text box. + 1. Select **Save changes**. + +## Data sync fails with `Invalid JWT` error + +If the GitLab for Jira Cloud app continuously fails to sync data, it may be due to an outdated secret token. Atlassian can send new secret tokens that must be processed and stored by GitLab. +If GitLab fails to store the token or misses the new token request, an `Invalid JWT` error occurs. + +To resolve this issue on GitLab self-managed, follow one of the solutions below, depending on your app installation method. + +- If you installed the app from the official marketplace listing: + + 1. Open the GitLab for Jira Cloud app on Jira. + 1. Select **Change GitLab version**. + 1. Select **GitLab.com (SaaS)**. + 1. Select **Change GitLab version** again. + 1. Select **GitLab (self-managed)**. + 1. Enter your **GitLab instance URL**. + 1. Select **Save**. + +- If you [installed the GitLab for Jira Cloud app manually](jira_cloud_app.md#install-the-gitlab-for-jira-cloud-app-manually): + + - In GitLab 14.9 and later: + - Contact the [Jira Software Cloud support](https://support.atlassian.com/jira-software-cloud/) and ask to trigger a new installed lifecycle event for the GitLab for Jira Cloud app in your group. + - In all GitLab versions: + - Re-install the GitLab for Jira Cloud app. This method might remove all synced data from the [Jira development panel](../../integration/jira/development_panel.md). + +## `Failed to update the GitLab instance` + +When you set up the GitLab for Jira Cloud app, you might get a `Failed to update the GitLab instance` error after you enter your self-managed instance URL. + +To resolve this issue, ensure all prerequisites for your installation method have been met: + +- [Prerequisites for connecting the GitLab for Jira Cloud app](jira_cloud_app.md#prerequisites) +- [Prerequisites for installing the GitLab for Jira Cloud app manually](jira_cloud_app.md#prerequisites-1) + +If you have configured a Jira Connect Proxy URL and the problem persists after checking the prerequisites, review [Debugging Jira Connect Proxy issues](#debugging-jira-connect-proxy-issues). + +If you're using GitLab 15.8 and earlier and have previously enabled both the `jira_connect_oauth_self_managed` +and the `jira_connect_oauth` feature flags, you must disable the `jira_connect_oauth_self_managed` flag +due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/388943). To check for these flags: + +1. Open a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). +1. Execute the following code: + + ```ruby + # Check if both feature flags are enabled. + # If the flags are enabled, these commands return `true`. + Feature.enabled?(:jira_connect_oauth) + Feature.enabled?(:jira_connect_oauth_self_managed) + + # If both flags are enabled, disable the `jira_connect_oauth_self_managed` flag. + Feature.disable(:jira_connect_oauth_self_managed) + ``` + +### Debugging Jira Connect Proxy issues + +If you are using a self-managed GitLab instance and you have configured `https://gitlab.com` for the Jira Connect Proxy URL when +[setting up the OAuth authentication](jira_cloud_app.md#set-up-oauth-authentication), you can inspect the network traffic in your browser's development +tools while reproducing the `Failed to update the GitLab instance` error to see a more precise error. + +You should see a `GET` request to `https://gitlab.com/-/jira_connect/installations`. + +This request should return a `200` status code, but it can return a `422` status code if there was a problem. The response body can be checked for the error. + +If you cannot resolve the problem and you are a GitLab customer, contact [GitLab Support](https://about.gitlab.com/support/) for assistance. Provide +GitLab Support with: + +1. Your GitLab self-managed instance URL. +1. Your GitLab.com username. +1. If possible, the `X-Request-Id` response header for the failed `GET` request to `https://gitlab.com/-/jira_connect/installations`. +1. Optional. [A HAR file that captured the problem](https://support.zendesk.com/hc/en-us/articles/4408828867098-Generating-a-HAR-file-for-troubleshooting). + +The GitLab Support team can then look up why this is failing in the GitLab.com server logs. + +#### Process for GitLab Support + +NOTE: +These steps can only be completed by GitLab Support. + +In Kibana, the logs should be filtered for `json.meta.caller_id: JiraConnect::InstallationsController#update` and `NOT json.status: 200`. +If you have been provided the `X-Request-Id` value, you can use that against `json.correlation_id` to narrow down the results. + +Each `GET` request to the Jira Connect Proxy URL `https://gitlab.com/-/jira_connect/installations` generates two log entries. + +For the first log: + +- `json.status` is `422`. +- `json.params.value` should match the GitLab self-managed URL `[[FILTERED], {"instance_url"=>"https://gitlab.example.com"}]`. + +For the second log: + +- `json.message` is `Proxy lifecycle event received error response` or similar. +- `json.jira_status_code` and `json.jira_body` might contain details on why GitLab.com wasn't able to connect back to the self-managed instance. +- If `json.jira_status_code` is `401` and `json.jira_body` is empty, this might indicate that the [**Jira Connect Proxy URL**](jira_cloud_app.md#set-up-your-instance) is not set to + `https://gitlab.com`. + +## `Failed to link group` + +After you connect the GitLab for Jira Cloud app for self-managed instances, you might get one of these errors: + +```plaintext +Failed to load Jira Connect Application ID. Please try again. +``` + +```plaintext +Failed to link group. Please try again. +``` + +When you check the browser console, you might see the following message: + +```plaintext +Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://gitlab.example.com/-/jira_connect/oauth_application_id. (Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 403. +``` + +`403` status code is returned if the user information cannot be fetched from Jira because of insufficient permissions. + +To resolve this issue, ensure that the Jira user that installs and configures the GitLab for Jira Cloud app meets certain [requirements](jira_cloud_app.md#jira-user-requirements). diff --git a/doc/administration/settings/localization.md b/doc/administration/settings/localization.md index a86e9c75a4e..71ceaa3c9bf 100644 --- a/doc/administration/settings/localization.md +++ b/doc/administration/settings/localization.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Localization **(FREE SELF)** @@ -15,8 +14,7 @@ deployment. You can change the [Default first day of the week](../../user/profile/preferences.md) for the entire GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired first day of the week. @@ -25,7 +23,6 @@ for the entire GitLab instance: You can change the [Default language](../../user/profile/preferences.md) for the entire GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Scroll to the **Localization** section, and select your desired default language. diff --git a/doc/administration/settings/package_registry_rate_limits.md b/doc/administration/settings/package_registry_rate_limits.md index 2ddb6bfcd17..db3170a625b 100644 --- a/doc/administration/settings/package_registry_rate_limits.md +++ b/doc/administration/settings/package_registry_rate_limits.md @@ -1,13 +1,12 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Package Registry Rate Limits **(FREE SELF)** +# Package registry rate limits **(FREE SELF)** -With the [GitLab Package Registry](../../user/packages/package_registry/index.md), +With the [GitLab package registry](../../user/packages/package_registry/index.md), you can use GitLab as a private or public registry for a variety of common package managers. You can publish and share packages, which others can consume as a dependency in downstream projects through the [Packages API](../../api/packages.md). @@ -30,8 +29,7 @@ no difference in functionality compared to the general user and IP rate limits. To enable the unauthenticated request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Package registry rate limits**. 1. Select **Enable unauthenticated request rate limit**. @@ -45,8 +43,7 @@ To enable the unauthenticated request rate limit: To enable the authenticated API request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network** 1. Expand **Package registry rate limits**. 1. Select **Enable authenticated API request rate limit**. diff --git a/doc/administration/settings/project_integration_management.md b/doc/administration/settings/project_integration_management.md index 32756e65eaf..7fea1bccaf6 100644 --- a/doc/administration/settings/project_integration_management.md +++ b/doc/administration/settings/project_integration_management.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project integration administration **(FREE SELF)** @@ -23,14 +23,13 @@ is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ## Manage instance-level default settings for a project integration -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To manage instance-level default settings for a project integration: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select an integration. 1. Complete the fields. @@ -65,14 +64,13 @@ is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ### Remove an instance-level default setting -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To remove an instance-level default setting: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select an integration. 1. Select **Reset** and confirm. @@ -83,14 +81,13 @@ Resetting an instance-level default setting removes the integration from all pro > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218252) in GitLab 14.2. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To view projects in your instance that [use custom settings](../../user/project/integrations/index.md#use-custom-settings-for-a-project-or-group-integration): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select an integration. 1. Select the **Projects using custom settings** tab. diff --git a/doc/administration/settings/protected_paths.md b/doc/administration/settings/protected_paths.md index 3244c25e906..9eae34c8c64 100644 --- a/doc/administration/settings/protected_paths.md +++ b/doc/administration/settings/protected_paths.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected paths **(FREE SELF)** @@ -34,8 +33,7 @@ See also: Throttling of protected paths is enabled by default and can be disabled or customized. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Protected paths**. diff --git a/doc/administration/settings/push_event_activities_limit.md b/doc/administration/settings/push_event_activities_limit.md index 36aa1eec306..edf64100eb7 100644 --- a/doc/administration/settings/push_event_activities_limit.md +++ b/doc/administration/settings/push_event_activities_limit.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Push event activities limit and bulk push events **(FREE SELF)** @@ -26,8 +25,7 @@ the activity feed. To modify this setting: - In the Admin Area: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Performance optimization**. - Through the [Application settings API](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) diff --git a/doc/administration/settings/rate_limit_on_issues_creation.md b/doc/administration/settings/rate_limit_on_issues_creation.md index 14d484d91b1..36e242b4ac4 100644 --- a/doc/administration/settings/rate_limit_on_issues_creation.md +++ b/doc/administration/settings/rate_limit_on_issues_creation.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on issue and epic creation **(FREE SELF)** @@ -18,8 +17,7 @@ action blocks requests that exceed a rate of 300 per minute. Access to the endpo To limit the number of requests made to the issue and epic creation endpoints: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Issues Rate Limits**. 1. Under **Max requests per minute**, enter the new value. diff --git a/doc/administration/settings/rate_limit_on_notes_creation.md b/doc/administration/settings/rate_limit_on_notes_creation.md index 3bd6eee8303..59ec47afaa9 100644 --- a/doc/administration/settings/rate_limit_on_notes_creation.md +++ b/doc/administration/settings/rate_limit_on_notes_creation.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on note creation **(FREE SELF)** @@ -13,8 +12,7 @@ You can configure the per-user rate limit for requests to the note creation endp To change the note creation rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Notes rate limit**. 1. In the **Maximum requests per minute** box, enter the new value. diff --git a/doc/administration/settings/rate_limit_on_pipelines_creation.md b/doc/administration/settings/rate_limit_on_pipelines_creation.md index d083acb190e..e99d6e65993 100644 --- a/doc/administration/settings/rate_limit_on_pipelines_creation.md +++ b/doc/administration/settings/rate_limit_on_pipelines_creation.md @@ -1,8 +1,7 @@ --- -type: reference stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on pipeline creation **(FREE SELF)** @@ -26,8 +25,7 @@ Requests that exceed the limit are logged in the `application_json.log` file. To limit the number of pipeline requests: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Pipelines Rate Limits**. 1. Under **Max requests per minute**, enter a value greater than `0`. diff --git a/doc/administration/settings/rate_limit_on_projects_api.md b/doc/administration/settings/rate_limit_on_projects_api.md index 33304e4f088..f2797b37171 100644 --- a/doc/administration/settings/rate_limit_on_projects_api.md +++ b/doc/administration/settings/rate_limit_on_projects_api.md @@ -1,8 +1,7 @@ --- -type: reference stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limit on Projects API **(FREE SELF)** @@ -16,8 +15,7 @@ You can configure the rate limit per IP address for unauthenticated requests to To change the rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Projects API rate limit**. 1. In the **Maximum requests per 10 minutes per IP address** text box, enter the new value. diff --git a/doc/administration/settings/rate_limit_on_users_api.md b/doc/administration/settings/rate_limit_on_users_api.md index 533bfe0b000..fcac30c9105 100644 --- a/doc/administration/settings/rate_limit_on_users_api.md +++ b/doc/administration/settings/rate_limit_on_users_api.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Users API **(FREE SELF)** @@ -13,8 +12,7 @@ You can configure the per user rate limit for requests to [Users API](../../api/ To change the rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Users API rate limit**. 1. In the **Maximum requests per 10 minutes** text box, enter the new value. diff --git a/doc/administration/settings/rate_limits.md b/doc/administration/settings/rate_limits.md index 2263455fa09..89e64344e0c 100644 --- a/doc/administration/settings/rate_limits.md +++ b/doc/administration/settings/rate_limits.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits @@ -15,7 +14,7 @@ You can change network settings to limit the rate of connections with your insta - [Incident management](incident_management_rate_limits.md) - [Issue creation](rate_limit_on_issues_creation.md) - [Note creation](rate_limit_on_notes_creation.md) -- [Package Registry](package_registry_rate_limits.md) +- [Package registry](package_registry_rate_limits.md) - [Pipeline creation](rate_limit_on_pipelines_creation.md) - [Projects API](rate_limit_on_projects_api.md) - [Raw endpoints](rate_limits_on_raw_endpoints.md) diff --git a/doc/administration/settings/rate_limits_on_git_ssh_operations.md b/doc/administration/settings/rate_limits_on_git_ssh_operations.md index 4e60fd55b19..dea939c7fe9 100644 --- a/doc/administration/settings/rate_limits_on_git_ssh_operations.md +++ b/doc/administration/settings/rate_limits_on_git_ssh_operations.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Git SSH operations **(FREE SELF)** @@ -26,8 +25,7 @@ Because the same commands are shared by `git-upload-pack`, `git pull`, and `git `Git operations using SSH` is enabled by default. Defaults to 600 per user per minute. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Git SSH operations rate limit**. 1. Enter a value for **Maximum number of Git operations per minute**. diff --git a/doc/administration/settings/rate_limits_on_raw_endpoints.md b/doc/administration/settings/rate_limits_on_raw_endpoints.md index 237b57f4436..9ff5637028d 100644 --- a/doc/administration/settings/rate_limits_on_raw_endpoints.md +++ b/doc/administration/settings/rate_limits_on_raw_endpoints.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on raw endpoints **(FREE SELF)** @@ -11,8 +10,7 @@ type: reference This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **Performance optimization**. diff --git a/doc/administration/settings/scim_setup.md b/doc/administration/settings/scim_setup.md index 45020fdfb59..52061150fa7 100644 --- a/doc/administration/settings/scim_setup.md +++ b/doc/administration/settings/scim_setup.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure SCIM for self-managed GitLab instances **(PREMIUM SELF)** @@ -27,8 +26,7 @@ Prerequisites: To configure GitLab SCIM: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **SCIM Token** section and select **Generate a SCIM token**. 1. For configuration of your identity provider, save the: diff --git a/doc/administration/settings/security_and_compliance.md b/doc/administration/settings/security_and_compliance.md index 78923b19b04..d0d9ed3256b 100644 --- a/doc/administration/settings/security_and_compliance.md +++ b/doc/administration/settings/security_and_compliance.md @@ -1,8 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Security and Compliance Admin Area settings **(ULTIMATE SELF)** @@ -13,8 +12,7 @@ The settings for package metadata synchronization are located in the [Admin Area To choose the packages you want to synchronize with the GitLab Package Metadata Database for [License Compliance](../../user/compliance/license_scanning_of_cyclonedx_files/index.md) and [Continuous Vulnerability Scanning](../../user/application_security/continuous_vulnerability_scanning/index.md): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Security and Compliance**. 1. Expand **License Compliance**. 1. Select or clear checkboxes for the package registries that you want to sync. diff --git a/doc/administration/settings/security_contact_information.md b/doc/administration/settings/security_contact_information.md new file mode 100644 index 00000000000..e4d2cf62bdc --- /dev/null +++ b/doc/administration/settings/security_contact_information.md @@ -0,0 +1,42 @@ +--- +stage: Govern +group: Compliance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Provide public security contact information **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433210) in GitLab 16.7. + +Organizations can facilitate the responsible disclosure of security issues by +providing public contact information. GitLab supports using a +[`security.txt`](https://securitytxt.org/) file for this purpose. + +Administrators can add a `security.txt` file using the GitLab UI or the +[REST API](../../api/settings.md#change-application-settings). +Any content added is made available at +`https://gitlab.example.com/.well-known/security.txt`. Authentication is not +required to view this file. + +To configure a `security.txt` file: + +1. On the left sidebar, select **Search or go to**. +1. Select **Admin Area**. +1. Select **Settings > General**. +1. Expand the **Add security contact information** section. +1. In **Content for security.txt**, enter security contact information in the + format documented at <https://securitytxt.org/>. +1. Select **Save changes**. + +For information about how to respond if you receive a report, see +[Responding to security incidents](../../security/responding_to_security_incidents.md). + +## Example `security.txt` file + +The format of this information is documented at <https://securitytxt.org/>. +An example `security.txt` file is: + +```plaintext +Contact: mailto:security@example.com +Expires: 2024-12-31T23:59Z +``` diff --git a/doc/administration/settings/sidekiq_job_limits.md b/doc/administration/settings/sidekiq_job_limits.md index 6c5ff29e96b..bf89678d4d2 100644 --- a/doc/administration/settings/sidekiq_job_limits.md +++ b/doc/administration/settings/sidekiq_job_limits.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq job size limits **(FREE SELF)** @@ -17,8 +16,7 @@ Redis. To avoid excessive memory for Redis, we: To access Sidekiq job size limits: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Sidekiq job size limits**. 1. Adjust the compression threshold or size limit. The compression can diff --git a/doc/administration/settings/sign_in_restrictions.md b/doc/administration/settings/sign_in_restrictions.md index 942b706b9a3..60994bc6e43 100644 --- a/doc/administration/settings/sign_in_restrictions.md +++ b/doc/administration/settings/sign_in_restrictions.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign-in restrictions **(FREE SELF)** @@ -12,8 +12,7 @@ You can use **Sign-in restrictions** to customize authentication restrictions fo To access sign-in restriction settings: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Sign-in restrictions** section. @@ -76,11 +75,11 @@ Open the [Rails console](../operations/rails_console.md) and run the following: To enable Admin Mode through the UI: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-in restrictions**. -1. In the **Admin Mode** section, select the **Require additional authentication for administrative tasks** checkbox. +1. Select **Enable Admin Mode**. +1. Select **Save changes**. ### Turn on Admin Mode for your session @@ -181,8 +180,7 @@ For example, if you include the following information in the noted text box: To access this text box: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Sign-in restrictions** section. ``` diff --git a/doc/administration/settings/sign_up_restrictions.md b/doc/administration/settings/sign_up_restrictions.md index da40a2bab05..3ebb80c34ab 100644 --- a/doc/administration/settings/sign_up_restrictions.md +++ b/doc/administration/settings/sign_up_restrictions.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign-up restrictions **(FREE SELF)** @@ -22,8 +21,7 @@ you do not expect public users to sign up for an account. To disable sign ups: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. @@ -40,8 +38,7 @@ enabled by default for new GitLab instances. It is only applicable if sign ups a To require administrator approval for new sign ups: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. @@ -66,8 +63,7 @@ their email address before they are allowed to sign in. To enforce confirmation of the email address used for new sign ups: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Under **Email confirmation settings**, select **Hard**. @@ -101,14 +97,13 @@ The user cap might apply only retrospectively after the cap has already been exc To ensure the cap is enabled immediately, set the cap to a value below the current number of billable users (for example, `1`). -Prerequisite: +Prerequisites: - You must be an administrator. To set a user cap: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Enter a number in **User cap**. @@ -121,14 +116,13 @@ administrator approval is not restricted. After you remove the user cap, users pending approval are automatically approved. -Prerequisite: +Prerequisites: - You must be an administrator. To remove the user cap: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Remove the number from **User cap**. @@ -153,8 +147,7 @@ You can add additional complexity requirements. Changes to password complexity r Existing passwords are unaffected. To change password complexity requirements: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Under **Minimum password length (number of characters)**, select additional password complexity requirements. You can require numbers, uppercase letters, lowercase letters, @@ -183,8 +176,7 @@ reduce the risk of malicious users creating spam accounts with disposable email To create an email domain allowlist or denylist: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list diff --git a/doc/administration/settings/slack_app.md b/doc/administration/settings/slack_app.md index de11da281e4..5e54294b720 100644 --- a/doc/administration/settings/slack_app.md +++ b/doc/administration/settings/slack_app.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab for Slack app administration **(FREE SELF)** @@ -18,7 +18,7 @@ The app is a private one-time copy installed in your Slack workspace only and no ## Create a GitLab for Slack app -Prerequisite: +Prerequisites: - You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). @@ -26,8 +26,7 @@ To create a GitLab for Slack app: - **In GitLab**: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Slack app**. 1. Select **Create Slack app**. @@ -46,9 +45,8 @@ You're then redirected to Slack for the next steps. After you've [created a GitLab for Slack app](#create-a-gitlab-for-slack-app), you can configure the settings in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **GitLab for Slack app**. 1. Select the **Enable GitLab for Slack app** checkbox. 1. Enter the details of your GitLab for Slack app: @@ -70,7 +68,7 @@ To use Slash commands for a project, configure the [GitLab for Slack app](../../ ## Update the GitLab for Slack app -Prerequisite: +Prerequisites: - You must be at least a [Slack workspace administrator](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack). @@ -80,8 +78,7 @@ To update your copy of the GitLab for Slack app: - **In GitLab**: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **GitLab for Slack app**. 1. Select **Download latest manifest file** to download `slack_manifest.json`. @@ -107,7 +104,7 @@ To enable the GitLab for Slack app functionality, your network must allow inboun When administering the GitLab for Slack app for self-managed instances, you might encounter the following issues. -For GitLab.com, see [GitLab for Slack app](../../user/project/integrations/gitlab_slack_application.md#troubleshooting). +For GitLab.com, see [GitLab for Slack app](../../user/project/integrations/gitlab_slack_app_troubleshooting.md). ### Slash commands return an error in Slack diff --git a/doc/administration/settings/terms.md b/doc/administration/settings/terms.md index 12678b6416a..dc12784ad82 100644 --- a/doc/administration/settings/terms.md +++ b/doc/administration/settings/terms.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terms of Service and Privacy Policy **(FREE SELF)** @@ -17,8 +16,7 @@ for example `https://gitlab.example.com/-/users/terms`. To enforce acceptance of a Terms of Service and Privacy Policy: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Terms of Service and Privacy Policy** section. 1. Check the **All users must accept the Terms of Service and Privacy Policy to access GitLab** checkbox. diff --git a/doc/administration/settings/terraform_limits.md b/doc/administration/settings/terraform_limits.md index 7f744b0a4e5..9650b2fdda1 100644 --- a/doc/administration/settings/terraform_limits.md +++ b/doc/administration/settings/terraform_limits.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform limits **(FREE SELF)** @@ -15,8 +14,7 @@ state file version, and is checked whenever a new version is created. To add a storage limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Preferences**. 1. Expand **Terraform limits**. 1. Enter a size limit in bytes. Set to `0` to allow files of unlimited size. diff --git a/doc/administration/settings/third_party_offers.md b/doc/administration/settings/third_party_offers.md index b91f13a6a30..861859e3639 100644 --- a/doc/administration/settings/third_party_offers.md +++ b/doc/administration/settings/third_party_offers.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customer experience improvement and third-party offers **(FREE SELF)** @@ -18,8 +17,7 @@ questions when creating a group. To toggle the display of customer experience improvement content and third-party offers: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Customer experience improvement and third-party offers**. 1. Select **Do not display content for customer experience improvement and offers from third parties**. diff --git a/doc/administration/settings/usage_statistics.md b/doc/administration/settings/usage_statistics.md index b9080f49f5d..20479a7dd8a 100644 --- a/doc/administration/settings/usage_statistics.md +++ b/doc/administration/settings/usage_statistics.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Usage statistics **(FREE SELF)** @@ -71,12 +71,16 @@ In the following table, you can see: | [Users and permissions report](../../administration/admin_area.md#user-permission-export) | GitLab 16.6 and later | | [Advanced search](../../user/search/advanced_search.md) | GitLab 16.6 and later | | [DevOps Adoption](../../user/group/devops_adoption/index.md) | GitLab 16.6 and later | +| [Сross-project pipelines with artifacts dependencies](../../ci/yaml/index.md#needsproject) | GitLab 16.7 and later | +| [Feature flag related issues](../../operations/feature_flags.md#feature-flag-related-issues) | GitLab 16.7 and later | +| [Merged results pipelines](../../ci/pipelines/merged_results_pipelines.md) | GitLab 16.7 and later | +| [CI/CD for external repositories](../../ci/ci_cd_for_external_repos/index.md) | GitLab 16.7 and later | +| [CI/CD for GitHub](../../ci/ci_cd_for_external_repos/github_integration.md) | GitLab 16.7 and later | ### Enable registration features 1. Sign in as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling**. 1. Expand the **Usage statistics** section. 1. If not enabled, select the **Enable Service Ping** checkbox. @@ -107,8 +111,7 @@ If you disable version check, this information isn't collected. ### Enable or disable version check -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling**. 1. Expand **Usage statistics**. 1. Select or clear the **Enable version check** checkbox. @@ -144,8 +147,7 @@ If your GitLab instance is behind a proxy, set the appropriate To enable or disable Service Ping: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling**. 1. Expand **Usage statistics**. 1. Select or clear the **Enable Service Ping** checkbox. @@ -207,8 +209,7 @@ the Admin Area. You can view the exact JSON payload sent to GitLab Inc. in the Admin Area. To view the payload: 1. Sign in as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling > Usage statistics**. 1. Select **Preview payload**. @@ -225,8 +226,7 @@ or if the Service Ping [cron job](../../development/internal_analytics/service_p To upload the payload manually: 1. Sign in as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Metrics and profiling > Usage statistics**. 1. Select **Download payload**. 1. Save the JSON file. diff --git a/doc/administration/settings/user_and_ip_rate_limits.md b/doc/administration/settings/user_and_ip_rate_limits.md index 22b16d01394..1f6cb1af814 100644 --- a/doc/administration/settings/user_and_ip_rate_limits.md +++ b/doc/administration/settings/user_and_ip_rate_limits.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User and IP rate limits **(FREE SELF)** @@ -31,8 +30,7 @@ counted as web traffic. To enable the unauthenticated request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Select **Enable unauthenticated API request rate limit**. @@ -46,8 +44,7 @@ To enable the unauthenticated request rate limit: To enable the unauthenticated request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Select **Enable unauthenticated web request rate limit**. @@ -61,8 +58,7 @@ To enable the unauthenticated request rate limit: To enable the authenticated API request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Select **Enable authenticated API request rate limit**. @@ -76,8 +72,7 @@ To enable the authenticated API request rate limit: To enable the unauthenticated request rate limit: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Select **Enable authenticated web request rate limit**. @@ -96,8 +91,7 @@ plain-text body, which by default is `Retry later`. To use a custom response: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. In the **Plain-text response to send to clients that hit a rate limit** text box, @@ -111,8 +105,7 @@ To reduce timeouts, the `project/:id/jobs` endpoint has a default [rate limit](. To modify the maximum number of requests: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Network**. 1. Expand **User and IP rate limits**. 1. Update the **Maximum authenticated requests to `project/:id/jobs` per minute** value. diff --git a/doc/administration/settings/visibility_and_access_controls.md b/doc/administration/settings/visibility_and_access_controls.md index 11652d8ee9a..671d0a70bd9 100644 --- a/doc/administration/settings/visibility_and_access_controls.md +++ b/doc/administration/settings/visibility_and_access_controls.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Control access and visibility **(FREE SELF)** @@ -13,8 +12,7 @@ specific controls on branches, projects, snippets, groups, and more. To access the visibility and access control options: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -25,8 +23,7 @@ Instance-level protections for project creation define which roles can on the instance. To alter which roles have permission to create projects: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. For **Default project creation protection**, select the desired roles: @@ -42,8 +39,7 @@ on the instance. To alter which roles have permission to create projects: By default both administrators and anyone with the **Owner** role can delete a project. To restrict project deletion to only administrators: 1. Sign in to GitLab as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: @@ -80,8 +76,7 @@ then it gets automatically changed to `1` while also disabling deletion protecti To configure delayed project deletion: 1. Sign in to GitLab as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Scroll to: @@ -113,7 +108,7 @@ In GitLab 15.11 and later with the `always_perform_delayed_deletion` feature fla Alternatively, projects that are marked for removal can be deleted immediately. To do so: -1. [Restore the project](../../user/project/settings/index.md#restore-a-project). +1. [Restore the project](../../user/project/settings/migrate_projects.md#restore-a-project). 1. Delete the project as described in the [Administering Projects page](../admin_area.md#administering-projects). @@ -122,8 +117,7 @@ Alternatively, projects that are marked for removal can be deleted immediately. To set the default [visibility levels for new projects](../../user/public_access.md): 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default project visibility: @@ -141,8 +135,7 @@ For more details on project visibility, see To set the default visibility levels for new [snippets](../../user/snippets.md): 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default snippet visibility. @@ -156,8 +149,7 @@ For more details on snippet visibility, read To set the default visibility levels for new groups: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired default group visibility: @@ -173,6 +165,7 @@ For more details on group visibility, see > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124649) in GitLab 16.3 to prevent restricting default project and group visibility, [with a flag](../feature_flags.md) named `prevent_visibility_restriction`. Disabled by default. > - `prevent_visibility_restriction` [enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131203) by default in GitLab 16.4. +> - The flag `prevent_visibility_restriction` was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/433280) in GitLab 16.7. When restricting visibility levels, consider how these restrictions interact with permissions for subgroups and projects that inherit their visibility from @@ -181,8 +174,7 @@ the item you're changing. To restrict visibility levels for groups, projects, snippets, and selected pages: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. @@ -211,8 +203,7 @@ The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. Select the desired Git access protocols: @@ -298,8 +289,7 @@ include the `10.0.0.0/24` range. To add a IP address range to the group-level allowlist: 1. Sign in to GitLab as a user with Administrator access level. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In **Globally-allowed IP ranges**, provide a list of IP address ranges. This list: diff --git a/doc/administration/sidekiq/extra_sidekiq_processes.md b/doc/administration/sidekiq/extra_sidekiq_processes.md index 89de4cd6cf3..bde60d17f0c 100644 --- a/doc/administration/sidekiq/extra_sidekiq_processes.md +++ b/doc/administration/sidekiq/extra_sidekiq_processes.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run multiple Sidekiq processes **(FREE SELF)** @@ -48,9 +48,8 @@ to all available queues: To view the Sidekiq processes in GitLab: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Monitoring > Background Jobs**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Monitoring > Background Jobs**. ## Concurrency diff --git a/doc/administration/sidekiq/index.md b/doc/administration/sidekiq/index.md index 0a7974c9622..6a6412a9944 100644 --- a/doc/administration/sidekiq/index.md +++ b/doc/administration/sidekiq/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure an external Sidekiq instance **(FREE SELF)** @@ -200,9 +200,9 @@ To set up multiple Sidekiq nodes: sudo gitlab-ctl reconfigure ``` -## Configure the Container Registry when using an external Sidekiq +## Configure the container registry when using an external Sidekiq -If you're using the Container Registry and it's running on a different +If you're using the container registry and it's running on a different node than Sidekiq, follow the steps below. 1. Edit `/etc/gitlab/gitlab.rb`, and configure the registry URL: @@ -217,7 +217,7 @@ node than Sidekiq, follow the steps below. sudo gitlab-ctl reconfigure ``` -1. In the instance where Container Registry is hosted, copy the `registry.key` +1. In the instance where container registry is hosted, copy the `registry.key` file to the Sidekiq node. ## Configure the Sidekiq metrics server diff --git a/doc/administration/sidekiq/processing_specific_job_classes.md b/doc/administration/sidekiq/processing_specific_job_classes.md index 74cbb6ca89b..26f3445f62c 100644 --- a/doc/administration/sidekiq/processing_specific_job_classes.md +++ b/doc/administration/sidekiq/processing_specific_job_classes.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Processing specific job classes diff --git a/doc/administration/sidekiq/sidekiq_health_check.md b/doc/administration/sidekiq/sidekiq_health_check.md index 74b478c1913..9da4a59dc42 100644 --- a/doc/administration/sidekiq/sidekiq_health_check.md +++ b/doc/administration/sidekiq/sidekiq_health_check.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq Health Check **(FREE SELF)** diff --git a/doc/administration/sidekiq/sidekiq_job_migration.md b/doc/administration/sidekiq/sidekiq_job_migration.md index 10a1faea850..ef79ed8eded 100644 --- a/doc/administration/sidekiq/sidekiq_job_migration.md +++ b/doc/administration/sidekiq/sidekiq_job_migration.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq job migration Rake tasks **(FREE SELF)** diff --git a/doc/administration/sidekiq/sidekiq_memory_killer.md b/doc/administration/sidekiq/sidekiq_memory_killer.md index cd69a47d283..6dcc97f2f7a 100644 --- a/doc/administration/sidekiq/sidekiq_memory_killer.md +++ b/doc/administration/sidekiq/sidekiq_memory_killer.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reducing memory use diff --git a/doc/administration/sidekiq/sidekiq_troubleshooting.md b/doc/administration/sidekiq/sidekiq_troubleshooting.md index 2990110150f..591d1e5f64d 100644 --- a/doc/administration/sidekiq/sidekiq_troubleshooting.md +++ b/doc/administration/sidekiq/sidekiq_troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Sidekiq **(FREE SELF)** @@ -641,6 +641,11 @@ indicate that additional Sidekiq processes would be beneficial. Consider [adding additional Sidekiq processes](extra_sidekiq_processes.md) to compensate for removing the `sidekiq-cluster` service. +## CPU saturation in Redis caused by Sidekiq BRPOP calls + +Sidekiq `BROP` calls can cause CPU usage to increase on Redis. +Increase the [`SIDEKIQ_SEMI_RELIABLE_FETCH_TIMEOUT` environment variable](../environment_variables.md) to improve CPU usage on Redis. + ## Related topics - [Elasticsearch workers overload Sidekiq](../../integration/advanced_search/elasticsearch_troubleshooting.md#elasticsearch-workers-overload-sidekiq). diff --git a/doc/administration/silent_mode/index.md b/doc/administration/silent_mode/index.md index 4f68a765585..f72b715ac5e 100644 --- a/doc/administration/silent_mode/index.md +++ b/doc/administration/silent_mode/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Silent Mode **(FREE SELF)** @@ -25,8 +25,7 @@ There are multiple ways to enable Silent Mode: - **Web UI** - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**.. 1. On the left sidebar, select **Settings > General**. 1. Expand **Silent Mode**, and toggle **Enable Silent Mode**. 1. Changes are saved immediately. @@ -55,8 +54,7 @@ There are multiple ways to disable Silent Mode: - **Web UI** - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Silent Mode**, and toggle **Enable Silent Mode**. 1. Changes are saved immediately. @@ -93,7 +91,7 @@ Outbound communications from the following features are silenced by Silent Mode. | [Executable integrations](../../user/project/integrations/index.md) | The integrations are not executed. | | [Service Desk](../../user/project/service_desk/index.md) | Incoming emails still raise issues, but the users who sent the emails to Service Desk are not notified of issue creation or comments on their issues. | | Outbound emails | | -| Outbound HTTP requests | Many HTTP requests are blocked where features are not blocked or skipped explicitly. These may produce errors. If a particular error is problematic for testing during Silent Mode, please consult [GitLab Support](https://about.gitlab.com/support/). | +| Outbound HTTP requests | Many HTTP requests are blocked where features are not blocked or skipped explicitly. These may produce errors. If a particular error is problematic for testing during Silent Mode, consult [GitLab Support](https://about.gitlab.com/support/). | ### Outbound communications that are not silenced diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md index 06bf4978a6b..5e303fc79a8 100644 --- a/doc/administration/smime_signing_email.md +++ b/doc/administration/smime_signing_email.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Signing outgoing email with S/MIME **(FREE SELF)** diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index b59432b0b9e..6b53c2b1d10 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Snippets **(FREE SELF)** diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index 203f59b60f7..258af6b045b 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -1,8 +1,7 @@ --- stage: Create group: IDE -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # External storage for static objects **(FREE SELF)** @@ -16,10 +15,9 @@ storage such as a content delivery network (CDN). To configure external storage for static objects: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Repository**. -1. Expand the **External storage for repository static objects** section. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Repository**. +1. Expand **External storage for repository static objects**. 1. Enter the base URL and an arbitrary token. When you [set up external storage](#set-up-external-storage), use a script that sets these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`. 1. Select **Save changes**. diff --git a/doc/administration/system_hooks.md b/doc/administration/system_hooks.md index daee7b61670..57a23a25a08 100644 --- a/doc/administration/system_hooks.md +++ b/doc/administration/system_hooks.md @@ -1,8 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # System hooks **(FREE SELF)** @@ -53,9 +52,8 @@ For push and tag events, the same structure and deprecations are followed as [pr To create a system hook: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **System Hooks**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **System Hooks**. 1. Select **Add new webhook**. 1. Provide the **URL** and **Secret Token**. 1. Select the checkbox next to each optional **Trigger** you want to enable. diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index bf0774478ee..0a993542847 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform state administration **(FREE SELF)** @@ -36,7 +36,7 @@ When Terraform state administration is disabled: To disable Terraform administration, follow the steps below according to your installation. -Prerequisite: +Prerequisites: - You must be an administrator. diff --git a/doc/administration/timezone.md b/doc/administration/timezone.md index e0f70cecb43..c5f4fed4ef8 100644 --- a/doc/administration/timezone.md +++ b/doc/administration/timezone.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Changing your time zone **(FREE SELF)** diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md index 32b07d8c4af..b9e77e72c65 100644 --- a/doc/administration/troubleshooting/diagnostics_tools.md +++ b/doc/administration/troubleshooting/diagnostics_tools.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Diagnostics tools **(FREE SELF)** diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 01c75c32366..57b2df000b1 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Rails Console Cheat Sheet **(FREE SELF)** @@ -56,11 +56,11 @@ This content has been moved to [Activate GitLab EE with a license file or key](. ### Registry Disk Space Usage by Project -Find this content in the [Container Registry troubleshooting documentation](../packages/container_registry.md#registry-disk-space-usage-by-project). +Find this content in the [container registry troubleshooting documentation](../packages/container_registry.md#registry-disk-space-usage-by-project). ### Run the Cleanup policy now -Find this content in the [Container Registry troubleshooting documentation](../packages/container_registry.md#run-the-cleanup-policy-now). +Find this content in the [container registry troubleshooting documentation](../packages/container_registry.md#run-the-cleanup-policy-now). ## Sidekiq diff --git a/doc/administration/troubleshooting/index.md b/doc/administration/troubleshooting/index.md index 8be6abc180d..a59429f1aee 100644 --- a/doc/administration/troubleshooting/index.md +++ b/doc/administration/troubleshooting/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting a GitLab installation **(FREE SELF)** @@ -14,7 +14,7 @@ for in this list, you should search the documentation. ## Troubleshooting guides -- [SSL](ssl.md) +- [SSL](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html) - [Geo](../geo/replication/troubleshooting.md) - [SAML](../../user/group/saml_sso/troubleshooting.md) - [Kubernetes cheat sheet](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html) @@ -47,7 +47,7 @@ who are aware of the risks. - [Troubleshooting Kubernetes](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html) - [Troubleshooting PostgreSQL](postgresql.md) - [Guide to test environments](test_environments.md) (for Support Engineers) -- [Troubleshooting SSL](ssl.md) +- [Troubleshooting SSL](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html) - Related links: - [Repairing and recovering broken Git repositories](https://git.seveas.net/repairing-and-recovering-broken-git-repositories.html) - [Testing with OpenSSL](https://www.feistyduck.com/library/openssl-cookbook/online/testing-with-openssl/index.html) diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md index ae0ef44f0b1..6255cae3a30 100644 --- a/doc/administration/troubleshooting/linux_cheat_sheet.md +++ b/doc/administration/troubleshooting/linux_cheat_sheet.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linux cheat sheet **(FREE SELF)** diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index e7965d451b6..315a68fb126 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL **(FREE SELF)** diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md deleted file mode 100644 index bf8e6b45fde..00000000000 --- a/doc/administration/troubleshooting/ssl.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html' -remove_date: '2023-10-27' ---- - -This document was moved to [another location](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html). - -<!-- This redirect file can be deleted after <2023-01-25>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/administration/troubleshooting/test_environments.md b/doc/administration/troubleshooting/test_environments.md index 63ccbce9480..1d148a654b8 100644 --- a/doc/administration/troubleshooting/test_environments.md +++ b/doc/administration/troubleshooting/test_environments.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Apps for a testing environment **(FREE SELF)** diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 6259304d68e..31d0781ee79 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads administration **(FREE SELF)** diff --git a/doc/administration/user_cohorts.md b/doc/administration/user_cohorts.md index c849d3115d2..fb9adc67dc0 100644 --- a/doc/administration/user_cohorts.md +++ b/doc/administration/user_cohorts.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cohorts **(FREE SELF)** @@ -34,7 +34,6 @@ How do we measure the activity of users? GitLab considers a user active if: To view user cohorts: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select the **Cohorts** tab. diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index cb796ccb993..ec6dab525ac 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Modify global user settings **(FREE SELF)** diff --git a/doc/administration/whats-new.md b/doc/administration/whats-new.md index 6d186ef0af5..8af9387f821 100644 --- a/doc/administration/whats-new.md +++ b/doc/administration/whats-new.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: For assistance with this What's new page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this What's new page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # What's new **(FREE ALL)** @@ -31,9 +31,8 @@ To access the **What's new** feature: You can configure **What's new** to display features based on the tier, or you can hide it. To configure it: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Preferences**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Preferences**. 1. Expand **What's new**, and choose one of the following options: | Option | Description | diff --git a/doc/administration/wikis/index.md b/doc/administration/wikis/index.md index fd7c1825e8d..abbb968e35d 100644 --- a/doc/administration/wikis/index.md +++ b/doc/administration/wikis/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Wiki settings **(FREE SELF)** diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 201a7161c56..3d3bddb3970 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Group and project access requests API **(FREE ALL)** diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index e5d60587dea..6240063e401 100644 --- a/doc/api/admin_sidekiq_queues.md +++ b/doc/api/admin_sidekiq_queues.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq queues administration API **(FREE SELF)** diff --git a/doc/api/alert_management_alerts.md b/doc/api/alert_management_alerts.md index 5da77d08605..1b213640f6c 100644 --- a/doc/api/alert_management_alerts.md +++ b/doc/api/alert_management_alerts.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Alert Management alerts API **(FREE ALL)** diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 76c91b00eb9..6e0963c5325 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # REST API resources **(FREE ALL)** @@ -34,13 +34,13 @@ The following API resources are available in the project context: | [Conan distributions](packages/conan.md) | `/projects/:id/packages/conan` (also available standalone) | | [Debian distributions](packages/debian_project_distributions.md) | `/projects/:id/debian_distributions` (also available for groups) | | [Debian packages](packages/debian.md) | `/projects/:id/packages/debian` (also available for groups) | -| [Dependencies](dependencies.md) **(ULTIMATE ALL)** | `/projects/:id/dependencies` | +| [Dependencies](dependencies.md) | `/projects/:id/dependencies` | | [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | | [Deploy tokens](deploy_tokens.md) | `/projects/:id/deploy_tokens` (also available for groups and standalone) | | [Deployments](deployments.md) | `/projects/:id/deployments` | | [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) | -| [Draft Notes](draft_notes.md) (comments) | `/projects/:id/merge_requests/.../draft_notes` -| [Emoji reactions](emoji_reactions.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | +| [Draft Notes](draft_notes.md) (comments) | `/projects/:id/merge_requests/.../draft_notes` +| [Emoji reactions](emoji_reactions.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | | [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) | @@ -56,14 +56,14 @@ The following API resources are available in the project context: | [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 ALL)** | `/projects/:id/iterations` (also available for groups) | +| [Iterations](iterations.md) | `/projects/:id/iterations` (also available for groups) | | [Project CI/CD job token scope](project_job_token_scopes.md) | `/projects/:id/job_token_scope` | | [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | | [Jobs Artifacts](job_artifacts.md) | `/projects/:id/jobs/:job_id/artifacts` | | [Labels](labels.md) | `/projects/:id/labels` | | [Maven repository](packages/maven.md) | `/projects/:id/packages/maven` (also available for groups and standalone) | | [Members](members.md) | `/projects/:id/members` (also available for groups) | -| [Merge request approvals](merge_request_approvals.md) **(PREMIUM ALL)** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | +| [Merge request approvals](merge_request_approvals.md) | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | | [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | | [Merge trains](merge_trains.md) | `/projects/:id/merge_trains` | | [Metadata](metadata.md) | `/metadata` | @@ -82,7 +82,7 @@ The following API resources are available in the project context: | [Project milestones](milestones.md) | `/projects/:id/milestones` | | [Project snippets](project_snippets.md) | `/projects/:id/snippets` | | [Project templates](project_templates.md) | `/projects/:id/templates` | -| [Project vulnerabilities](project_vulnerabilities.md) **(ULTIMATE ALL)** | `/projects/:id/vulnerabilities` | +| [Project vulnerabilities](project_vulnerabilities.md). | `/projects/:id/vulnerabilities` | | [Project wikis](wikis.md) | `/projects/:id/wikis` | | [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | | [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | @@ -103,10 +103,10 @@ The following API resources are available in the project context: | [Tags](tags.md) | `/projects/:id/repository/tags` | | [Terraform modules](packages/terraform-modules.md) | `/projects/:id/packages/terraform/modules` (also available standalone) | | [User-starred metrics dashboards](metrics_user_starred_dashboards.md ) | `/projects/:id/metrics/user_starred_dashboards` | -| [Visual Review discussions](visual_review_discussions.md) **(PREMIUM ALL)** | `/projects/:id/merge_requests/:merge_request_id/visual_review_discussions` | -| [Vulnerabilities](vulnerabilities.md) **(ULTIMATE ALL)** | `/vulnerabilities/:id` | -| [Vulnerability exports](vulnerability_exports.md) **(ULTIMATE ALL)** | `/projects/:id/vulnerability_exports` | -| [Vulnerability findings](vulnerability_findings.md) **(ULTIMATE ALL)** | `/projects/:id/vulnerability_findings` | +| [Visual Review discussions](visual_review_discussions.md) | `/projects/:id/merge_requests/:merge_request_id/visual_review_discussions` | +| [Vulnerabilities](vulnerabilities.md) | `/vulnerabilities/:id` | +| [Vulnerability exports](vulnerability_exports.md) | `/projects/:id/vulnerability_exports` | +| [Vulnerability findings](vulnerability_findings.md) | `/projects/:id/vulnerability_findings` | ## Group resources @@ -120,19 +120,19 @@ The following API resources are available in the group context: | [Debian distributions](packages/debian_group_distributions.md) | `/groups/:id/-/packages/debian` (also available for projects) | | [Deploy tokens](deploy_tokens.md) | `/groups/:id/deploy_tokens` (also available for projects and standalone) | | [Discussions](discussions.md) (comments and threads) | `/groups/:id/epics/.../discussions` (also available for projects) | -| [Epic issues](epic_issues.md) **(PREMIUM ALL)** | `/groups/:id/epics/.../issues` | -| [Epic links](epic_links.md) **(PREMIUM ALL)** | `/groups/:id/epics/.../epics` | -| [Epics](epics.md) **(PREMIUM ALL)** | `/groups/:id/epics` | +| [Epic issues](epic_issues.md) | `/groups/:id/epics/.../issues` | +| [Epic links](epic_links.md) | `/groups/:id/epics/.../epics` | +| [Epics](epics.md) | `/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 ALL)** | `/groups/:id/iterations` (also available for projects) | +| [Group iterations](group_iterations.md) | `/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 releases](group_releases.md) | `/groups/:id/releases` | -| [Group SSH certificates](group_ssh_certificates.md) **(PREMIUM ALL)** | `/groups/:id/ssh_certificates` | -| [Group wikis](group_wikis.md) **(PREMIUM ALL)** | `/groups/:id/wikis` | +| [Group SSH certificates](group_ssh_certificates.md) | `/groups/:id/ssh_certificates` | +| [Group wikis](group_wikis.md) | `/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) | @@ -151,31 +151,31 @@ The following API resources are available outside of project and group contexts | Resource | Available endpoints | |:---------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------| -| [Appearance](appearance.md) **(FREE SELF)** | `/application/appearance` | +| [Appearance](appearance.md) | `/application/appearance` | | [Applications](applications.md) | `/applications` | -| [Audit Events](audit_events.md) **(PREMIUM SELF)** | `/audit_events` | +| [Audit Events](audit_events.md) | `/audit_events` | | [Avatar](avatar.md) | `/avatar` | | [Broadcast messages](broadcast_messages.md) | `/broadcast_messages` | | [Code snippets](snippets.md) | `/snippets` | | [Code Suggestions](code_suggestions.md) | `/code_suggestions` | | [Custom attributes](custom_attributes.md) | `/users/:id/custom_attributes` (also available for groups and projects) | -| [Dependency list exports](dependency_list_export.md) **(ULTIMATE ALL)** | `/pipelines/:id/dependency_list_exports`, `/projects/:id/dependency_list_exports`, `/groups/:id/dependency_list_exports`, `/security/dependency_list_exports/:id`, `/security/dependency_list_exports/:id/download` | +| [Dependency list exports](dependency_list_export.md) | `/pipelines/:id/dependency_list_exports`, `/projects/:id/dependency_list_exports`, `/groups/:id/dependency_list_exports`, `/security/dependency_list_exports/:id`, `/security/dependency_list_exports/:id/download` | | [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | | [Deploy tokens](deploy_tokens.md) | `/deploy_tokens` (also available for projects and groups) | | [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` | +| [Geo Nodes](geo_nodes.md) | `/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` | +| [Group repository storage moves](group_repository_storage_moves.md) | `/group_repository_storage_moves` | | [Import repository from GitHub](import.md#import-repository-from-github) | `/import/github` | | [Import repository from Bitbucket Server](import.md#import-repository-from-bitbucket-server) | `/import/bitbucket_server` | -| [Instance clusters](instance_clusters.md) **(FREE SELF)** | `/admin/clusters` | -| [Instance-level CI/CD variables](instance_level_ci_variables.md) **(FREE SELF)** | `/admin/ci/variables` | +| [Instance clusters](instance_clusters.md) | `/admin/clusters` | +| [Instance-level CI/CD variables](instance_level_ci_variables.md) | `/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` | +| [License](license.md) | `/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` | @@ -184,15 +184,15 @@ The following API resources are available outside of project and group contexts | [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` | +| [Project repository storage moves](project_repository_storage_moves.md) | `/project_repository_storage_moves` | | [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` | +| [Settings](settings.md) | `/application/settings` | +| [Sidekiq metrics](sidekiq_metrics.md) | `/sidekiq` | +| [Sidekiq queues administration](admin_sidekiq_queues.md) | `/admin/sidekiq/queues/:queue_name` | +| [Snippet repository storage moves](snippet_repository_storage_moves.md) | `/snippet_repository_storage_moves` | | [Statistics](statistics.md) | `/application/statistics` | | [Suggestions](suggestions.md) | `/suggestions` | | [System hooks](system_hooks.md) | `/hooks` | diff --git a/doc/api/appearance.md b/doc/api/appearance.md index d2a2f0687b2..bf08581639b 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Appearance API **(FREE SELF)** diff --git a/doc/api/applications.md b/doc/api/applications.md index 64516465cfa..be526aec8f8 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Applications API **(FREE ALL)** diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 0e60fdbcd0a..2676a343a15 100644 --- a/doc/api/audit_events.md +++ b/doc/api/audit_events.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit Events API **(PREMIUM ALL)** diff --git a/doc/api/avatar.md b/doc/api/avatar.md index 72dff3c1174..fe6ad8f589f 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Avatar API **(FREE ALL)** diff --git a/doc/api/boards.md b/doc/api/boards.md index 34aa7d6e68a..ef4a0838876 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project issue boards API **(FREE ALL)** diff --git a/doc/api/branches.md b/doc/api/branches.md index cd0266a05f1..f5fe7d0526c 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Branches API **(FREE ALL)** diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index 35afd2ad164..8c4134e13d4 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Broadcast Messages API **(FREE SELF)** diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md index 0f9df4eba31..1d7556f863a 100644 --- a/doc/api/bulk_imports.md +++ b/doc/api/bulk_imports.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group and project migration by direct transfer API **(FREE ALL)** diff --git a/doc/api/cluster_agents.md b/doc/api/cluster_agents.md index 552c549e3b9..e1241eb572c 100644 --- a/doc/api/cluster_agents.md +++ b/doc/api/cluster_agents.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Agents API **(FREE ALL)** diff --git a/doc/api/code_suggestions.md b/doc/api/code_suggestions.md index d9fc4de3c8e..91c5c988acd 100644 --- a/doc/api/code_suggestions.md +++ b/doc/api/code_suggestions.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Suggestions API @@ -19,7 +19,9 @@ POST /code_suggestions/tokens ``` ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/code_suggestions/tokens" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/code_suggestions/tokens" ``` Example response: @@ -38,10 +40,13 @@ Example response: > - Requirement to generate a JWT before calling this endpoint was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127863) in GitLab 16.3. FLAG: -On self-managed GitLab, by default this feature is not available. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `code_suggestions_completion_api`. On GitLab.com, this feature is not available. This feature is not ready for production use. +NOTE: +This endpoint rate-limits each user to 60 requests per 1-minute window. + Use the AI abstraction layer to generate code completions. ```plaintext @@ -51,7 +56,10 @@ POST /code_suggestions/completions Requests to this endpoint are proxied directly to the [model gateway](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist#completions). The documentation for the endpoint is currently the SSoT for named parameters. ```shell -curl --request POST --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" --data "<JSON_BODY>" https://gitlab.example.com/api/v4/code_suggestions/completions +curl --request POST \ + --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \ + --data "<JSON_BODY>" \ + --url "https://gitlab.example.com/api/v4/code_suggestions/completions" ``` Example body: diff --git a/doc/api/commits.md b/doc/api/commits.md index 94cdaaa191d..e3350931446 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Commits API **(FREE ALL)** @@ -43,7 +43,8 @@ GET /projects/:id/repository/commits | `trailers` | boolean | no | Parse and include [Git trailers](https://git-scm.com/docs/git-interpret-trailers) for every commit | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits" ``` Example response: @@ -65,7 +66,9 @@ Example response: "parent_ids": [ "6104942438c14ec7bd21c6cd5bd995272b3faff6" ], - "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746" + "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746", + "trailers": {}, + "extended_trailers": {} }, { "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6", @@ -76,11 +79,13 @@ Example response: "committer_name": "ExampleName", "committer_email": "user@example.com", "created_at": "2021-09-20T09:06:12.201+00:00", - "message": "Sanitize for network graph", + "message": "Sanitize for network graph\nCc: John Doe <johndoe@gitlab.com>\nCc: Jane Doe <janedoe@gitlab.com>", "parent_ids": [ "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba" ], - "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746" + "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746", + "trailers": { "Cc": "Jane Doe <janedoe@gitlab.com>" }, + "extended_trailers": { "Cc": ["John Doe <johndoe@gitlab.com>", "Jane Doe <janedoe@gitlab.com>"] } } ] ``` @@ -152,8 +157,11 @@ PAYLOAD=$(cat << 'JSON' } JSON ) -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ - --data "$PAYLOAD" "https://gitlab.example.com/api/v4/projects/1/repository/commits" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-Type: application/json" \ + --data "$PAYLOAD" \ + --url "https://gitlab.example.com/api/v4/projects/1/repository/commits" ``` Example response: @@ -227,7 +235,8 @@ Parameters: | `stats` | boolean | no | Include commit stats. Default is true | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/main" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main" ``` Example response: @@ -282,7 +291,8 @@ Parameters: | `type` | string | no | The scope of commits. Possible values `branch`, `tag`, `all`. Default is `all`. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all" ``` Example response: @@ -316,8 +326,10 @@ Parameters: | `message` | string | no | A custom commit message to use for the new commit. [Introduced in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62481) ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ - --form "branch=main" "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/cherry_pick" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "branch=main" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/cherry_pick" ``` Example response: @@ -388,8 +400,10 @@ Parameters: | `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) in GitLab 13.3 | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=main" \ - "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "branch=main" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert" ``` Example response: @@ -455,7 +469,8 @@ Parameters: | `unidiff` | boolean | no | Present diffs in the [unified diff](https://www.gnu.org/software/diffutils/manual/html_node/Detailed-Unified.html) format. Default is false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130610) in GitLab 16.5. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/diff" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/diff" ``` Example response: @@ -491,7 +506,8 @@ Parameters: | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/comments" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/comments" ``` Example response: @@ -548,9 +564,13 @@ POST /projects/:id/repository/commits/:sha/comments | `line_type` | string | no | The line type. Takes `new` or `old` as arguments | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ - --form "note=Nice picture\!" --form "path=README.md" --form "line=11" --form "line_type=new" \ - "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "note=Nice picture\!" \ + --form "path=README.md" \ + --form "line=11" \ + --form "line_type=new" \ + --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments" ``` Example response: @@ -589,7 +609,8 @@ Parameters: | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/4604744a1c64de00ff62e1e8a6766919923d2b41/discussions" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/4604744a1c64de00ff62e1e8a6766919923d2b41/discussions" ``` Example response: @@ -652,7 +673,8 @@ GET /projects/:id/repository/commits/:sha/statuses | `all` | boolean | no | Return all statuses, not only the latest ones ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses" ``` Example response: @@ -730,7 +752,9 @@ POST /projects/:id/statuses/:sha | `pipeline_id` | integer | no | The ID of the pipeline to set status. Use in case of several pipeline on same SHA. ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success" ``` Example response: @@ -774,7 +798,8 @@ GET /projects/:id/repository/commits/:sha/merge_requests | `sha` | string | yes | The commit SHA ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests" ``` Example response: @@ -846,7 +871,8 @@ Parameters: | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/repository/commits/da738facbc19eb2fc2cef57c49be0e6038570352/signature" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/1/repository/commits/da738facbc19eb2fc2cef57c49be0e6038570352/signature" ``` Example response if commit is GPG signed: diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 35b74965d2e..ab8be6abab7 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -1,14 +1,14 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Container Registry API **(FREE ALL)** +# Container registry API **(FREE ALL)** > The use of `CI_JOB_TOKEN` scoped to the current project was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49750) in GitLab 13.12. -This API documentation is about the [GitLab Container Registry](../user/packages/container_registry/index.md). +This API documentation is about the [GitLab container registry](../user/packages/container_registry/index.md). When the `ci_job_token_scope` feature flag is enabled (it is **disabled by default**), you can use the below endpoints from a CI/CD job, by passing the `$CI_JOB_TOKEN` variable as the `JOB-TOKEN` header. @@ -29,11 +29,11 @@ To disable it: Feature.disable(:ci_job_token_scope) ``` -## Change the visibility of the Container Registry +## Change the visibility of the container registry > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18792) in GitLab 14.2. -This controls who can view the Container Registry. +This controls who can view the container registry. ```plaintext PUT /projects/:id/ @@ -42,21 +42,21 @@ PUT /projects/:id/ | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) accessible by the authenticated user. | -| `container_registry_access_level` | string | no | The desired visibility of the Container Registry. One of `enabled` (default), `private`, or `disabled`. | +| `container_registry_access_level` | string | no | The desired visibility of the container registry. One of `enabled` (default), `private`, or `disabled`. | Descriptions of the possible values for `container_registry_access_level`: -- **enabled** (Default): The Container Registry is visible to everyone with access to the project. -If the project is public, the Container Registry is also public. If the project is internal or -private, the Container Registry is also internal or private. +- **enabled** (Default): The container registry is visible to everyone with access to the project. +If the project is public, the container registry is also public. If the project is internal or +private, the container registry is also internal or private. -- **private**: The Container Registry is visible only to project members with Reporter role or -higher. This behavior is similar to that of a private project with Container Registry visibility set +- **private**: The container registry is visible only to project members with Reporter role or +higher. This behavior is similar to that of a private project with container registry visibility set to **enabled**. -- **disabled**: The Container Registry is disabled. +- **disabled**: The container registry is disabled. -See the [Container Registry visibility permissions](../user/packages/container_registry/index.md#container-registry-visibility-permissions) +See the [container registry visibility permissions](../user/packages/container_registry/index.md#container-registry-visibility-permissions) for more details about the permissions that this setting grants to users. ```shell @@ -80,7 +80,7 @@ Example response: } ``` -## Container Registry pagination +## Container registry pagination By default, `GET` requests return 20 results at a time because the API results are [paginated](rest/index.md#pagination). @@ -116,7 +116,8 @@ Example response: "project_id": 9, "location": "gitlab.example.com:5000/group/project", "created_at": "2019-01-10T13:38:57.391Z", - "cleanup_policy_started_at": "2020-01-10T15:40:57.391Z" + "cleanup_policy_started_at": "2020-01-10T15:40:57.391Z", + "status": null }, { "id": 2, @@ -125,7 +126,8 @@ Example response: "project_id": 9, "location": "gitlab.example.com:5000/group/project/releases", "created_at": "2019-01-10T13:39:08.229Z", - "cleanup_policy_started_at": "2020-08-17T03:12:35.489Z" + "cleanup_policy_started_at": "2020-08-17T03:12:35.489Z", + "status": "delete_ongoing" } ] ``` @@ -189,7 +191,7 @@ GET /registry/repositories/:id | `id` | integer/string | yes | The ID of the registry repository accessible by the authenticated user. | | `tags` | boolean | no | If the parameter is included as `true`, the response includes an array of `"tags"`. | | `tags_count` | boolean | no | If the parameter is included as `true`, the response includes `"tags_count"`. | -| `size` | boolean | no | If the parameter is included as `true`, the response includes `"size"`. This is the deduplicated size of all images within the repository. Deduplication eliminates extra copies of identical data. For example, if you upload the same image twice, the Container Registry stores only one copy. This field is only available on GitLab.com for repositories created after `2021-11-04`. | +| `size` | boolean | no | If the parameter is included as `true`, the response includes `"size"`. This is the deduplicated size of all images within the repository. Deduplication eliminates extra copies of identical data. For example, if you upload the same image twice, the container registry stores only one copy. This field is only available on GitLab.com for repositories created after `2021-11-04`. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -215,7 +217,8 @@ Example response: "location": "gitlab.example.com:5000/group/project:0.0.1" } ], - "size": 2818413 + "size": 2818413, + "status": "delete_scheduled" } ``` @@ -337,7 +340,7 @@ This action doesn't delete blobs. To delete them and recycle disk space, Delete registry repository tags in bulk based on given criteria. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Use the Container Registry API to delete all tags except *](https://youtu.be/Hi19bKe_xsg). +For an overview, see [Use the container registry API to delete all tags except *](https://youtu.be/Hi19bKe_xsg). ```plaintext DELETE /projects/:id/registry/repositories/:repository_id/tags @@ -373,8 +376,8 @@ action doesn't delete blobs. To delete them and recycle disk space, WARNING: The number of tags deleted by this API is limited on GitLab.com -because of the scale of the Container Registry there. -If your Container Registry has a large number of tags to delete, +because of the scale of the container registry there. +If your container registry has a large number of tags to delete, only some of them are deleted, and you might need to call this API multiple times. To schedule tags for automatic deletion, use a [cleanup policy](../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy) instead. @@ -423,7 +426,7 @@ curl --request DELETE --data-urlencode 'name_regex_delete=dev-.+' \ ## Instance-wide endpoints Beside the group- and project-specific GitLab APIs explained above, -the Container Registry has its own endpoints. +the container registry has its own endpoints. To query those, follow the Registry's built-in mechanism to obtain and use an [authentication token](https://distribution.github.io/distribution/spec/auth/token/). diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index 5ce2aa34744..735c4ebb239 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom Attributes API **(FREE SELF)** diff --git a/doc/api/database_migrations.md b/doc/api/database_migrations.md index d7aea7ad57e..0786e801b9c 100644 --- a/doc/api/database_migrations.md +++ b/doc/api/database_migrations.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database migrations API **(FREE SELF)** diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 388ea3c71fc..5b0b92467c0 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependencies API **(ULTIMATE ALL)** diff --git a/doc/api/dependency_list_export.md b/doc/api/dependency_list_export.md index db43ea238c1..d53f997a363 100644 --- a/doc/api/dependency_list_export.md +++ b/doc/api/dependency_list_export.md @@ -1,25 +1,17 @@ --- stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency list export API **(ULTIMATE ALL)** Every call to this endpoint requires authentication. -## Create a pipeline-level dependency list export **(EXPERIMENT)** +## Create a pipeline-level dependency list export -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333463) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `merge_sbom_api`. Enabled by default. This feature is an [Experiment](../policy/experiment-beta-support.md#experiment). - -FLAG: -On self-managed GitLab, by default this feature is available. -To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `merge_sbom_api`. -On GitLab.com, this feature is available. - -WARNING: -This feature is an [Experiment](../policy/experiment-beta-support.md#experiment) -and subject to change without notice. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333463) in GitLab 16.4 [with a flag](../administration/feature_flags.md) named `merge_sbom_api`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425312) in GitLab 16.7. Feature flag `merge_sbom_api` removed. Create a new CycloneDX JSON export for all the project dependencies detected in a pipeline. diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index 1ffd959d18d..b187a939236 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Proxy API **(FREE ALL)** diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index ee568b41832..d4b31991af4 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy keys API **(FREE ALL)** diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index c0e6a57a9d7..aa8460872fc 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy Tokens API **(FREE ALL)** diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 2dbc4bd0831..ca2f5f78e38 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deployments API **(FREE ALL)** diff --git a/doc/api/discussions.md b/doc/api/discussions.md index dac2c886166..8640f3b45c6 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Discussions API **(FREE ALL)** @@ -982,7 +981,7 @@ Parameters for multiline comments only: A line code is of the form `<SHA>_<old>_<new>`, like this: `adc83b19e793491b1c6ea0fd8b46cd9f32e292fc_5_5` -- `<SHA>` is the SHA1 hash of the filename. +- `<SHA>` is the SHA1 hash of the file name. - `<old>` is the line number before the change. - `<new>` is the line number after the change. @@ -1010,7 +1009,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ Resolve or unresolve a thread of discussion in a merge request. -Prerequisite: +Prerequisites: - You must have at least the Developer role, or be the author of the change being reviewed. diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 1af21e84f5e..93ce6a1de30 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -1,8 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DevOps Research and Assessment (DORA) key metrics API **(ULTIMATE ALL)** diff --git a/doc/api/draft_notes.md b/doc/api/draft_notes.md index 38ca572f91f..753f2064ff8 100644 --- a/doc/api/draft_notes.md +++ b/doc/api/draft_notes.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Draft Notes API **(FREE ALL)** @@ -161,7 +161,8 @@ PUT /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id | `position[y]` | float | no | For `image` diff notes, Y coordinate. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5" ``` @@ -180,7 +181,8 @@ DELETE /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_i | `merge_request_iid` | integer | yes | The IID of a project merge request. ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request DELETE \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5" ``` @@ -199,7 +201,8 @@ PUT /projects/:id/merge_requests/:merge_request_iid/draft_notes/:draft_note_id/p | `merge_request_iid` | integer | yes | The IID of a project merge request. ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/5/publish" ``` @@ -217,6 +220,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/draft_notes/bulk_publish | `merge_request_iid` | integer | yes | The IID of a project merge request. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/14/merge_requests/11/draft_notes/bulk_publish" ``` diff --git a/doc/api/emoji_reactions.md b/doc/api/emoji_reactions.md index f9e44a1337a..7e45a9abc6a 100644 --- a/doc/api/emoji_reactions.md +++ b/doc/api/emoji_reactions.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Emoji reactions API **(FREE ALL)** diff --git a/doc/api/environments.md b/doc/api/environments.md index 06f75381000..95ed65a4885 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Environments API **(FREE ALL)** diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index 1b22447da97..b22048d2ec8 100644 --- a/doc/api/epic_issues.md +++ b/doc/api/epic_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epic Issues API **(PREMIUM ALL)** diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index aa88aa563e7..80ad3506a8a 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epic Links API **(ULTIMATE ALL)** diff --git a/doc/api/epics.md b/doc/api/epics.md index d80cc0efab8..2798e74bea8 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epics API **(PREMIUM ALL)** diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index fb22e96c20b..ff612e4bd9c 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Observability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Error Tracking settings API **(FREE ALL)** diff --git a/doc/api/events.md b/doc/api/events.md index 8564b9b0942..655b6b43a6b 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Events API **(FREE ALL)** diff --git a/doc/api/experiments.md b/doc/api/experiments.md index 8e34868b282..d886a4e8e31 100644 --- a/doc/api/experiments.md +++ b/doc/api/experiments.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Experiments API (GitLab team only) **(FREE SAAS)** diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index 39c5f298be4..46ffbc3bb6b 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Feature flag user lists API **(FREE ALL)** diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index 824c892c17b..59fb4660f30 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Feature flags API **(FREE ALL)** diff --git a/doc/api/features.md b/doc/api/features.md index 742d4527be5..438963ca2be 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Feature flags API **(FREE SELF)** diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index 55a083ae9a7..e497ea19b6a 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Freeze Periods API **(FREE ALL)** diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index c376d7a6774..3e6751fe740 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo Nodes API **(PREMIUM SELF)** diff --git a/doc/api/geo_sites.md b/doc/api/geo_sites.md index 95691960a78..8026e276202 100644 --- a/doc/api/geo_sites.md +++ b/doc/api/geo_sites.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo sites API **(PREMIUM SELF)** diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md index dbe5681028b..c9c2de8e850 100644 --- a/doc/api/graphql/audit_report.md +++ b/doc/api/graphql/audit_report.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up an Audit Report with GraphQL **(FREE ALL)** diff --git a/doc/api/graphql/branch_rules.md b/doc/api/graphql/branch_rules.md index f0c4dc308b7..f5f2a714ec6 100644 --- a/doc/api/graphql/branch_rules.md +++ b/doc/api/graphql/branch_rules.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # List branch rules for a project **(FREE ALL)** diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md index c1caf4f90b1..ef0db847091 100644 --- a/doc/api/graphql/custom_emoji.md +++ b/doc/api/graphql/custom_emoji.md @@ -1,17 +1,17 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use custom emoji with GraphQL **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../../administration/feature_flags.md) named `custom_emoji`. Disabled by default. > - Enabled on GitLab.com in GitLab 14.0. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138969) in GitLab 16.7. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `custom_emoji`. -On GitLab.com, this feature is available. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `custom_emoji`. This feature is ready for production use. To use [custom emoji](../../user/emoji_reactions.md) in comments and descriptions, you can add them to a top-level group using the GraphQL API. diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 874d243ee2d..cf756027e01 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run GraphQL API queries and mutations **(FREE ALL)** @@ -22,7 +22,7 @@ The examples documented here can be run using: ### GraphiQL -GraphiQL (pronounced "graphical") allows you to run real GraphQL queries against the API interactively. +GraphiQL (pronounced "graphical") allows you to run real GraphQL queries against the API interactively. It makes exploring the schema easier by providing a UI with syntax highlighting and autocompletion. For most people, using GraphiQL will be the easiest way to explore the GitLab GraphQL API. @@ -97,6 +97,7 @@ NOTE: In the GitLab GraphQL API, `id` refers to a [Global ID](https://graphql.org/learn/global-object-identification/), which is an object identifier in the format of `"gid://gitlab/Issue/123"`. +For more information, see [Global IDs](index.md#global-ids). [GitLab GraphQL Schema](reference/index.md) outlines which objects and fields are available for clients to query and their corresponding data types. @@ -342,7 +343,7 @@ More about introspection: ### Query complexity -The calculated [complexity score and limit](index.md#max-query-complexity) for a query can be revealed to clients by +The calculated [complexity score and limit](index.md#maximum-query-complexity) for a query can be revealed to clients by querying for `queryComplexity`. ```graphql diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 36f16ff9141..37bd9fc38ed 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -1,13 +1,11 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL API **(FREE ALL)** -> Enabled and [made generally available](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. [Feature flag `graphql`](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) removed. - [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. @@ -15,38 +13,22 @@ 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. -There are no fixed endpoints and no data model, so you can add -to the API without creating [breaking changes](../../development/deprecation_guidelines/index.md). -This enables us to have a [versionless API](https://graphql.org/learn/best-practices/#versioning). - -## 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. - -To help us meet this vision, the frontend should use GraphQL in preference to -the REST API for new features. +The GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning). -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. - -## Work with GraphQL +## Getting started 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 +### Interactive GraphQL explorer + +Explore the GraphQL API using the interactive GraphQL explorer, either: -Explore the GraphQL API using the interactive [GraphiQL explorer](https://gitlab.com/-/graphql-explorer), -or on your self-managed GitLab instance on -`https://<your-gitlab-site.com>/-/graphql-explorer`. +- [On GitLab.com](https://gitlab.com/-/graphql-explorer). +- On your self-managed GitLab instance on `https://<your-gitlab-site.com>/-/graphql-explorer`. For more information, see [GraphiQL](getting_started.md#graphiql). @@ -61,25 +43,55 @@ You can work with sample queries that pull data from public projects on GitLab.c The [get started](getting_started.md) page includes different methods to customize GraphQL queries. +### Global IDs + +In the GitLab GraphQL API, an `id` field is nearly always a [Global ID](https://graphql.org/learn/global-object-identification/) +and never a database primary key ID. A Global ID in the GitLab GraphQL API +begins with `"gid://gitlab/"`. For example, `"gid://gitlab/Issue/123"`. + +Global IDs are a convention used for caching and fetching in some client-side libraries. + +GitLab Global IDs are subject to change. If changed, the use of the old Global ID as an argument is deprecated and supported according to the [deprecation and breaking change](#breaking-changes) process. +You should not expect that a cached Global ID will be valid beyond the time of a GitLab GraphQL deprecation cycle. + +## Available top-level queries + +The top-level entry points for all queries are defined in the [`Query` type](reference/index.md#query-type) in the +GraphQL reference. + +### Multiplex queries + +GitLab supports batching queries into a single request. For more information, see +[Multiplex](https://graphql-ruby.org/queries/multiplex.html). + ## Breaking changes -The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible. +The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are +primarily backward-compatible. 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). -To avoid having a breaking change affect your integrations, you should -familiarize yourself with the [deprecation and removal process](#deprecation-and-removal-process) and -frequently [verify your API calls against the future breaking-change schema](#verify-against-the-future-breaking-change-schema). +To avoid having a breaking change affect your integrations, you should: -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. +- Familiarize yourself with the [deprecation and removal process](#deprecation-and-removal-process). +- Frequently [verify your API calls against the future breaking-change schema](#verify-against-the-future-breaking-change-schema). For more information, see [Deprecating GitLab features](../../development/deprecation_guidelines/index.md). +### Breaking change exemptions + +Schema items labeled as Experiments in the [GraphQL API reference](reference/index.md) +are exempt from the deprecation process. These items can be removed or changed at any +time without notice. + +Fields behind a feature flag and disabled by default do not follow the +deprecation and removal process. These fields can be removed at any time without notice. + WARNING: 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 +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. @@ -92,8 +104,8 @@ This way, you can verify API calls ahead of a [breaking-change release](#depreca before the items are actually removed from the schema. To make these calls, add a -`remove_deprecated=true` query parameter to the GitLab GraphQL API endpoint (for example, -`https://gitlab.com/api/graphql?remove_deprecated=true` for GitLab SaaS GraphQL). +`remove_deprecated=true` query parameter to the GraphQL API endpoint. For example, +`https://gitlab.com/api/graphql?remove_deprecated=true` for GraphQL on GitLab.com. ### Deprecation and removal process @@ -115,10 +127,8 @@ Items are marked as deprecated in: The deprecation message provides an alternative for the deprecated schema item, if applicable. -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. -You should [verify your API calls against the schema without the deprecated schema items](#verify-against-the-future-breaking-change-schema). +To avoid experiencing breaking changes, you should remove the deprecated schema from your GraphQL API calls as soon as +possible. You should [verify your API calls against the schema without the deprecated schema items](#verify-against-the-future-breaking-change-schema). #### Deprecation example @@ -126,7 +136,7 @@ The following fields are deprecated in different minor releases, but both removed in GitLab 14.0: | 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. | @@ -134,50 +144,21 @@ removed in GitLab 14.0: 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: - -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 authenticated user. -`users` | Information about a collection of users. -`metaData` | Metadata about GitLab and the GraphQL API. -`snippets` | Snippets visible to the authenticated 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 -[`app/graphql/types/query_type.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/query_type.rb). - -### Multiplex queries - -GitLab supports batching queries into a single request using -[`@apollo/client/link/batch-http`](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http/). More -information about multiplexed queries is also available for -[GraphQL Ruby](https://graphql-ruby.org/queries/multiplex.html), the -library GitLab uses on the backend. - ## Limits The following limits apply to the GitLab GraphQL API. -Limit | Default ----------------------|--------------------------------------------------------------------- -Max page size | 100 records (nodes) per page. Applies to most connections in the API. Particular connections may have different max page size limits that are higher or lower. -[Max query complexity](#max-query-complexity) | `200` for unauthenticated requests and `250` for authenticated requests. -Request timeout | 30 seconds. -Max query size | 10,000 characters per query or mutation. If this limit is reached, use [variables](https://graphql.org/learn/queries/#variables) and [fragments](https://graphql.org/learn/queries/#fragments) to reduce the query or mutation size. Remove white spaces as last resort. +| Limit | Default | +|:------------------------------------------------------|:--------| +| Maximum 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. | +| [Maximum query complexity](#maximum-query-complexity) | 200 for unauthenticated requests and 250 for authenticated requests. | +| Request timeout | 30 seconds. | +| Maximum query size | 10,000 characters per query or mutation. If this limit is reached, use [variables](https://graphql.org/learn/queries/#variables) and [fragments](https://graphql.org/learn/queries/#fragments) to reduce the query or mutation size. Remove white spaces as last resort. | -### Max query complexity +### Maximum query complexity The GitLab GraphQL API scores the _complexity_ of a query. Generally, larger -queries have a higher complexity score. This limit is designed to protect +queries have a higher complexity score. This limit is designed to protecting the API from performing queries that could negatively impact its overall performance. You can [query](getting_started.md#query-complexity) the complexity score of a query @@ -190,14 +171,8 @@ 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. - ## Resolve mutations detected as spam -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327360) in GitLab 13.11. - GraphQL mutations can be detected as spam. If a mutation is detected as spam and: - A CAPTCHA service is not configured, a diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 7c5f9ebd6e0..46ddad63360 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!--- @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This documentation is self-generated based on GitLab current GraphQL schema. -The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql). +The API can be explored using the [interactive GraphQL explorer](../index.md#interactive-graphql-explorer). Each table below documents a GraphQL type. Types match loosely to models, but not all fields and methods on a model are available via GraphQL. @@ -64,7 +64,7 @@ Returns [`LabelConnection`](#labelconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -72,6 +72,23 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="queryabusereportlabelssearchterm"></a>`searchTerm` | [`String`](#string) | Search term to find labels with. | +### `Query.addOnPurchase` + +Retrieve the active add-on purchase. This query can be used in GitLab SaaS and self-managed environments. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`AddOnPurchase`](#addonpurchase). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="queryaddonpurchaseaddontype"></a>`addOnType` | [`GitlabSubscriptionsAddOnType!`](#gitlabsubscriptionsaddontype) | Type of add-on for the add-on purchase. | +| <a id="queryaddonpurchasenamespaceid"></a>`namespaceId` | [`NamespaceID`](#namespaceid) | ID of namespace that the add-on was purchased for. | + ### `Query.aiMessages` Find GitLab Duo Chat messages. @@ -84,7 +101,7 @@ Returns [`AiMessageConnection!`](#aimessageconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -101,7 +118,17 @@ Returns [`AuditEventDefinitionConnection!`](#auditeventdefinitionconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +### `Query.auditEventsInstanceAmazonS3Configurations` + +Instance-level Amazon S3 configurations for audit events. + +Returns [`InstanceAmazonS3ConfigurationTypeConnection`](#instanceamazons3configurationtypeconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. ### `Query.boardList` @@ -151,7 +178,7 @@ Returns [`CiCatalogResourceConnection`](#cicatalogresourceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -187,7 +214,7 @@ Returns [`CiMinutesNamespaceMonthlyUsageConnection`](#ciminutesnamespacemonthlyu This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -234,7 +261,7 @@ Returns [`CiInstanceVariableConnection`](#ciinstancevariableconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -264,7 +291,7 @@ Returns [`CurrentLicense`](#currentlicense). Get information about current user. -Returns [`UserCore`](#usercore). +Returns [`CurrentUser`](#currentuser). ### `Query.designManagement` @@ -280,7 +307,7 @@ Returns [`DevopsAdoptionEnabledNamespaceConnection`](#devopsadoptionenablednames This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -329,21 +356,13 @@ Returns [`ExplainVulnerabilityPrompt`](#explainvulnerabilityprompt). ### `Query.frecentGroups` -A user's frecently visited groups. Requires the `frecent_namespaces_suggestions` feature flag to be enabled. - -WARNING: -**Introduced** in 16.6. -This feature is an Experiment. It can be changed or removed at any time. +A user's frecently visited groups. Returns [`[Group!]`](#group). ### `Query.frecentProjects` -A user's frecently visited projects. Requires the `frecent_namespaces_suggestions` feature flag to be enabled. - -WARNING: -**Introduced** in 16.6. -This feature is an Experiment. It can be changed or removed at any time. +A user's frecently visited projects. Returns [`[Project!]`](#project). @@ -385,7 +404,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -401,7 +420,7 @@ Returns [`InstanceExternalAuditEventDestinationConnection`](#instanceexternalaud This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ### `Query.instanceGoogleCloudLoggingConfigurations` @@ -411,7 +430,7 @@ Returns [`InstanceGoogleCloudLoggingConfigurationTypeConnection`](#instancegoogl This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ### `Query.instanceSecurityDashboard` @@ -443,7 +462,7 @@ Returns [`IssueConnection`](#issueconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -508,7 +527,7 @@ Returns [`CiJobConnection`](#cijobconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -526,7 +545,7 @@ Returns [`LicenseHistoryEntryConnection`](#licensehistoryentryconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ### `Query.memberRole` @@ -548,11 +567,15 @@ Returns [`MemberRole`](#memberrole). List of all customizable permissions. +WARNING: +**Introduced** in 16.4. +This feature is an Experiment. It can be changed or removed at any time. + Returns [`CustomizablePermissionConnection`](#customizablepermissionconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ### `Query.mergeRequest` @@ -584,6 +607,22 @@ Returns [`Milestone`](#milestone). | ---- | ---- | ----------- | | <a id="querymilestoneid"></a>`id` | [`MilestoneID!`](#milestoneid) | Find a milestone by its ID. | +### `Query.mlModel` + +Find machine learning models. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`MlModel`](#mlmodel). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="querymlmodelid"></a>`id` | [`MlModelID!`](#mlmodelid) | ID of the model. | + ### `Query.namespace` Find a namespace. @@ -660,7 +699,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -706,7 +745,7 @@ Returns [`RunnerPlatformConnection`](#runnerplatformconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ### `Query.runnerSetup` @@ -735,7 +774,7 @@ Returns [`CiRunnerConnection`](#cirunnerconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -752,6 +791,27 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="queryrunnersupgradestatus"></a>`upgradeStatus` | [`CiRunnerUpgradeStatus`](#cirunnerupgradestatus) | Filter by upgrade status. | | <a id="queryrunnersversionprefix"></a>`versionPrefix` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.6. This feature is an Experiment. It can be changed or removed at any time. Filter runners by version. Runners that contain runner managers with the version at the start of the search term are returned. For example, the search term '14.' returns runner managers with versions '14.11.1' and '14.2.3'. | +### `Query.selfManagedAddOnEligibleUsers` + +Users within the self-managed instance who are eligible for add-ons. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`AddOnUserConnection`](#addonuserconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="queryselfmanagedaddoneligibleusersaddontype"></a>`addOnType` | [`GitlabSubscriptionsAddOnType!`](#gitlabsubscriptionsaddontype) | Type of add on to filter the eligible users by. | +| <a id="queryselfmanagedaddoneligibleuserssearch"></a>`search` | [`String`](#string) | Search the user list. | + ### `Query.snippets` Find Snippets visible to the current user. @@ -760,7 +820,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -781,7 +841,7 @@ 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`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ### `Query.syntheticNote` @@ -808,7 +868,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -843,7 +903,7 @@ Returns [`TopicConnection`](#topicconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -859,7 +919,7 @@ Returns [`UsageTrendsMeasurementConnection`](#usagetrendsmeasurementconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -890,7 +950,7 @@ Returns [`UserCoreConnection`](#usercoreconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -910,7 +970,7 @@ Returns [`VulnerabilityConnection`](#vulnerabilityconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -940,7 +1000,7 @@ Returns [`VulnerabilitiesCountByDayConnection`](#vulnerabilitiescountbydayconnec This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments @@ -977,6 +1037,27 @@ Returns [`WorkItem`](#workitem). | ---- | ---- | ----------- | | <a id="queryworkitemid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | +### `Query.workItemsByReference` + +Find work items by their reference. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`WorkItemConnection`](#workitemconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="queryworkitemsbyreferencecontextnamespacepath"></a>`contextNamespacePath` | [`ID`](#id) | Full path of the context namespace (project or group). | +| <a id="queryworkitemsbyreferencerefs"></a>`refs` | [`[String!]!`](#string) | Work item references. Can be either a short reference or URL. | + ### `Query.workspace` Find a workspace. @@ -995,7 +1076,7 @@ Returns [`Workspace`](#workspace). ### `Query.workspaces` -Find workspaces owned by the current user by their IDs. +Find workspaces across the entire instance. This field is only available to instance admins, it will return an empty result for all non-admins. WARNING: **Introduced** in 16.0. @@ -1005,15 +1086,18 @@ Returns [`WorkspaceConnection`](#workspaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. #### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="queryworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="queryworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="queryworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | +| <a id="queryworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="queryworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="queryworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="queryworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="queryworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | +| <a id="queryworkspacesuserids"></a>`userIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by user GlobalIDs. | ## `Mutation` type @@ -1212,6 +1296,7 @@ Input type: `AdminSidekiqQueuesDeleteJobsInput` | <a id="mutationadminsidekiqqueuesdeletejobsartifactusedcdn"></a>`artifactUsedCdn` | [`String`](#string) | Delete jobs matching artifact_used_cdn in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobsartifactsdependenciescount"></a>`artifactsDependenciesCount` | [`String`](#string) | Delete jobs matching artifacts_dependencies_count in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobsartifactsdependenciessize"></a>`artifactsDependenciesSize` | [`String`](#string) | Delete jobs matching artifacts_dependencies_size in the context metadata. | +| <a id="mutationadminsidekiqqueuesdeletejobsbulkimportentityid"></a>`bulkImportEntityId` | [`String`](#string) | Delete jobs matching bulk_import_entity_id in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobscallerid"></a>`callerId` | [`String`](#string) | Delete jobs matching caller_id in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobsclientid"></a>`clientId` | [`String`](#string) | Delete jobs matching client_id in the context metadata. | | <a id="mutationadminsidekiqqueuesdeletejobsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | @@ -1263,7 +1348,6 @@ Input type: `AiActionInput` | <a id="mutationaiactionresolvevulnerability"></a>`resolveVulnerability` | [`AiResolveVulnerabilityInput`](#airesolvevulnerabilityinput) | Input for resolve_vulnerability AI action. | | <a id="mutationaiactionsummarizecomments"></a>`summarizeComments` | [`AiSummarizeCommentsInput`](#aisummarizecommentsinput) | Input for summarize_comments AI action. | | <a id="mutationaiactionsummarizereview"></a>`summarizeReview` | [`AiSummarizeReviewInput`](#aisummarizereviewinput) | Input for summarize_review AI action. | -| <a id="mutationaiactiontanukibot"></a>`tanukiBot` | [`AiTanukiBotInput`](#aitanukibotinput) | Input for tanuki_bot AI action. | #### Fields @@ -1426,6 +1510,71 @@ Input type: `AuditEventsAmazonS3ConfigurationUpdateInput` | <a id="mutationauditeventsamazons3configurationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationauditeventsamazons3configurationupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.auditEventsInstanceAmazonS3ConfigurationCreate` + +Input type: `AuditEventsInstanceAmazonS3ConfigurationCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsinstanceamazons3configurationcreateaccesskeyxid"></a>`accessKeyXid` | [`String!`](#string) | Access key ID of the Amazon S3 account. | +| <a id="mutationauditeventsinstanceamazons3configurationcreateawsregion"></a>`awsRegion` | [`String!`](#string) | AWS region where the bucket is created. | +| <a id="mutationauditeventsinstanceamazons3configurationcreatebucketname"></a>`bucketName` | [`String!`](#string) | Name of the bucket where the audit events would be logged. | +| <a id="mutationauditeventsinstanceamazons3configurationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsinstanceamazons3configurationcreatename"></a>`name` | [`String`](#string) | Destination name. | +| <a id="mutationauditeventsinstanceamazons3configurationcreatesecretaccesskey"></a>`secretAccessKey` | [`String!`](#string) | Secret access key of the Amazon S3 account. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsinstanceamazons3configurationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsinstanceamazons3configurationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationauditeventsinstanceamazons3configurationcreateinstanceamazons3configuration"></a>`instanceAmazonS3Configuration` | [`InstanceAmazonS3ConfigurationType`](#instanceamazons3configurationtype) | Created instance Amazon S3 configuration. | + +### `Mutation.auditEventsInstanceAmazonS3ConfigurationDelete` + +Input type: `AuditEventsInstanceAmazonS3ConfigurationDeleteInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsinstanceamazons3configurationdeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsinstanceamazons3configurationdeleteid"></a>`id` | [`AuditEventsInstanceAmazonS3ConfigurationID!`](#auditeventsinstanceamazons3configurationid) | ID of the instance-level Amazon S3 configuration to delete. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsinstanceamazons3configurationdeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsinstanceamazons3configurationdeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + +### `Mutation.auditEventsInstanceAmazonS3ConfigurationUpdate` + +Input type: `AuditEventsInstanceAmazonS3ConfigurationUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsinstanceamazons3configurationupdateaccesskeyxid"></a>`accessKeyXid` | [`String`](#string) | Access key ID of the Amazon S3 account. | +| <a id="mutationauditeventsinstanceamazons3configurationupdateawsregion"></a>`awsRegion` | [`String`](#string) | AWS region where the bucket is created. | +| <a id="mutationauditeventsinstanceamazons3configurationupdatebucketname"></a>`bucketName` | [`String`](#string) | Name of the bucket where the audit events would be logged. | +| <a id="mutationauditeventsinstanceamazons3configurationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsinstanceamazons3configurationupdateid"></a>`id` | [`AuditEventsInstanceAmazonS3ConfigurationID!`](#auditeventsinstanceamazons3configurationid) | ID of the instance-level Amazon S3 configuration to update. | +| <a id="mutationauditeventsinstanceamazons3configurationupdatename"></a>`name` | [`String`](#string) | Destination name. | +| <a id="mutationauditeventsinstanceamazons3configurationupdatesecretaccesskey"></a>`secretAccessKey` | [`String`](#string) | Secret access key of the Amazon S3 account. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsinstanceamazons3configurationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsinstanceamazons3configurationupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationauditeventsinstanceamazons3configurationupdateinstanceamazons3configuration"></a>`instanceAmazonS3Configuration` | [`InstanceAmazonS3ConfigurationType`](#instanceamazons3configurationtype) | Updated instance-level Amazon S3 configuration. | + ### `Mutation.auditEventsStreamingDestinationEventsAdd` Input type: `AuditEventsStreamingDestinationEventsAddInput` @@ -1587,6 +1736,24 @@ Input type: `AuditEventsStreamingHTTPNamespaceFiltersAddInput` | <a id="mutationauditeventsstreaminghttpnamespacefiltersadderrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationauditeventsstreaminghttpnamespacefiltersaddnamespacefilter"></a>`namespaceFilter` | [`AuditEventStreamingHTTPNamespaceFilter`](#auditeventstreaminghttpnamespacefilter) | Namespace filter created. | +### `Mutation.auditEventsStreamingHttpNamespaceFiltersDelete` + +Input type: `AuditEventsStreamingHTTPNamespaceFiltersDeleteInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsstreaminghttpnamespacefiltersdeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsstreaminghttpnamespacefiltersdeletenamespacefilterid"></a>`namespaceFilterId` | [`AuditEventsStreamingHTTPNamespaceFilterID!`](#auditeventsstreaminghttpnamespacefilterid) | Namespace filter ID. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationauditeventsstreaminghttpnamespacefiltersdeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationauditeventsstreaminghttpnamespacefiltersdeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.auditEventsStreamingInstanceHeadersCreate` Input type: `AuditEventsStreamingInstanceHeadersCreateInput` @@ -1778,6 +1945,31 @@ Input type: `BoardListUpdateLimitMetricsInput` | <a id="mutationboardlistupdatelimitmetricserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationboardlistupdatelimitmetricslist"></a>`list` | [`BoardList`](#boardlist) | Updated list. | +### `Mutation.branchRuleUpdate` + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `BranchRuleUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationbranchruleupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationbranchruleupdateid"></a>`id` | [`ProtectedBranchID!`](#protectedbranchid) | Global ID of the protected branch. | +| <a id="mutationbranchruleupdatename"></a>`name` | [`String!`](#string) | Branch name, with wildcards, for the branch rules. | +| <a id="mutationbranchruleupdateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path to the project that the branch is associated with. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationbranchruleupdatebranchrule"></a>`branchRule` | [`BranchRule`](#branchrule) | Branch rule after mutation. | +| <a id="mutationbranchruleupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationbranchruleupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.buildForecast` WARNING: @@ -1874,28 +2066,6 @@ Input type: `BulkRunnerDeleteInput` | <a id="mutationbulkrunnerdeletedeletedids"></a>`deletedIds` | [`[CiRunnerID!]`](#cirunnerid) | IDs of records effectively deleted. Only present if operation was performed synchronously. | | <a id="mutationbulkrunnerdeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -### `Mutation.catalogResourceUnpublish` - -WARNING: -**Introduced** in 16.6. -This feature is an Experiment. It can be changed or removed at any time. - -Input type: `CatalogResourceUnpublishInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationcatalogresourceunpublishclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcatalogresourceunpublishid"></a>`id` | [`CiCatalogResourceID!`](#cicatalogresourceid) | Global ID of the catalog resource to unpublish. | - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationcatalogresourceunpublishclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcatalogresourceunpublisherrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | - ### `Mutation.catalogResourcesCreate` WARNING: @@ -1909,7 +2079,7 @@ Input type: `CatalogResourcesCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcatalogresourcescreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcatalogresourcescreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project to convert to a catalog resource. | +| <a id="mutationcatalogresourcescreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Project path belonging to the catalog resource. | #### Fields @@ -1918,29 +2088,27 @@ Input type: `CatalogResourcesCreateInput` | <a id="mutationcatalogresourcescreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcatalogresourcescreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -### `Mutation.ciAiGenerateConfig` +### `Mutation.catalogResourcesDestroy` WARNING: -**Introduced** in 16.0. +**Introduced** in 16.6. This feature is an Experiment. It can be changed or removed at any time. -Input type: `CiAiGenerateConfigInput` +Input type: `CatalogResourcesDestroyInput` #### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationciaigenerateconfigclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationciaigenerateconfigprojectpath"></a>`projectPath` | [`ID!`](#id) | Project path for the project related to the open config editor. | -| <a id="mutationciaigenerateconfigusercontent"></a>`userContent` | [`String!`](#string) | Content of the user message to be sent to the language model. | +| <a id="mutationcatalogresourcesdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcatalogresourcesdestroyprojectpath"></a>`projectPath` | [`ID!`](#id) | Project path belonging to the catalog resource. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mutationciaigenerateconfigclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationciaigenerateconfigerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationciaigenerateconfigusermessage"></a>`userMessage` | [`DeprecatedAiMessage`](#deprecatedaimessage) | User Chat message. | +| <a id="mutationcatalogresourcesdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcatalogresourcesdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.ciJobTokenScopeAddProject` @@ -2365,10 +2533,10 @@ Input type: `CreateContainerRegistryProtectionRuleInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationcreatecontainerregistryprotectionruleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationcreatecontainerregistryprotectionrulecontainerpathpattern"></a>`containerPathPattern` | [`String!`](#string) | ContainerRegistryname protected by the protection rule. For example `@my-scope/my-container-*`. Wildcard character `*` allowed. | | <a id="mutationcreatecontainerregistryprotectionruledeleteprotecteduptoaccesslevel"></a>`deleteProtectedUpToAccessLevel` | [`ContainerRegistryProtectionRuleAccessLevel!`](#containerregistryprotectionruleaccesslevel) | Max GitLab access level to prevent from deleting container images in the container registry. For example `DEVELOPER`, `MAINTAINER`, `OWNER`. | | <a id="mutationcreatecontainerregistryprotectionruleprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project where a protection rule is located. | | <a id="mutationcreatecontainerregistryprotectionrulepushprotecteduptoaccesslevel"></a>`pushProtectedUpToAccessLevel` | [`ContainerRegistryProtectionRuleAccessLevel!`](#containerregistryprotectionruleaccesslevel) | Max GitLab access level to prevent from pushing container images to the container registry. For example `DEVELOPER`, `MAINTAINER`, `OWNER`. | +| <a id="mutationcreatecontainerregistryprotectionrulerepositorypathpattern"></a>`repositoryPathPattern` | [`String!`](#string) | Container repository path pattern protected by the protection rule. For example `my-project/my-container-*`. Wildcard character `*` allowed. | #### Fields @@ -3122,6 +3290,31 @@ Input type: `DeleteAnnotationInput` | <a id="mutationdeleteannotationclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationdeleteannotationerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.deleteContainerRegistryProtectionRule` + +Deletes a container registry protection rule. Available only when feature flag `container_registry_protected_containers` is enabled. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `DeleteContainerRegistryProtectionRuleInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdeletecontainerregistryprotectionruleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdeletecontainerregistryprotectionruleid"></a>`id` | [`ContainerRegistryProtectionRuleID!`](#containerregistryprotectionruleid) | Global ID of the container registry protection rule to delete. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdeletecontainerregistryprotectionruleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdeletecontainerregistryprotectionrulecontainerregistryprotectionrule"></a>`containerRegistryProtectionRule` | [`ContainerRegistryProtectionRule`](#containerregistryprotectionrule) | Container registry protection rule that was deleted successfully. | +| <a id="mutationdeletecontainerregistryprotectionruleerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.deletePackagesProtectionRule` Deletes a protection rule for packages. Available only when feature flag `packages_protected_packages` is enabled. @@ -5138,9 +5331,10 @@ Input type: `MemberRoleCreateInput` | <a id="mutationmemberrolecreatebaseaccesslevel"></a>`baseAccessLevel` | [`MemberAccessLevel!`](#memberaccesslevel) | Base access level for the custom role. | | <a id="mutationmemberrolecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationmemberrolecreatedescription"></a>`description` | [`String`](#string) | Description of the member role. | -| <a id="mutationmemberrolecreategrouppath"></a>`groupPath` | [`ID!`](#id) | Group the member role to mutate is in. | +| <a id="mutationmemberrolecreategrouppath"></a>`groupPath` | [`ID`](#id) | Group the member role to mutate is in. Required for SaaS. | | <a id="mutationmemberrolecreatemanageprojectaccesstokens"></a>`manageProjectAccessTokens` | [`Boolean`](#boolean) | Permission to admin project access tokens. | | <a id="mutationmemberrolecreatename"></a>`name` | [`String`](#string) | Name of the member role. | +| <a id="mutationmemberrolecreatepermissions"></a>`permissions` | [`[MemberRolePermission!]`](#memberrolepermission) | List of all customizable permissions. | | <a id="mutationmemberrolecreatereadcode"></a>`readCode` | [`Boolean`](#boolean) | Permission to read code. | | <a id="mutationmemberrolecreatereaddependency"></a>`readDependency` | [`Boolean`](#boolean) | Permission to read dependency. | | <a id="mutationmemberrolecreatereadvulnerability"></a>`readVulnerability` | [`Boolean`](#boolean) | Permission to read vulnerability. | @@ -5153,6 +5347,29 @@ Input type: `MemberRoleCreateInput` | <a id="mutationmemberrolecreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationmemberrolecreatememberrole"></a>`memberRole` | [`MemberRole`](#memberrole) | Updated member role. | +### `Mutation.memberRoleDelete` + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `MemberRoleDeleteInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationmemberroledeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationmemberroledeleteid"></a>`id` | [`MemberRoleID!`](#memberroleid) | ID of the member role to delete. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationmemberroledeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationmemberroledeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationmemberroledeletememberrole"></a>`memberRole` | [`MemberRole`](#memberrole) | Deleted member role. | + ### `Mutation.memberRoleUpdate` Input type: `MemberRoleUpdateInput` @@ -5663,7 +5880,9 @@ Input type: `OrganizationCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="mutationorganizationcreateavatar"></a>`avatar` | [`Upload`](#upload) | Avatar for the organization. | | <a id="mutationorganizationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationorganizationcreatedescription"></a>`description` | [`String`](#string) | Description of the organization. | | <a id="mutationorganizationcreatename"></a>`name` | [`String!`](#string) | Name for the organization. | | <a id="mutationorganizationcreatepath"></a>`path` | [`String!`](#string) | Path for the organization. | @@ -5673,7 +5892,34 @@ Input type: `OrganizationCreateInput` | ---- | ---- | ----------- | | <a id="mutationorganizationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationorganizationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationorganizationcreateorganization"></a>`organization` | [`Organization`](#organization) | Organization created. | +| <a id="mutationorganizationcreateorganization"></a>`organization` | [`Organization`](#organization) | Organization after mutation. | + +### `Mutation.organizationUpdate` + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `OrganizationUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationorganizationupdateavatar"></a>`avatar` | [`Upload`](#upload) | Avatar for the organization. | +| <a id="mutationorganizationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationorganizationupdatedescription"></a>`description` | [`String`](#string) | Description of the organization. | +| <a id="mutationorganizationupdateid"></a>`id` | [`OrganizationsOrganizationID!`](#organizationsorganizationid) | ID of the organization to mutate. | +| <a id="mutationorganizationupdatename"></a>`name` | [`String`](#string) | Name for the organization. | +| <a id="mutationorganizationupdatepath"></a>`path` | [`String`](#string) | Path for the organization. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationorganizationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationorganizationupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationorganizationupdateorganization"></a>`organization` | [`Organization`](#organization) | Organization after mutation. | ### `Mutation.pagesMarkOnboardingComplete` @@ -6463,6 +6709,28 @@ Input type: `RunnerUpdateInput` | <a id="mutationrunnerupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationrunnerupdaterunner"></a>`runner` | [`CiRunner`](#cirunner) | Runner after mutation. | +### `Mutation.runnersExportUsage` + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `RunnersExportUsageInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationrunnersexportusageclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationrunnersexportusagetype"></a>`type` | [`CiRunnerType`](#cirunnertype) | Scope of the runners to include in the report. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationrunnersexportusageclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationrunnersexportusageerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.runnersRegistrationTokenReset` Input type: `RunnersRegistrationTokenResetInput` @@ -6639,6 +6907,7 @@ Input type: `SecurityFindingRevertToDetectedInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationsecurityfindingreverttodetectedclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationsecurityfindingreverttodetectedcomment"></a>`comment` | [`String`](#string) | Comment that explains why finding was reverted to detected status. | | <a id="mutationsecurityfindingreverttodetecteduuid"></a>`uuid` | [`String!`](#string) | UUID of the finding to be dismissed. | #### Fields @@ -6736,6 +7005,30 @@ Input type: `SecurityTrainingUpdateInput` | <a id="mutationsecuritytrainingupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationsecuritytrainingupdatetraining"></a>`training` | [`ProjectSecurityTraining`](#projectsecuritytraining) | Represents the training entity subject to mutation. | +### `Mutation.starProject` + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `StarProjectInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationstarprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationstarprojectprojectid"></a>`projectId` | [`ProjectID!`](#projectid) | Full path of the project to star or unstar. | +| <a id="mutationstarprojectstarred"></a>`starred` | [`Boolean!`](#boolean) | Indicates whether to star or unstar the project. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationstarprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationstarprojectcount"></a>`count` | [`String!`](#string) | Number of stars for the project. | +| <a id="mutationstarprojecterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.terraformStateDelete` Input type: `TerraformStateDeleteInput` @@ -7171,6 +7464,34 @@ Input type: `UpdateContainerExpirationPolicyInput` | <a id="mutationupdatecontainerexpirationpolicycontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy after mutation. | | <a id="mutationupdatecontainerexpirationpolicyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.updateContainerRegistryProtectionRule` + +Updates a container registry protection rule to restrict access to project containers. You can prevent users without certain roles from altering containers. Available only when feature flag `container_registry_protected_containers` is enabled. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `UpdateContainerRegistryProtectionRuleInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationupdatecontainerregistryprotectionruleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationupdatecontainerregistryprotectionruledeleteprotecteduptoaccesslevel"></a>`deleteProtectedUpToAccessLevel` | [`ContainerRegistryProtectionRuleAccessLevel`](#containerregistryprotectionruleaccesslevel) | Maximum GitLab access level prevented from deleting a container. For example, `DEVELOPER`, `MAINTAINER`, `OWNER`. | +| <a id="mutationupdatecontainerregistryprotectionruleid"></a>`id` | [`ContainerRegistryProtectionRuleID!`](#containerregistryprotectionruleid) | Global ID of the container registry protection rule to be updated. | +| <a id="mutationupdatecontainerregistryprotectionrulepushprotecteduptoaccesslevel"></a>`pushProtectedUpToAccessLevel` | [`ContainerRegistryProtectionRuleAccessLevel`](#containerregistryprotectionruleaccesslevel) | Maximum GitLab access level prevented from pushing a container. For example, `DEVELOPER`, `MAINTAINER`, `OWNER`. | +| <a id="mutationupdatecontainerregistryprotectionrulerepositorypathpattern"></a>`repositoryPathPattern` | [`String`](#string) | Container's repository path pattern of the protection rule. For example, `my-scope/my-project/container-dev-*`. Wildcard character `*` allowed. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationupdatecontainerregistryprotectionruleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationupdatecontainerregistryprotectionrulecontainerregistryprotectionrule"></a>`containerRegistryProtectionRule` | [`ContainerRegistryProtectionRule`](#containerregistryprotectionrule) | Container registry protection rule after mutation. | +| <a id="mutationupdatecontainerregistryprotectionruleerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.updateDependencyProxyImageTtlGroupPolicy` These settings can be adjusted by the group Owner or Maintainer. @@ -7416,6 +7737,7 @@ Input type: `UpdateNamespacePackageSettingsInput` | <a id="mutationupdatenamespacepackagesettingsnpmpackagerequestsforwarding"></a>`npmPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether npm package forwarding is allowed for this namespace. | | <a id="mutationupdatenamespacepackagesettingsnugetduplicateexceptionregex"></a>`nugetDuplicateExceptionRegex` | [`UntrustedRegexp`](#untrustedregexp) | When nuget_duplicates_allowed is false, you can publish duplicate packages with names that match this regex. Otherwise, this setting has no effect. | | <a id="mutationupdatenamespacepackagesettingsnugetduplicatesallowed"></a>`nugetDuplicatesAllowed` | [`Boolean`](#boolean) | Indicates whether duplicate NuGet packages are allowed for this namespace. | +| <a id="mutationupdatenamespacepackagesettingsnugetsymbolserverenabled"></a>`nugetSymbolServerEnabled` | [`Boolean`](#boolean) | Indicates wheather the NuGet symbol server is enabled for this namespace. | | <a id="mutationupdatenamespacepackagesettingspypipackagerequestsforwarding"></a>`pypiPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether PyPI package forwarding is allowed for this namespace. | #### Fields @@ -7472,6 +7794,34 @@ Input type: `UpdatePackagesCleanupPolicyInput` | <a id="mutationupdatepackagescleanuppolicyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationupdatepackagescleanuppolicypackagescleanuppolicy"></a>`packagesCleanupPolicy` | [`PackagesCleanupPolicy`](#packagescleanuppolicy) | Packages cleanup policy after mutation. | +### `Mutation.updatePackagesProtectionRule` + +Updates a package protection rule to restrict access to project packages. You can prevent users without certain permissions from altering packages. Available only when feature flag `packages_protected_packages` is enabled. + +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `UpdatePackagesProtectionRuleInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationupdatepackagesprotectionruleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationupdatepackagesprotectionruleid"></a>`id` | [`PackagesProtectionRuleID!`](#packagesprotectionruleid) | Global ID of the package protection rule to be updated. | +| <a id="mutationupdatepackagesprotectionrulepackagenamepattern"></a>`packageNamePattern` | [`String`](#string) | Package name protected by the protection rule. For example, `@my-scope/my-package-*`. Wildcard character `*` allowed. | +| <a id="mutationupdatepackagesprotectionrulepackagetype"></a>`packageType` | [`PackagesProtectionRulePackageType`](#packagesprotectionrulepackagetype) | Package type protected by the protection rule. For example, `NPM`. | +| <a id="mutationupdatepackagesprotectionrulepushprotecteduptoaccesslevel"></a>`pushProtectedUpToAccessLevel` | [`PackagesProtectionRuleAccessLevel`](#packagesprotectionruleaccesslevel) | Maximum GitLab access level unable to push a package. For example, `DEVELOPER`, `MAINTAINER`, `OWNER`. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationupdatepackagesprotectionruleclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationupdatepackagesprotectionruleerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationupdatepackagesprotectionrulepackageprotectionrule"></a>`packageProtectionRule` | [`PackagesProtectionRule`](#packagesprotectionrule) | Packages protection rule after mutation. | + ### `Mutation.updateRequirement` Input type: `UpdateRequirementInput` @@ -7669,6 +8019,7 @@ Input type: `UserPreferencesUpdateInput` | ---- | ---- | ----------- | | <a id="mutationuserpreferencesupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationuserpreferencesupdateissuessort"></a>`issuesSort` | [`IssueSort`](#issuesort) | Sort order for issue lists. | +| <a id="mutationuserpreferencesupdateusewebideextensionmarketplace"></a>`useWebIdeExtensionMarketplace` | [`Boolean`](#boolean) | Whether Web IDE Extension Marketplace is enabled for the user. | | <a id="mutationuserpreferencesupdatevisibilitypipelineidtype"></a>`visibilityPipelineIdType` | [`VisibilityPipelineIdType`](#visibilitypipelineidtype) | Determines whether the pipeline list shows ID or IID. | #### Fields @@ -7716,6 +8067,8 @@ Input type: `ValueStreamCreateInput` | <a id="mutationvaluestreamcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvaluestreamcreatename"></a>`name` | [`String!`](#string) | Value stream name. | | <a id="mutationvaluestreamcreatenamespacepath"></a>`namespacePath` | [`ID!`](#id) | Full path of the namespace(project or group) the value stream is created in. | +| <a id="mutationvaluestreamcreatesetting"></a>`setting` | [`ValueStreamSettingInput`](#valuestreamsettinginput) | Value stream configuration. | +| <a id="mutationvaluestreamcreatestages"></a>`stages` | [`[ValueStreamStageInput!]`](#valuestreamstageinput) | Value stream custom stages. | #### Fields @@ -7766,7 +8119,9 @@ Input type: `ValueStreamUpdateInput` | ---- | ---- | ----------- | | <a id="mutationvaluestreamupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvaluestreamupdateid"></a>`id` | [`AnalyticsCycleAnalyticsValueStreamID!`](#analyticscycleanalyticsvaluestreamid) | Global ID of the value stream to update. | -| <a id="mutationvaluestreamupdatename"></a>`name` | [`String!`](#string) | Value stream name. | +| <a id="mutationvaluestreamupdatename"></a>`name` | [`String`](#string) | Value stream name. | +| <a id="mutationvaluestreamupdatesetting"></a>`setting` | [`ValueStreamSettingInput`](#valuestreamsettinginput) | Value stream configuration. | +| <a id="mutationvaluestreamupdatestages"></a>`stages` | [`[ValueStreamStageInput!]`](#valuestreamstageinput) | Value stream custom stages. | #### Fields @@ -7797,6 +8152,29 @@ Input type: `VulnerabilitiesDismissInput` | <a id="mutationvulnerabilitiesdismisserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationvulnerabilitiesdismissvulnerabilities"></a>`vulnerabilities` | [`[Vulnerability!]!`](#vulnerability) | Vulnerabilities after state change. | +### `Mutation.vulnerabilitiesRemoveAllFromProject` + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `VulnerabilitiesRemoveAllFromProjectInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationvulnerabilitiesremoveallfromprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationvulnerabilitiesremoveallfromprojectprojectids"></a>`projectIds` | [`[ProjectID!]!`](#projectid) | IDs of project for which all Vulnerabilities should be removed. The deletion will happen in the background so the changes will not be visible immediately. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationvulnerabilitiesremoveallfromprojectclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationvulnerabilitiesremoveallfromprojecterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationvulnerabilitiesremoveallfromprojectprojects"></a>`projects` | [`[Project!]!`](#project) | Projects for which the deletion was scheduled. | + ### `Mutation.vulnerabilityConfirm` Input type: `VulnerabilityConfirmInput` @@ -8108,33 +8486,6 @@ Input type: `WorkItemDeleteInput` | <a id="mutationworkitemdeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationworkitemdeleteproject"></a>`project` | [`Project`](#project) | Project the deleted work item belonged to. | -### `Mutation.workItemDeleteTask` - -Deletes a task in a work item's description. - -WARNING: -**Introduced** in 15.1. -This feature is an Experiment. It can be changed or removed at any time. - -Input type: `WorkItemDeleteTaskInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationworkitemdeletetaskclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationworkitemdeletetaskid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | -| <a id="mutationworkitemdeletetasklockversion"></a>`lockVersion` | [`Int!`](#int) | Current lock version of the work item containing the task in the description. | -| <a id="mutationworkitemdeletetasktaskdata"></a>`taskData` | [`WorkItemDeletedTaskInput!`](#workitemdeletedtaskinput) | Arguments necessary to delete a task from a work item's description. | - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationworkitemdeletetaskclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationworkitemdeletetaskerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationworkitemdeletetaskworkitem"></a>`workItem` | [`WorkItem`](#workitem) | Updated work item. | - ### `Mutation.workItemExport` WARNING: @@ -8298,7 +8649,7 @@ Input type: `WorkspaceCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationworkspacecreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationworkspacecreateclusteragentid"></a>`clusterAgentId` | [`ClustersAgentID!`](#clustersagentid) | ID of the cluster agent the created workspace will be associated with. | +| <a id="mutationworkspacecreateclusteragentid"></a>`clusterAgentId` | [`ClustersAgentID!`](#clustersagentid) | GlobalID of the cluster agent the created workspace will be associated with. | | <a id="mutationworkspacecreatedesiredstate"></a>`desiredState` | [`String!`](#string) | Desired state of the created workspace. | | <a id="mutationworkspacecreatedevfilepath"></a>`devfilePath` | [`String!`](#string) | Project repo git path containing the devfile used to configure the workspace. | | <a id="mutationworkspacecreatedevfileref"></a>`devfileRef` | [`String!`](#string) | Project repo git ref containing the devfile used to configure the workspace. | @@ -8817,6 +9168,29 @@ The edge type for [`CiBuildNeed`](#cibuildneed). | <a id="cibuildneededgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="cibuildneededgenode"></a>`node` | [`CiBuildNeed`](#cibuildneed) | The item at the end of the edge. | +#### `CiCatalogResourceComponentConnection` + +The connection type for [`CiCatalogResourceComponent`](#cicatalogresourcecomponent). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cicatalogresourcecomponentconnectionedges"></a>`edges` | [`[CiCatalogResourceComponentEdge]`](#cicatalogresourcecomponentedge) | A list of edges. | +| <a id="cicatalogresourcecomponentconnectionnodes"></a>`nodes` | [`[CiCatalogResourceComponent]`](#cicatalogresourcecomponent) | A list of nodes. | +| <a id="cicatalogresourcecomponentconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `CiCatalogResourceComponentEdge` + +The edge type for [`CiCatalogResourceComponent`](#cicatalogresourcecomponent). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cicatalogresourcecomponentedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="cicatalogresourcecomponentedgenode"></a>`node` | [`CiCatalogResourceComponent`](#cicatalogresourcecomponent) | The item at the end of the edge. | + #### `CiCatalogResourceConnection` The connection type for [`CiCatalogResource`](#cicatalogresource). @@ -8841,6 +9215,30 @@ The edge type for [`CiCatalogResource`](#cicatalogresource). | <a id="cicatalogresourceedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="cicatalogresourceedgenode"></a>`node` | [`CiCatalogResource`](#cicatalogresource) | The item at the end of the edge. | +#### `CiCatalogResourceVersionConnection` + +The connection type for [`CiCatalogResourceVersion`](#cicatalogresourceversion). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cicatalogresourceversionconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | +| <a id="cicatalogresourceversionconnectionedges"></a>`edges` | [`[CiCatalogResourceVersionEdge]`](#cicatalogresourceversionedge) | A list of edges. | +| <a id="cicatalogresourceversionconnectionnodes"></a>`nodes` | [`[CiCatalogResourceVersion]`](#cicatalogresourceversion) | A list of nodes. | +| <a id="cicatalogresourceversionconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `CiCatalogResourceVersionEdge` + +The edge type for [`CiCatalogResourceVersion`](#cicatalogresourceversion). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cicatalogresourceversionedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="cicatalogresourceversionedgenode"></a>`node` | [`CiCatalogResourceVersion`](#cicatalogresourceversion) | The item at the end of the edge. | + #### `CiConfigGroupConnection` The connection type for [`CiConfigGroup`](#ciconfiggroup). @@ -9276,6 +9674,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. | +#### `CiSubscriptionsProjectConnection` + +The connection type for [`CiSubscriptionsProject`](#cisubscriptionsproject). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cisubscriptionsprojectconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | +| <a id="cisubscriptionsprojectconnectionedges"></a>`edges` | [`[CiSubscriptionsProjectEdge]`](#cisubscriptionsprojectedge) | A list of edges. | +| <a id="cisubscriptionsprojectconnectionnodes"></a>`nodes` | [`[CiSubscriptionsProject]`](#cisubscriptionsproject) | A list of nodes. | +| <a id="cisubscriptionsprojectconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `CiSubscriptionsProjectEdge` + +The edge type for [`CiSubscriptionsProject`](#cisubscriptionsproject). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cisubscriptionsprojectedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="cisubscriptionsprojectedgenode"></a>`node` | [`CiSubscriptionsProject`](#cisubscriptionsproject) | The item at the end of the edge. | + #### `ClusterAgentActivityEventConnection` The connection type for [`ClusterAgentActivityEvent`](#clusteragentactivityevent). @@ -10064,29 +10486,6 @@ The edge type for [`Deployment`](#deployment). | <a id="deploymentedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="deploymentedgenode"></a>`node` | [`Deployment`](#deployment) | The item at the end of the edge. | -#### `DeprecatedAiMessageConnection` - -The connection type for [`DeprecatedAiMessage`](#deprecatedaimessage). - -##### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="deprecatedaimessageconnectionedges"></a>`edges` | [`[DeprecatedAiMessageEdge]`](#deprecatedaimessageedge) | A list of edges. | -| <a id="deprecatedaimessageconnectionnodes"></a>`nodes` | [`[DeprecatedAiMessage]`](#deprecatedaimessage) | A list of nodes. | -| <a id="deprecatedaimessageconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | - -#### `DeprecatedAiMessageEdge` - -The edge type for [`DeprecatedAiMessage`](#deprecatedaimessage). - -##### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="deprecatedaimessageedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | -| <a id="deprecatedaimessageedgenode"></a>`node` | [`DeprecatedAiMessage`](#deprecatedaimessage) | The item at the end of the edge. | - #### `DesignAtVersionConnection` The connection type for [`DesignAtVersion`](#designatversion). @@ -10736,6 +11135,29 @@ The edge type for [`InheritedCiVariable`](#inheritedcivariable). | <a id="inheritedcivariableedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="inheritedcivariableedgenode"></a>`node` | [`InheritedCiVariable`](#inheritedcivariable) | The item at the end of the edge. | +#### `InstanceAmazonS3ConfigurationTypeConnection` + +The connection type for [`InstanceAmazonS3ConfigurationType`](#instanceamazons3configurationtype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="instanceamazons3configurationtypeconnectionedges"></a>`edges` | [`[InstanceAmazonS3ConfigurationTypeEdge]`](#instanceamazons3configurationtypeedge) | A list of edges. | +| <a id="instanceamazons3configurationtypeconnectionnodes"></a>`nodes` | [`[InstanceAmazonS3ConfigurationType]`](#instanceamazons3configurationtype) | A list of nodes. | +| <a id="instanceamazons3configurationtypeconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `InstanceAmazonS3ConfigurationTypeEdge` + +The edge type for [`InstanceAmazonS3ConfigurationType`](#instanceamazons3configurationtype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="instanceamazons3configurationtypeedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="instanceamazons3configurationtypeedgenode"></a>`node` | [`InstanceAmazonS3ConfigurationType`](#instanceamazons3configurationtype) | The item at the end of the edge. | + #### `InstanceExternalAuditEventDestinationConnection` The connection type for [`InstanceExternalAuditEventDestination`](#instanceexternalauditeventdestination). @@ -11342,6 +11764,80 @@ The edge type for [`Milestone`](#milestone). | <a id="milestoneedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="milestoneedgenode"></a>`node` | [`Milestone`](#milestone) | The item at the end of the edge. | +#### `MlCandidateConnection` + +The connection type for [`MlCandidate`](#mlcandidate). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlcandidateconnectionedges"></a>`edges` | [`[MlCandidateEdge]`](#mlcandidateedge) | A list of edges. | +| <a id="mlcandidateconnectionnodes"></a>`nodes` | [`[MlCandidate]`](#mlcandidate) | A list of nodes. | +| <a id="mlcandidateconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +##### Fields with arguments + +###### `MlCandidateConnection.count` + +Limited count of collection. Returns limit + 1 for counts greater than the limit. + +Returns [`Int!`](#int). + +####### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlcandidateconnectioncountlimit"></a>`limit` | [`Int`](#int) | Limit value to be applied to the count query. Default is 1000. | + +#### `MlCandidateEdge` + +The edge type for [`MlCandidate`](#mlcandidate). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlcandidateedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="mlcandidateedgenode"></a>`node` | [`MlCandidate`](#mlcandidate) | The item at the end of the edge. | + +#### `MlModelVersionConnection` + +The connection type for [`MlModelVersion`](#mlmodelversion). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlmodelversionconnectionedges"></a>`edges` | [`[MlModelVersionEdge]`](#mlmodelversionedge) | A list of edges. | +| <a id="mlmodelversionconnectionnodes"></a>`nodes` | [`[MlModelVersion]`](#mlmodelversion) | A list of nodes. | +| <a id="mlmodelversionconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +##### Fields with arguments + +###### `MlModelVersionConnection.count` + +Limited count of collection. Returns limit + 1 for counts greater than the limit. + +Returns [`Int!`](#int). + +####### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlmodelversionconnectioncountlimit"></a>`limit` | [`Int`](#int) | Limit value to be applied to the count query. Default is 1000. | + +#### `MlModelVersionEdge` + +The edge type for [`MlModelVersion`](#mlmodelversion). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlmodelversionedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="mlmodelversionedgenode"></a>`node` | [`MlModelVersion`](#mlmodelversion) | The item at the end of the edge. | + #### `NamespaceCommitEmailConnection` The connection type for [`NamespaceCommitEmail`](#namespacecommitemail). @@ -13084,6 +13580,29 @@ The edge type for [`UserCore`](#usercore). | <a id="usercoreedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="usercoreedgenode"></a>`node` | [`UserCore`](#usercore) | The item at the end of the edge. | +#### `ValueStreamConnection` + +The connection type for [`ValueStream`](#valuestream). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="valuestreamconnectionedges"></a>`edges` | [`[ValueStreamEdge]`](#valuestreamedge) | A list of edges. | +| <a id="valuestreamconnectionnodes"></a>`nodes` | [`[ValueStream]`](#valuestream) | A list of nodes. | +| <a id="valuestreamconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ValueStreamEdge` + +The edge type for [`ValueStream`](#valuestream). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="valuestreamedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="valuestreamedgenode"></a>`node` | [`ValueStream`](#valuestream) | The item at the end of the edge. | + #### `VulnerabilitiesCountByDayConnection` The connection type for [`VulnerabilitiesCountByDay`](#vulnerabilitiescountbyday). @@ -13339,7 +13858,6 @@ An abuse report. | <a id="abusereportdiscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="abusereportid"></a>`id` | [`AbuseReportID!`](#abusereportid) | Global ID of the abuse report. | | <a id="abusereportlabels"></a>`labels` | [`LabelConnection`](#labelconnection) | Labels of the abuse report. (see [Connections](#connections)) | -| <a id="abusereportuserpermissions"></a>`userPermissions` | [`AbuseReportPermissions!`](#abusereportpermissions) | Permissions for the current user on the resource. | #### Fields with arguments @@ -13351,7 +13869,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13359,15 +13877,6 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="abusereportnotesfilter"></a>`filter` | [`NotesFilterType`](#notesfiltertype) | Type of notes collection: ALL_NOTES, ONLY_COMMENTS, ONLY_ACTIVITY. | -### `AbuseReportPermissions` - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="abusereportpermissionscreatenote"></a>`createNote` | [`Boolean!`](#boolean) | If `true`, the user can perform `create_note` on this resource. | -| <a id="abusereportpermissionsreadabusereport"></a>`readAbuseReport` | [`Boolean!`](#boolean) | If `true`, the user can perform `read_abuse_report` on this resource. | - ### `AccessLevel` Represents the access level of a relationship between a User and object that it is related to. @@ -13490,7 +13999,7 @@ A user with add-on data. | <a id="addonusersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | | <a id="addonuserstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="addonuserstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | -| <a id="addonusertwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="addonusertwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | | <a id="addonuseruserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | | <a id="addonuseruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | | <a id="addonuserusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | @@ -13511,7 +14020,7 @@ Returns [`UserAddOnAssignmentConnection`](#useraddonassignmentconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13527,7 +14036,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13563,7 +14072,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13599,7 +14108,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13616,7 +14125,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13664,7 +14173,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13682,7 +14191,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13698,7 +14207,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13721,7 +14230,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13738,19 +14247,25 @@ four standard [pagination arguments](#connection-pagination-arguments): Workspaces owned by the current user. +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + Returns [`WorkspaceConnection`](#workspaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="addonuserworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="addonuserworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="addonuserworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | +| <a id="addonuserworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="addonuserworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="addonuserworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="addonuserworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="addonuserworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | ### `AgentConfiguration` @@ -13849,7 +14364,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -13865,7 +14380,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14109,6 +14624,17 @@ Autogenerated return type of AuditEventsStreamingHTTPNamespaceFiltersAdd. | <a id="auditeventsstreaminghttpnamespacefiltersaddpayloaderrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="auditeventsstreaminghttpnamespacefiltersaddpayloadnamespacefilter"></a>`namespaceFilter` | [`AuditEventStreamingHTTPNamespaceFilter`](#auditeventstreaminghttpnamespacefilter) | Namespace filter created. | +### `AuditEventsStreamingHTTPNamespaceFiltersDeletePayload` + +Autogenerated return type of AuditEventsStreamingHTTPNamespaceFiltersDelete. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="auditeventsstreaminghttpnamespacefiltersdeletepayloadclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="auditeventsstreaminghttpnamespacefiltersdeletepayloaderrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `AuditEventsStreamingInstanceHeader` Represents a HTTP header key/value that belongs to an instance level audit streaming destination. @@ -14161,7 +14687,7 @@ Core representation of a GitLab user. | <a id="autocompletedusersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | | <a id="autocompleteduserstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="autocompleteduserstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | -| <a id="autocompletedusertwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="autocompletedusertwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | | <a id="autocompleteduseruserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | | <a id="autocompleteduseruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | | <a id="autocompleteduserusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | @@ -14178,7 +14704,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14214,7 +14740,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14250,7 +14776,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14279,7 +14805,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14327,7 +14853,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14345,7 +14871,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14361,7 +14887,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14384,7 +14910,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14401,19 +14927,25 @@ four standard [pagination arguments](#connection-pagination-arguments): Workspaces owned by the current user. +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + Returns [`WorkspaceConnection`](#workspaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="autocompleteduserworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="autocompleteduserworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="autocompleteduserworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | +| <a id="autocompleteduserworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="autocompleteduserworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="autocompleteduserworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="autocompleteduserworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="autocompleteduserworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | ### `AwardEmoji` @@ -14527,7 +15059,7 @@ Returns [`BoardEpicConnection`](#boardepicconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14543,7 +15075,7 @@ Returns [`BoardListConnection`](#boardlistconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14626,7 +15158,7 @@ Returns [`EpicConnection`](#epicconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14663,7 +15195,7 @@ Returns [`EpicConnection`](#epicconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14700,7 +15232,7 @@ Returns [`TodoConnection!`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14716,7 +15248,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14780,7 +15312,7 @@ Returns [`IssueConnection`](#issueconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -14867,16 +15399,14 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="cicatalogresourcedescription"></a>`description` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.11. This feature is an Experiment. It can be changed or removed at any time. Description of the catalog resource. | -| <a id="cicatalogresourceforkscount"></a>`forksCount` **{warning-solid}** | [`Int!`](#int) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Number of times the catalog resource has been forked. | | <a id="cicatalogresourceicon"></a>`icon` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.11. This feature is an Experiment. It can be changed or removed at any time. Icon for the catalog resource. | | <a id="cicatalogresourceid"></a>`id` **{warning-solid}** | [`ID!`](#id) | **Introduced** in 15.11. This feature is an Experiment. It can be changed or removed at any time. ID of the catalog resource. | | <a id="cicatalogresourcelatestreleasedat"></a>`latestReleasedAt` **{warning-solid}** | [`Time`](#time) | **Introduced** in 16.5. This feature is an Experiment. It can be changed or removed at any time. Release date of the catalog resource's latest version. | -| <a id="cicatalogresourcelatestversion"></a>`latestVersion` **{warning-solid}** | [`Release`](#release) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Latest version of the catalog resource. | +| <a id="cicatalogresourcelatestversion"></a>`latestVersion` **{warning-solid}** | [`CiCatalogResourceVersion`](#cicatalogresourceversion) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Latest version of the catalog resource. | | <a id="cicatalogresourcename"></a>`name` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.11. This feature is an Experiment. It can be changed or removed at any time. Name of the catalog resource. | | <a id="cicatalogresourceopenissuescount"></a>`openIssuesCount` **{warning-solid}** | [`Int!`](#int) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Count of open issues that belong to the the catalog resource. | | <a id="cicatalogresourceopenmergerequestscount"></a>`openMergeRequestsCount` **{warning-solid}** | [`Int!`](#int) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Count of open merge requests that belong to the the catalog resource. | | <a id="cicatalogresourcereadmehtml"></a>`readmeHtml` **{warning-solid}** | [`String!`](#string) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. GitLab Flavored Markdown rendering of `readme`. | -| <a id="cicatalogresourcerootnamespace"></a>`rootNamespace` **{warning-solid}** | [`Namespace`](#namespace) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Root namespace of the catalog resource. | | <a id="cicatalogresourcestarcount"></a>`starCount` **{warning-solid}** | [`Int!`](#int) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Number of times the catalog resource has been starred. | | <a id="cicatalogresourcewebpath"></a>`webPath` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.1. This feature is an Experiment. It can be changed or removed at any time. Web path of the catalog resource. | @@ -14890,17 +15420,53 @@ WARNING: **Introduced** in 16.2. This feature is an Experiment. It can be changed or removed at any time. -Returns [`ReleaseConnection`](#releaseconnection). +Returns [`CiCatalogResourceVersionConnection`](#cicatalogresourceversionconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="cicatalogresourceversionssort"></a>`sort` | [`ReleaseSort`](#releasesort) | Sort releases by given criteria. | +| <a id="cicatalogresourceversionssort"></a>`sort` | [`CiCatalogResourceVersionSort`](#cicatalogresourceversionsort) | Sort versions by given criteria. | + +### `CiCatalogResourceComponent` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cicatalogresourcecomponentid"></a>`id` **{warning-solid}** | [`CiCatalogResourcesComponentID!`](#cicatalogresourcescomponentid) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. ID of the component. | +| <a id="cicatalogresourcecomponentinputs"></a>`inputs` **{warning-solid}** | [`[CiCatalogResourceComponentInput!]`](#cicatalogresourcecomponentinput) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Inputs for the component. | +| <a id="cicatalogresourcecomponentname"></a>`name` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Name of the component. | +| <a id="cicatalogresourcecomponentpath"></a>`path` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Path used to include the component. | + +### `CiCatalogResourceComponentInput` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cicatalogresourcecomponentinputdefault"></a>`default` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Default value for the input. | +| <a id="cicatalogresourcecomponentinputname"></a>`name` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Name of the input. | +| <a id="cicatalogresourcecomponentinputrequired"></a>`required` **{warning-solid}** | [`Boolean`](#boolean) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Indicates if an input is required. | + +### `CiCatalogResourceVersion` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="cicatalogresourceversionauthor"></a>`author` **{warning-solid}** | [`UserCore`](#usercore) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. User that created the version. | +| <a id="cicatalogresourceversioncommit"></a>`commit` **{warning-solid}** | [`Commit`](#commit) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Commit associated with the version. | +| <a id="cicatalogresourceversioncomponents"></a>`components` **{warning-solid}** | [`CiCatalogResourceComponentConnection`](#cicatalogresourcecomponentconnection) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Components belonging to the catalog resource. | +| <a id="cicatalogresourceversioncreatedat"></a>`createdAt` **{warning-solid}** | [`Time`](#time) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Timestamp of when the version was created. | +| <a id="cicatalogresourceversionid"></a>`id` **{warning-solid}** | [`CiCatalogResourcesVersionID!`](#cicatalogresourcesversionid) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Global ID of the version. | +| <a id="cicatalogresourceversionreleasedat"></a>`releasedAt` **{warning-solid}** | [`Time`](#time) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Timestamp of when the version was released. | +| <a id="cicatalogresourceversiontagname"></a>`tagName` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Name of the tag associated with the version. | +| <a id="cicatalogresourceversiontagpath"></a>`tagPath` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Relative web path to the tag associated with the version. | ### `CiConfig` @@ -15316,7 +15882,7 @@ Returns [`CiJobConnection`](#cijobconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -15332,7 +15898,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -15454,6 +16020,30 @@ GitLab CI/CD configuration template. | <a id="clusteragentvulnerabilityimages"></a>`vulnerabilityImages` | [`VulnerabilityContainerImageConnection`](#vulnerabilitycontainerimageconnection) | Container images reported on the agent vulnerabilities. (see [Connections](#connections)) | | <a id="clusteragentwebpath"></a>`webPath` | [`String`](#string) | Web path of the cluster agent. | +#### Fields with arguments + +##### `ClusterAgent.workspaces` + +Workspaces associated with the agent. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`WorkspaceConnection`](#workspaceconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="clusteragentworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="clusteragentworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="clusteragentworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalID. | + ### `ClusterAgentActivityEvent` #### Fields @@ -15590,7 +16180,7 @@ Represents a degradation on the compared codequality report. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="codequalityreportscomparerreportdegradationdescription"></a>`description` | [`String!`](#string) | Description of the code quality degradation. | -| <a id="codequalityreportscomparerreportdegradationenginename"></a>`engineName` | [`String!`](#string) | Code quality plugin that reported the degradation. | +| <a id="codequalityreportscomparerreportdegradationenginename"></a>`engineName` | [`String`](#string) | Code quality plugin that reported the degradation. | | <a id="codequalityreportscomparerreportdegradationfilepath"></a>`filePath` | [`String!`](#string) | Relative path to the file containing the code quality degradation. | | <a id="codequalityreportscomparerreportdegradationfingerprint"></a>`fingerprint` | [`String!`](#string) | Unique fingerprint to identify the code quality degradation. For example, an MD5 hash. | | <a id="codequalityreportscomparerreportdegradationline"></a>`line` | [`Int!`](#int) | Line on which the code quality degradation occurred. | @@ -15649,7 +16239,7 @@ Returns [`PipelineConnection`](#pipelineconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -15765,11 +16355,24 @@ Represents finding. | <a id="comparedsecurityreportfindingfoundbypipelineiid"></a>`foundByPipelineIid` | [`String`](#string) | IID of the pipeline. | | <a id="comparedsecurityreportfindingidentifiers"></a>`identifiers` **{warning-solid}** | [`[VulnerabilityIdentifier!]`](#vulnerabilityidentifier) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Identifiers of the vulnerability finding. Returns `null` if `sast_reports_in_inline_diff` feature flag is disabled. | | <a id="comparedsecurityreportfindinglocation"></a>`location` **{warning-solid}** | [`VulnerabilityLocation`](#vulnerabilitylocation) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. Location of the vulnerability finding. Returns `null` if `sast_reports_in_inline_diff` feature flag is disabled. | +| <a id="comparedsecurityreportfindingscanner"></a>`scanner` | [`ComparedSecurityReportScanner`](#comparedsecurityreportscanner) | Compared report vulnerability scanner. | | <a id="comparedsecurityreportfindingseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability finding. | | <a id="comparedsecurityreportfindingstate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | Finding status. | | <a id="comparedsecurityreportfindingtitle"></a>`title` | [`String`](#string) | Title of the vulnerability finding. | | <a id="comparedsecurityreportfindinguuid"></a>`uuid` | [`String`](#string) | UUIDv5 digest based on the vulnerability's report type, primary identifier, location, fingerprint, project identifier. | +### `ComparedSecurityReportScanner` + +Represents a compared report vulnerability scanner. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="comparedsecurityreportscannerexternalid"></a>`externalId` | [`String`](#string) | External ID of the vulnerability scanner. | +| <a id="comparedsecurityreportscannername"></a>`name` | [`String`](#string) | Name of the vulnerability scanner. | +| <a id="comparedsecurityreportscannervendor"></a>`vendor` | [`String`](#string) | Vendor of the vulnerability scanner. | + ### `ComplianceFramework` Represents a ComplianceFramework associated with a Project. @@ -15784,6 +16387,7 @@ Represents a ComplianceFramework associated with a Project. | <a id="complianceframeworkid"></a>`id` | [`ID!`](#id) | Compliance framework ID. | | <a id="complianceframeworkname"></a>`name` | [`String!`](#string) | Name of the compliance framework. | | <a id="complianceframeworkpipelineconfigurationfullpath"></a>`pipelineConfigurationFullPath` | [`String`](#string) | Full path of the compliance pipeline configuration stored in a project repository, such as `.gitlab/.compliance-gitlab-ci.yml@compliance/hipaa` **(ULTIMATE ALL)**. | +| <a id="complianceframeworkprojects"></a>`projects` | [`ProjectConnection`](#projectconnection) | Projects associated with the compliance framework. (see [Connections](#connections)) | ### `ComplianceStandardsAdherence` @@ -15907,10 +16511,10 @@ A container registry protection rule designed to prevent users with a certain ac | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="containerregistryprotectionrulecontainerpathpattern"></a>`containerPathPattern` | [`String!`](#string) | Container repository path pattern protected by the protection rule. For example `@my-scope/my-container-*`. Wildcard character `*` allowed. | | <a id="containerregistryprotectionruledeleteprotecteduptoaccesslevel"></a>`deleteProtectedUpToAccessLevel` | [`ContainerRegistryProtectionRuleAccessLevel!`](#containerregistryprotectionruleaccesslevel) | Max GitLab access level to prevent from pushing container images to the container registry. For example `DEVELOPER`, `MAINTAINER`, `OWNER`. | | <a id="containerregistryprotectionruleid"></a>`id` | [`ContainerRegistryProtectionRuleID!`](#containerregistryprotectionruleid) | ID of the container registry protection rule. | | <a id="containerregistryprotectionrulepushprotecteduptoaccesslevel"></a>`pushProtectedUpToAccessLevel` | [`ContainerRegistryProtectionRuleAccessLevel!`](#containerregistryprotectionruleaccesslevel) | Max GitLab access level to prevent from pushing container images to the container registry. For example `DEVELOPER`, `MAINTAINER`, `OWNER`. | +| <a id="containerregistryprotectionrulerepositorypathpattern"></a>`repositoryPathPattern` | [`String!`](#string) | Container repository path pattern protected by the protection rule. For example `my-project/my-container-*`. Wildcard character `*` allowed. | ### `ContainerRepository` @@ -15920,7 +16524,7 @@ A container repository. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="containerrepositorycandelete"></a>`canDelete` | [`Boolean!`](#boolean) | Can the current user delete the container repository. | +| <a id="containerrepositorycandelete"></a>`canDelete` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.7. Use `userPermissions` field. See `ContainerRepositoryPermissions` type. | | <a id="containerrepositorycreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp when the container repository was created. | | <a id="containerrepositoryexpirationpolicycleanupstatus"></a>`expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | Tags cleanup status for the container repository. | | <a id="containerrepositoryexpirationpolicystartedat"></a>`expirationPolicyStartedAt` | [`Time`](#time) | Timestamp when the cleanup done by the expiration policy was started on the container repository. | @@ -15934,6 +16538,7 @@ A container repository. | <a id="containerrepositorystatus"></a>`status` | [`ContainerRepositoryStatus`](#containerrepositorystatus) | Status of the container repository. | | <a id="containerrepositorytagscount"></a>`tagsCount` | [`Int!`](#int) | Number of tags associated with this image. | | <a id="containerrepositoryupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp when the container repository was updated. | +| <a id="containerrepositoryuserpermissions"></a>`userPermissions` | [`ContainerRepositoryPermissions!`](#containerrepositorypermissions) | Permissions for the current user on the resource. | ### `ContainerRepositoryDetails` @@ -15943,7 +16548,7 @@ Details of a container repository. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="containerrepositorydetailscandelete"></a>`canDelete` | [`Boolean!`](#boolean) | Can the current user delete the container repository. | +| <a id="containerrepositorydetailscandelete"></a>`canDelete` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.7. Use `userPermissions` field. See `ContainerRepositoryPermissions` type. | | <a id="containerrepositorydetailscreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp when the container repository was created. | | <a id="containerrepositorydetailsexpirationpolicycleanupstatus"></a>`expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | Tags cleanup status for the container repository. | | <a id="containerrepositorydetailsexpirationpolicystartedat"></a>`expirationPolicyStartedAt` | [`Time`](#time) | Timestamp when the cleanup done by the expiration policy was started on the container repository. | @@ -15958,6 +16563,7 @@ Details of a container repository. | <a id="containerrepositorydetailsstatus"></a>`status` | [`ContainerRepositoryStatus`](#containerrepositorystatus) | Status of the container repository. | | <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. | +| <a id="containerrepositorydetailsuserpermissions"></a>`userPermissions` | [`ContainerRepositoryPermissions!`](#containerrepositorypermissions) | Permissions for the current user on the resource. | #### Fields with arguments @@ -15969,7 +16575,7 @@ 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`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -15978,6 +16584,14 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="containerrepositorydetailstagsname"></a>`name` | [`String`](#string) | Search by tag name. | | <a id="containerrepositorydetailstagssort"></a>`sort` | [`ContainerRepositoryTagSort`](#containerrepositorytagsort) | Sort tags by these criteria. | +### `ContainerRepositoryPermissions` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="containerrepositorypermissionsdestroycontainerrepository"></a>`destroyContainerRepository` | [`Boolean!`](#boolean) | If `true`, the user can perform `destroy_container_image` on this resource. | + ### `ContainerRepositoryRegistry` Represents the Geo replication and verification state of an Container Repository. @@ -16010,7 +16624,7 @@ A tag from a container repository. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="containerrepositorytagcandelete"></a>`canDelete` | [`Boolean!`](#boolean) | Can the current user delete this tag. | +| <a id="containerrepositorytagcandelete"></a>`canDelete` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.7. Use `userPermissions` field. See `ContainerRepositoryTagPermissions` type. | | <a id="containerrepositorytagcreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp when the tag was created. | | <a id="containerrepositorytagdigest"></a>`digest` | [`String`](#string) | Digest of the tag. | | <a id="containerrepositorytaglocation"></a>`location` | [`String!`](#string) | URL of the tag. | @@ -16019,6 +16633,15 @@ A tag from a container repository. | <a id="containerrepositorytagrevision"></a>`revision` | [`String`](#string) | Revision of the tag. | | <a id="containerrepositorytagshortrevision"></a>`shortRevision` | [`String`](#string) | Short revision of the tag. | | <a id="containerrepositorytagtotalsize"></a>`totalSize` | [`BigInt`](#bigint) | Size of the tag. | +| <a id="containerrepositorytaguserpermissions"></a>`userPermissions` | [`ContainerRepositoryTagPermissions!`](#containerrepositorytagpermissions) | Permissions for the current user on the resource. | + +### `ContainerRepositoryTagPermissions` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="containerrepositorytagpermissionsdestroycontainerrepositorytag"></a>`destroyContainerRepositoryTag` | [`Boolean!`](#boolean) | If `true`, the user can perform `destroy_container_image` on this resource. | ### `ContributionAnalyticsContribution` @@ -16074,6 +16697,293 @@ Represents the current license. | <a id="currentlicenseusersinlicensecount"></a>`usersInLicenseCount` | [`Int`](#int) | Number of paid users in the license. | | <a id="currentlicenseusersoverlicensecount"></a>`usersOverLicenseCount` | [`Int`](#int) | Number of users over the paid users in the license. | +### `CurrentUser` + +The currently authenticated GitLab user. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentuseravatarurl"></a>`avatarUrl` | [`String`](#string) | URL of the user's avatar. | +| <a id="currentuserbio"></a>`bio` | [`String`](#string) | Bio of the user. | +| <a id="currentuserbot"></a>`bot` | [`Boolean!`](#boolean) | Indicates if the user is a bot. | +| <a id="currentusercallouts"></a>`callouts` | [`UserCalloutConnection`](#usercalloutconnection) | User callouts that belong to the user. (see [Connections](#connections)) | +| <a id="currentusercommitemail"></a>`commitEmail` | [`String`](#string) | User's default commit email. | +| <a id="currentusercreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of when the user was created. | +| <a id="currentuserdiscord"></a>`discord` | [`String`](#string) | Discord ID of the user. | +| <a id="currentuseremail"></a>`email` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.7. This was renamed. Use: [`User.publicEmail`](#userpublicemail). | +| <a id="currentuseremails"></a>`emails` | [`EmailConnection`](#emailconnection) | User's email addresses. (see [Connections](#connections)) | +| <a id="currentusergitpodenabled"></a>`gitpodEnabled` | [`Boolean`](#boolean) | Whether Gitpod is enabled at the user level. | +| <a id="currentusergroupcount"></a>`groupCount` | [`Int`](#int) | Group count for the user. | +| <a id="currentusergroupmemberships"></a>`groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | +| <a id="currentuserid"></a>`id` | [`ID!`](#id) | ID of the user. | +| <a id="currentuseride"></a>`ide` | [`Ide`](#ide) | IDE settings. | +| <a id="currentuserjobtitle"></a>`jobTitle` | [`String`](#string) | Job title of the user. | +| <a id="currentuserlastactivityon"></a>`lastActivityOn` | [`Date`](#date) | Date the user last performed any actions. | +| <a id="currentuserlinkedin"></a>`linkedin` | [`String`](#string) | LinkedIn profile name of the user. | +| <a id="currentuserlocation"></a>`location` | [`String`](#string) | Location of the user. | +| <a id="currentusername"></a>`name` | [`String!`](#string) | Human-readable name of the user. Returns `****` if the user is a project bot and the requester does not have permission to view the project. | +| <a id="currentusernamespace"></a>`namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | +| <a id="currentusernamespacecommitemails"></a>`namespaceCommitEmails` | [`NamespaceCommitEmailConnection`](#namespacecommitemailconnection) | User's custom namespace commit emails. (see [Connections](#connections)) | +| <a id="currentuserorganization"></a>`organization` | [`String`](#string) | Who the user represents or works for. | +| <a id="currentuserorganizations"></a>`organizations` **{warning-solid}** | [`OrganizationConnection`](#organizationconnection) | **Introduced** in 16.6. This feature is an Experiment. It can be changed or removed at any time. Organizations where the user has access. | +| <a id="currentuserpreferencesgitpodpath"></a>`preferencesGitpodPath` | [`String`](#string) | Web path to the Gitpod section within user preferences. | +| <a id="currentuserprofileenablegitpodpath"></a>`profileEnableGitpodPath` | [`String`](#string) | Web path to enable Gitpod for the user. | +| <a id="currentuserprojectmemberships"></a>`projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | +| <a id="currentuserpronouns"></a>`pronouns` | [`String`](#string) | Pronouns of the user. | +| <a id="currentuserpublicemail"></a>`publicEmail` | [`String`](#string) | User's public email. | +| <a id="currentusersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | +| <a id="currentuserstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | +| <a id="currentuserstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | +| <a id="currentusertwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | +| <a id="currentuseruserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | +| <a id="currentuseruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | +| <a id="currentuserusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | +| <a id="currentuserwebpath"></a>`webPath` | [`String!`](#string) | Web path of the user. | +| <a id="currentuserweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the user. | + +#### Fields with arguments + +##### `CurrentUser.assignedMergeRequests` + +Merge requests assigned to the user. + +Returns [`MergeRequestConnection`](#mergerequestconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentuserassignedmergerequestsapproved"></a>`approved` | [`Boolean`](#boolean) | Limit results to approved merge requests. Available only when the feature flag `mr_approved_filter` is enabled. | +| <a id="currentuserassignedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | +| <a id="currentuserassignedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | +| <a id="currentuserassignedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="currentuserassignedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | +| <a id="currentuserassignedmergerequestsgroupid"></a>`groupId` | [`GroupID`](#groupid) | The global ID of the group the authored merge requests should be in. Merge requests in subgroups are included. | +| <a id="currentuserassignedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | +| <a id="currentuserassignedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | +| <a id="currentuserassignedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | +| <a id="currentuserassignedmergerequestsmergedbefore"></a>`mergedBefore` | [`Time`](#time) | Merge requests merged before this date. | +| <a id="currentuserassignedmergerequestsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Title of the milestone. | +| <a id="currentuserassignedmergerequestsnot"></a>`not` | [`MergeRequestsResolverNegatedParams`](#mergerequestsresolvernegatedparams) | List of negated arguments. Warning: this argument is experimental and a subject to change in future. | +| <a id="currentuserassignedmergerequestsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | The global ID of the project the authored merge requests should be in. Incompatible with projectPath. | +| <a id="currentuserassignedmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | +| <a id="currentuserassignedmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | +| <a id="currentuserassignedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | +| <a id="currentuserassignedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | +| <a id="currentuserassignedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | +| <a id="currentuserassignedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| <a id="currentuserassignedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| <a id="currentuserassignedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | + +##### `CurrentUser.authoredMergeRequests` + +Merge requests authored by the user. + +Returns [`MergeRequestConnection`](#mergerequestconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentuserauthoredmergerequestsapproved"></a>`approved` | [`Boolean`](#boolean) | Limit results to approved merge requests. Available only when the feature flag `mr_approved_filter` is enabled. | +| <a id="currentuserauthoredmergerequestsassigneeusername"></a>`assigneeUsername` | [`String`](#string) | Username of the assignee. | +| <a id="currentuserauthoredmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | +| <a id="currentuserauthoredmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="currentuserauthoredmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | +| <a id="currentuserauthoredmergerequestsgroupid"></a>`groupId` | [`GroupID`](#groupid) | The global ID of the group the authored merge requests should be in. Merge requests in subgroups are included. | +| <a id="currentuserauthoredmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | +| <a id="currentuserauthoredmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | +| <a id="currentuserauthoredmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | +| <a id="currentuserauthoredmergerequestsmergedbefore"></a>`mergedBefore` | [`Time`](#time) | Merge requests merged before this date. | +| <a id="currentuserauthoredmergerequestsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Title of the milestone. | +| <a id="currentuserauthoredmergerequestsnot"></a>`not` | [`MergeRequestsResolverNegatedParams`](#mergerequestsresolvernegatedparams) | List of negated arguments. Warning: this argument is experimental and a subject to change in future. | +| <a id="currentuserauthoredmergerequestsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | The global ID of the project the authored merge requests should be in. Incompatible with projectPath. | +| <a id="currentuserauthoredmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | +| <a id="currentuserauthoredmergerequestsreviewerusername"></a>`reviewerUsername` | [`String`](#string) | Username of the reviewer. | +| <a id="currentuserauthoredmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | +| <a id="currentuserauthoredmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | +| <a id="currentuserauthoredmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | +| <a id="currentuserauthoredmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| <a id="currentuserauthoredmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| <a id="currentuserauthoredmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | + +##### `CurrentUser.groups` + +Groups where the user has access. + +Returns [`GroupConnection`](#groupconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentusergroupspermissionscope"></a>`permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| <a id="currentusergroupssearch"></a>`search` | [`String`](#string) | Search by group name or path. | + +##### `CurrentUser.reviewRequestedMergeRequests` + +Merge requests assigned to the user for review. + +Returns [`MergeRequestConnection`](#mergerequestconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentuserreviewrequestedmergerequestsapproved"></a>`approved` | [`Boolean`](#boolean) | Limit results to approved merge requests. Available only when the feature flag `mr_approved_filter` is enabled. | +| <a id="currentuserreviewrequestedmergerequestsassigneeusername"></a>`assigneeUsername` | [`String`](#string) | Username of the assignee. | +| <a id="currentuserreviewrequestedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | +| <a id="currentuserreviewrequestedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | +| <a id="currentuserreviewrequestedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="currentuserreviewrequestedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | +| <a id="currentuserreviewrequestedmergerequestsgroupid"></a>`groupId` | [`GroupID`](#groupid) | The global ID of the group the authored merge requests should be in. Merge requests in subgroups are included. | +| <a id="currentuserreviewrequestedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | +| <a id="currentuserreviewrequestedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | +| <a id="currentuserreviewrequestedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | +| <a id="currentuserreviewrequestedmergerequestsmergedbefore"></a>`mergedBefore` | [`Time`](#time) | Merge requests merged before this date. | +| <a id="currentuserreviewrequestedmergerequestsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Title of the milestone. | +| <a id="currentuserreviewrequestedmergerequestsnot"></a>`not` | [`MergeRequestsResolverNegatedParams`](#mergerequestsresolvernegatedparams) | List of negated arguments. Warning: this argument is experimental and a subject to change in future. | +| <a id="currentuserreviewrequestedmergerequestsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | The global ID of the project the authored merge requests should be in. Incompatible with projectPath. | +| <a id="currentuserreviewrequestedmergerequestsprojectpath"></a>`projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | +| <a id="currentuserreviewrequestedmergerequestssort"></a>`sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | +| <a id="currentuserreviewrequestedmergerequestssourcebranches"></a>`sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | +| <a id="currentuserreviewrequestedmergerequestsstate"></a>`state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | +| <a id="currentuserreviewrequestedmergerequeststargetbranches"></a>`targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +| <a id="currentuserreviewrequestedmergerequestsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Merge requests updated after this timestamp. | +| <a id="currentuserreviewrequestedmergerequestsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Merge requests updated before this timestamp. | + +##### `CurrentUser.savedReply` + +Saved reply authored by the user. + +Returns [`SavedReply`](#savedreply). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentusersavedreplyid"></a>`id` | [`UsersSavedReplyID!`](#userssavedreplyid) | ID of a saved reply. | + +##### `CurrentUser.snippets` + +Snippets authored by the user. + +Returns [`SnippetConnection`](#snippetconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentusersnippetsids"></a>`ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | +| <a id="currentusersnippetstype"></a>`type` | [`TypeEnum`](#typeenum) | Type of snippet. | +| <a id="currentusersnippetsvisibility"></a>`visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | + +##### `CurrentUser.starredProjects` + +Projects starred by the user. + +Returns [`ProjectConnection`](#projectconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentuserstarredprojectssearch"></a>`search` | [`String`](#string) | Search query. | + +##### `CurrentUser.timelogs` + +Time logged by the user. + +Returns [`TimelogConnection`](#timelogconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentusertimelogsenddate"></a>`endDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or before endDate. | +| <a id="currentusertimelogsendtime"></a>`endTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or before endTime. | +| <a id="currentusertimelogsgroupid"></a>`groupId` | [`GroupID`](#groupid) | List timelogs for a group. | +| <a id="currentusertimelogsprojectid"></a>`projectId` | [`ProjectID`](#projectid) | List timelogs for a project. | +| <a id="currentusertimelogssort"></a>`sort` | [`TimelogSort`](#timelogsort) | List timelogs in a particular order. | +| <a id="currentusertimelogsstartdate"></a>`startDate` | [`Time`](#time) | List timelogs within a date range where the logged date is equal to or after startDate. | +| <a id="currentusertimelogsstarttime"></a>`startTime` | [`Time`](#time) | List timelogs within a time range where the logged time is equal to or after startTime. | +| <a id="currentusertimelogsusername"></a>`username` | [`String`](#string) | List timelogs for a user. | + +##### `CurrentUser.todos` + +To-do items of the user. + +Returns [`TodoConnection`](#todoconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentusertodosaction"></a>`action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| <a id="currentusertodosauthorid"></a>`authorId` | [`[ID!]`](#id) | ID of an author. | +| <a id="currentusertodosgroupid"></a>`groupId` | [`[ID!]`](#id) | ID of a group. | +| <a id="currentusertodosprojectid"></a>`projectId` | [`[ID!]`](#id) | ID of a project. | +| <a id="currentusertodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| <a id="currentusertodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | + +##### `CurrentUser.workspaces` + +Workspaces owned by the current user. + +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`WorkspaceConnection`](#workspaceconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="currentuserworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="currentuserworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="currentuserworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="currentuserworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="currentuserworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | + ### `CustomEmoji` A custom emoji uploaded by user. @@ -16573,18 +17483,6 @@ Tags for a given deployment. | <a id="deploymenttagname"></a>`name` | [`String`](#string) | Name of this git tag. | | <a id="deploymenttagpath"></a>`path` | [`String`](#string) | Path for this tag. | -### `DeprecatedAiMessage` - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="deprecatedaimessagecontent"></a>`content` | [`String`](#string) | Content of the message or null if loading. | -| <a id="deprecatedaimessageerrors"></a>`errors` | [`[String!]!`](#string) | Errors that occurred while asynchronously fetching an AI(assistant) response. | -| <a id="deprecatedaimessageid"></a>`id` | [`ID`](#id) | Global ID of the message. | -| <a id="deprecatedaimessageisfetching"></a>`isFetching` | [`Boolean`](#boolean) | Whether the content is still being fetched, for a message with the assistant role. | -| <a id="deprecatedaimessagerole"></a>`role` | [`String!`](#string) | Role of the message (system, user, assistant). | - ### `DescriptionVersion` #### Fields @@ -16646,7 +17544,7 @@ Returns [`TodoConnection!`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -16662,7 +17560,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -16678,7 +17576,7 @@ Returns [`DesignVersionConnection!`](#designversionconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -16755,7 +17653,7 @@ Returns [`DesignConnection!`](#designconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -16786,7 +17684,7 @@ Returns [`DesignVersionConnection!`](#designversionconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -16885,7 +17783,7 @@ Returns [`DesignAtVersionConnection!`](#designatversionconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -16951,7 +17849,7 @@ Returns [`DevopsAdoptionSnapshotConnection`](#devopsadoptionsnapshotconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17181,7 +18079,7 @@ Returns [`DeploymentConnection`](#deploymentconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17285,7 +18183,7 @@ Returns [`EpicConnection`](#epicconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17322,7 +18220,7 @@ Returns [`EpicConnection`](#epicconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17359,7 +18257,7 @@ Returns [`TodoConnection!`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17375,7 +18273,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17422,7 +18320,7 @@ Returns [`EpicListConnection`](#epiclistconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17499,7 +18397,7 @@ Relationship between an epic and an issue. | <a id="epicissuedownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the issue has received. | | <a id="epicissueduedate"></a>`dueDate` | [`Time`](#time) | Due date of the issue. | | <a id="epicissueemailsdisabled"></a>`emailsDisabled` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.3. Use `emails_enabled`. | -| <a id="epicissueemailsenabled"></a>`emailsEnabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `false` if email notifications are disabled. | +| <a id="epicissueemailsenabled"></a>`emailsEnabled` | [`Boolean!`](#boolean) | Indicates if the parent project or group has email notifications disabled: `false` if email notifications are disabled. | | <a id="epicissueepic"></a>`epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | <a id="epicissueepicissueid"></a>`epicIssueId` | [`ID!`](#id) | ID of the epic-issue relation. | | <a id="epicissueescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy associated with the issue. Available for issues which support escalation. | @@ -17521,7 +18419,7 @@ Relationship between an epic and an issue. | <a id="epicissuemoved"></a>`moved` | [`Boolean`](#boolean) | Indicates if issue got moved from other project. | | <a id="epicissuemovedto"></a>`movedTo` | [`Issue`](#issue) | Updated Issue after it got moved to another project. | | <a id="epicissueparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants in the issue. (see [Connections](#connections)) | -| <a id="epicissueprojectid"></a>`projectId` | [`Int!`](#int) | ID of the issue project. | +| <a id="epicissueprojectid"></a>`projectId` | [`Int`](#int) | ID of the issue project. | | <a id="epicissuerelatedmergerequests"></a>`relatedMergeRequests` | [`MergeRequestConnection`](#mergerequestconnection) | Merge requests related to the issue. This field can only be resolved for one issue in any single request. (see [Connections](#connections)) | | <a id="epicissuerelatedvulnerabilities"></a>`relatedVulnerabilities` | [`VulnerabilityConnection`](#vulnerabilityconnection) | Related vulnerabilities of the issue. (see [Connections](#connections)) | | <a id="epicissuerelationpath"></a>`relationPath` | [`String`](#string) | URI path of the epic-issue relation. | @@ -17558,7 +18456,7 @@ Returns [`AlertManagementAlertConnection`](#alertmanagementalertconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17579,7 +18477,7 @@ Returns [`TodoConnection!`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17595,7 +18493,7 @@ Returns [`IssuableResourceLinkConnection`](#issuableresourcelinkconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17611,7 +18509,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17658,7 +18556,7 @@ Returns [`EpicConnection`](#epicconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17888,7 +18786,7 @@ Returns [`CiSecureFileRegistryConnection`](#cisecurefileregistryconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17907,7 +18805,7 @@ Returns [`ContainerRepositoryRegistryConnection`](#containerrepositoryregistryco This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17930,7 +18828,7 @@ Returns [`DependencyProxyBlobRegistryConnection`](#dependencyproxyblobregistryco This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17949,7 +18847,7 @@ Returns [`DependencyProxyManifestRegistryConnection`](#dependencyproxymanifestre This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17972,7 +18870,7 @@ Returns [`DesignManagementRepositoryRegistryConnection`](#designmanagementreposi This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -17991,7 +18889,7 @@ Returns [`GroupWikiRepositoryRegistryConnection`](#groupwikirepositoryregistryco This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18010,7 +18908,7 @@ Returns [`JobArtifactRegistryConnection`](#jobartifactregistryconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18029,7 +18927,7 @@ Returns [`LfsObjectRegistryConnection`](#lfsobjectregistryconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18048,7 +18946,7 @@ Returns [`MergeRequestDiffRegistryConnection`](#mergerequestdiffregistryconnecti This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18067,7 +18965,7 @@ Returns [`PackageFileRegistryConnection`](#packagefileregistryconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18086,7 +18984,7 @@ Returns [`PagesDeploymentRegistryConnection`](#pagesdeploymentregistryconnection This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18105,7 +19003,7 @@ Returns [`PipelineArtifactRegistryConnection`](#pipelineartifactregistryconnecti This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18124,7 +19022,7 @@ Returns [`ProjectRepositoryRegistryConnection`](#projectrepositoryregistryconnec This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18143,7 +19041,7 @@ Returns [`ProjectWikiRepositoryRegistryConnection`](#projectwikirepositoryregist This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18162,7 +19060,7 @@ Returns [`SnippetRepositoryRegistryConnection`](#snippetrepositoryregistryconnec This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18181,7 +19079,7 @@ Returns [`TerraformStateVersionRegistryConnection`](#terraformstateversionregist This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18200,7 +19098,7 @@ Returns [`UploadRegistryConnection`](#uploadregistryconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18270,7 +19168,6 @@ GPG signature for a signed commit. | <a id="groupcontainerrepositoriescount"></a>`containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the group. | | <a id="groupcontainslockedprojects"></a>`containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. This only applies to namespaces under Project limit enforcement. | | <a id="groupcrossprojectpipelineavailable"></a>`crossProjectPipelineAvailable` | [`Boolean!`](#boolean) | Indicates if the cross_project_pipeline feature is available for the namespace. | -| <a id="groupcustomemoji"></a>`customEmoji` **{warning-solid}** | [`CustomEmojiConnection`](#customemojiconnection) | **Introduced** in 13.6. This feature is an Experiment. It can be changed or removed at any time. Custom emoji within this namespace. | | <a id="groupdependencyproxyblobcount"></a>`dependencyProxyBlobCount` | [`Int!`](#int) | Number of dependency proxy blobs cached in the group. | | <a id="groupdependencyproxyblobs"></a>`dependencyProxyBlobs` | [`DependencyProxyBlobConnection`](#dependencyproxyblobconnection) | Dependency Proxy blobs. (see [Connections](#connections)) | | <a id="groupdependencyproxyimagecount"></a>`dependencyProxyImageCount` | [`Int!`](#int) | Number of dependency proxy images cached in the group. | @@ -18294,7 +19191,7 @@ GPG signature for a signed commit. | <a id="groupfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the namespace. | | <a id="groupgooglecloudloggingconfigurations"></a>`googleCloudLoggingConfigurations` | [`GoogleCloudLoggingConfigurationTypeConnection`](#googlecloudloggingconfigurationtypeconnection) | Google Cloud logging configurations that receive audit events belonging to the group. (see [Connections](#connections)) | | <a id="groupid"></a>`id` | [`ID!`](#id) | ID of the namespace. | -| <a id="groupistemporarystorageincreaseenabled"></a>`isTemporaryStorageIncreaseEnabled` | [`Boolean!`](#boolean) | Status of the temporary storage increase. | +| <a id="groupistemporarystorageincreaseenabled"></a>`isTemporaryStorageIncreaseEnabled` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.7. Feature removal, will be completely removed in 17.0. | | <a id="grouplfsenabled"></a>`lfsEnabled` | [`Boolean`](#boolean) | Indicates if Large File Storage (LFS) is enabled for namespace. | | <a id="groupmentionsdisabled"></a>`mentionsDisabled` | [`Boolean`](#boolean) | Indicates if a group is disabled from getting mentioned. | | <a id="groupname"></a>`name` | [`String!`](#string) | Name of the namespace. | @@ -18313,12 +19210,13 @@ GPG signature for a signed commit. | <a id="groupstats"></a>`stats` | [`GroupStats`](#groupstats) | Group statistics. | | <a id="groupstoragesizelimit"></a>`storageSizeLimit` | [`Float`](#float) | The storage limit (in bytes) included with the root namespace plan. This limit only applies to namespaces under namespace limit enforcement. | | <a id="groupsubgroupcreationlevel"></a>`subgroupCreationLevel` | [`String`](#string) | Permission level required to create subgroups within the group. | -| <a id="grouptemporarystorageincreaseendson"></a>`temporaryStorageIncreaseEndsOn` | [`Time`](#time) | Date until the temporary storage increase is active. | +| <a id="grouptemporarystorageincreaseendson"></a>`temporaryStorageIncreaseEndsOn` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 16.7. Feature removal, will be completely removed in 17.0. | | <a id="grouptimelogcategories"></a>`timelogCategories` **{warning-solid}** | [`TimeTrackingTimelogCategoryConnection`](#timetrackingtimelogcategoryconnection) | **Introduced** in 15.3. This feature is an Experiment. It can be changed or removed at any time. Timelog categories for the namespace. | | <a id="grouptotalrepositorysize"></a>`totalRepositorySize` | [`Float`](#float) | Total repository size of all projects in the root namespace in bytes. | | <a id="grouptotalrepositorysizeexcess"></a>`totalRepositorySizeExcess` | [`Float`](#float) | Total excess repository size of all projects in the root namespace in bytes. This only applies to namespaces under Project limit enforcement. | | <a id="grouptwofactorgraceperiod"></a>`twoFactorGracePeriod` | [`Int`](#int) | Time before two-factor authentication is enforced. | | <a id="groupuserpermissions"></a>`userPermissions` | [`GroupPermissions!`](#grouppermissions) | Permissions for the current user on the resource. | +| <a id="groupvaluestreams"></a>`valueStreams` | [`ValueStreamConnection`](#valuestreamconnection) | Value streams available to the group. (see [Connections](#connections)) | | <a id="groupvisibility"></a>`visibility` | [`String`](#string) | Visibility of the namespace. | | <a id="groupvulnerabilityscanners"></a>`vulnerabilityScanners` | [`VulnerabilityScannerConnection`](#vulnerabilityscannerconnection) | Vulnerability scanners reported on the project vulnerabilities of the group and its subgroups. (see [Connections](#connections)) | | <a id="groupweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the group. | @@ -18337,7 +19235,7 @@ Returns [`AchievementConnection`](#achievementconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18357,7 +19255,7 @@ Returns [`AddOnUserConnection`](#addonuserconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18422,7 +19320,7 @@ Returns [`BoardConnection`](#boardconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18438,7 +19336,7 @@ Returns [`CiGroupVariableConnection`](#cigroupvariableconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18454,13 +19352,14 @@ Returns [`ClusterAgentConnection`](#clusteragentconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | | <a id="groupclusteragentshasremotedevelopmentagentconfig"></a>`hasRemoteDevelopmentAgentConfig` | [`Boolean`](#boolean) | Returns only cluster agents which have an associated remote development agent config. | +| <a id="groupclusteragentshasremotedevelopmentenabled"></a>`hasRemoteDevelopmentEnabled` | [`Boolean`](#boolean) | Returns only cluster agents which have been enabled with the remote development feature. | | <a id="groupclusteragentshasvulnerabilities"></a>`hasVulnerabilities` | [`Boolean`](#boolean) | Returns only cluster agents which have vulnerabilities. | ##### `Group.codeCoverageActivities` @@ -18471,7 +19370,7 @@ Returns [`CodeCoverageActivityConnection`](#codecoverageactivityconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18487,13 +19386,15 @@ Returns [`ComplianceFrameworkConnection`](#complianceframeworkconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | | <a id="groupcomplianceframeworksid"></a>`id` | [`ComplianceManagementFrameworkID`](#compliancemanagementframeworkid) | Global ID of a specific compliance framework to return. | +| <a id="groupcomplianceframeworksids"></a>`ids` | [`[ComplianceManagementFrameworkID!]`](#compliancemanagementframeworkid) | List of Global IDs of compliance frameworks to return. | +| <a id="groupcomplianceframeworkssearch"></a>`search` | [`String`](#string) | Search framework with most similar names. | ##### `Group.contactStateCounts` @@ -18516,7 +19417,7 @@ Returns [`CustomerRelationsContactConnection`](#customerrelationscontactconnecti This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18535,7 +19436,7 @@ Returns [`ContainerRepositoryConnection`](#containerrepositoryconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18552,7 +19453,7 @@ Returns [`ContributionAnalyticsContributionConnection`](#contributionanalyticsco This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18561,6 +19462,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupcontributionsfrom"></a>`from` | [`ISO8601Date!`](#iso8601date) | Start date of the reporting time range. | | <a id="groupcontributionsto"></a>`to` | [`ISO8601Date!`](#iso8601date) | End date of the reporting time range. The end date must be within 93 days after the start date. | +##### `Group.customEmoji` + +Custom emoji in this namespace. + +WARNING: +**Introduced** in 13.6. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`CustomEmojiConnection`](#customemojiconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, and `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupcustomemojiincludeancestorgroups"></a>`includeAncestorGroups` | [`Boolean`](#boolean) | Includes custom emoji from parent groups. | + ##### `Group.customizableDashboardVisualizations` Visualizations of the group or associated configuration project. @@ -18573,7 +19494,7 @@ Returns [`CustomizableDashboardVisualizationConnection`](#customizabledashboardv This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18593,7 +19514,7 @@ Returns [`CustomizableDashboardConnection`](#customizabledashboardconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18623,7 +19544,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18641,7 +19562,7 @@ Returns [`DoraPerformanceScoreCountConnection`](#doraperformancescorecountconnec This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18657,7 +19578,7 @@ Returns [`CiGroupEnvironmentScopeConnection`](#cigroupenvironmentscopeconnection This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18719,7 +19640,7 @@ Returns [`EpicConnection`](#epicconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18761,6 +19682,7 @@ Returns [`PreviewBillableUserChange`](#previewbillableuserchange). | <a id="groupgitlabsubscriptionspreviewbillableuserchangeaddgroupid"></a>`addGroupId` | [`Int`](#int) | Group ID to add. | | <a id="groupgitlabsubscriptionspreviewbillableuserchangeadduseremails"></a>`addUserEmails` | [`[String!]`](#string) | User emails to add. | | <a id="groupgitlabsubscriptionspreviewbillableuserchangeadduserids"></a>`addUserIds` | [`[Int!]`](#int) | User IDs to add. | +| <a id="groupgitlabsubscriptionspreviewbillableuserchangememberroleid"></a>`memberRoleId` | [`Int`](#int) | Custom role assigned to the users. | | <a id="groupgitlabsubscriptionspreviewbillableuserchangerole"></a>`role` | [`GitlabSubscriptionsUserRole!`](#gitlabsubscriptionsuserrole) | Role of users being added to group. | ##### `Group.groupMembers` @@ -18771,7 +19693,7 @@ Returns [`GroupMemberConnection`](#groupmemberconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18790,7 +19712,7 @@ Returns [`IssueConnection`](#issueconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18845,7 +19767,7 @@ Returns [`IterationCadenceConnection`](#iterationcadenceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18866,7 +19788,7 @@ Returns [`IterationConnection`](#iterationconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18876,6 +19798,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupiterationsiid"></a>`iid` | [`ID`](#id) | Internal ID of the Iteration to look up. | | <a id="groupiterationsin"></a>`in` | [`[IterationSearchableField!]`](#iterationsearchablefield) | Fields in which the fuzzy-search should be performed with the query given in the argument `search`. Defaults to `[title]`. | | <a id="groupiterationsincludeancestors"></a>`includeAncestors` | [`Boolean`](#boolean) | Whether to include ancestor iterations. Defaults to true. | +| <a id="groupiterationsincludedescendants"></a>`includeDescendants` | [`Boolean`](#boolean) | Whether to include descendant iterations. | | <a id="groupiterationsiterationcadenceids"></a>`iterationCadenceIds` | [`[IterationsCadenceID!]`](#iterationscadenceid) | Global iteration cadence IDs by which to look up the iterations. | | <a id="groupiterationssearch"></a>`search` | [`String`](#string) | Query used for fuzzy-searching in the fields selected in the argument `in`. Returns all iterations if empty. | | <a id="groupiterationssort"></a>`sort` | [`IterationSort`](#iterationsort) | List iterations by sort order. If unspecified, an arbitrary order (subject to change) is used. | @@ -18903,7 +19826,7 @@ Returns [`LabelConnection`](#labelconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18926,7 +19849,7 @@ Returns [`MemberRoleConnection`](#memberroleconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18942,7 +19865,7 @@ Returns [`ComplianceViolationConnection`](#complianceviolationconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18959,7 +19882,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -18994,7 +19917,7 @@ Returns [`MilestoneConnection`](#milestoneconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19031,7 +19954,7 @@ Returns [`CustomerRelationsOrganizationConnection`](#customerrelationsorganizati This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19050,7 +19973,7 @@ Returns [`PackageConnection`](#packageconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19071,7 +19994,7 @@ Returns [`ComplianceStandardsAdherenceConnection`](#compliancestandardsadherence This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19087,7 +20010,7 @@ Returns [`ProjectConnection!`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19113,7 +20036,7 @@ Returns [`ReleaseConnection`](#releaseconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19129,7 +20052,7 @@ Returns [`CiRunnerConnection`](#cirunnerconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19155,7 +20078,7 @@ Returns [`ScanExecutionPolicyConnection`](#scanexecutionpolicyconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19172,7 +20095,7 @@ Returns [`ScanResultPolicyConnection`](#scanresultpolicyconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19188,7 +20111,7 @@ Returns [`TimelogConnection!`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19228,7 +20151,7 @@ Returns [`VulnerabilityConnection`](#vulnerabilityconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19258,7 +20181,7 @@ Returns [`VulnerabilitiesCountByDayConnection`](#vulnerabilitiescountbydayconnec This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19320,6 +20243,31 @@ Returns [`WorkItem`](#workitem). | ---- | ---- | ----------- | | <a id="groupworkitemiid"></a>`iid` | [`String!`](#string) | IID of the work item. | +##### `Group.workItemStateCounts` + +Counts of work items by state for the namespace. Returns `null` if the `namespace_level_work_items` feature flag is disabled. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`WorkItemStateCountsType`](#workitemstatecountstype). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupworkitemstatecountsauthorusername"></a>`authorUsername` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.9. This feature is an Experiment. It can be changed or removed at any time. Filter work items by author username. | +| <a id="groupworkitemstatecountsiid"></a>`iid` | [`String`](#string) | IID of the work item. For example, "1". | +| <a id="groupworkitemstatecountsiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of work items. For example, `["1", "2"]`. | +| <a id="groupworkitemstatecountsin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument.'. | +| <a id="groupworkitemstatecountsrequirementlegacywidget"></a>`requirementLegacyWidget` **{warning-solid}** | [`RequirementLegacyFilterInput`](#requirementlegacyfilterinput) | **Deprecated** in 15.9. Use work item IID filter instead. | +| <a id="groupworkitemstatecountssearch"></a>`search` | [`String`](#string) | Search query for title or description. | +| <a id="groupworkitemstatecountssort"></a>`sort` | [`WorkItemSort`](#workitemsort) | Sort work items by criteria. | +| <a id="groupworkitemstatecountsstate"></a>`state` | [`IssuableState`](#issuablestate) | Current state of the work item. | +| <a id="groupworkitemstatecountsstatuswidget"></a>`statusWidget` | [`StatusFilterInput`](#statusfilterinput) | Input for status widget filter. Ignored if `work_items_mvc_2` is disabled. | +| <a id="groupworkitemstatecountstypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filter work items by the given work item types. | + ##### `Group.workItemTypes` Work item types available to the group. @@ -19328,7 +20276,7 @@ Returns [`WorkItemTypeConnection`](#workitemtypeconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19348,7 +20296,7 @@ Returns [`WorkItemConnection`](#workitemconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19560,6 +20508,24 @@ Returns [`ValueStreamAnalyticsMetric`](#valuestreamanalyticsmetric). | <a id="groupvaluestreamanalyticsflowmetricsleadtimeto"></a>`to` | [`Time!`](#time) | Timestamp marking the end date and time. | | <a id="groupvaluestreamanalyticsflowmetricsleadtimeweight"></a>`weight` | [`Int`](#int) | Weight applied to the issue. | +##### `GroupValueStreamAnalyticsFlowMetrics.timeToMerge` + +Median time from merge request creation to merge request merged. + +Returns [`ValueStreamAnalyticsMetric`](#valuestreamanalyticsmetric). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="groupvaluestreamanalyticsflowmetricstimetomergeassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the merge request. | +| <a id="groupvaluestreamanalyticsflowmetricstimetomergeauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the merge request. | +| <a id="groupvaluestreamanalyticsflowmetricstimetomergefrom"></a>`from` | [`Time!`](#time) | Timestamp marking the start date and time. | +| <a id="groupvaluestreamanalyticsflowmetricstimetomergelabelnames"></a>`labelNames` | [`[String!]`](#string) | Labels applied to the merge request. | +| <a id="groupvaluestreamanalyticsflowmetricstimetomergemilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Milestone applied to the merge request. | +| <a id="groupvaluestreamanalyticsflowmetricstimetomergeprojectids"></a>`projectIds` | [`[ID!]`](#id) | Project IDs within the group hierarchy. | +| <a id="groupvaluestreamanalyticsflowmetricstimetomergeto"></a>`to` | [`Time!`](#time) | Timestamp marking the end date and time. | + ### `GroupWikiRepositoryRegistry` Represents the Geo sync and verification state of a group wiki repository. @@ -19646,7 +20612,7 @@ Returns [`IncidentManagementOncallShiftConnection`](#incidentmanagementoncallshi This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19714,6 +20680,20 @@ CI/CD variables a project inherites from its parent group and ancestors. | <a id="inheritedcivariableraw"></a>`raw` | [`Boolean`](#boolean) | Indicates whether the variable is raw. | | <a id="inheritedcivariablevariabletype"></a>`variableType` | [`CiVariableType`](#civariabletype) | Type of the variable. | +### `InstanceAmazonS3ConfigurationType` + +Stores instance level Amazon S3 configurations for audit event streaming. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="instanceamazons3configurationtypeaccesskeyxid"></a>`accessKeyXid` | [`String!`](#string) | Access key ID of the Amazon S3 account. | +| <a id="instanceamazons3configurationtypeawsregion"></a>`awsRegion` | [`String!`](#string) | AWS region where the bucket is created. | +| <a id="instanceamazons3configurationtypebucketname"></a>`bucketName` | [`String!`](#string) | Name of the bucket where the audit events would be logged. | +| <a id="instanceamazons3configurationtypeid"></a>`id` | [`ID!`](#id) | ID of the configuration. | +| <a id="instanceamazons3configurationtypename"></a>`name` | [`String!`](#string) | Name of the external destination to send audit events to. | + ### `InstanceExternalAuditEventDestination` Represents an external resource to send instance audit events to. @@ -19761,13 +20741,14 @@ Returns [`ClusterAgentConnection`](#clusteragentconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | | <a id="instancesecuritydashboardclusteragentshasremotedevelopmentagentconfig"></a>`hasRemoteDevelopmentAgentConfig` | [`Boolean`](#boolean) | Returns only cluster agents which have an associated remote development agent config. | +| <a id="instancesecuritydashboardclusteragentshasremotedevelopmentenabled"></a>`hasRemoteDevelopmentEnabled` | [`Boolean`](#boolean) | Returns only cluster agents which have been enabled with the remote development feature. | | <a id="instancesecuritydashboardclusteragentshasvulnerabilities"></a>`hasVulnerabilities` | [`Boolean`](#boolean) | Returns only cluster agents which have vulnerabilities. | ##### `InstanceSecurityDashboard.projects` @@ -19778,7 +20759,7 @@ Returns [`ProjectConnection!`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19864,7 +20845,7 @@ Describes an issuable resource link for incident issues. | <a id="issuedownvotes"></a>`downvotes` | [`Int!`](#int) | Number of downvotes the issue has received. | | <a id="issueduedate"></a>`dueDate` | [`Time`](#time) | Due date of the issue. | | <a id="issueemailsdisabled"></a>`emailsDisabled` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.3. Use `emails_enabled`. | -| <a id="issueemailsenabled"></a>`emailsEnabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `false` if email notifications are disabled. | +| <a id="issueemailsenabled"></a>`emailsEnabled` | [`Boolean!`](#boolean) | Indicates if the parent project or group has email notifications disabled: `false` if email notifications are disabled. | | <a id="issueepic"></a>`epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | <a id="issueescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy associated with the issue. Available for issues which support escalation. | | <a id="issueescalationstatus"></a>`escalationStatus` | [`IssueEscalationStatus`](#issueescalationstatus) | Escalation status of the issue. | @@ -19885,7 +20866,7 @@ Describes an issuable resource link for incident issues. | <a id="issuemoved"></a>`moved` | [`Boolean`](#boolean) | Indicates if issue got moved from other project. | | <a id="issuemovedto"></a>`movedTo` | [`Issue`](#issue) | Updated Issue after it got moved to another project. | | <a id="issueparticipants"></a>`participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants in the issue. (see [Connections](#connections)) | -| <a id="issueprojectid"></a>`projectId` | [`Int!`](#int) | ID of the issue project. | +| <a id="issueprojectid"></a>`projectId` | [`Int`](#int) | ID of the issue project. | | <a id="issuerelatedmergerequests"></a>`relatedMergeRequests` | [`MergeRequestConnection`](#mergerequestconnection) | Merge requests related to the issue. This field can only be resolved for one issue in any single request. (see [Connections](#connections)) | | <a id="issuerelatedvulnerabilities"></a>`relatedVulnerabilities` | [`VulnerabilityConnection`](#vulnerabilityconnection) | Related vulnerabilities of the issue. (see [Connections](#connections)) | | <a id="issuerelativeposition"></a>`relativePosition` | [`Int`](#int) | Relative position of the issue (used for positioning in epic tree and issue boards). | @@ -19921,7 +20902,7 @@ Returns [`AlertManagementAlertConnection`](#alertmanagementalertconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19942,7 +20923,7 @@ Returns [`TodoConnection!`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19958,7 +20939,7 @@ Returns [`IssuableResourceLinkConnection`](#issuableresourcelinkconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -19974,7 +20955,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20125,7 +21106,7 @@ Returns [`JiraProjectConnection`](#jiraprojectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20296,6 +21277,27 @@ Represents an entry from the Cloud License history. | <a id="locationblobpath"></a>`blobPath` | [`String`](#string) | HTTP URI path to view the input file in GitLab. | | <a id="locationpath"></a>`path` | [`String`](#string) | Path, relative to the root of the repository, of the filewhich was analyzed to detect the dependency. | +### `MLCandidateLinks` + +Represents links to perform actions on the candidate. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlcandidatelinksartifactpath"></a>`artifactPath` | [`String`](#string) | Path to the artifact. | +| <a id="mlcandidatelinksshowpath"></a>`showPath` | [`String`](#string) | Path to the details page of the candidate. | + +### `MLModelVersionLinks` + +Represents links to perform actions on the model version. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlmodelversionlinksshowpath"></a>`showPath` | [`String`](#string) | Path to the details page of the model version. | + ### `MavenMetadata` Maven metadata. @@ -20329,6 +21331,7 @@ Represents a member role. | <a id="memberroleenabledpermissions"></a>`enabledPermissions` **{warning-solid}** | [`[MemberRolePermission!]`](#memberrolepermission) | **Introduced** in 16.5. This feature is an Experiment. It can be changed or removed at any time. Array of all permissions enabled for the custom role. | | <a id="memberroleid"></a>`id` | [`MemberRoleID!`](#memberroleid) | ID of the member role. | | <a id="memberrolemanageprojectaccesstokens"></a>`manageProjectAccessTokens` **{warning-solid}** | [`Boolean`](#boolean) | **Introduced** in 16.5. This feature is an Experiment. It can be changed or removed at any time. Permission to admin project access tokens. | +| <a id="memberrolememberscount"></a>`membersCount` **{warning-solid}** | [`Int!`](#int) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Total number of members with the custom role. | | <a id="memberrolename"></a>`name` | [`String!`](#string) | Name of the member role. | | <a id="memberrolereadcode"></a>`readCode` **{warning-solid}** | [`Boolean`](#boolean) | **Introduced** in 16.5. This feature is an Experiment. It can be changed or removed at any time. Permission to read code. | | <a id="memberrolereaddependency"></a>`readDependency` **{warning-solid}** | [`Boolean`](#boolean) | **Introduced** in 16.5. This feature is an Experiment. It can be changed or removed at any time. Permission to read dependency. | @@ -20461,7 +21464,7 @@ Returns [`TodoConnection!`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20505,7 +21508,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20521,7 +21524,7 @@ Returns [`PipelineConnection`](#pipelineconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20601,7 +21604,7 @@ A user assigned to a merge request. | <a id="mergerequestassigneesavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | | <a id="mergerequestassigneestate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="mergerequestassigneestatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | -| <a id="mergerequestassigneetwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="mergerequestassigneetwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | | <a id="mergerequestassigneeuserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | | <a id="mergerequestassigneeuserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | | <a id="mergerequestassigneeusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | @@ -20618,7 +21621,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20654,7 +21657,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20690,7 +21693,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20707,7 +21710,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20755,7 +21758,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20773,7 +21776,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20789,7 +21792,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20812,7 +21815,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20829,19 +21832,25 @@ four standard [pagination arguments](#connection-pagination-arguments): Workspaces owned by the current user. +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + Returns [`WorkspaceConnection`](#workspaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mergerequestassigneeworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="mergerequestassigneeworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="mergerequestassigneeworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | +| <a id="mergerequestassigneeworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="mergerequestassigneeworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="mergerequestassigneeworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="mergerequestassigneeworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="mergerequestassigneeworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | ### `MergeRequestAuthor` @@ -20883,7 +21892,7 @@ The author of the merge request. | <a id="mergerequestauthorsavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | | <a id="mergerequestauthorstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="mergerequestauthorstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | -| <a id="mergerequestauthortwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="mergerequestauthortwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | | <a id="mergerequestauthoruserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | | <a id="mergerequestauthoruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | | <a id="mergerequestauthorusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | @@ -20900,7 +21909,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20936,7 +21945,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20972,7 +21981,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -20989,7 +21998,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21037,7 +22046,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21055,7 +22064,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21071,7 +22080,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21094,7 +22103,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21111,19 +22120,25 @@ four standard [pagination arguments](#connection-pagination-arguments): Workspaces owned by the current user. +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + Returns [`WorkspaceConnection`](#workspaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mergerequestauthorworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="mergerequestauthorworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="mergerequestauthorworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | +| <a id="mergerequestauthorworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="mergerequestauthorworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="mergerequestauthorworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="mergerequestauthorworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="mergerequestauthorworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | ### `MergeRequestDiff` @@ -21228,7 +22243,7 @@ A user participating in a merge request. | <a id="mergerequestparticipantsavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | | <a id="mergerequestparticipantstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="mergerequestparticipantstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | -| <a id="mergerequestparticipanttwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="mergerequestparticipanttwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | | <a id="mergerequestparticipantuserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | | <a id="mergerequestparticipantuserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | | <a id="mergerequestparticipantusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | @@ -21245,7 +22260,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21281,7 +22296,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21317,7 +22332,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21334,7 +22349,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21382,7 +22397,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21400,7 +22415,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21416,7 +22431,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21439,7 +22454,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21456,19 +22471,25 @@ four standard [pagination arguments](#connection-pagination-arguments): Workspaces owned by the current user. +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + Returns [`WorkspaceConnection`](#workspaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mergerequestparticipantworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="mergerequestparticipantworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="mergerequestparticipantworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | +| <a id="mergerequestparticipantworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="mergerequestparticipantworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="mergerequestparticipantworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="mergerequestparticipantworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="mergerequestparticipantworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | ### `MergeRequestPermissions` @@ -21546,7 +22567,7 @@ A user assigned to a merge request as a reviewer. | <a id="mergerequestreviewersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | | <a id="mergerequestreviewerstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="mergerequestreviewerstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | -| <a id="mergerequestreviewertwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="mergerequestreviewertwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | | <a id="mergerequestrevieweruserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | | <a id="mergerequestrevieweruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | | <a id="mergerequestreviewerusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | @@ -21563,7 +22584,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21599,7 +22620,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21635,7 +22656,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21652,7 +22673,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21700,7 +22721,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21718,7 +22739,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21734,7 +22755,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21757,7 +22778,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21774,19 +22795,25 @@ four standard [pagination arguments](#connection-pagination-arguments): Workspaces owned by the current user. +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + Returns [`WorkspaceConnection`](#workspaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="mergerequestreviewerworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="mergerequestreviewerworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="mergerequestreviewerworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | +| <a id="mergerequestreviewerworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="mergerequestreviewerworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="mergerequestreviewerworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="mergerequestreviewerworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="mergerequestreviewerworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | ### `Metadata` @@ -21875,6 +22902,57 @@ Contains statistics about a milestone. | <a id="milestonestatsclosedissuescount"></a>`closedIssuesCount` | [`Int`](#int) | Number of closed issues associated with the milestone. | | <a id="milestonestatstotalissuescount"></a>`totalIssuesCount` | [`Int`](#int) | Total number of issues associated with the milestone. | +### `MlCandidate` + +Candidate for a model version in the model registry. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlcandidate_links"></a>`_links` | [`MLCandidateLinks!`](#mlcandidatelinks) | Map of links to perform actions on the candidate. | +| <a id="mlcandidatecreatedat"></a>`createdAt` | [`Time!`](#time) | Date of creation. | +| <a id="mlcandidateid"></a>`id` | [`MlCandidateID!`](#mlcandidateid) | ID of the candidate. | +| <a id="mlcandidatename"></a>`name` | [`String!`](#string) | Name of the candidate. | + +### `MlModel` + +Machine learning model in the model registry. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlmodelcandidates"></a>`candidates` | [`MlCandidateConnection`](#mlcandidateconnection) | Version candidates of the model. (see [Connections](#connections)) | +| <a id="mlmodelid"></a>`id` | [`MlModelID!`](#mlmodelid) | ID of the model. | +| <a id="mlmodelname"></a>`name` | [`String!`](#string) | Name of the model. | +| <a id="mlmodelversions"></a>`versions` | [`MlModelVersionConnection`](#mlmodelversionconnection) | Versions of the model. (see [Connections](#connections)) | + +### `MlModelVersion` + +Version of a machine learning model. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mlmodelversion_links"></a>`_links` | [`MLModelVersionLinks!`](#mlmodelversionlinks) | Map of links to perform actions on the model version. | +| <a id="mlmodelversioncreatedat"></a>`createdAt` | [`Time!`](#time) | Date of creation. | +| <a id="mlmodelversionid"></a>`id` | [`MlModelVersionID!`](#mlmodelversionid) | ID of the model version. | +| <a id="mlmodelversionversion"></a>`version` | [`String!`](#string) | Name of the version. | + +### `MonthlyUsage` + +Product analytics events for a specific month and year. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="monthlyusagecount"></a>`count` | [`Int`](#int) | Count of product analytics events. | +| <a id="monthlyusagemonth"></a>`month` | [`Int!`](#int) | Month of the data. | +| <a id="monthlyusageyear"></a>`year` | [`Int!`](#int) | Year of the data. | + ### `Namespace` #### Fields @@ -21891,7 +22969,7 @@ Contains statistics about a milestone. | <a id="namespacefullname"></a>`fullName` | [`String!`](#string) | Full name of the namespace. | | <a id="namespacefullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the namespace. | | <a id="namespaceid"></a>`id` | [`ID!`](#id) | ID of the namespace. | -| <a id="namespaceistemporarystorageincreaseenabled"></a>`isTemporaryStorageIncreaseEnabled` | [`Boolean!`](#boolean) | Status of the temporary storage increase. | +| <a id="namespaceistemporarystorageincreaseenabled"></a>`isTemporaryStorageIncreaseEnabled` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.7. Feature removal, will be completely removed in 17.0. | | <a id="namespacelfsenabled"></a>`lfsEnabled` | [`Boolean`](#boolean) | Indicates if Large File Storage (LFS) is enabled for namespace. | | <a id="namespacename"></a>`name` | [`String!`](#string) | Name of the namespace. | | <a id="namespacepackagesettings"></a>`packageSettings` | [`PackageSettings`](#packagesettings) | Package settings for the namespace. | @@ -21901,7 +22979,7 @@ Contains statistics about a milestone. | <a id="namespacerootstoragestatistics"></a>`rootStorageStatistics` | [`RootStorageStatistics`](#rootstoragestatistics) | Aggregated storage statistics of the namespace. Only available for root namespaces. | | <a id="namespacesharedrunnerssetting"></a>`sharedRunnersSetting` | [`SharedRunnersSetting`](#sharedrunnerssetting) | Shared runners availability for the namespace and its descendants. | | <a id="namespacestoragesizelimit"></a>`storageSizeLimit` | [`Float`](#float) | The storage limit (in bytes) included with the root namespace plan. This limit only applies to namespaces under namespace limit enforcement. | -| <a id="namespacetemporarystorageincreaseendson"></a>`temporaryStorageIncreaseEndsOn` | [`Time`](#time) | Date until the temporary storage increase is active. | +| <a id="namespacetemporarystorageincreaseendson"></a>`temporaryStorageIncreaseEndsOn` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 16.7. Feature removal, will be completely removed in 17.0. | | <a id="namespacetimelogcategories"></a>`timelogCategories` **{warning-solid}** | [`TimeTrackingTimelogCategoryConnection`](#timetrackingtimelogcategoryconnection) | **Introduced** in 15.3. This feature is an Experiment. It can be changed or removed at any time. Timelog categories for the namespace. | | <a id="namespacetotalrepositorysize"></a>`totalRepositorySize` | [`Float`](#float) | Total repository size of all projects in the root namespace in bytes. | | <a id="namespacetotalrepositorysizeexcess"></a>`totalRepositorySizeExcess` | [`Float`](#float) | Total excess repository size of all projects in the root namespace in bytes. This only applies to namespaces under Project limit enforcement. | @@ -21921,7 +22999,7 @@ Returns [`AchievementConnection`](#achievementconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21941,7 +23019,7 @@ Returns [`AddOnUserConnection`](#addonuserconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -21970,13 +23048,15 @@ Returns [`ComplianceFrameworkConnection`](#complianceframeworkconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | | <a id="namespacecomplianceframeworksid"></a>`id` | [`ComplianceManagementFrameworkID`](#compliancemanagementframeworkid) | Global ID of a specific compliance framework to return. | +| <a id="namespacecomplianceframeworksids"></a>`ids` | [`[ComplianceManagementFrameworkID!]`](#compliancemanagementframeworkid) | List of Global IDs of compliance frameworks to return. | +| <a id="namespacecomplianceframeworkssearch"></a>`search` | [`String`](#string) | Search framework with most similar names. | ##### `Namespace.projects` @@ -21986,7 +23066,7 @@ Returns [`ProjectConnection!`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -22012,7 +23092,7 @@ Returns [`ScanExecutionPolicyConnection`](#scanexecutionpolicyconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -22029,7 +23109,7 @@ Returns [`ScanResultPolicyConnection`](#scanresultpolicyconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -22196,6 +23276,9 @@ Active period time range for on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="organizationavatarurl"></a>`avatarUrl` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Avatar URL of the organization. | +| <a id="organizationdescription"></a>`description` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Description of the organization. | +| <a id="organizationdescriptionhtml"></a>`descriptionHtml` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. GitLab Flavored Markdown rendering of `description`. | | <a id="organizationid"></a>`id` **{warning-solid}** | [`ID!`](#id) | **Introduced** in 16.4. This feature is an Experiment. It can be changed or removed at any time. ID of the organization. | | <a id="organizationname"></a>`name` **{warning-solid}** | [`String!`](#string) | **Introduced** in 16.4. This feature is an Experiment. It can be changed or removed at any time. Name of the organization. | | <a id="organizationorganizationusers"></a>`organizationUsers` **{warning-solid}** | [`OrganizationUserConnection!`](#organizationuserconnection) | **Introduced** in 16.4. This feature is an Experiment. It can be changed or removed at any time. Users with access to the organization. | @@ -22216,7 +23299,7 @@ Returns [`GroupConnection!`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -22519,6 +23602,7 @@ Namespace-level Package Registry settings. | <a id="packagesettingsnpmpackagerequestsforwardinglocked"></a>`npmPackageRequestsForwardingLocked` | [`Boolean!`](#boolean) | Indicates whether npm package forwarding settings are locked by a parent namespace. | | <a id="packagesettingsnugetduplicateexceptionregex"></a>`nugetDuplicateExceptionRegex` | [`UntrustedRegexp`](#untrustedregexp) | When nuget_duplicates_allowed is false, you can publish duplicate packages with names that match this regex. Otherwise, this setting has no effect. | | <a id="packagesettingsnugetduplicatesallowed"></a>`nugetDuplicatesAllowed` | [`Boolean!`](#boolean) | Indicates whether duplicate NuGet packages are allowed for this namespace. | +| <a id="packagesettingsnugetsymbolserverenabled"></a>`nugetSymbolServerEnabled` | [`Boolean!`](#boolean) | Indicates wheather the NuGet symbol server is enabled for this namespace. | | <a id="packagesettingspypipackagerequestsforwarding"></a>`pypiPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether PyPI package forwarding is allowed for this namespace. | | <a id="packagesettingspypipackagerequestsforwardinglocked"></a>`pypiPackageRequestsForwardingLocked` | [`Boolean!`](#boolean) | Indicates whether PyPI package forwarding settings are locked by a parent namespace. | @@ -22729,7 +23813,7 @@ Returns [`CiJobConnection`](#cijobconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -22761,7 +23845,7 @@ Returns [`PipelineSecurityReportFindingConnection`](#pipelinesecurityreportfindi This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23000,7 +24084,6 @@ Represents vulnerability finding of a security report on the pipeline. | ---- | ---- | ----------- | | <a id="projectactualrepositorysizelimit"></a>`actualRepositorySizeLimit` | [`Float`](#float) | Size limit for the repository in bytes. | | <a id="projectagentconfigurations"></a>`agentConfigurations` | [`AgentConfigurationConnection`](#agentconfigurationconnection) | Agent configurations defined by the project. (see [Connections](#connections)) | -| <a id="projectaiconversations"></a>`aiConversations` **{warning-solid}** | [`ProjectConversations`](#projectconversations) | **Introduced** in 16.0. This feature is an Experiment. It can be changed or removed at any time. Ai Chat conversations related to a given project. | | <a id="projectallowmergeonskippedpipeline"></a>`allowMergeOnSkippedPipeline` | [`Boolean`](#boolean) | If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs. | | <a id="projectapifuzzingciconfiguration"></a>`apiFuzzingCiConfiguration` | [`ApiFuzzingCiConfiguration`](#apifuzzingciconfiguration) | API fuzzing configuration for the project. | | <a id="projectarchived"></a>`archived` | [`Boolean`](#boolean) | Indicates the archived status of the project. | @@ -23011,6 +24094,8 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectcicdsettings"></a>`ciCdSettings` | [`ProjectCiCdSetting`](#projectcicdsetting) | CI/CD settings for the project. | | <a id="projectciconfigpathordefault"></a>`ciConfigPathOrDefault` | [`String!`](#string) | Path of the CI configuration file. | | <a id="projectcijobtokenscope"></a>`ciJobTokenScope` | [`CiJobTokenScopeType`](#cijobtokenscopetype) | The CI Job Tokens scope of access. | +| <a id="projectcisubscribedprojects"></a>`ciSubscribedProjects` | [`CiSubscriptionsProjectConnection`](#cisubscriptionsprojectconnection) | Triggers a new pipeline in the downstream project when a pipeline successfullycompletes on the(upstream) project. (see [Connections](#connections)) | +| <a id="projectcisubscriptionsprojects"></a>`ciSubscriptionsProjects` | [`CiSubscriptionsProjectConnection`](#cisubscriptionsprojectconnection) | Triggers a new pipeline in the(downstream) project when a pipeline successfullycompletes on the upstream project. (see [Connections](#connections)) | | <a id="projectcodecoveragesummary"></a>`codeCoverageSummary` | [`CodeCoverageSummary`](#codecoveragesummary) | Code coverage summary associated with the project. | | <a id="projectcomplianceframeworks"></a>`complianceFrameworks` | [`ComplianceFrameworkConnection`](#complianceframeworkconnection) | Compliance frameworks associated with the project. (see [Connections](#connections)) | | <a id="projectcontainerexpirationpolicy"></a>`containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy of the project. | @@ -23026,6 +24111,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectdetailedimportstatus"></a>`detailedImportStatus` | [`DetailedImportStatus`](#detailedimportstatus) | Detailed import status of the project. | | <a id="projectdora"></a>`dora` | [`Dora`](#dora) | Project's DORA metrics. | | <a id="projectflowmetrics"></a>`flowMetrics` **{warning-solid}** | [`ProjectValueStreamAnalyticsFlowMetrics`](#projectvaluestreamanalyticsflowmetrics) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Flow metrics for value stream analytics. | +| <a id="projectforkingaccesslevel"></a>`forkingAccessLevel` | [`ProjectFeatureAccess`](#projectfeatureaccess) | Access level required for forking access. | | <a id="projectforkscount"></a>`forksCount` | [`Int!`](#int) | Number of times the project has been forked. | | <a id="projectfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the project. | | <a id="projectgrafanaintegration"></a>`grafanaIntegration` | [`GrafanaIntegration`](#grafanaintegration) | Grafana integration details for the project. | @@ -23036,6 +24122,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectimportstatus"></a>`importStatus` | [`String`](#string) | Status of import background job of the project. | | <a id="projectincidentmanagementtimelineeventtags"></a>`incidentManagementTimelineEventTags` | [`[TimelineEventTagType!]`](#timelineeventtagtype) | Timeline event tags for the project. | | <a id="projectiscatalogresource"></a>`isCatalogResource` **{warning-solid}** | [`Boolean`](#boolean) | **Introduced** in 15.11. This feature is an Experiment. It can be changed or removed at any time. Indicates if a project is a catalog resource. | +| <a id="projectissuesaccesslevel"></a>`issuesAccessLevel` | [`ProjectFeatureAccess`](#projectfeatureaccess) | Access level required for issues access. | | <a id="projectissuesenabled"></a>`issuesEnabled` | [`Boolean`](#boolean) | Indicates if Issues are enabled for the current user. | | <a id="projectjiraimportstatus"></a>`jiraImportStatus` | [`String`](#string) | Status of Jira import background job of the project. | | <a id="projectjiraimports"></a>`jiraImports` | [`JiraImportConnection`](#jiraimportconnection) | Jira imports into the project. (see [Connections](#connections)) | @@ -23044,6 +24131,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectlastactivityat"></a>`lastActivityAt` | [`Time`](#time) | Timestamp of the project last activity. | | <a id="projectlfsenabled"></a>`lfsEnabled` | [`Boolean`](#boolean) | Indicates if the project has Large File Storage (LFS) enabled. | | <a id="projectmergecommittemplate"></a>`mergeCommitTemplate` | [`String`](#string) | Template used to create merge commit message in merge requests. | +| <a id="projectmergerequestsaccesslevel"></a>`mergeRequestsAccessLevel` | [`ProjectFeatureAccess`](#projectfeatureaccess) | Access level required for merge requests access. | | <a id="projectmergerequestsdisablecommittersapproval"></a>`mergeRequestsDisableCommittersApproval` | [`Boolean!`](#boolean) | Indicates that committers of the given merge request cannot approve. | | <a id="projectmergerequestsenabled"></a>`mergeRequestsEnabled` | [`Boolean`](#boolean) | Indicates if Merge Requests are enabled for the current user. | | <a id="projectmergerequestsffonlyenabled"></a>`mergeRequestsFfOnlyEnabled` | [`Boolean`](#boolean) | Indicates if no merge commits should be created and all merges should instead be fast-forwarded, which means that merging is only allowed if the branch could be fast-forwarded. | @@ -23054,12 +24142,14 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectonlyallowmergeifallstatuscheckspassed"></a>`onlyAllowMergeIfAllStatusChecksPassed` | [`Boolean`](#boolean) | Indicates that merges of merge requests should be blocked unless all status checks have passed. | | <a id="projectonlyallowmergeifpipelinesucceeds"></a>`onlyAllowMergeIfPipelineSucceeds` | [`Boolean`](#boolean) | Indicates if merge requests of the project can only be merged with successful jobs. | | <a id="projectopenissuescount"></a>`openIssuesCount` | [`Int`](#int) | Number of open issues for the project. | +| <a id="projectopenmergerequestscount"></a>`openMergeRequestsCount` | [`Int`](#int) | Number of open merge requests for the project. | | <a id="projectpackagescleanuppolicy"></a>`packagesCleanupPolicy` | [`PackagesCleanupPolicy`](#packagescleanuppolicy) | Packages cleanup policy for the project. | | <a id="projectpackagesprotectionrules"></a>`packagesProtectionRules` | [`PackagesProtectionRuleConnection`](#packagesprotectionruleconnection) | Packages protection rules for the project. (see [Connections](#connections)) | | <a id="projectpath"></a>`path` | [`String!`](#string) | Path of the project. | | <a id="projectpathlocks"></a>`pathLocks` | [`PathLockConnection`](#pathlockconnection) | The project's path locks. (see [Connections](#connections)) | | <a id="projectpipelineanalytics"></a>`pipelineAnalytics` | [`PipelineAnalytics`](#pipelineanalytics) | Pipeline analytics. | | <a id="projectpipelinetriggers"></a>`pipelineTriggers` **{warning-solid}** | [`PipelineTriggerConnection`](#pipelinetriggerconnection) | **Introduced** in 16.3. This feature is an Experiment. It can be changed or removed at any time. List of pipeline trigger tokens. | +| <a id="projectpreventmergewithoutjiraissueenabled"></a>`preventMergeWithoutJiraIssueEnabled` | [`Boolean!`](#boolean) | Indicates if an associated issue from Jira is required. | | <a id="projectprintingmergerequestlinkenabled"></a>`printingMergeRequestLinkEnabled` | [`Boolean`](#boolean) | Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line. | | <a id="projectproductanalyticsinstrumentationkey"></a>`productAnalyticsInstrumentationKey` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.0. This feature is an Experiment. It can be changed or removed at any time. Product Analytics instrumentation key assigned to the project. | | <a id="projectproductanalyticsstate"></a>`productAnalyticsState` **{warning-solid}** | [`ProductAnalyticsState`](#productanalyticsstate) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Current state of the product analytics stack for this project.Can only be called for one project in a single request. | @@ -23093,6 +24183,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projecttrackingkey"></a>`trackingKey` **{warning-solid}** | [`String`](#string) | **Introduced** in 16.0. This feature is an Experiment. It can be changed or removed at any time. Tracking key assigned to the project. | | <a id="projectuseraccessauthorizedagents"></a>`userAccessAuthorizedAgents` | [`ClusterAgentAuthorizationUserAccessConnection`](#clusteragentauthorizationuseraccessconnection) | Authorized cluster agents for the project through user_access keyword. (see [Connections](#connections)) | | <a id="projectuserpermissions"></a>`userPermissions` | [`ProjectPermissions!`](#projectpermissions) | Permissions for the current user on the resource. | +| <a id="projectvaluestreams"></a>`valueStreams` | [`ValueStreamConnection`](#valuestreamconnection) | Value streams available to the project. (see [Connections](#connections)) | | <a id="projectvisibility"></a>`visibility` | [`String`](#string) | Visibility of the project. | | <a id="projectvulnerabilityimages"></a>`vulnerabilityImages` | [`VulnerabilityContainerImageConnection`](#vulnerabilitycontainerimageconnection) | Container images reported on the project vulnerabilities. (see [Connections](#connections)) | | <a id="projectvulnerabilityscanners"></a>`vulnerabilityScanners` | [`VulnerabilityScannerConnection`](#vulnerabilityscannerconnection) | Vulnerability scanners reported on the project vulnerabilities. (see [Connections](#connections)) | @@ -23139,7 +24230,7 @@ Returns [`AlertManagementAlertConnection`](#alertmanagementalertconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23160,7 +24251,7 @@ Returns [`AlertManagementHttpIntegrationConnection`](#alertmanagementhttpintegra This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23176,7 +24267,7 @@ Returns [`AlertManagementIntegrationConnection`](#alertmanagementintegrationconn This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23228,7 +24319,7 @@ Returns [`BoardConnection`](#boardconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23272,7 +24363,7 @@ Returns [`CiProjectVariableConnection`](#ciprojectvariableconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23291,6 +24382,7 @@ Returns [`ClusterAgent`](#clusteragent). | Name | Type | Description | | ---- | ---- | ----------- | | <a id="projectclusteragenthasremotedevelopmentagentconfig"></a>`hasRemoteDevelopmentAgentConfig` | [`Boolean`](#boolean) | Returns only cluster agents which have an associated remote development agent config. | +| <a id="projectclusteragenthasremotedevelopmentenabled"></a>`hasRemoteDevelopmentEnabled` | [`Boolean`](#boolean) | Returns only cluster agents which have been enabled with the remote development feature. | | <a id="projectclusteragenthasvulnerabilities"></a>`hasVulnerabilities` | [`Boolean`](#boolean) | Returns only cluster agents which have vulnerabilities. | | <a id="projectclusteragentname"></a>`name` | [`String!`](#string) | Name of the cluster agent. | @@ -23302,13 +24394,14 @@ Returns [`ClusterAgentConnection`](#clusteragentconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | | <a id="projectclusteragentshasremotedevelopmentagentconfig"></a>`hasRemoteDevelopmentAgentConfig` | [`Boolean`](#boolean) | Returns only cluster agents which have an associated remote development agent config. | +| <a id="projectclusteragentshasremotedevelopmentenabled"></a>`hasRemoteDevelopmentEnabled` | [`Boolean`](#boolean) | Returns only cluster agents which have been enabled with the remote development feature. | | <a id="projectclusteragentshasvulnerabilities"></a>`hasVulnerabilities` | [`Boolean`](#boolean) | Returns only cluster agents which have vulnerabilities. | ##### `Project.commitReferences` @@ -23335,7 +24428,7 @@ Returns [`ContainerRepositoryConnection`](#containerrepositoryconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23356,7 +24449,7 @@ Returns [`CustomizableDashboardVisualizationConnection`](#customizabledashboardv This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23376,7 +24469,7 @@ Returns [`CustomizableDashboardConnection`](#customizabledashboardconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23406,7 +24499,7 @@ Returns [`DastProfileConnection`](#dastprofileconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23434,7 +24527,7 @@ Returns [`DastSiteValidationConnection`](#dastsitevalidationconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23468,7 +24561,7 @@ Returns [`DependencyConnection`](#dependencyconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23513,7 +24606,7 @@ Returns [`EnvironmentConnection`](#environmentconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23548,7 +24641,7 @@ Returns [`NamespaceConnection`](#namespaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23569,6 +24662,7 @@ Returns [`PreviewBillableUserChange`](#previewbillableuserchange). | <a id="projectgitlabsubscriptionspreviewbillableuserchangeaddgroupid"></a>`addGroupId` | [`Int`](#int) | Group ID to add. | | <a id="projectgitlabsubscriptionspreviewbillableuserchangeadduseremails"></a>`addUserEmails` | [`[String!]`](#string) | User emails to add. | | <a id="projectgitlabsubscriptionspreviewbillableuserchangeadduserids"></a>`addUserIds` | [`[Int!]`](#int) | User IDs to add. | +| <a id="projectgitlabsubscriptionspreviewbillableuserchangememberroleid"></a>`memberRoleId` | [`Int`](#int) | Custom role assigned to the users. | | <a id="projectgitlabsubscriptionspreviewbillableuserchangerole"></a>`role` | [`GitlabSubscriptionsUserRole!`](#gitlabsubscriptionsuserrole) | Role of users being added to group. | ##### `Project.incidentManagementEscalationPolicies` @@ -23579,7 +24673,7 @@ Returns [`EscalationPolicyTypeConnection`](#escalationpolicytypeconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23608,7 +24702,7 @@ Returns [`IncidentManagementOncallScheduleConnection`](#incidentmanagementoncall This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23637,7 +24731,7 @@ Returns [`TimelineEventTypeConnection`](#timelineeventtypeconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23653,7 +24747,7 @@ Returns [`InheritedCiVariableConnection`](#inheritedcivariableconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23768,7 +24862,7 @@ Returns [`IssueConnection`](#issueconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23823,7 +24917,7 @@ Returns [`IterationCadenceConnection`](#iterationcadenceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23844,7 +24938,7 @@ Returns [`IterationConnection`](#iterationconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23854,6 +24948,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectiterationsiid"></a>`iid` | [`ID`](#id) | Internal ID of the Iteration to look up. | | <a id="projectiterationsin"></a>`in` | [`[IterationSearchableField!]`](#iterationsearchablefield) | Fields in which the fuzzy-search should be performed with the query given in the argument `search`. Defaults to `[title]`. | | <a id="projectiterationsincludeancestors"></a>`includeAncestors` | [`Boolean`](#boolean) | Whether to include ancestor iterations. Defaults to true. | +| <a id="projectiterationsincludedescendants"></a>`includeDescendants` | [`Boolean`](#boolean) | Whether to include descendant iterations. | | <a id="projectiterationsiterationcadenceids"></a>`iterationCadenceIds` | [`[IterationsCadenceID!]`](#iterationscadenceid) | Global iteration cadence IDs by which to look up the iterations. | | <a id="projectiterationssearch"></a>`search` | [`String`](#string) | Query used for fuzzy-searching in the fields selected in the argument `in`. Returns all iterations if empty. | | <a id="projectiterationssort"></a>`sort` | [`IterationSort`](#iterationsort) | List iterations by sort order. If unspecified, an arbitrary order (subject to change) is used. | @@ -23881,7 +24976,7 @@ Returns [`CiJobConnection`](#cijobconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23910,7 +25005,7 @@ Returns [`LabelConnection`](#labelconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23931,7 +25026,7 @@ Returns [`MemberRoleConnection`](#memberroleconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23959,7 +25054,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -23993,7 +25088,7 @@ Returns [`MilestoneConnection`](#milestoneconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24016,7 +25111,7 @@ Returns [`NestedEnvironmentConnection`](#nestedenvironmentconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24039,7 +25134,7 @@ Returns [`NetworkPolicyConnection`](#networkpolicyconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24055,7 +25150,7 @@ Returns [`PackageConnection`](#packageconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24103,7 +25198,7 @@ Returns [`PipelineScheduleConnection`](#pipelinescheduleconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24120,7 +25215,7 @@ Returns [`PipelineConnection`](#pipelineconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24137,16 +25232,19 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `Project.productAnalyticsEventsStored` -Count of all events used, filtered optionally by month. +Count of all events used, broken down by month. -Returns [`Int`](#int). +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`[MonthlyUsage!]`](#monthlyusage). ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectproductanalyticseventsstoredmonth"></a>`month` | [`Int`](#int) | Month for the period to return. | -| <a id="projectproductanalyticseventsstoredyear"></a>`year` | [`Int`](#int) | Year for the period to return. | +| <a id="projectproductanalyticseventsstoredmonthselection"></a>`monthSelection` | [`[MonthSelectionInput!]!`](#monthselectioninput) | Selection for the period to return. | ##### `Project.projectMembers` @@ -24156,7 +25254,7 @@ Returns [`MemberInterfaceConnection`](#memberinterfaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24186,7 +25284,7 @@ Returns [`ReleaseConnection`](#releaseconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24222,7 +25320,7 @@ Returns [`RequirementConnection`](#requirementconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24246,7 +25344,7 @@ Returns [`CiRunnerConnection`](#cirunnerconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24271,7 +25369,7 @@ Returns [`ScanExecutionPolicyConnection`](#scanexecutionpolicyconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24288,7 +25386,7 @@ Returns [`ScanResultPolicyConnection`](#scanresultpolicyconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24345,7 +25443,7 @@ Returns [`ServiceConnection`](#serviceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24362,7 +25460,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24391,7 +25489,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24418,7 +25516,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24434,7 +25532,7 @@ Returns [`VulnerabilityConnection`](#vulnerabilityconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24464,7 +25562,7 @@ Returns [`VulnerabilitiesCountByDayConnection`](#vulnerabilitiescountbydayconnec This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24497,6 +25595,31 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | <a id="projectvulnerabilityseveritiescountseverity"></a>`severity` | [`[VulnerabilitySeverity!]`](#vulnerabilityseverity) | Filter vulnerabilities by severity. | | <a id="projectvulnerabilityseveritiescountstate"></a>`state` | [`[VulnerabilityState!]`](#vulnerabilitystate) | Filter vulnerabilities by state. | +##### `Project.workItemStateCounts` + +Counts of work items by state for the project. + +WARNING: +**Introduced** in 16.7. +This feature is an Experiment. It can be changed or removed at any time. + +Returns [`WorkItemStateCountsType`](#workitemstatecountstype). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectworkitemstatecountsauthorusername"></a>`authorUsername` **{warning-solid}** | [`String`](#string) | **Introduced** in 15.9. This feature is an Experiment. It can be changed or removed at any time. Filter work items by author username. | +| <a id="projectworkitemstatecountsiid"></a>`iid` | [`String`](#string) | IID of the work item. For example, "1". | +| <a id="projectworkitemstatecountsiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of work items. For example, `["1", "2"]`. | +| <a id="projectworkitemstatecountsin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument.'. | +| <a id="projectworkitemstatecountsrequirementlegacywidget"></a>`requirementLegacyWidget` **{warning-solid}** | [`RequirementLegacyFilterInput`](#requirementlegacyfilterinput) | **Deprecated** in 15.9. Use work item IID filter instead. | +| <a id="projectworkitemstatecountssearch"></a>`search` | [`String`](#string) | Search query for title or description. | +| <a id="projectworkitemstatecountssort"></a>`sort` | [`WorkItemSort`](#workitemsort) | Sort work items by criteria. | +| <a id="projectworkitemstatecountsstate"></a>`state` | [`IssuableState`](#issuablestate) | Current state of the work item. | +| <a id="projectworkitemstatecountsstatuswidget"></a>`statusWidget` | [`StatusFilterInput`](#statusfilterinput) | Input for status widget filter. Ignored if `work_items_mvc_2` is disabled. | +| <a id="projectworkitemstatecountstypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filter work items by the given work item types. | + ##### `Project.workItemTypes` Work item types available to the project. @@ -24505,7 +25628,7 @@ Returns [`WorkItemTypeConnection`](#workitemtypeconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24525,7 +25648,7 @@ Returns [`WorkItemConnection`](#workitemconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -24556,22 +25679,25 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectcicdsettingmergetrainsskiptrainallowed"></a>`mergeTrainsSkipTrainAllowed` | [`Boolean!`](#boolean) | Whether merge immediately is allowed for merge trains. | | <a id="projectcicdsettingproject"></a>`project` | [`Project`](#project) | Project the CI/CD settings belong to. | -### `ProjectConversations` +### `ProjectDataTransfer` #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectconversationsciconfigmessages"></a>`ciConfigMessages` **{warning-solid}** | [`DeprecatedAiMessageConnection`](#deprecatedaimessageconnection) | **Introduced** in 16.0. This feature is an Experiment. It can be changed or removed at any time. Messages generated by open ai and the user. | +| <a id="projectdatatransferegressnodes"></a>`egressNodes` | [`EgressNodeConnection`](#egressnodeconnection) | Data nodes. (see [Connections](#connections)) | +| <a id="projectdatatransfertotalegress"></a>`totalEgress` | [`BigInt`](#bigint) | Total egress for that project in that period of time. | -### `ProjectDataTransfer` +### `ProjectFeatureAccess` + +Represents the access level required by the user to access a project feature. #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectdatatransferegressnodes"></a>`egressNodes` | [`EgressNodeConnection`](#egressnodeconnection) | Data nodes. (see [Connections](#connections)) | -| <a id="projectdatatransfertotalegress"></a>`totalEgress` | [`BigInt`](#bigint) | Total egress for that project in that period of time. | +| <a id="projectfeatureaccessintegervalue"></a>`integerValue` | [`Int`](#int) | Integer representation of access level. | +| <a id="projectfeatureaccessstringvalue"></a>`stringValue` | [`ProjectFeatureAccessLevel`](#projectfeatureaccesslevel) | String representation of access level. | ### `ProjectMember` @@ -24849,6 +25975,23 @@ Returns [`ValueStreamAnalyticsMetric`](#valuestreamanalyticsmetric). | <a id="projectvaluestreamanalyticsflowmetricsleadtimeto"></a>`to` | [`Time!`](#time) | Timestamp marking the end date and time. | | <a id="projectvaluestreamanalyticsflowmetricsleadtimeweight"></a>`weight` | [`Int`](#int) | Weight applied to the issue. | +##### `ProjectValueStreamAnalyticsFlowMetrics.timeToMerge` + +Median time from merge request creation to merge request merged. + +Returns [`ValueStreamAnalyticsMetric`](#valuestreamanalyticsmetric). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectvaluestreamanalyticsflowmetricstimetomergeassigneeusernames"></a>`assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the merge request. | +| <a id="projectvaluestreamanalyticsflowmetricstimetomergeauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the merge request. | +| <a id="projectvaluestreamanalyticsflowmetricstimetomergefrom"></a>`from` | [`Time!`](#time) | Timestamp marking the start date and time. | +| <a id="projectvaluestreamanalyticsflowmetricstimetomergelabelnames"></a>`labelNames` | [`[String!]`](#string) | Labels applied to the merge request. | +| <a id="projectvaluestreamanalyticsflowmetricstimetomergemilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Milestone applied to the merge request. | +| <a id="projectvaluestreamanalyticsflowmetricstimetomergeto"></a>`to` | [`Time!`](#time) | Timestamp marking the end date and time. | + ### `ProjectWikiRepositoryRegistry` Represents the Geo replication and verification state of a project_wiki_repository. @@ -25138,7 +26281,7 @@ Returns [`RepositoryBlobConnection`](#repositoryblobconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -25182,7 +26325,7 @@ Returns [`TreeConnection`](#treeconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -25285,7 +26428,7 @@ Returns [`Blame`](#blame). | Name | Type | Description | | ---- | ---- | ----------- | | <a id="repositoryblobblamefromline"></a>`fromLine` | [`Int`](#int) | Range starting from the line. Cannot be less than 1 or greater than `to_line`. | -| <a id="repositoryblobblametoline"></a>`toLine` | [`Int`](#int) | Range ending on the line. Cannot be less than 1 or less than `to_line`. | +| <a id="repositoryblobblametoline"></a>`toLine` | [`Int`](#int) | Range ending on the line. Cannot be smaller than `from_line` or greater than `from_line` + 100. | ### `RepositoryCodeownerError` @@ -25349,7 +26492,7 @@ Returns [`TestReportConnection`](#testreportconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -25744,7 +26887,7 @@ Returns [`SentryErrorConnection`](#sentryerrorconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -25847,7 +26990,7 @@ Returns [`SnippetBlobConnection`](#snippetblobconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -25863,7 +27006,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26491,7 +27634,7 @@ Core representation of a GitLab user. | <a id="usercoresavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | | <a id="usercorestate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="usercorestatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | -| <a id="usercoretwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="usercoretwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | | <a id="usercoreuserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | | <a id="usercoreuserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | | <a id="usercoreusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | @@ -26508,7 +27651,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26544,7 +27687,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26580,7 +27723,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26597,7 +27740,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26645,7 +27788,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26663,7 +27806,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26679,7 +27822,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26702,7 +27845,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26719,19 +27862,25 @@ four standard [pagination arguments](#connection-pagination-arguments): Workspaces owned by the current user. +WARNING: +**Introduced** in 16.6. +This feature is an Experiment. It can be changed or removed at any time. + Returns [`WorkspaceConnection`](#workspaceconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="usercoreworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="usercoreworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="usercoreworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | +| <a id="usercoreworkspacesactualstates"></a>`actualStates` | [`[String!]`](#string) | Filter workspaces by actual states. | +| <a id="usercoreworkspacesagentids"></a>`agentIds` | [`[ClustersAgentID!]`](#clustersagentid) | Filter workspaces by agent GlobalIDs. | +| <a id="usercoreworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Filter workspaces by workspace GlobalIDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | +| <a id="usercoreworkspacesincludeactualstates"></a>`includeActualStates` **{warning-solid}** | [`[String!]`](#string) | **Deprecated** in 16.7. Use actual_states instead. | +| <a id="usercoreworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project GlobalIDs. | ### `UserMergeRequestInteraction` @@ -26766,6 +27915,7 @@ fields relate to interactions between the two entities. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="userpreferencesissuessort"></a>`issuesSort` | [`IssueSort`](#issuesort) | Sort order for issue lists. | +| <a id="userpreferencesusewebideextensionmarketplace"></a>`useWebIdeExtensionMarketplace` | [`Boolean!`](#boolean) | Whether Web IDE Extension Marketplace is enabled for the user. | | <a id="userpreferencesvisibilitypipelineidtype"></a>`visibilityPipelineIdType` | [`VisibilityPipelineIdType`](#visibilitypipelineidtype) | Determines whether the pipeline list shows ID or IID. | ### `UserStatus` @@ -26789,6 +27939,7 @@ fields relate to interactions between the two entities. | <a id="valuestreamname"></a>`name` | [`String!`](#string) | Name of the value stream. | | <a id="valuestreamnamespace"></a>`namespace` | [`Namespace!`](#namespace) | Namespace the value stream belongs to. | | <a id="valuestreamproject"></a>`project` **{warning-solid}** | [`Project`](#project) | **Introduced** in 15.6. This feature is an Experiment. It can be changed or removed at any time. Project the value stream belongs to, returns empty if it belongs to a group. | +| <a id="valuestreamstages"></a>`stages` | [`[ValueStreamStage!]`](#valuestreamstage) | Value Stream stages. | ### `ValueStreamAnalyticsMetric` @@ -26825,6 +27976,20 @@ Represents a recorded measurement (object count) for the requested group. | <a id="valuestreammetriclinktypename"></a>`name` | [`String!`](#string) | Name of the link group. | | <a id="valuestreammetriclinktypeurl"></a>`url` | [`String!`](#string) | Drill-down URL. | +### `ValueStreamStage` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="valuestreamstagecustom"></a>`custom` | [`Boolean!`](#boolean) | Whether the stage is customized. | +| <a id="valuestreamstageendeventidentifier"></a>`endEventIdentifier` | [`ValueStreamStageEvent!`](#valuestreamstageevent) | End event identifier. | +| <a id="valuestreamstageendeventlabel"></a>`endEventLabel` | [`Label`](#label) | Label associated with end event. | +| <a id="valuestreamstagehidden"></a>`hidden` | [`Boolean!`](#boolean) | Whether the stage is hidden. | +| <a id="valuestreamstagename"></a>`name` | [`String!`](#string) | Name of the stage. | +| <a id="valuestreamstagestarteventidentifier"></a>`startEventIdentifier` | [`ValueStreamStageEvent!`](#valuestreamstageevent) | Start event identifier. | +| <a id="valuestreamstagestarteventlabel"></a>`startEventLabel` | [`Label`](#label) | Label associated with start event. | + ### `VulnerabilitiesCountByDay` Represents the count of vulnerabilities by severity on a particular day. This data is retained for 365 days. @@ -26871,6 +28036,7 @@ Represents a vulnerability. | <a id="vulnerabilitylocation"></a>`location` | [`VulnerabilityLocation`](#vulnerabilitylocation) | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability. | | <a id="vulnerabilitymergerequest"></a>`mergeRequest` | [`MergeRequest`](#mergerequest) | Merge request that fixes the vulnerability. | | <a id="vulnerabilitymessage"></a>`message` **{warning-solid}** | [`String`](#string) | **Deprecated** in 16.1. message field has been removed from security reports schema. | +| <a id="vulnerabilitypresentondefaultbranch"></a>`presentOnDefaultBranch` | [`Boolean!`](#boolean) | Indicates whether the vulnerability is present on the default branch or not. | | <a id="vulnerabilityprimaryidentifier"></a>`primaryIdentifier` | [`VulnerabilityIdentifier`](#vulnerabilityidentifier) | Primary identifier of the vulnerability. | | <a id="vulnerabilityproject"></a>`project` | [`Project`](#project) | Project on which the vulnerability was found. | | <a id="vulnerabilityreporttype"></a>`reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING, CLUSTER_IMAGE_SCANNING, GENERIC). `Scan Type` in the UI. | @@ -26901,7 +28067,7 @@ Returns [`VulnerabilityIssueLinkConnection!`](#vulnerabilityissuelinkconnection) This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -26917,7 +28083,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -27561,6 +28727,18 @@ Check permissions for the current user on a work item. | <a id="workitempermissionssetworkitemmetadata"></a>`setWorkItemMetadata` | [`Boolean!`](#boolean) | If `true`, the user can perform `set_work_item_metadata` on this resource. | | <a id="workitempermissionsupdateworkitem"></a>`updateWorkItem` | [`Boolean!`](#boolean) | If `true`, the user can perform `update_work_item` on this resource. | +### `WorkItemStateCountsType` + +Represents total number of work items for the represented states. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemstatecountstypeall"></a>`all` | [`Int`](#int) | Number of work items for the project or group. | +| <a id="workitemstatecountstypeclosed"></a>`closed` | [`Int`](#int) | Number of work items with state CLOSED for the project or group. | +| <a id="workitemstatecountstypeopened"></a>`opened` | [`Int`](#int) | Number of work items with state OPENED for the project or group. | + ### `WorkItemType` #### Fields @@ -27570,6 +28748,7 @@ Check permissions for the current user on a work item. | <a id="workitemtypeiconname"></a>`iconName` | [`String`](#string) | Icon name of the work item type. | | <a id="workitemtypeid"></a>`id` | [`WorkItemsTypeID!`](#workitemstypeid) | Global ID of the work item type. | | <a id="workitemtypename"></a>`name` | [`String!`](#string) | Name of the work item type. | +| <a id="workitemtypewidgetdefinitions"></a>`widgetDefinitions` **{warning-solid}** | [`[WorkItemWidgetDefinition!]`](#workitemwidgetdefinition) | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Available widgets for the work item type. | ### `WorkItemWidgetAssignees` @@ -27579,9 +28758,9 @@ Represents an assignees widget. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="workitemwidgetassigneesallowsmultipleassignees"></a>`allowsMultipleAssignees` | [`Boolean`](#boolean) | Indicates whether multiple assignees are allowed. | +| <a id="workitemwidgetassigneesallowsmultipleassignees"></a>`allowsMultipleAssignees` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 16.7. Field moved to workItemType widget definition interface. Use: [`workitemWidgetDefinitionAssignees.allowsMultipleAssignees`](#workitemwidgetdefinitionassigneesallowsmultipleassignees). | | <a id="workitemwidgetassigneesassignees"></a>`assignees` | [`UserCoreConnection`](#usercoreconnection) | Assignees of the work item. (see [Connections](#connections)) | -| <a id="workitemwidgetassigneescaninvitemembers"></a>`canInviteMembers` | [`Boolean!`](#boolean) | Indicates whether the current user can invite members to the work item's project. | +| <a id="workitemwidgetassigneescaninvitemembers"></a>`canInviteMembers` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 16.7. Field moved to workItemType widget definition interface. Use: [`workitemWidgetDefinitionAssignees.canInviteMembers`](#workitemwidgetdefinitionassigneescaninvitemembers). | | <a id="workitemwidgetassigneestype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | ### `WorkItemWidgetAwardEmoji` @@ -27617,7 +28796,7 @@ Returns [`TodoConnection!`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -27625,6 +28804,50 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="workitemwidgetcurrentusertodoscurrentusertodosstate"></a>`state` | [`TodoStateEnum`](#todostateenum) | State of the to-do items. | +### `WorkItemWidgetDefinitionAssignees` + +Represents an assignees widget definition. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetdefinitionassigneesallowsmultipleassignees"></a>`allowsMultipleAssignees` | [`Boolean!`](#boolean) | Indicates whether multiple assignees are allowed. | +| <a id="workitemwidgetdefinitionassigneescaninvitemembers"></a>`canInviteMembers` | [`Boolean!`](#boolean) | Indicates whether the current user can invite members to the work item's parent. | +| <a id="workitemwidgetdefinitionassigneestype"></a>`type` | [`WorkItemWidgetType!`](#workitemwidgettype) | Widget type. | + +### `WorkItemWidgetDefinitionGeneric` + +Represents a generic widget definition. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetdefinitiongenerictype"></a>`type` | [`WorkItemWidgetType!`](#workitemwidgettype) | Widget type. | + +### `WorkItemWidgetDefinitionHierarchy` + +Represents a hierarchy widget definition. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetdefinitionhierarchyallowedchildtypes"></a>`allowedChildTypes` | [`WorkItemTypeConnection`](#workitemtypeconnection) | Allowed child types for the work item type. (see [Connections](#connections)) | +| <a id="workitemwidgetdefinitionhierarchytype"></a>`type` | [`WorkItemWidgetType!`](#workitemwidgettype) | Widget type. | + +### `WorkItemWidgetDefinitionLabels` + +Represents a labels widget definition. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetdefinitionlabelsallowsscopedlabels"></a>`allowsScopedLabels` | [`Boolean!`](#boolean) | Indicates whether scoped labels are available. | +| <a id="workitemwidgetdefinitionlabelstype"></a>`type` | [`WorkItemWidgetType!`](#workitemwidgettype) | Widget type. | + ### `WorkItemWidgetDescription` Represents a description widget. @@ -27684,7 +28907,7 @@ Represents the labels widget. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="workitemwidgetlabelsallowsscopedlabels"></a>`allowsScopedLabels` | [`Boolean`](#boolean) | Indicates whether a scoped label is allowed. | +| <a id="workitemwidgetlabelsallowsscopedlabels"></a>`allowsScopedLabels` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 16.7. Field moved to workItemType widget definition interface. Use: [`WorkItemWidgetDefinitionLabels.allowsScopedLabels`](#workitemwidgetdefinitionlabelsallowsscopedlabels). | | <a id="workitemwidgetlabelslabels"></a>`labels` | [`LabelConnection`](#labelconnection) | Labels assigned to the work item. (see [Connections](#connections)) | | <a id="workitemwidgetlabelstype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | @@ -27715,7 +28938,7 @@ Returns [`LinkedWorkItemTypeConnection`](#linkedworkitemtypeconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -27754,7 +28977,7 @@ Returns [`DiscussionConnection`](#discussionconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ###### Arguments @@ -28155,6 +29378,7 @@ Values for scoping catalog resources. | Value | Description | | ----- | ----------- | | <a id="cicatalogresourcescopeall"></a>`ALL` | All catalog resources visible to the current user. | +| <a id="cicatalogresourcescopenamespaces"></a>`NAMESPACES` | Catalog resources belonging to authorized namespaces of the user. | ### `CiCatalogResourceSort` @@ -28169,6 +29393,17 @@ Values for sorting catalog resources. | <a id="cicatalogresourcesortname_asc"></a>`NAME_ASC` | Name by ascending order. | | <a id="cicatalogresourcesortname_desc"></a>`NAME_DESC` | Name by descending order. | +### `CiCatalogResourceVersionSort` + +Values for sorting catalog resource versions. + +| Value | Description | +| ----- | ----------- | +| <a id="cicatalogresourceversionsortcreated_asc"></a>`CREATED_ASC` | Created at ascending order. | +| <a id="cicatalogresourceversionsortcreated_desc"></a>`CREATED_DESC` | Created at descending order. | +| <a id="cicatalogresourceversionsortreleased_at_asc"></a>`RELEASED_AT_ASC` | Released at by ascending order. | +| <a id="cicatalogresourceversionsortreleased_at_desc"></a>`RELEASED_AT_DESC` | Released at by descending order. | + ### `CiConfigIncludeType` Include type. @@ -28785,6 +30020,8 @@ Values for sorting dependencies. | <a id="dependencysortname_desc"></a>`NAME_DESC` | Name by descending order. | | <a id="dependencysortpackager_asc"></a>`PACKAGER_ASC` | Packager by ascending order. | | <a id="dependencysortpackager_desc"></a>`PACKAGER_DESC` | Packager by descending order. | +| <a id="dependencysortseverity_asc"></a>`SEVERITY_ASC` | Severity by ascending order. | +| <a id="dependencysortseverity_desc"></a>`SEVERITY_DESC` | Severity by descending order. | ### `DeploymentApprovalSummaryStatus` @@ -28866,6 +30103,7 @@ Detailed representation of whether a GitLab merge request can be merged. | <a id="detailedmergestatusdiscussions_not_resolved"></a>`DISCUSSIONS_NOT_RESOLVED` | Discussions must be resolved before merging. | | <a id="detailedmergestatusdraft_status"></a>`DRAFT_STATUS` | Merge request must not be draft before merging. | | <a id="detailedmergestatusexternal_status_checks"></a>`EXTERNAL_STATUS_CHECKS` | Status checks must pass. | +| <a id="detailedmergestatusjira_association"></a>`JIRA_ASSOCIATION` | Either the title or description must reference a Jira issue. | | <a id="detailedmergestatusmergeable"></a>`MERGEABLE` | Branch can be merged. | | <a id="detailedmergestatusnot_approved"></a>`NOT_APPROVED` | Merge request must be approved before merging. | | <a id="detailedmergestatusnot_open"></a>`NOT_OPEN` | Merge request must be open before merging. | @@ -29265,12 +30503,13 @@ Issue type. | Value | Description | | ----- | ----------- | +| <a id="issuetypeepic"></a>`EPIC` **{warning-solid}** | **Introduced** in 16.7. This feature is an Experiment. It can be changed or removed at any time. Epic issue type. Available only when feature flag `namespace_level_work_items` is enabled. | | <a id="issuetypeincident"></a>`INCIDENT` | Incident issue type. | | <a id="issuetypeissue"></a>`ISSUE` | Issue issue type. | | <a id="issuetypekey_result"></a>`KEY_RESULT` **{warning-solid}** | **Introduced** in 15.7. This feature is an Experiment. It can be changed or removed at any time. Key Result issue type. Available only when feature flag `okrs_mvc` is enabled. | | <a id="issuetypeobjective"></a>`OBJECTIVE` **{warning-solid}** | **Introduced** in 15.6. This feature is an Experiment. It can be changed or removed at any time. Objective issue type. Available only when feature flag `okrs_mvc` is enabled. | | <a id="issuetyperequirement"></a>`REQUIREMENT` | Requirement issue type. | -| <a id="issuetypetask"></a>`TASK` **{warning-solid}** | **Introduced** in 15.2. This feature is an Experiment. It can be changed or removed at any time. Task issue type. | +| <a id="issuetypetask"></a>`TASK` | Task issue type. | | <a id="issuetypetest_case"></a>`TEST_CASE` | Test Case issue type. | ### `IterationSearchableField` @@ -29341,6 +30580,7 @@ Iteration ID wildcard values. | <a id="jobartifactfiletypemetrics_referee"></a>`METRICS_REFEREE` | METRICS REFEREE job artifact file type. | | <a id="jobartifactfiletypenetwork_referee"></a>`NETWORK_REFEREE` | NETWORK REFEREE job artifact file type. | | <a id="jobartifactfiletypeperformance"></a>`PERFORMANCE` | PERFORMANCE job artifact file type. | +| <a id="jobartifactfiletyperepository_xray"></a>`REPOSITORY_XRAY` | REPOSITORY XRAY job artifact file type. | | <a id="jobartifactfiletyperequirements"></a>`REQUIREMENTS` | REQUIREMENTS job artifact file type. | | <a id="jobartifactfiletyperequirements_v2"></a>`REQUIREMENTS_V2` | REQUIREMENTS V2 job artifact file type. | | <a id="jobartifactfiletypesast"></a>`SAST` | SAST job artifact file type. | @@ -29406,8 +30646,8 @@ Member role permission. | Value | Description | | ----- | ----------- | -| <a id="memberrolepermissionadmin_group_member"></a>`ADMIN_GROUP_MEMBER` | Allows admin access to group members. | -| <a id="memberrolepermissionadmin_merge_request"></a>`ADMIN_MERGE_REQUEST` | Allows admin access to the merge requests. | +| <a id="memberrolepermissionadmin_group_member"></a>`ADMIN_GROUP_MEMBER` | Allows to admin group members. | +| <a id="memberrolepermissionadmin_merge_request"></a>`ADMIN_MERGE_REQUEST` | Allows to approve merge requests. | | <a id="memberrolepermissionadmin_vulnerability"></a>`ADMIN_VULNERABILITY` | Allows admin access to the vulnerability reports. | | <a id="memberrolepermissionarchive_project"></a>`ARCHIVE_PROJECT` | Allows to archive projects. | | <a id="memberrolepermissionmanage_project_access_tokens"></a>`MANAGE_PROJECT_ACCESS_TOKENS` | Allows manage access to the project access tokens. | @@ -29519,17 +30759,17 @@ Representation of mergeability check identifier. | Value | Description | | ----- | ----------- | -| <a id="mergeabilitycheckidentifierbroken_status"></a>`BROKEN_STATUS` | Mergeability check identifier is broken_status. | -| <a id="mergeabilitycheckidentifierci_must_pass"></a>`CI_MUST_PASS` | Mergeability check identifier is ci_must_pass. | -| <a id="mergeabilitycheckidentifierconflict"></a>`CONFLICT` | Mergeability check identifier is conflict. | -| <a id="mergeabilitycheckidentifierdiscussions_not_resolved"></a>`DISCUSSIONS_NOT_RESOLVED` | Mergeability check identifier is discussions_not_resolved. | -| <a id="mergeabilitycheckidentifierdraft_status"></a>`DRAFT_STATUS` | Mergeability check identifier is draft_status. | -| <a id="mergeabilitycheckidentifiermerge_request_blocked"></a>`MERGE_REQUEST_BLOCKED` | Mergeability check identifier is merge_request_blocked. | -| <a id="mergeabilitycheckidentifierneed_rebase"></a>`NEED_REBASE` | Mergeability check identifier is need_rebase. | -| <a id="mergeabilitycheckidentifiernot_approved"></a>`NOT_APPROVED` | Mergeability check identifier is not_approved. | -| <a id="mergeabilitycheckidentifiernot_open"></a>`NOT_OPEN` | Mergeability check identifier is not_open. | -| <a id="mergeabilitycheckidentifierpolicies_denied"></a>`POLICIES_DENIED` | Mergeability check identifier is policies_denied. | -| <a id="mergeabilitycheckidentifierstatus_checks_must_pass"></a>`STATUS_CHECKS_MUST_PASS` | Mergeability check identifier is status_checks_must_pass. | +| <a id="mergeabilitycheckidentifierbroken_status"></a>`BROKEN_STATUS` | Checks whether the merge request is broken. | +| <a id="mergeabilitycheckidentifierci_must_pass"></a>`CI_MUST_PASS` | Checks whether CI has passed. | +| <a id="mergeabilitycheckidentifierconflict"></a>`CONFLICT` | Checks whether the merge request has a conflict. | +| <a id="mergeabilitycheckidentifierdiscussions_not_resolved"></a>`DISCUSSIONS_NOT_RESOLVED` | Checks whether the merge request has open discussions. | +| <a id="mergeabilitycheckidentifierdraft_status"></a>`DRAFT_STATUS` | Checks whether the merge request is draft. | +| <a id="mergeabilitycheckidentifierjira_association_missing"></a>`JIRA_ASSOCIATION_MISSING` | Checks whether the title or description references a Jira issue. | +| <a id="mergeabilitycheckidentifiermerge_request_blocked"></a>`MERGE_REQUEST_BLOCKED` | Checks whether the merge request is blocked. | +| <a id="mergeabilitycheckidentifierneed_rebase"></a>`NEED_REBASE` | Checks whether the merge request needs to be rebased. | +| <a id="mergeabilitycheckidentifiernot_approved"></a>`NOT_APPROVED` | Checks whether the merge request is approved. | +| <a id="mergeabilitycheckidentifiernot_open"></a>`NOT_OPEN` | Checks whether the merge request is open. | +| <a id="mergeabilitycheckidentifierstatus_checks_must_pass"></a>`STATUS_CHECKS_MUST_PASS` | Checks whether the external status checks pass. | ### `MergeabilityCheckStatus` @@ -29887,6 +31127,16 @@ Current state of the product analytics stack. | <a id="productanalyticsstateloading_instance"></a>`LOADING_INSTANCE` | Stack is currently initializing. | | <a id="productanalyticsstatewaiting_for_events"></a>`WAITING_FOR_EVENTS` | Stack is waiting for events from users. | +### `ProjectFeatureAccessLevel` + +Access level of a project feature. + +| Value | Description | +| ----- | ----------- | +| <a id="projectfeatureaccessleveldisabled"></a>`DISABLED` | Not enabled for anyone. | +| <a id="projectfeatureaccesslevelenabled"></a>`ENABLED` | Enabled for everyone able to access the project. | +| <a id="projectfeatureaccesslevelprivate"></a>`PRIVATE` | Enabled only for team members. | + ### `ProjectMemberRelation` Project member relation. @@ -30100,7 +31350,6 @@ State of a Sentry error. | <a id="servicetypepumble_service"></a>`PUMBLE_SERVICE` | PumbleService type. | | <a id="servicetypepushover_service"></a>`PUSHOVER_SERVICE` | PushoverService type. | | <a id="servicetyperedmine_service"></a>`REDMINE_SERVICE` | RedmineService type. | -| <a id="servicetypeshimo_service"></a>`SHIMO_SERVICE` | ShimoService type. | | <a id="servicetypeslack_service"></a>`SLACK_SERVICE` | SlackService type. | | <a id="servicetypeslack_slash_commands_service"></a>`SLACK_SLASH_COMMANDS_SERVICE` | SlackSlashCommandsService type. | | <a id="servicetypesquash_tm_service"></a>`SQUASH_TM_SERVICE` | SquashTmService type. | @@ -30290,6 +31539,8 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumci_deprecation_warning_for_types_keyword"></a>`CI_DEPRECATION_WARNING_FOR_TYPES_KEYWORD` | Callout feature name for ci_deprecation_warning_for_types_keyword. | | <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="usercalloutfeaturenameenumcode_suggestions_ga_non_owner_alert"></a>`CODE_SUGGESTIONS_GA_NON_OWNER_ALERT` | Callout feature name for code_suggestions_ga_non_owner_alert. | +| <a id="usercalloutfeaturenameenumduo_chat_callout"></a>`DUO_CHAT_CALLOUT` | Callout feature name for duo_chat_callout. | | <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. | @@ -30360,12 +31611,44 @@ Possible identifier types for a measurement. | Value | Description | | ----- | ----------- | +| <a id="valuestreamdashboardmetriccontributors"></a>`CONTRIBUTORS` | Contributor count. EXPERIMENTAL: Only available on the SaaS version of GitLab when the ClickHouse database backend is enabled. | | <a id="valuestreamdashboardmetricgroups"></a>`GROUPS` | Group count. | | <a id="valuestreamdashboardmetricissues"></a>`ISSUES` | Issue count. | | <a id="valuestreamdashboardmetricmerge_requests"></a>`MERGE_REQUESTS` | Merge request count. | | <a id="valuestreamdashboardmetricpipelines"></a>`PIPELINES` | Pipeline count. | | <a id="valuestreamdashboardmetricprojects"></a>`PROJECTS` | Project count. | +### `ValueStreamStageEvent` + +Stage event identifiers. + +| Value | Description | +| ----- | ----------- | +| <a id="valuestreamstageeventcode_stage_start"></a>`CODE_STAGE_START` | Code stage start event. | +| <a id="valuestreamstageeventissue_closed"></a>`ISSUE_CLOSED` | Issue closed event. | +| <a id="valuestreamstageeventissue_created"></a>`ISSUE_CREATED` | Issue created event. | +| <a id="valuestreamstageeventissue_deployed_to_production"></a>`ISSUE_DEPLOYED_TO_PRODUCTION` | Issue deployed to production event. | +| <a id="valuestreamstageeventissue_first_added_to_board"></a>`ISSUE_FIRST_ADDED_TO_BOARD` | Issue first added to board event. | +| <a id="valuestreamstageeventissue_first_assigned_at"></a>`ISSUE_FIRST_ASSIGNED_AT` | Issue first assigned at event. | +| <a id="valuestreamstageeventissue_first_associated_with_milestone"></a>`ISSUE_FIRST_ASSOCIATED_WITH_MILESTONE` | Issue first associated with milestone event. | +| <a id="valuestreamstageeventissue_first_mentioned_in_commit"></a>`ISSUE_FIRST_MENTIONED_IN_COMMIT` | Issue first mentioned in commit event. | +| <a id="valuestreamstageeventissue_label_added"></a>`ISSUE_LABEL_ADDED` | Issue label added event. | +| <a id="valuestreamstageeventissue_label_removed"></a>`ISSUE_LABEL_REMOVED` | Issue label removed event. | +| <a id="valuestreamstageeventissue_last_edited"></a>`ISSUE_LAST_EDITED` | Issue last edited event. | +| <a id="valuestreamstageeventissue_stage_end"></a>`ISSUE_STAGE_END` | Issue stage end event. | +| <a id="valuestreamstageeventmerge_request_closed"></a>`MERGE_REQUEST_CLOSED` | Merge request closed event. | +| <a id="valuestreamstageeventmerge_request_created"></a>`MERGE_REQUEST_CREATED` | Merge request created event. | +| <a id="valuestreamstageeventmerge_request_first_assigned_at"></a>`MERGE_REQUEST_FIRST_ASSIGNED_AT` | Merge request first assigned at event. | +| <a id="valuestreamstageeventmerge_request_first_commit_at"></a>`MERGE_REQUEST_FIRST_COMMIT_AT` | Merge request first commit at event. | +| <a id="valuestreamstageeventmerge_request_first_deployed_to_production"></a>`MERGE_REQUEST_FIRST_DEPLOYED_TO_PRODUCTION` | Merge request first deployed to production event. | +| <a id="valuestreamstageeventmerge_request_label_added"></a>`MERGE_REQUEST_LABEL_ADDED` | Merge request label added event. | +| <a id="valuestreamstageeventmerge_request_label_removed"></a>`MERGE_REQUEST_LABEL_REMOVED` | Merge request label removed event. | +| <a id="valuestreamstageeventmerge_request_last_build_finished"></a>`MERGE_REQUEST_LAST_BUILD_FINISHED` | Merge request last build finished event. | +| <a id="valuestreamstageeventmerge_request_last_build_started"></a>`MERGE_REQUEST_LAST_BUILD_STARTED` | Merge request last build started event. | +| <a id="valuestreamstageeventmerge_request_last_edited"></a>`MERGE_REQUEST_LAST_EDITED` | Merge request last edited event. | +| <a id="valuestreamstageeventmerge_request_merged"></a>`MERGE_REQUEST_MERGED` | Merge request merged event. | +| <a id="valuestreamstageeventplan_stage_start"></a>`PLAN_STAGE_START` | Plan stage start event. | + ### `VerificationStateEnum` | Value | Description | @@ -30712,6 +31995,12 @@ A `AuditEventsGoogleCloudLoggingConfigurationID` is a global ID. It is encoded a An example `AuditEventsGoogleCloudLoggingConfigurationID` is: `"gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1"`. +### `AuditEventsInstanceAmazonS3ConfigurationID` + +A `AuditEventsInstanceAmazonS3ConfigurationID` is a global ID. It is encoded as a string. + +An example `AuditEventsInstanceAmazonS3ConfigurationID` is: `"gid://gitlab/AuditEvents::Instance::AmazonS3Configuration/1"`. + ### `AuditEventsInstanceExternalAuditEventDestinationID` A `AuditEventsInstanceExternalAuditEventDestinationID` is a global ID. It is encoded as a string. @@ -30724,6 +32013,12 @@ A `AuditEventsInstanceGoogleCloudLoggingConfigurationID` is a global ID. It is e An example `AuditEventsInstanceGoogleCloudLoggingConfigurationID` is: `"gid://gitlab/AuditEvents::Instance::GoogleCloudLoggingConfiguration/1"`. +### `AuditEventsStreamingHTTPNamespaceFilterID` + +A `AuditEventsStreamingHTTPNamespaceFilterID` is a global ID. It is encoded as a string. + +An example `AuditEventsStreamingHTTPNamespaceFilterID` is: `"gid://gitlab/AuditEvents::Streaming::HTTP::NamespaceFilter/1"`. + ### `AuditEventsStreamingHeaderID` A `AuditEventsStreamingHeaderID` is a global ID. It is encoded as a string. @@ -30780,6 +32075,18 @@ A `CiCatalogResourceID` is a global ID. It is encoded as a string. An example `CiCatalogResourceID` is: `"gid://gitlab/Ci::Catalog::Resource/1"`. +### `CiCatalogResourcesComponentID` + +A `CiCatalogResourcesComponentID` is a global ID. It is encoded as a string. + +An example `CiCatalogResourcesComponentID` is: `"gid://gitlab/Ci::Catalog::Resources::Component/1"`. + +### `CiCatalogResourcesVersionID` + +A `CiCatalogResourcesVersionID` is a global ID. It is encoded as a string. + +An example `CiCatalogResourcesVersionID` is: `"gid://gitlab/Ci::Catalog::Resources::Version/1"`. + ### `CiJobArtifactID` A `CiJobArtifactID` is a global ID. It is encoded as a string. @@ -31195,6 +32502,24 @@ A `MilestoneID` is a global ID. It is encoded as a string. An example `MilestoneID` is: `"gid://gitlab/Milestone/1"`. +### `MlCandidateID` + +A `MlCandidateID` is a global ID. It is encoded as a string. + +An example `MlCandidateID` is: `"gid://gitlab/Ml::Candidate/1"`. + +### `MlModelID` + +A `MlModelID` is a global ID. It is encoded as a string. + +An example `MlModelID` is: `"gid://gitlab/Ml::Model/1"`. + +### `MlModelVersionID` + +A `MlModelVersionID` is a global ID. It is encoded as a string. + +An example `MlModelVersionID` is: `"gid://gitlab/Ml::ModelVersion/1"`. + ### `NamespaceID` A `NamespaceID` is a global ID. It is encoded as a string. @@ -31313,6 +32638,12 @@ A `ProjectImportStateID` is a global ID. It is encoded as a string. An example `ProjectImportStateID` is: `"gid://gitlab/ProjectImportState/1"`. +### `ProtectedBranchID` + +A `ProtectedBranchID` is a global ID. It is encoded as a string. + +An example `ProtectedBranchID` is: `"gid://gitlab/ProtectedBranch/1"`. + ### `ReleaseID` A `ReleaseID` is a global ID. It is encoded as a string. @@ -31605,6 +32936,7 @@ Implementations: Implementations: - [`AmazonS3ConfigurationType`](#amazons3configurationtype) +- [`InstanceAmazonS3ConfigurationType`](#instanceamazons3configurationtype) ##### Fields @@ -31692,7 +33024,7 @@ Returns [`TodoConnection!`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -31854,7 +33186,7 @@ Returns [`NoteConnection!`](#noteconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -31976,6 +33308,7 @@ Implementations: - [`AddOnUser`](#addonuser) - [`AutocompletedUser`](#autocompleteduser) +- [`CurrentUser`](#currentuser) - [`MergeRequestAssignee`](#mergerequestassignee) - [`MergeRequestAuthor`](#mergerequestauthor) - [`MergeRequestParticipant`](#mergerequestparticipant) @@ -32017,7 +33350,7 @@ Implementations: | <a id="usersavedreplies"></a>`savedReplies` | [`SavedReplyConnection`](#savedreplyconnection) | Saved replies authored by the user. (see [Connections](#connections)) | | <a id="userstate"></a>`state` | [`UserState!`](#userstate) | State of the user. | | <a id="userstatus"></a>`status` | [`UserStatus`](#userstatus) | User status. | -| <a id="usertwitter"></a>`twitter` | [`String`](#string) | Twitter username of the user. | +| <a id="usertwitter"></a>`twitter` | [`String`](#string) | X (formerly Twitter) username of the user. | | <a id="useruserachievements"></a>`userAchievements` **{warning-solid}** | [`UserAchievementConnection`](#userachievementconnection) | **Introduced** in 15.10. This feature is an Experiment. It can be changed or removed at any time. Achievements for the user. Only returns for namespaces where the `achievements` feature flag is enabled. | | <a id="useruserpermissions"></a>`userPermissions` | [`UserPermissions!`](#userpermissions) | Permissions for the current user on the resource. | | <a id="userusername"></a>`username` | [`String!`](#string) | Username of the user. Unique within this instance of GitLab. | @@ -32034,7 +33367,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -32070,7 +33403,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -32106,7 +33439,7 @@ Returns [`GroupConnection`](#groupconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -32123,7 +33456,7 @@ Returns [`MergeRequestConnection`](#mergerequestconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -32171,7 +33504,7 @@ Returns [`SnippetConnection`](#snippetconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -32189,7 +33522,7 @@ Returns [`ProjectConnection`](#projectconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -32205,7 +33538,7 @@ Returns [`TimelogConnection`](#timelogconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -32228,7 +33561,7 @@ Returns [`TodoConnection`](#todoconnection). This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): -`before: String`, `after: String`, `first: Int`, `last: Int`. +`before: String`, `after: String`, `first: Int`, and `last: Int`. ####### Arguments @@ -32241,24 +33574,6 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usertodosstate"></a>`state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | | <a id="usertodostype"></a>`type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | -###### `User.workspaces` - -Workspaces owned by the current user. - -Returns [`WorkspaceConnection`](#workspaceconnection). - -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="userworkspacesids"></a>`ids` | [`[RemoteDevelopmentWorkspaceID!]`](#remotedevelopmentworkspaceid) | Array of global workspace IDs. For example, `["gid://gitlab/RemoteDevelopment::Workspace/1"]`. | -| <a id="userworkspacesincludeactualstates"></a>`includeActualStates` | [`[String!]`](#string) | Includes all workspaces that match any of the actual states. | -| <a id="userworkspacesprojectids"></a>`projectIds` | [`[ProjectID!]`](#projectid) | Filter workspaces by project id. | - #### `WorkItemWidget` Implementations: @@ -32288,6 +33603,21 @@ Implementations: | ---- | ---- | ----------- | | <a id="workitemwidgettype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | +#### `WorkItemWidgetDefinition` + +Implementations: + +- [`WorkItemWidgetDefinitionAssignees`](#workitemwidgetdefinitionassignees) +- [`WorkItemWidgetDefinitionGeneric`](#workitemwidgetdefinitiongeneric) +- [`WorkItemWidgetDefinitionHierarchy`](#workitemwidgetdefinitionhierarchy) +- [`WorkItemWidgetDefinitionLabels`](#workitemwidgetdefinitionlabels) + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetdefinitiontype"></a>`type` | [`WorkItemWidgetType!`](#workitemwidgettype) | Widget type. | + ## Input types Types that may be used as arguments (all scalar types may also @@ -32400,15 +33730,6 @@ see the associated mutation type above. | ---- | ---- | ----------- | | <a id="aisummarizereviewinputresourceid"></a>`resourceId` | [`AiModelID!`](#aimodelid) | Global ID of the resource to mutate. | -### `AiTanukiBotInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="aitanukibotinputquestion"></a>`question` | [`String!`](#string) | GitLab documentation question for AI to answer. | -| <a id="aitanukibotinputresourceid"></a>`resourceId` | [`AiModelID!`](#aimodelid) | Global ID of the resource to mutate. | - ### `AlertManagementPayloadAlertFieldInput` Field that are available while modifying the custom mapping attributes for an HTTP integration. @@ -32693,6 +34014,17 @@ Represents an escalation rule. | <a id="mergerequestsresolvernegatedparamslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will not have these labels. | | <a id="mergerequestsresolvernegatedparamsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Title of the milestone. | +### `MonthSelectionInput` + +A year and month input for querying product analytics usage data. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="monthselectioninputmonth"></a>`month` | [`Int!`](#int) | Month of the period to return. | +| <a id="monthselectioninputyear"></a>`year` | [`Int!`](#int) | Year of the period to return. | + ### `NegatedBoardIssueInput` #### Arguments @@ -32978,6 +34310,32 @@ A time-frame defined as a closed inclusive range of two dates. | <a id="updatediffimagepositioninputx"></a>`x` | [`Int`](#int) | X position of the note. | | <a id="updatediffimagepositioninputy"></a>`y` | [`Int`](#int) | Y position of the note. | +### `ValueStreamSettingInput` + +Attributes for value stream setting. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="valuestreamsettinginputprojectidsfilter"></a>`projectIdsFilter` | [`[ProjectID!]`](#projectid) | Projects' global IDs used to filter value stream data. | + +### `ValueStreamStageInput` + +Attributes for value stream stage. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="valuestreamstageinputcustom"></a>`custom` | [`Boolean`](#boolean) | Whether the stage is customized. If false, it assigns a built-in default stage by name. | +| <a id="valuestreamstageinputendeventidentifier"></a>`endEventIdentifier` | [`ValueStreamStageEvent`](#valuestreamstageevent) | End event identifier. | +| <a id="valuestreamstageinputendeventlabelid"></a>`endEventLabelId` | [`LabelID`](#labelid) | Label ID associated with the end event identifier. | +| <a id="valuestreamstageinputhidden"></a>`hidden` | [`Boolean`](#boolean) | Whether the stage is hidden. | +| <a id="valuestreamstageinputname"></a>`name` | [`String!`](#string) | Name of the stage. | +| <a id="valuestreamstageinputstarteventidentifier"></a>`startEventIdentifier` | [`ValueStreamStageEvent`](#valuestreamstageevent) | Start event identifier. | +| <a id="valuestreamstageinputstarteventlabelid"></a>`startEventLabelId` | [`LabelID`](#labelid) | Label ID associated with the start event identifier. | + ### `VulnerabilityIdentifierInput` #### Arguments @@ -33021,16 +34379,6 @@ A time-frame defined as a closed inclusive range of two dates. | <a id="workitemconverttaskinputtitle"></a>`title` | [`String!`](#string) | Full string of the task to be replaced. New title for the created work item. | | <a id="workitemconverttaskinputworkitemtypeid"></a>`workItemTypeId` | [`WorkItemsTypeID!`](#workitemstypeid) | Global ID of the work item type used to create the new work item. | -### `WorkItemDeletedTaskInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="workitemdeletedtaskinputid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the task referenced in the work item's description. | -| <a id="workitemdeletedtaskinputlinenumberend"></a>`lineNumberEnd` | [`Int!`](#int) | Last line in the Markdown source that defines the list item task. | -| <a id="workitemdeletedtaskinputlinenumberstart"></a>`lineNumberStart` | [`Int!`](#int) | First line in the Markdown source that defines the list item task. | - ### `WorkItemUpdatedTaskInput` #### Arguments diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index f47a6d37528..ec4d783f3fb 100644 --- a/doc/api/graphql/removed_items.md +++ b/doc/api/graphql/removed_items.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL API removed items **(FREE ALL)** diff --git a/doc/api/graphql/sample_issue_boards.md b/doc/api/graphql/sample_issue_boards.md index e78d2f07e2e..7ee209dc9ad 100644 --- a/doc/api/graphql/sample_issue_boards.md +++ b/doc/api/graphql/sample_issue_boards.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Identify issue boards with GraphQL **(FREE ALL)** diff --git a/doc/api/graphql/users_example.md b/doc/api/graphql/users_example.md index 4aadf9ea76b..479824964dc 100644 --- a/doc/api/graphql/users_example.md +++ b/doc/api/graphql/users_example.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Query users with GraphQL **(FREE ALL)** diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md index 18469741814..621b3241de2 100644 --- a/doc/api/group_access_tokens.md +++ b/doc/api/group_access_tokens.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group access tokens API **(FREE ALL)** @@ -130,14 +130,17 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ Rotate a group access token. Revokes the previous token and creates a new token that expires in one week. +In GitLab 16.6 and later, you can use the `expires_at` parameter to set a different expiry date. This non-default expiry date can be up to a maximum of one year from the rotation date. + ```plaintext POST /groups/:id/access_tokens/:token_id/rotate ``` -| Attribute | Type | required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | -| `token_id` | integer or string | yes | ID of the project access token | +| Attribute | Type | required | Description | +|-----------|------------|----------|---------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | +| `token_id` | integer/string | yes | ID of the access token | +| `expires_at` | date | no | Expiration date of the access token in ISO format (`YYYY-MM-DD`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>/rotate" diff --git a/doc/api/group_activity_analytics.md b/doc/api/group_activity_analytics.md index 5426c4912c4..65228c37b58 100644 --- a/doc/api/group_activity_analytics.md +++ b/doc/api/group_activity_analytics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group Activity Analytics API **(PREMIUM ALL)** diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 61a2ef4a89b..a7ecc993e37 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group badges API **(FREE ALL)** diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 5a7b67b562c..48e1658e0ab 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group issue boards API **(FREE ALL)** diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index c32a14ee21e..6a10294d295 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group clusters API (certificate-based) (deprecated) **(FREE ALL)** diff --git a/doc/api/group_epic_boards.md b/doc/api/group_epic_boards.md index fa5580dcbbc..4ad7a20d2d7 100644 --- a/doc/api/group_epic_boards.md +++ b/doc/api/group_epic_boards.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group epic boards API **(PREMIUM ALL)** diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index e431d3c47d8..7a3b031f18a 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group import and export API **(FREE ALL)** diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index b8cb1b7e053..0ceef8267f5 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group iterations API **(PREMIUM ALL)** @@ -26,18 +26,20 @@ GET /groups/:id/iterations?state=opened GET /groups/:id/iterations?state=closed GET /groups/:id/iterations?search=version GET /groups/:id/iterations?include_ancestors=false +GET /groups/:id/iterations?include_descendants=true GET /groups/:id/iterations?updated_before=2013-10-02T09%3A24%3A18Z GET /groups/:id/iterations?updated_after=2013-10-02T09%3A24%3A18Z ``` -| Attribute | Type | Required | Description | -| ------------------- | ------- | -------- | ----------- | -| `state` | string | no | 'Return `opened`, `upcoming`, `current`, `closed`, or `all` iterations.' | -| `search` | string | no | Return only iterations with a title matching the provided string. | -| `in` | array of strings | no | Fields in which fuzzy search should be performed with the query given in the argument `search`. The available options are `title` and `cadence_title`. Default is `[title]`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350991) in GitLab 16.2. | -| `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | -| `updated_before` | datetime | no | Return only iterations updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | -| `updated_after` | datetime | no | Return only iterations updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | +| Attribute | Type | Required | Description | +| --------------------- | -------- | -------- | ----------- | +| `state` | string | no | 'Return `opened`, `upcoming`, `current`, `closed`, or `all` iterations.' | +| `search` | string | no | Return only iterations with a title matching the provided string. | +| `in` | array of strings | no | Fields in which fuzzy search should be performed with the query given in the argument `search`. The available options are `title` and `cadence_title`. Default is `[title]`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350991) in GitLab 16.2. | +| `include_ancestors` | boolean | no | Include iterations for group and its ancestors. Defaults to `true`. | +| `include_descendants` | boolean | no | Include iterations for group and its descendants. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135764) in GitLab 16.7. | +| `updated_before` | datetime | no | Return only iterations updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | +| `updated_after` | datetime | no | Return only iterations updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | Example request: diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 4f745987156..36d14c87819 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group labels API **(FREE ALL)** diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index ef373e5b7fa..109f3ba5f6e 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group-level Variables API **(FREE ALL)** diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 92664376365..57994e069a5 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group milestones API **(FREE ALL)** @@ -30,11 +30,13 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ------ | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `iids[]` | integer array | no | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | +| `iids[]` | integer array | no | Return only the milestones having the given `iid`. Ignored if `include_ancestors` is `true`. | | `state` | string | no | Return only `active` or `closed` milestones | | `title` | string | no | Return only the milestones having the given `title` | | `search` | string | no | Return only milestones with a title or description matching the provided string | -| `include_parent_milestones` | boolean | no | Include milestones from parent group and its ancestors. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) in GitLab 13.4 | +| `include_parent_milestones` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/433298) in GitLab 16.7. Use `include_ancestors` instead. | +| `include_ancestors` | boolean | no | Include milestones for all parent groups. | +| `include_descendants` | boolean | no | Include milestones for group and its descendants. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421030) in GitLab 16.7. | | `updated_before` | datetime | no | Return only milestones updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Introduced in GitLab 15.10 | | `updated_after` | datetime | no | Return only milestones updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Introduced in GitLab 15.10 | diff --git a/doc/api/group_protected_branches.md b/doc/api/group_protected_branches.md index 59599e1a257..844156f80b0 100644 --- a/doc/api/group_protected_branches.md +++ b/doc/api/group_protected_branches.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group-level protected branches API **(PREMIUM SELF)** diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index 3010c9794b6..81d4738bdfd 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group-level protected environments API **(PREMIUM ALL)** diff --git a/doc/api/group_relations_export.md b/doc/api/group_relations_export.md index c32dec54177..e1c0cd81bd6 100644 --- a/doc/api/group_relations_export.md +++ b/doc/api/group_relations_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group relations export API **(FREE ALL)** @@ -64,10 +64,6 @@ The status can be one of the following: - `1`: `finished` - `-1`: `failed` -- `0` - `started` -- `1` - `finished` -- `-1` - `failed` - ```json [ { @@ -76,6 +72,7 @@ The status can be one of the following: "error": null, "updated_at": "2021-05-04T11:25:20.423Z", "batched": true, + "batches_count": 1, "batches": [ { "status": 1, @@ -91,7 +88,8 @@ The status can be one of the following: "status": 1, "error": null, "updated_at": "2021-05-04T11:25:20.085Z", - "batched": false + "batched": false, + "batches_count": 0 } ] ``` diff --git a/doc/api/group_releases.md b/doc/api/group_releases.md index 05b4b3b0655..d32d8db4b85 100644 --- a/doc/api/group_releases.md +++ b/doc/api/group_releases.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group releases API **(FREE ALL)** diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index 6f0e0ee0b74..4f168aa73f7 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -1,8 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group repository storage moves API **(PREMIUM SELF)** diff --git a/doc/api/group_ssh_certificates.md b/doc/api/group_ssh_certificates.md index 3d99bdcaa3a..b6ffabb7749 100644 --- a/doc/api/group_ssh_certificates.md +++ b/doc/api/group_ssh_certificates.md @@ -1,15 +1,14 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Group SSH certificates API **(PREMIUM ALL)** +# Group SSH certificates API **(PREMIUM SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.4 [with a flag](../user/feature_flags.md) named `ssh_certificates_rest_endpoints`. Disabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `ssh_certificates_rest_endpoints`. On GitLab.com, this feature is not available. Use this API to create, read and delete SSH certificates for a group. diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index a3b8fec9248..1b10523abfd 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -1,8 +1,7 @@ --- stage: Plan group: Knowledge -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Group wikis API **(PREMIUM ALL)** diff --git a/doc/api/groups.md b/doc/api/groups.md index c9ec64e83db..2dbfb5a4937 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Groups API **(FREE ALL)** @@ -1285,6 +1285,87 @@ Example response: ] ``` +## List group users **(PREMIUM ALL EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424505) in GitLab 16.6. This feature is an [Experiment](../policy/experiment-beta-support.md). + +Get a list of users for a group. This endpoint returns users that are related to a top-level group regardless +of their current membership. For example, users that have a SAML identity connected to the group, or service accounts created +by the group or subgroups. + +This endpoint is an [Experiment](../policy/experiment-beta-support.md) and might be changed or removed without notice. + +Requires at least the Maintainer role in the group. + +```plaintext +GET /groups/:id/users +``` + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/users?include_saml_users=true&include_service_accounts=true" +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:---------------------------|:---------------|:--------------------------|:-------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | +| `include_saml_users` | boolean | yes (see description) | Include users with a SAML identity. Either this value or `include_service_accounts` must be `true`. | +| `include_service_accounts` | boolean | yes (see description) | Include service account users. Either this value or `include_saml_users` must be `true`. | +| `search` | string | no | Search users by name, email, username. | + +If successful, returns [`200 OK`](../api/rest/index.md#status-codes) and the +following response attributes: + +Example response: + +```json +[ + { + "id": 66, + "username": "user22", + "name": "John Doe22", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon", + "web_url": "http://my.gitlab.com/user22", + "created_at": "2021-09-10T12:48:22.381Z", + "bio": "", + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": null, + "job_title": "", + "pronouns": null, + "bot": false, + "work_information": null, + "followers": 0, + "following": 0, + "local_time": null, + "last_sign_in_at": null, + "confirmed_at": "2021-09-10T12:48:22.330Z", + "last_activity_on": null, + "email": "user22@example.org", + "theme_id": 1, + "color_scheme_id": 1, + "projects_limit": 100000, + "current_sign_in_at": null, + "identities": [ ], + "can_create_group": true, + "can_create_project": true, + "two_factor_enabled": false, + "external": false, + "private_profile": false, + "commit_email": "user22@example.org", + "shared_runners_minutes_limit": null, + "extra_shared_runners_minutes_limit": null + }, + ... +] +``` + ## Service Accounts **(PREMIUM ALL)** ### Create Service Account User @@ -1607,6 +1688,7 @@ To delete the LDAP group link, provide either a `cn` or a `filter`, but not both > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.0. > - `access_level` type [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95607) from `string` to `integer` in GitLab 15.3.3. +> - `member_role_id` type [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `custom_roles_for_saml_group_links`. Disabled by default. List, get, add, and delete SAML group links. @@ -1630,6 +1712,7 @@ If successful, returns [`200`](rest/index.md#status-codes) and the following res |:-------------------|:--------|:-----------------------------------------------------------------------------| | `[].name` | string | Name of the SAML group | | `[].access_level` | integer | [Role (`access_level`)](members.md#roles) for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3 | +| `[].member_role_id` | integer | [Member Role ID (`member_role_id`)](member_roles.md) for members of the SAML group. | Example request: @@ -1643,11 +1726,13 @@ Example response: [ { "name": "saml-group-1", - "access_level": 10 + "access_level": 10, + "member_role_id": 12 }, { "name": "saml-group-2", - "access_level": 40 + "access_level": 40, + "member_role_id": 99 } ] ``` @@ -1673,6 +1758,7 @@ If successful, returns [`200`](rest/index.md#status-codes) and the following res |:---------------|:--------|:-----------------------------------------------------------------------------| | `name` | string | Name of the SAML group | | `access_level` | integer | [Role (`access_level`)](members.md#roles) for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3 | +| `member_role_id` | integer | [Member Role ID (`member_role_id`)](member_roles.md) for members of the SAML group. | Example request: @@ -1685,7 +1771,8 @@ Example response: ```json { "name": "saml-group-1", -"access_level": 10 +"access_level": 10, +"member_role_id": 12 } ``` @@ -1704,6 +1791,7 @@ Supported attributes: | `id` | integer or string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) | | `saml_group_name` | string | yes | Name of a SAML group | | `access_level` | integer | yes | [Role (`access_level`)](members.md#roles) for members of the SAML group | +| `member_role_id` | integer | no | [Member Role ID (`member_role_id`)](member_roles.md) for members of the SAML group. | If successful, returns [`201`](rest/index.md#status-codes) and the following response attributes: @@ -1711,11 +1799,12 @@ If successful, returns [`201`](rest/index.md#status-codes) and the following res |:---------------|:--------|:-----------------------------------------------------------------------------| | `name` | string | Name of the SAML group | | `access_level` | integer | [Role (`access_level`)](members.md#roles) for members of the for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3 | +| `member_role_id` | integer | [Member Role ID (`member_role_id`)](member_roles.md) for members of the SAML group. | Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{ "saml_group_name": "<your_saml_group_name`>", "access_level": <chosen_access_level> }' --url "https://gitlab.example.com/api/v4/groups/1/saml_group_links" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{ "saml_group_name": "<your_saml_group_name`>", "access_level": <chosen_access_level>, "member_role_id": <chosen_member_role_id> }' --url "https://gitlab.example.com/api/v4/groups/1/saml_group_links" ``` Example response: @@ -1723,7 +1812,8 @@ Example response: ```json { "name": "saml-group-1", -"access_level": 10 +"access_level": 10, +"member_role_id": 12 } ``` @@ -1830,6 +1920,9 @@ GET /groups/:id/push_rule { "id": 2, "created_at": "2020-08-17T19:09:19.580Z", + "commit_committer_check": true, + "commit_committer_name_check": true, + "reject_unsigned_commits": false, "commit_message_regex": "[a-zA-Z]", "commit_message_negative_regex": "[x+]", "branch_name_regex": "[a-z]", @@ -1842,19 +1935,6 @@ GET /groups/:id/push_rule } ``` -Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see -the `commit_committer_check` and `reject_unsigned_commits` parameters: - -```json -{ - "id": 2, - "created_at": "2020-08-17T19:09:19.580Z", - "commit_committer_check": true, - "reject_unsigned_commits": false, - ... -} -``` - ### Add group push rule Adds [push rules](../user/group/access_and_permissions.md#group-push-rules) to the specified group. @@ -1871,6 +1951,7 @@ POST /groups/:id/push_rule | `deny_delete_tag` | boolean | no | Deny deleting a tag | | `member_check` | boolean | no | Allows only GitLab users to author commits | | `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | +| `commit_committer_name_check` | boolean | no | Users can only push commits to this repository if the commit author name is consistent with their GitLab account name | | `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, for example, `Fixed \d+\..*` | | `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, for example, `ssh\:\/\/` | | `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, for example, `(feature|hotfix)\/*` | @@ -1890,6 +1971,7 @@ Response: { "id": 19, "created_at": "2020-08-31T15:53:00.073Z", + "commit_committer_name_check": false, "commit_message_regex": "[a-zA-Z]", "commit_message_negative_regex": "[x+]", "branch_name_regex": null, @@ -1918,6 +2000,7 @@ PUT /groups/:id/push_rule | `deny_delete_tag` | boolean | no | Deny deleting a tag | | `member_check` | boolean | no | Restricts commits to be authored by existing GitLab users only | | `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | +| `commit_committer_name_check` | boolean | no | Users can only push commits to this repository if the commit author name is consistent with their GitLab account name | | `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, for example, `Fixed \d+\..*` | | `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, for example, `ssh\:\/\/` | | `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, for example, `(feature|hotfix)\/*` | @@ -1937,6 +2020,7 @@ Response: { "id": 19, "created_at": "2020-08-31T15:53:00.073Z", + "commit_committer_name_check": false, "commit_message_regex": "[a-zA-Z]", "commit_message_negative_regex": "[x+]", "branch_name_regex": null, diff --git a/doc/api/import.md b/doc/api/import.md index 4b7abfdfec1..81aae9b59e4 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import API **(FREE ALL)** @@ -53,7 +53,6 @@ curl --request POST \ "attachments_import": true, "collaborators_import": true }, - "additional_access_tokens": "foo,bar" }' ``` @@ -66,8 +65,6 @@ The following keys are available for `optional_stages`: For more information, see [Select additional items to import](../user/project/import/github.md#select-additional-items-to-import). -You can supply multiple personal access tokens in `additional_access_tokens` from different user accounts to import projects faster. - Example response: ```json @@ -180,7 +177,7 @@ If you do not specify `target_namespace`, the project imports to your personal u Prerequisites: -- For more information, see [prerequisites for Bitbucket Server importer](../user/project/import/bitbucket_server.md#import-your-bitbucket-repositories). +- For more information, see [prerequisites for Bitbucket Server importer](../user/project/import/bitbucket_server.md). ```plaintext POST /import/bitbucket_server diff --git a/doc/api/index.md b/doc/api/index.md index 8837c8a6016..19b6c13b085 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Develop with GitLab **(FREE ALL)** @@ -14,4 +14,3 @@ Automate with GitLab and integrate with external applications. - [GraphQL API](graphql/index.md) - [OAuth 2.0 identity provider API](oauth2.md) - [Editor and IDE extensions](../editor_extensions/index.md) -- [Code Suggestions](../user/project/repository/code_suggestions/index.md) diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index 751e3203990..51be27856b3 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance clusters API (certificate-based) (deprecated) **(FREE SELF)** diff --git a/doc/api/instance_level_ci_variables.md b/doc/api/instance_level_ci_variables.md index 2bf9b209e20..a4018a46525 100644 --- a/doc/api/instance_level_ci_variables.md +++ b/doc/api/instance_level_ci_variables.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance-level CI/CD variables API **(FREE SELF)** diff --git a/doc/api/integrations.md b/doc/api/integrations.md index d3e8540f7b2..f713d845762 100644 --- a/doc/api/integrations.md +++ b/doc/api/integrations.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrations API **(FREE ALL)** @@ -78,11 +78,11 @@ Example response: ] ``` -## Apple App Store +## Apple App Store Connect -### Set up Apple App Store +### Set up Apple App Store Connect -Set up the Apple App Store integration for a project. +Set up the Apple App Store Connect integration for a project. ```plaintext PUT /projects/:id/integrations/apple_app_store @@ -92,10 +92,11 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `app_store_issuer_id` | string | true | The Apple App Store Connect Issuer ID. | -| `app_store_key_id` | string | true | The Apple App Store Connect Key ID. | -| `app_store_private_key` | string | true | The Apple App Store Connect Private Key. | -| `app_store_protected_refs` | boolean | false | Set variables only on protected branches and tags. Defaults to `true` (enabled). | +| `app_store_issuer_id` | string | true | Apple App Store Connect issuer ID. | +| `app_store_key_id` | string | true | Apple App Store Connect key ID. | +| `app_store_private_key_file_name` | string | true | Apple App Store Connect private key file name. | +| `app_store_private_key` | string | true | Apple App Store Connect private key. | +| `app_store_protected_refs` | boolean | false | Set variables on protected branches and tags only. | ### Disable Apple App Store @@ -127,8 +128,8 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `api_key` | string | true | User API token. User must have access to task. All comments are attributed to this user. | -| `restrict_to_branch` | string | false | Comma-separated list of branches to be are automatically inspected. Leave blank to include all branches. | +| `api_key` | string | true | User API token. The user must have access to the task. All comments are attributed to this user. | +| `restrict_to_branch` | string | false | Comma-separated list of branches to be automatically inspected. Leave blank to include all branches. | ### Disable Asana @@ -677,7 +678,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `token` | string | true | GitHub API token with `repo:status` OAuth scope. | | `repository_url` | string | true | GitHub repository URL. | -| `static_context` | boolean | false | Append instance name instead of branch to [status check name](../user/project/integrations/github.md#static-or-dynamic-status-check-names). | +| `static_context` | boolean | false | Append the hostname of your GitLab instance to the [status check name](../user/project/integrations/github.md#static-or-dynamic-status-check-names). | ### Disable GitHub diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 0bf38b6e616..036eeaa8185 100644 --- a/doc/api/invitations.md +++ b/doc/api/invitations.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Invitations API **(FREE ALL)** diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 653f21e2f0b..f8be853d479 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue links API **(FREE ALL)** diff --git a/doc/api/issues.md b/doc/api/issues.md index 07678f3ca42..b2c6f0cb739 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues API **(FREE ALL)** @@ -15,13 +15,8 @@ request on that project results in a `404` status code. By default, `GET` requests return 20 results at a time because the API results are paginated. - Read more on [pagination](rest/index.md#pagination). -WARNING: -The `reference` attribute in responses is deprecated in favor of `references`. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.6. - NOTE: The `references.relative` attribute is relative to the group or project of the issue being requested. When an issue is fetched from its project, the `relative` format is the same as the `short` format. @@ -29,9 +24,7 @@ When requested across groups or projects, it's expected to be the same as the `f ## List issues -> - The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. -> - The `weight` property moved to GitLab Premium in 13.9. -> - The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get all issues the authenticated user has access to. By default it returns only issues created by the current user. To get all issues, @@ -54,41 +47,46 @@ GET /issues?state=closed GET /issues?state=opened ``` +Supported attributes: + | Attribute | Type | Required | Description | |---------------------------------|---------------| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | -| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | -| `epic_id` **(PREMIUM ALL)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `health_status` **(ULTIMATE ALL)** | string | no | Return issues with the specified `health_status`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370721) in GitLab 15.4)._ In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/370721), `None` returns issues with no health status assigned, and `Any` returns issues with a health status assigned. -| `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | -| `iteration_id` **(PREMIUM ALL)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `iteration_title` **(PREMIUM ALL)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. Using `None` or `Any` will be [deprecated in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/336044). Please use `milestone_id` attribute instead. `milestone` and `milestone_id` are mutually exclusive. | -| `milestone_id` | string | no | Returns issues assigned to milestones with a given timebox value (`None`, `Any`, `Upcoming`, and `Started`). `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. `Upcoming` lists all issues assigned to milestones due in the future. `Started` lists all issues assigned to open, started milestones. `milestone` and `milestone_id` are mutually exclusive. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335939) in GitLab 14.3)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197170) in GitLab 13.0)_ | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, `milestone_id` and `weight`. | -| `order_by` | string | no | Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, `updated_at`, or `weight` fields. Default is `created_at`. | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | -| `search` | string | no | Search issues against their `title` and `description` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | -| `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`) | -| `weight` **(PREMIUM ALL)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7| +| `assignee_id` | integer | No | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | +| `assignee_username` | string array | No | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | +| `author_id` | integer | No | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | +| `author_username` | string | No | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | +| `confidential` | boolean | No | Filter confidential or public issues. | +| `created_after` | datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `due_date` | string | No | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. | +| `health_status` **(ULTIMATE ALL)** | string | No | Return issues with the specified `health_status`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370721) in GitLab 15.4)._ In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/370721), `None` returns issues with no health status assigned, and `Any` returns issues with a health status assigned. +| `iids[]` | integer array | No | Return only the issues having the given `iid`. | +| `in` | string | No | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description`. | +| `issue_type` | string | No | Filter to a given type of issue. One of `issue`, `incident`, `test_case` or `task`. | +| `iteration_id` **(PREMIUM ALL)** | integer | No | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. | +| `iteration_title` **(PREMIUM ALL)** | string | No | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. | +| `labels` | string | No | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone_id` | string | No | Returns issues assigned to milestones with a given timebox value (`None`, `Any`, `Upcoming`, and `Started`). `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. `Upcoming` lists all issues assigned to milestones due in the future. `Started` lists all issues assigned to open, started milestones. `milestone` and `milestone_id` are mutually exclusive. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335939) in GitLab 14.3)_ | +| `milestone` | string | No | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. Using `None` or `Any` will be [deprecated in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/336044). Use `milestone_id` attribute instead. `milestone` and `milestone_id` are mutually exclusive. | +| `my_reaction_emoji` | string | No | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `non_archived` | boolean | No | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. | +| `not` | Hash | No | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, `milestone_id` and `weight`. | +| `order_by` | string | No | Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, `updated_at`, or `weight` fields. Default is `created_at`. | +| `scope` | string | No | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | +| `search` | string | No | Search issues against their `title` and `description`. | +| `sort` | string | No | Return issues sorted in `asc` or `desc` order. Default is `desc`. | +| `state` | string | No | Return `all` issues or just those that are `opened` or `closed`. | +| `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`). | +| `weight` **(PREMIUM ALL)** | integer | No | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `with_labels_details` | boolean | No | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/issues" ``` Example response: @@ -254,17 +252,15 @@ to the GitLab EE API. WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## List group issues -> - The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. -> - The `weight` property moved to GitLab Premium in 13.9. -> - The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get a list of a group's issues. -If the group is private, credentials need to be provided for authorization. +If the group is private, you must provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext @@ -284,39 +280,44 @@ GET /groups/:id/issues?state=closed GET /groups/:id/issues?state=opened ``` +Supported attributes: + | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | -| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | -| `epic_id` **(PREMIUM ALL)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `id` | integer/string | yes | The global ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | -| `iteration_id` **(PREMIUM ALL)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `iteration_title` **(PREMIUM ALL)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785) in GitLab 12.8)_ | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | -| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | -| `search` | string | no | Search group issues against their `title` and `description` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `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`) | -| `weight` **(PREMIUM ALL)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `assignee_id` | integer | No | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | +| `assignee_username` | string array | No | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | +| `author_id` | integer | No | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | +| `author_username` | string | No | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | +| `confidential` | boolean | No | Filter confidential or public issues. | +| `created_after` | datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `due_date` | string | No | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. | +| `iids[]` | integer array | No | Return only the issues having the given `iid`. | +| `issue_type` | string | No | Filter to a given type of issue. One of `issue`, `incident`, `test_case` or `task`. | +| `iteration_id` **(PREMIUM ALL)** | integer | No | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. | +| `iteration_title` **(PREMIUM ALL)** | string | No | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. | +| `labels` | string | No | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone` | string | No | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | +| `my_reaction_emoji` | string | No | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `non_archived` | boolean | No | Return issues from non archived projects. Default is true. | +| `not` | Hash | No | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in`. | +| `order_by` | string | No | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | +| `scope` | string | No | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | +| `search` | string | No | Search group issues against their `title` and `description`. | +| `sort` | string | No | Return issues sorted in `asc` or `desc` order. Default is `desc`. | +| `state` | string | No | Return all issues or just those that are `opened` or `closed`. | +| `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`). | +| `weight` **(PREMIUM ALL)** | integer | No | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `with_labels_details` | boolean | No | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/issues" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/groups/4/issues" ``` Example response: @@ -458,13 +459,11 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## List project issues -> - The `due_date` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3. -> - The `weight` property moved to GitLab Premium in 13.9. -> - The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. +> The `due_date` filters `any`, `today`, and `tomorrow` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78460) in GitLab 14.8. Get a list of a project's issues. @@ -488,38 +487,43 @@ GET /projects/:id/issues?state=closed GET /projects/:id/issues?state=opened ``` +Supported attributes: + | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | -| `assignee_username` | string array | no | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | -| `author_username` | string | no | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | -| `confidential` | boolean | no | Filter confidential or public issues. | -| `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | -| `epic_id` **(PREMIUM ALL)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | -| `iteration_id` **(PREMIUM ALL)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `iteration_title` **(PREMIUM ALL)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | -| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | -| `search` | string | no | Search project issues against their `title` and `description` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `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`) | -| `weight` **(PREMIUM ALL)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `assignee_id` | integer | No | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. | +| `assignee_username` | string array | No | Return issues assigned to the given `username`. Similar to `assignee_id` and mutually exclusive with `assignee_id`. In GitLab CE, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | +| `author_id` | integer | No | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | +| `author_username` | string | No | Return issues created by the given `username`. Similar to `author_id` and mutually exclusive with `author_id`. | +| `confidential` | boolean | No | Filter confidential or public issues. | +| `created_after` | datetime | No | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `created_before` | datetime | No | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | +| `due_date` | string | No | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `any`, `today`, `tomorrow`, `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. | +| `iids[]` | integer array | No | Return only the issues having the given `iid`. | +| `issue_type` | string | No | Filter to a given type of issue. One of `issue`, `incident`, `test_case` or `task`. | +| `iteration_id` **(PREMIUM ALL)** | integer | No | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. | +| `iteration_title` **(PREMIUM ALL)** | string | No | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. | +| `labels` | string | No | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone` | string | No | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | +| `my_reaction_emoji` | string | No | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | +| `not` | Hash | No | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in`. | +| `order_by` | string | No | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at`. | +| `scope` | string | No | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | +| `search` | string | No | Search project issues against their `title` and `description`. | +| `sort` | string | No | Return issues sorted in `asc` or `desc` order. Default is `desc`. | +| `state` | string | No | Return all issues or just those that are `opened` or `closed`. | +| `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`). | +| `weight` **(PREMIUM ALL)** | integer | No | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | +| `with_labels_details` | boolean | No | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues" ``` Example response: @@ -668,11 +672,13 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## Single issue -Only for administrators. Get a single issue. +Only for administrators. + +Get a single issue. The preferred way to do this is by using [personal access tokens](../user/profile/personal_access_tokens.md). @@ -680,12 +686,17 @@ The preferred way to do this is by using [personal access tokens](../user/profil GET /issues/:id ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer | yes | The ID of the issue | +| `id` | integer | Yes | The ID of the issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues/41" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/issues/41" ``` Example response: @@ -831,7 +842,7 @@ to the GitLab EE API. WARNING: The `epic_iid` attribute is deprecated, and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## Single project issue @@ -844,13 +855,18 @@ The preferred way to do this, is by using [personal access tokens](../user/profi GET /projects/:id/issues/:issue_iid ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/41" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/41" ``` Example response: @@ -989,40 +1005,44 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## New issue -> The `weight` property moved to GitLab Premium in 13.9. - Creates a new project issue. ```plaintext POST /projects/:id/issues ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------------------------------------|----------------|----------|--------------| -| `assignee_id` | integer | no | The ID of the user to assign the issue to. Only appears on GitLab Free. | -| `assignee_ids` **(PREMIUM ALL)** | integer array | no | The IDs of the users to assign the issue to. | -| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | -| `created_at` | string | no | When the issue was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. | -| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | -| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This fills out the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | -| `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | -| `epic_id` **(PREMIUM ALL)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | -| `epic_iid` **(PREMIUM ALL)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | -| `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | -| `labels` | string | no | Comma-separated label names for an issue | -| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these values take precedence over the default values.| -| `milestone_id` | integer | no | The global ID of a milestone to assign issue. To find the `milestone_id` associated with a milestone, view an issue with the milestone assigned and [use the API](#single-project-issue) to retrieve the issue's details. | -| `title` | string | yes | The title of an issue | -| `weight` **(PREMIUM ALL)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `assignee_id` | integer | No | The ID of the user to assign the issue to. Only appears on GitLab Free. | +| `assignee_ids` **(PREMIUM ALL)** | integer array | No | The IDs of the users to assign the issue to. | +| `confidential` | boolean | No | Set an issue to be confidential. Default is `false`. | +| `created_at` | string | No | When the issue was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. | +| `description` | string | No | The description of an issue. Limited to 1,048,576 characters. | +| `discussion_to_resolve` | string | No | The ID of a discussion to resolve. This fills out the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +| `due_date` | string | No | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | +| `epic_iid` **(PREMIUM ALL)** | integer | No | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5). | +| `iid` | integer/string | No | The internal ID of the project's issue (requires administrator or project owner rights). | +| `issue_type` | string | No | The type of issue. One of `issue`, `incident`, `test_case` or `task`. Default is `issue`. | +| `labels` | string | No | Comma-separated label names for an issue. | +| `merge_request_to_resolve_discussions_of` | integer | No | The IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these values take precedence over the default values.| +| `milestone_id` | integer | No | The global ID of a milestone to assign issue. To find the `milestone_id` associated with a milestone, view an issue with the milestone assigned and [use the API](#single-project-issue) to retrieve the issue's details. | +| `title` | string | Yes | The title of an issue. | +| `weight` **(PREMIUM ALL)** | integer | No | The weight of the issue. Valid values are greater than or equal to 0. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug" ``` Example response: @@ -1137,19 +1157,16 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. -## Rate limits +### Rate limits To help avoid abuse, users can be limited to a specific number of `Create` requests per minute. See [Issues rate limits](../administration/settings/rate_limit_on_issues_creation.md). -## Edit issue - -> The `weight` property moved to GitLab Premium in 13.9. +## Edit an issue -Updates an existing project issue. This call is also used to mark an issue as -closed. +Updates an existing project issue. This request is also used to close or reopen an issue (with `state_event`). At least one of the following parameters is required for the request to be successful: @@ -1170,29 +1187,35 @@ At least one of the following parameters is required for the request to be succe PUT /projects/:id/issues/:issue_iid ``` +Supported attributes: + | Attribute | Type | Required | Description | |----------------|---------|----------|------------------------------------------------------------------------------------------------------------| -| `add_labels` | string | no | Comma-separated label names to add to an issue. | -| `assignee_ids` | integer array | no | The ID of the users to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | -| `confidential` | boolean | no | Updates an issue to be confidential | -| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | -| `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | -| `due_date` | string | no | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11` | -| `epic_id` **(PREMIUM ALL)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | -| `epic_iid` **(PREMIUM ALL)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `issue_type` | string | no | Updates the type of issue. One of `issue`, `incident`, or `test_case`. | -| `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | -| `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| -| `remove_labels`| string | no | Comma-separated label names to remove from an issue. | -| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | -| `title` | string | no | The title of an issue | -| `updated_at` | string | no | When the issue was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.| -| `weight` **(PREMIUM ALL)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `add_labels` | string | No | Comma-separated label names to add to an issue. | +| `assignee_ids` | integer array | No | The ID of the users to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | +| `confidential` | boolean | No | Updates an issue to be confidential. | +| `description` | string | No | The description of an issue. Limited to 1,048,576 characters. | +| `discussion_locked` | boolean | No | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | +| `due_date` | string | No | The due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11`. | +| `epic_id` **(PREMIUM ALL)** | integer | No | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | +| `epic_iid` **(PREMIUM ALL)** | integer | No | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5). | +| `issue_type` | string | No | Updates the type of issue. One of `issue`, `incident`, `test_case` or `task`. | +| `labels` | string | No | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | +| `milestone_id` | integer | No | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| +| `remove_labels`| string | No | Comma-separated label names to remove from an issue. | +| `state_event` | string | No | The state event of an issue. To close the issue, use `close`, and to reopen it, use `reopen`. | +| `title` | string | No | The title of an issue. | +| `updated_at` | string | No | When the issue was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.| +| `weight` **(PREMIUM ALL)** | integer | No | The weight of the issue. Valid values are greater than or equal to 0. | + +Example request: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close" +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close" ``` Example response: @@ -1311,47 +1334,61 @@ Issues created by users on GitLab Ultimate include the `health_status` property: WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. WARNING: `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. ## Delete an issue -Only for administrators and project owners. Deletes an issue. +Only for administrators and project owners. + +Deletes an issue. ```plaintext DELETE /projects/:id/issues/:issue_iid ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85" +curl --request DELETE \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/85" ``` -## Reorder an issue +If successful, returns [`204 No Content`](rest/index.md#status-codes). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211864) in GitLab 13.2. +## Reorder an issue -Reorders an issue, you can see the results when sorting issues manually +Reorders an issue. You can see the results when [sorting issues manually](../user/project/issues/sorting_issue_lists.md#manual-sorting). ```plaintext PUT /projects/:id/issues/:issue_iid/reorder ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of the project's issue | -| `move_after_id` | integer | no | The global ID of a project's issue that should be placed after this issue | -| `move_before_id` | integer | no | The global ID of a project's issue that should be placed before this issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of the project's issue. | +| `move_after_id` | integer | No | The global ID of a project's issue that should be placed after this issue. | +| `move_before_id` | integer | No | The global ID of a project's issue that should be placed before this issue. | + +Example request: ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/85/reorder?move_after_id=51&move_before_id=92" +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/85/reorder?move_after_id=51&move_before_id=92" ``` ## Move an issue @@ -1367,14 +1404,20 @@ project, it's then assigned to the issue being moved. POST /projects/:id/issues/:issue_iid/move ``` +Supported attributes: + | Attribute | Type | Required | Description | |-----------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `to_project_id` | integer | yes | The ID of the new project | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `to_project_id` | integer | Yes | The ID of the new project. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --form to_project_id=5 "https://gitlab.example.com/api/v4/projects/4/issues/85/move" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --form to_project_id=5 \ + --url "https://gitlab.example.com/api/v4/projects/4/issues/85/move" ``` Example response: @@ -1499,20 +1542,22 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. ## Clone an issue -Clone the issue to given project. If the user has insufficient permissions, -an error message with status code `400` is returned. - +Clone the issue to given project. Copies as much data as possible as long as the target project contains equivalent -criteria such as labels or milestones. +criteria, such as labels or milestones. + +If you have insufficient permissions, an error message with status code `400` is returned. ```plaintext POST /projects/:id/issues/:issue_iid/clone ``` +Supported attributes: + | Attribute | Type | Required | Description | | --------------- | -------------- | ---------------------- | --------------------------------- | | `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | @@ -1520,9 +1565,12 @@ POST /projects/:id/issues/:issue_iid/clone | `to_project_id` | integer | Yes | ID of the new project. | | `with_notes` | boolean | No | Clone the issue with [notes](notes.md). Default is `false`. | +Example request: + ```shell curl --request POST \ ---header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/1/clone?with_notes=true&to_project_id=6" + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/1/clone?with_notes=true&to_project_id=6" ``` Example response: @@ -1610,7 +1658,11 @@ Example response: } ``` -## Subscribe to an issue +## Notifications + +The following requests are related to [email notifications](../user/profile/notifications.md) for issues. + +### Subscribe to an issue Subscribes the authenticated user to an issue to receive notifications. If the user is already subscribed to the issue, the status code `304` @@ -1620,13 +1672,19 @@ is returned. POST /projects/:id/issues/:issue_iid/subscribe ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe" ``` Example response: @@ -1751,9 +1809,9 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. -Please use `iid` of the `epic` attribute instead. +Use `iid` of the `epic` attribute instead. -## Unsubscribe from an issue +### Unsubscribe from an issue Unsubscribes the authenticated user from the issue to not receive notifications from it. If the user is not subscribed to the issue, the @@ -1763,13 +1821,19 @@ status code `304` is returned. POST /projects/:id/issues/:issue_iid/unsubscribe ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe" ``` Example response: @@ -1837,13 +1901,19 @@ returned. POST /projects/:id/issues/:issue_iid/todo ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/todo" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/todo" ``` Example response: @@ -1960,14 +2030,16 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `body` | String | yes | The content of a note. Must contain `/promote` at the start of a new line. | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `body` | String | Yes | The content of a note. Must contain `/promote` at the start of a new line. If the note only contains `/promote`, promotes the issue, but doesn't add a comment. Otherwise, the other lines form a comment.| Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=Lets%20promote%20this%20to%20an%20epic%0A%0A%2Fpromote" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=Lets%20promote%20this%20to%20an%20epic%0A%0A%2Fpromote" ``` Example response: @@ -2000,7 +2072,11 @@ Example response: } ``` -## Set a time estimate for an issue +## Time tracking + +The following requests are related to [time tracking](../user/project/time_tracking.md) on issues. + +### Set a time estimate for an issue Sets an estimated time of work for this issue. @@ -2008,14 +2084,20 @@ Sets an estimated time of work for this issue. POST /projects/:id/issues/:issue_iid/time_estimate ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| -| `duration` | string | yes | The duration in human format. e.g: `3h30m` | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `duration` | string | Yes | The duration in human-readable format. For example: `3h30m`. | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m" ``` Example response: @@ -2029,7 +2111,7 @@ Example response: } ``` -## Reset the time estimate for an issue +### Reset the time estimate for an issue Resets the estimated time for this issue to 0 seconds. @@ -2037,13 +2119,19 @@ Resets the estimated time for this issue to 0 seconds. POST /projects/:id/issues/:issue_iid/reset_time_estimate ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate" ``` Example response: @@ -2057,23 +2145,29 @@ Example response: } ``` -## Add spent time for an issue +### Add spent time for an issue -Adds spent time for this issue +Adds spent time for this issue. ```plaintext POST /projects/:id/issues/:issue_iid/add_spent_time ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| -| `duration` | string | yes | The duration in human format. e.g: `3h30m` | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `summary` | string | no | A summary of how the time was spent | +| `duration` | string | Yes | The duration in human-readable format. For example: `3h30m` | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `summary` | string | No | A summary of how the time was spent. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h" ``` Example response: @@ -2087,7 +2181,7 @@ Example response: } ``` -## Reset spent time for an issue +### Reset spent time for an issue Resets the total spent time for this issue to 0 seconds. @@ -2095,13 +2189,19 @@ Resets the total spent time for this issue to 0 seconds. POST /projects/:id/issues/:issue_iid/reset_spent_time ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time" +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time" ``` Example response: @@ -2115,22 +2215,29 @@ Example response: } ``` -## Get time tracking stats +### Get time tracking stats -If the project is private or the issue is confidential, you need to provide credentials to authorize. +Gets time tracking stats for an issue in human-readable format (for example, `1h30m`) and in number of seconds. + +If the project is private or the issue is confidential, you must provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). ```plaintext GET /projects/:id/issues/:issue_iid/time_stats ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats" ``` Example response: @@ -2144,9 +2251,13 @@ Example response: } ``` -## List merge requests related to issue +## Merge requests + +The following requests are related to relationships between issues and merge requests. + +### List merge requests related to issue -Get all the merge requests that are related to the issue. +Gets all the merge requests that are related to the issue. If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). @@ -2155,13 +2266,18 @@ The preferred way to do this, is by using [personal access tokens](../user/profi GET /projects/:id/issues/:issue_iid/related_merge_requests ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests" ``` Example response: @@ -2304,9 +2420,9 @@ Example response: ] ``` -## List merge requests that close a particular issue on merge +### List merge requests that close a particular issue on merge -Get all merge requests that close a particular issue when merged. +Gets all merge requests that close a particular issue when merged. If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). @@ -2315,13 +2431,18 @@ The preferred way to do this, is by using [personal access tokens](../user/profi GET /projects/:id/issues/:issue_iid/closed_by ``` +Supported attributes: + | Attribute | Type | Required | Description | | ----------- | ---------------| -------- | ---------------------------------- | -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by" ``` Example response: @@ -2383,7 +2504,9 @@ Example response: ] ``` -## Participants on issues +## List participants in an issue + +Lists users that are participants in the issue. If the project is private or the issue is confidential, you need to provide credentials to authorize. The preferred way to do this, is by using [personal access tokens](../user/profile/personal_access_tokens.md). @@ -2392,13 +2515,18 @@ The preferred way to do this, is by using [personal access tokens](../user/profi GET /projects/:id/issues/:issue_iid/participants ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/participants" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + -url "https://gitlab.example.com/api/v4/projects/5/issues/93/participants" ``` Example response: @@ -2426,23 +2554,31 @@ Example response: ## Comments on issues -Comments are done via the [notes](notes.md) resource. +Interact with comments using the [Notes API](notes.md). ## Get user agent details Available only for administrators. +Gets the user agent string and IP of the user who created the issue. +Used for spam tracking. + ```plaintext GET /projects/:id/issues/:issue_iid/user_agent_detail ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/user_agent_detail" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/user_agent_detail" ``` Example response: @@ -2457,28 +2593,43 @@ Example response: ## List issue state events -To track which state was set, who did it, and when it happened, check out +To track which state was set, who did it, and when it happened, use [Resource state events API](resource_state_events.md#issues). -## Upload metric image +## Incidents -Available only for Incident issues. +The following requests are available only for [incidents](../operations/incident_management/incidents.md). + +### Upload metric image + +Available only for [incidents](../operations/incident_management/incidents.md). + +Uploads a screenshot of metric charts to show in the incident's **Metrics** tab. +When you upload an image, you can associate the image with text or a link to the original graph. +If you add a URL, you can access the original graph by selecting the hyperlink above the uploaded image. ```plaintext POST /projects/:id/issues/:issue_iid/metric_images ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `file` | file | yes | The image file to be uploaded | -| `url` | string | no | The URL to view more metric information | -| `url_text` | string | no | A description of the image or URL | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `file` | file | Yes | The image file to be uploaded. | +| `url` | string | No | The URL to view more metric information. | +| `url_text` | string | No | A description of the image or URL. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --form 'file=@/path/to/file.png' \ ---form 'url=http://example.com' --form 'url_text=Example website' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --form 'file=@/path/to/file.png' \ + --form 'url=http://example.com' \ + --form 'url_text=Example website' \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" ``` Example response: @@ -2494,21 +2645,28 @@ Example response: } ``` -## List metric images +### List metric images -Available only for Incident issues. +Available only for [incidents](../operations/incident_management/incidents.md). + +Lists screenshots of metric charts shown in the incident's **Metrics** tab. ```plaintext GET /projects/:id/issues/:issue_iid/metric_images ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + -url "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images" ``` Example response: @@ -2532,24 +2690,34 @@ Example response: ] ``` -## Update metric image +### Update metric image + +Available only for [incidents](../operations/incident_management/incidents.md). -Available only for Incident issues. +Edits attributes of a screenshot of metric charts shown in the incident's **Metrics** tab. ```plaintext PUT /projects/:id/issues/:issue_iid/metric_images/:image_id ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `image_id` | integer | yes | The ID of the image | -| `url` | string | no | The URL to view more metric information | -| `url_text` | string | no | A description of the image or URL | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `image_id` | integer | Yes | The ID of the image. | +| `url` | string | No | The URL to view more metric information. | +| `url_text` | string | No | A description of the image or URL. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --request PUT --form 'url=http://example.com' --form 'url_text=Example website' "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --request PUT \ + --form 'url=http://example.com' \ + --form 'url_text=Example website' \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" ``` Example response: @@ -2565,22 +2733,30 @@ Example response: } ``` -## Delete metric image +### Delete metric image + +Available only for [incidents](../operations/incident_management/incidents.md). -Available only for Incident issues. +Delete a screenshot of metric charts shown in the incident's **Metrics** tab. ```plaintext DELETE /projects/:id/issues/:issue_iid/metric_images/:image_id ``` +Supported attributes: + | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | -| `image_id` | integer | yes | The ID of the image | +| `id` | integer/string | Yes | The global ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | Yes | The internal ID of a project's issue. | +| `image_id` | integer | Yes | The ID of the image. | + +Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --request DELETE \ + --url "https://gitlab.example.com/api/v4/projects/5/issues/93/metric_images/1" ``` Can return the following status codes: diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 2c3383aa328..4e14a8f4f6c 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues statistics API **(FREE ALL)** diff --git a/doc/api/iterations.md b/doc/api/iterations.md index ef718fffe0a..b89d1eeb15e 100644 --- a/doc/api/iterations.md +++ b/doc/api/iterations.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project iterations API **(PREMIUM ALL)** @@ -28,18 +28,20 @@ GET /projects/:id/iterations?state=opened GET /projects/:id/iterations?state=closed GET /projects/:id/iterations?search=version GET /projects/:id/iterations?include_ancestors=false +GET /projects/:id/iterations?include_descendants=true GET /projects/:id/iterations?updated_before=2013-10-02T09%3A24%3A18Z GET /projects/:id/iterations?updated_after=2013-10-02T09%3A24%3A18Z ``` -| Attribute | Type | Required | Description | -| ------------------- | ------- | -------- | ----------- | -| `state` | string | no | 'Return `opened`, `upcoming`, `current`, `closed`, or `all` iterations.' | -| `search` | string | no | Return only iterations with a title matching the provided string. | -| `in` | array of strings | no | Fields in which fuzzy search should be performed with the query given in the argument `search`. The available options are `title` and `cadence_title`. Default is `[title]`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350991) in GitLab 16.2. | -| `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | -| `updated_before` | datetime | no | Return only iterations updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | -| `updated_after` | datetime | no | Return only iterations updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | +| Attribute | Type | Required | Description | +| --------------------- | -------- | -------- | ----------- | +| `state` | string | no | 'Return `opened`, `upcoming`, `current`, `closed`, or `all` iterations.' | +| `search` | string | no | Return only iterations with a title matching the provided string. | +| `in` | array of strings | no | Fields in which fuzzy search should be performed with the query given in the argument `search`. The available options are `title` and `cadence_title`. Default is `[title]`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350991) in GitLab 16.2. | +| `include_ancestors` | boolean | no | Include iterations for parent group and its ancestors. Defaults to `true`. | +| `include_descendants` | boolean | no | Include iterations for parent group and its descendants. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135764) in GitLab 16.7. | +| `updated_before` | datetime | no | Return only iterations updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | +| `updated_after` | datetime | no | Return only iterations updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378662) in GitLab 15.10. | Example request: diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index e9d4915da57..31a72c44d02 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Job Artifacts API **(FREE ALL)** @@ -18,7 +18,7 @@ available in the Premium and Ultimate tier. Get the job's artifacts zipped archive of a project. If you use cURL to download artifacts from GitLab.com, use the `--location` parameter -as the request might redirect through a CND. +as the request might redirect through a CDN. ```plaintext GET /projects/:id/jobs/:job_id/artifacts @@ -80,7 +80,7 @@ is the same as [getting the job's artifacts](#get-job-artifacts), but by defining the job's name instead of its ID. If you use cURL to download artifacts from GitLab.com, use the `--location` parameter -as the request might redirect through a CND. +as the request might redirect through a CDN. NOTE: If a pipeline is [parent of other child pipelines](../ci/pipelines/downstream_pipelines.md#parent-child-pipelines), artifacts @@ -148,7 +148,7 @@ the job's artifacts zipped archive. The file is extracted from the archive and streamed to the client. If you use cURL to download artifacts from GitLab.com, use the `--location` parameter -as the request might redirect through a CND. +as the request might redirect through a CDN. ```plaintext GET /projects/:id/jobs/:job_id/artifacts/*artifact_path @@ -184,7 +184,7 @@ Possible response status codes: Download a single artifact file for a specific job of the latest **successful** pipeline for the given reference name from inside the job's artifacts archive. -The file is extracted from the archive and streamed to the client. +The file is extracted from the archive and streamed to the client, with the `plain/text` content type. The artifact file provides more detail than what is available in the [CSV export](../user/application_security/vulnerability_report/index.md#export-vulnerability-details). @@ -194,7 +194,7 @@ are searched in hierarchical order from parent to child. For example, if both pa have a job with the same name, the artifact from the parent pipeline is returned. If you use cURL to download artifacts from GitLab.com, use the `--location` parameter -as the request might redirect through a CND. +as the request might redirect through a CDN. ```plaintext GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name @@ -326,7 +326,7 @@ of the regular cleanup of expired job artifacts. Job logs are never deleted. The regular cleanup occurs asynchronously on a schedule, so there might be a short delay before artifacts are deleted. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 06fd354f2be..594add64b0a 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs API **(FREE ALL)** diff --git a/doc/api/keys.md b/doc/api/keys.md index 571c193c1d3..3422104184c 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Keys API **(FREE ALL)** diff --git a/doc/api/labels.md b/doc/api/labels.md index c96350219b9..74850b14581 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Labels API **(FREE ALL)** diff --git a/doc/api/license.md b/doc/api/license.md index d393229fcf2..99304df0d1b 100644 --- a/doc/api/license.md +++ b/doc/api/license.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Utilization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # License **(FREE SELF)** diff --git a/doc/api/linked_epics.md b/doc/api/linked_epics.md index 4d0f1dbe6a0..6492a16569e 100644 --- a/doc/api/linked_epics.md +++ b/doc/api/linked_epics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked epics API **(ULTIMATE ALL)** diff --git a/doc/api/lint.md b/doc/api/lint.md index 45ae739ef86..210cec67d8f 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI Lint API **(FREE ALL)** diff --git a/doc/api/markdown.md b/doc/api/markdown.md index fdbdbf65b53..cce230f073b 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Markdown API **(FREE ALL)** diff --git a/doc/api/member_roles.md b/doc/api/member_roles.md index 63de583de25..24ac7099004 100644 --- a/doc/api/member_roles.md +++ b/doc/api/member_roles.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Member roles API **(ULTIMATE ALL)** @@ -16,10 +16,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Feature flag `admin_merge_request` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132578) in GitLab 16.5. > - [Admin group members introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131914) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `admin_group_member`. Disabled by default. The feature flag has been removed in GitLab 16.6. > - [Manage project access tokens introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132342) in GitLab 16.5 in [with a flag](../administration/feature_flags.md) named `manage_project_access_tokens`. Disabled by default. -> - [Archive project introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134998) in GitLab 16.6 in [with a flag](../administration/feature_flags.md) named `archive_project`. Disabled by default. +> - [Archive project introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134998) in GitLab 16.7. FLAG: -On self-managed GitLab, by default these features are not available. To make them available, an administrator can [enable the feature flags](../administration/feature_flags.md) named `admin_group_member`, `manage_project_access_tokens` and `archive_project`. +On self-managed GitLab, by default these features are not available. To make them available, an administrator can [enable the feature flags](../administration/feature_flags.md) named `admin_group_member` and `manage_project_access_tokens`. On GitLab.com, these features are not available. ## List all member roles of a group diff --git a/doc/api/members.md b/doc/api/members.md index de59c66890d..3e832ca60c9 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group and project members API **(FREE ALL)** @@ -27,9 +27,10 @@ In GitLab 14.8 and earlier, projects in personal namespaces have an `access_leve ## Limitations -The `group_saml_identity` attribute is only visible to a group owner for [SSO enabled groups](../user/group/saml_sso/index.md). +The `group_saml_identity` attribute is only visible to group owners for [SSO-enabled groups](../user/group/saml_sso/index.md). -The `email` attribute is only visible to group Owners for any [enterprise user](../user/enterprise_user/index.md). +The `email` attribute is only visible to group owners for users provisioned by the group with [SCIM](../user/group/saml_sso/scim_setup.md). +[Issue 391453](https://gitlab.com/gitlab-org/gitlab/-/issues/391453) proposes to change the criteria for access to the `email` attribute from provisioned users to [enterprise users](../user/enterprise_user/index.md). ## List all members of a group or project diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 628f274c38f..c150eda720c 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Merge request approvals API **(PREMIUM ALL)** @@ -1039,7 +1039,7 @@ Supported attributes: | Attribute | Type | Required | Description | |---------------------|-------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer or string | Yes | The ID or [URL-encoded path of a project](rest/index.md#namespaced-path-encoding). | -| `approval_password` | string | No | Current user's password. Required if [**Require user re-authentication to approve**](../user/project/merge_requests/approvals/settings.md#require-user-re-authentication-to-approve) is enabled in the project settings. | +| `approval_password` | string | No | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-re-authentication-to-approve) is enabled in the project settings. | | `merge_request_iid` | integer | Yes | The IID of the merge request. | | `sha` | string | No | The `HEAD` of the merge request. | diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index b277b9147b5..a38a54c0fab 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Merge request context commits API **(FREE ALL)** diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index bf071e9ae51..a852c7c0b96 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests API **(FREE ALL)** @@ -83,6 +83,8 @@ Supported attributes: | `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`.In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | | `wip` | string | No | Filter merge requests against their `wip` status. `yes` to return *only* draft merge requests, `no` to return *non-draft* merge requests. | +Example response: + ```json [ { @@ -206,17 +208,15 @@ Supported attributes: ### Merge requests list response notes -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0, listing merge requests may +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0, listing merge requests might not proactively update `merge_status` (which also affects the `has_conflicts`), as this can be an expensive operation. If you need the value of these fields from this endpoint, set the `with_merge_status_recheck` parameter to `true` in the query. -- For notes on merge request object fields, read [Single merge request response notes](#single-merge-request-response-notes). +- For notes on merge request object fields, see [Single merge request response notes](#single-merge-request-response-notes). ## List project merge requests Get all merge requests for this project. -The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). -The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. ```plaintext GET /projects/:id/merge_requests @@ -228,15 +228,6 @@ GET /projects/:id/merge_requests?labels=bug,reproduced GET /projects/:id/merge_requests?my_reaction_emoji=star ``` -`project_id` represents the ID of the project where the merge request resides. -`project_id` always equals `target_project_id`. - -In the case of a merge request from the same project, -`source_project_id`, `target_project_id` and `project_id` -are the same. In the case of a merge request from a fork, -`target_project_id` and `project_id` are the same and -`source_project_id` is the fork project's ID. - Supported attributes: | Attribute | Type | Required | Description | @@ -263,7 +254,7 @@ Supported attributes: | `search` | string | No | Search merge requests against their `title` and `description`. | | `sort` | string | No | Returns requests sorted in `asc` or `desc` order. Default is `desc`. | | `source_branch` | string | No | Returns merge requests with the given source branch. | -| `state` | string | No | Returns all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | +| `state` | string | No | Returns all merge requests (`all`) or just those that are `opened`, `closed`, `locked`, or `merged`. | | `target_branch` | string | No | Returns merge requests with the given target branch. | | `updated_after` | datetime | No | Returns merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `updated_before` | datetime | No | Returns merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -272,6 +263,18 @@ Supported attributes: | `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`. In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | +In the response: + +- `project_id` represents the ID of the project where the merge request resides. + `project_id` always equals `target_project_id`. +- Use the pagination parameters `page` and `per_page` to restrict the list of merge requests. +- Project IDs vary depending on whether the merge request originates from the project, or a fork. + In merge requests originating from + - The same project: `target_project_id`, `project_id`, and `source_project_id` are the same. + - A fork: `target_project_id` and `project_id` are the same, but `source_project_id` is the fork project's ID. + +Example response: + ```json [ { @@ -395,13 +398,11 @@ Supported attributes: ] ``` -For important notes on response data, read [Merge requests list response notes](#merge-requests-list-response-notes). +For important notes on response data, see [Merge requests list response notes](#merge-requests-list-response-notes). ## List group merge requests Get all merge requests for this group and its subgroups. -The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). -The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. ```plaintext GET /groups/:id/merge_requests @@ -412,8 +413,6 @@ GET /groups/:id/merge_requests?labels=bug,reproduced GET /groups/:id/merge_requests?my_reaction_emoji=star ``` -`group_id` represents the ID of the group which contains the project where the merge request resides. - Supported attributes: | Attribute | Type | Required | Description | @@ -440,7 +439,7 @@ Supported attributes: | `search` | string | No | Search merge requests against their `title` and `description`. | | `source_branch` | string | No | Returns merge requests with the given source branch. | | `sort` | string | No | Returns merge requests sorted in `asc` or `desc` order. Default is `desc`. | -| `state` | string | No | Returns all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. | +| `state` | string | No | Returns all merge requests (`all`) or just those that are `opened`, `closed`, `locked`, or `merged`. | | `target_branch` | string | No | Returns merge requests with the given target branch. | | `updated_after` | datetime | No | Returns merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `updated_before` | datetime | No | Returns merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -448,6 +447,12 @@ Supported attributes: | `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`. In GitLab 15.11 and later, enable the `restrict_merge_status_recheck` feature [flag](../administration/feature_flags.md) for this attribute to be ignored when requested by users without at least the Developer role. | +The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. + +In the response, `group_id` represents the ID of the group containing the project where the merge request resides. + +Example response: + ```json [ { @@ -569,17 +574,12 @@ Supported attributes: ] ``` -For important notes on response data, read [Merge requests list response notes](#merge-requests-list-response-notes). +For important notes on response data, see [Merge requests list response notes](#merge-requests-list-response-notes). ## Get single MR Shows information about a single merge request. -**Note**: the `changes_count` value in the response is a string, not an -integer. When an merge request has too many changes to display and store, -it is capped at 1,000. In that case, the API returns the string -`"1000+"` for the changes count. - ```plaintext GET /projects/:id/merge_requests/:merge_request_iid ``` @@ -598,24 +598,24 @@ Supported attributes: | Attribute | Type | Description | |----------------------------------|------|-------------| -| `approvals_before_merge`| integer | **(PREMIUM ALL)** Number of approvals required before this merge request can merge. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0. | +| `approvals_before_merge`| integer | **(PREMIUM ALL)** Number of approvals required before this merge request can merge. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/353097) in GitLab 16.0. | | `assignee` | object | First assignee of the merge request. | | `assignees` | array | Assignees of the merge request. | | `author` | object | User who created this merge request. | | `blocking_discussions_resolved` | boolean | Indicates if all discussions are resolved only if all are required before merge request can be merged. | -| `changes_count` | string | Number of changes made on the merge request. Empty when the merge request is created, and populates asynchronously. See [Empty API Fields for new merge requests](#empty-api-fields-for-new-merge-requests).| +| `changes_count` | string | Number of changes made on the merge request. Empty when the merge request is created, and populates asynchronously. A string, not an integer. When a merge request has too many changes to display and store, the value is capped at 1000 and returns the string `"1000+"`. See [Empty API Fields for new merge requests](#empty-api-fields-for-new-merge-requests).| | `closed_at` | datetime | Timestamp of when the merge request was closed. | | `closed_by` | object | User who closed this merge request. | | `created_at` | datetime | Timestamp of when the merge request was created. | | `description` | string | Description of the merge request. Contains Markdown rendered as HTML for caching. | -| `detailed_merge_status` | string | Detailed merge status of the merge request. Read [merge status](#merge-status) for a list of potential values. | +| `detailed_merge_status` | string | Detailed merge status of the merge request. See [merge status](#merge-status) for a list of potential values. | | `diff_refs` | object | References of the base SHA, the head SHA, and the start SHA for this merge request. Corresponds to the latest diff version of the merge request. Empty when the merge request is created, and populates asynchronously. See [Empty API fields for new merge requests](#empty-api-fields-for-new-merge-requests). | | `discussion_locked` | boolean | Indicates if comments on the merge request are locked to members only. | | `downvotes` | integer | Number of downvotes for the merge request. | | `draft` | boolean | Indicates if the merge request is a draft. | | `first_contribution` | boolean | Indicates if the merge request is the first contribution of the author. | | `first_deployed_to_production_at` | datetime | Timestamp of when the first deployment finished. | -| `force_remove_source_branch` | boolean | Indicates if the project settings will lead to source branch deletion after merge. | +| `force_remove_source_branch` | boolean | Indicates if the project settings lead to source branch deletion after merge. | | `has_conflicts` | boolean | Indicates if merge request has conflicts and cannot be merged. Dependent on the `merge_status` property. Returns `false` unless `merge_status` is `cannot_be_merged`. | | `head_pipeline` | object | Pipeline running on the branch HEAD of the merge request. Contains more complete information than `pipeline` and should be used instead of it. | | `id` | integer | ID of the merge request. | @@ -626,7 +626,7 @@ Supported attributes: | `merge_commit_sha` | string | SHA of the merge request commit. Returns `null` until merged. | | `merge_error` | string | Error message shown when a merge has failed. To check mergeability, use `detailed_merge_status` instead | | `merge_user` | object | The user who merged this merge request, the user who set it to auto-merge, or `null`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) in GitLab 14.7. | -| `merge_status` | string | Status of the merge request. Can be `unchecked`, `checking`, `can_be_merged`, `cannot_be_merged`, or `cannot_be_merged_recheck`. Affects the `has_conflicts` property. For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6. Use `detailed_merge_status` instead. | +| `merge_status` | string | Status of the merge request. Can be `unchecked`, `checking`, `can_be_merged`, `cannot_be_merged`, or `cannot_be_merged_recheck`. Affects the `has_conflicts` property. For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6. Use `detailed_merge_status` instead. | | `merge_when_pipeline_succeeds` | boolean | Indicates if the merge has been set to be merged when its pipeline succeeds. | | `merged_at` | datetime | Timestamp of when the merge request was merged. | | `merged_by` | object | User who merged this merge request or set it to auto-merge. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350534) in GitLab 14.7, and scheduled for removal in [API version 5](https://gitlab.com/groups/gitlab-org/-/epics/8115). Use `merge_user` instead. | @@ -638,13 +638,13 @@ Supported attributes: | `references` | object | Internal references of the merge request. Includes `short`, `relative`, and `full` references. `references.relative` is relative to the merge request's group or project. When fetched from the merge request's project, `relative` and `short` formats are identical. When requested across groups or projects, `relative` and `full` formats are identical.| | `reviewers` | array | Reviewers of the merge request. | | `sha` | string | Diff head SHA of the merge request. | -| `should_remove_source_branch` | boolean | Indicates if the source branch of the merge request will be deleted after merge. | +| `should_remove_source_branch` | boolean | Indicates if the source branch of the merge request should be deleted after merge. | | `source_branch` | string | Source branch of the merge request. | | `source_project_id` | integer | ID of the merge request source project. | | `squash` | boolean | Indicates if squash on merge is enabled. | | `squash_commit_sha` | string | SHA of the squash commit. Empty until merged. | | `state` | string | State of the merge request. Can be `opened`, `closed`, `merged` or `locked`. | -| `subscribed` | boolean | Indicates if the currently authenticated user is subscribed to this merge request. | +| `subscribed` | boolean | Indicates if the current authenticated user is subscribed to this merge request. | | `target_branch` | string | Target branch of the merge request. | | `target_project_id` | integer | ID of the merge request target project. | | `task_completion_status` | object | Completion status of tasks. | @@ -656,6 +656,8 @@ Supported attributes: | `web_url` | string | Web URL of the merge request. | | `work_in_progress` | boolean | Deprecated: Use `draft` instead. Indicates if the merge request is a draft. | +Example response: + ```json { "id": 155016530, @@ -801,10 +803,10 @@ Supported attributes: ### Single merge request response notes -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29984) in GitLab 12.8, the mergeability (`merge_status`) - of each merge request is checked asynchronously when a request is made to this endpoint. Poll this API endpoint - to get updated status. This affects the `has_conflicts` property as it is dependent on the `merge_status`. It returns - `false` unless `merge_status` is `cannot_be_merged`. +The mergeability (`merge_status`) +of each merge request is checked asynchronously when a request is made to this endpoint. Poll this API endpoint +to get updated status. This affects the `has_conflicts` property as it is dependent on the `merge_status`. It returns +`false` unless `merge_status` is `cannot_be_merged`. ### Merge status @@ -827,6 +829,7 @@ Use `detailed_merge_status` instead of `merge_status` to account for all potenti - `not_approved`: Approval is required before merge. - `not_open`: The merge request must be open before merge. - `policies_denied`: The merge request contains denied policies. + - `jira_association_missing`: The title or description must reference a Jira issue. ### Preparation steps @@ -855,6 +858,8 @@ Supported attributes: | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +Example response: + ```json [ { @@ -891,6 +896,8 @@ Supported attributes: | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +Example response: + ```json [ { @@ -935,6 +942,8 @@ Supported attributes: | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +Example response: + ```json [ { @@ -962,19 +971,10 @@ Supported attributes: WARNING: This endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/322117) in GitLab 15.7 -and will be removed in API v5. Use the [List merge request diffs](#list-merge-request-diffs) endpoint instead. +and is scheduled for removal in API v5. Use the [List merge request diffs](#list-merge-request-diffs) endpoint instead. Shows information about the merge request including its files and changes. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46190) in GitLab 13.6, -diffs associated with the set of changes have the same size limitations applied as other diffs -returned by the API or viewed via the UI. When these limits impact the results, the `overflow` -field contains a value of `true`. Diff data without these limits applied can be retrieved by -adding the `access_raw_diffs` parameter, accessing diffs not from the database but from Gitaly directly. -This approach is generally slower and more resource-intensive, but isn't subject to size limits -placed on database-backed diffs. [Limits inherent to Gitaly](../development/merge_request_concepts/diffs/index.md#diff-limits) -still apply. - ```plaintext GET /projects/:id/merge_requests/:merge_request_iid/changes ``` @@ -985,9 +985,19 @@ Supported attributes: |---------------------|----------------|----------|-------------| | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | -| `access_raw_diffs` | boolean | No | Retrieve change diffs via Gitaly. | +| `access_raw_diffs` | boolean | No | Retrieve change diffs through Gitaly. | | `unidiff` | boolean | No | Present change diffs in the [unified diff](https://www.gnu.org/software/diffutils/manual/html_node/Detailed-Unified.html) format. Default is false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130610) in GitLab 16.5. | +Diffs associated with the set of changes have the same size limitations applied as other diffs +returned by the API or viewed through the UI. When these limits impact the results, the `overflow` +field contains a value of `true`. Diff data without these limits applied can be retrieved by +adding the `access_raw_diffs` parameter, accessing diffs not from the database but from Gitaly directly. +This approach is generally slower and more resource-intensive, but isn't subject to size limits +placed on database-backed diffs. [Limits inherent to Gitaly](../development/merge_request_concepts/diffs/index.md#diff-limits) +still apply. + +Example response: + ```json { "id": 21, @@ -1167,8 +1177,7 @@ Merge requests that exceed the diff limits return limited results. ## List merge request pipelines -Get a list of merge request pipelines. The pagination parameters `page` and -`per_page` can be used to restrict the list of merge request pipelines. +Get a list of merge request pipelines. ```plaintext GET /projects/:id/merge_requests/:merge_request_iid/pipelines @@ -1181,6 +1190,11 @@ Supported attributes: | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +The pagination parameters `page` and +`per_page` can be used to restrict the list of merge request pipelines. + +Example response: + ```json [ { @@ -1195,7 +1209,7 @@ Supported attributes: ## Create merge request pipeline Create a new [pipeline for a merge request](../ci/pipelines/merge_request_pipelines.md). -A pipeline created via this endpoint doesn't run a regular branch/tag pipeline. +A pipeline created from this endpoint doesn't run a regular branch/tag pipeline. It requires `.gitlab-ci.yml` to be configured with `only: [merge_requests]` to create jobs. The new pipeline can be: @@ -1215,6 +1229,8 @@ Supported attributes: | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +Example response: + ```json { "id": 2, @@ -1277,10 +1293,12 @@ POST /projects/:id/merge_requests | `labels` | string | No | Labels for the merge request, as a comma-separated list. | | `milestone_id` | integer | No | The global ID of a milestone. | | `remove_source_branch` | boolean | No | Flag indicating if a merge request should remove the source branch when merging. | -| `reviewer_ids` | integer array | No | The ID of the users added as a reviewer to the merge request. If set to `0` or left empty, no reviewers are added. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | -| `squash` | boolean | No | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. | +| `reviewer_ids` | integer array | No | The ID of the users added as a reviewer to the merge request. If set to `0` or left empty, no reviewers are added. | +| `squash` | boolean | No | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) might override this value. | | `target_project_id` | integer | No | Numeric ID of the target project. | +Example response: + ```json { "id": 1, @@ -1403,7 +1421,7 @@ POST /projects/:id/merge_requests } ``` -For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). +For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). ## Update MR @@ -1428,7 +1446,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `milestone_id` | integer | No | The global ID of a milestone to assign the merge request to. Set to `0` or provide an empty value to unassign a milestone.| | `remove_labels` | string | No | Comma-separated label names to remove from a merge request. | | `remove_source_branch` | boolean | No | Flag indicating if a merge request should remove the source branch when merging. | -| `reviewer_ids` | integer array | No | The ID of the users set as a reviewer to the merge request. Set the value to `0` or provide an empty value to unset all reviewers. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | +| `reviewer_ids` | integer array | No | The ID of the users set as a reviewer to the merge request. Set the value to `0` or provide an empty value to unset all reviewers. | | `squash` | boolean | No | Indicates if the merge request is set to be squashed when merged. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) may override this value. | | `state_event` | string | No | New state (close/reopen). | | `target_branch` | string | No | The target branch. | @@ -1436,6 +1454,8 @@ PUT /projects/:id/merge_requests/:merge_request_iid Must include at least one non-required attribute from above. +Example response: + ```json { "id": 1, @@ -1574,7 +1594,7 @@ Must include at least one non-required attribute from above. } ``` -For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). +For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). ## Delete a merge request @@ -1590,7 +1610,8 @@ DELETE /projects/:id/merge_requests/:merge_request_iid | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request DELETE \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/4/merge_requests/85" ``` @@ -1615,6 +1636,19 @@ Supported attributes: | `squash_commit_message` | string | No | Custom squash commit message. | | `squash` | boolean | No | If `true`, the commits are squashed into a single commit on merge. | +This API returns specific HTTP status codes on failure: + +| HTTP Status | Message | Reason | +|-------------|--------------------------------------------|--------| +| `401` | `401 Unauthorized` | This user does not have permission to accept this merge request. | +| `405` | `405 Method Not Allowed` | The merge request is not able to be merged. | +| `409` | `SHA does not match HEAD of source branch` | The provided `sha` parameter does not match the HEAD of the source. | +| `422` | `Branch cannot be merged` | The merge request failed to merge. | + +For additional important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). + +Example response: + ```json { "id": 1, @@ -1753,17 +1787,6 @@ Supported attributes: } ``` -This API returns specific HTTP status codes on failure: - -| HTTP Status | Message | Reason | -|-------------|--------------------------------------------|--------| -| `401` | `Unauthorized` | This user does not have permission to accept this merge request. | -| `405` | `Method Not Allowed` | The merge request is not able to be merged. | -| `409` | `SHA does not match HEAD of source branch` | The provided `sha` parameter does not match the HEAD of the source. | -| `422` | `Branch cannot be merged` | The merge request failed to merge. | - -For additional important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). - ## Merge to default merge ref path Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` @@ -1775,10 +1798,6 @@ This action isn't a regular merge action, because it doesn't change the merge re This ref (`refs/merge-requests/:iid/merge`) isn't necessarily overwritten when submitting requests to this API, though it makes sure the ref has the latest possible state. -If the merge request has conflicts, is empty or already merged, you receive a `400` and a descriptive error message. - -It returns the HEAD commit of `refs/merge-requests/:iid/merge` in the response body in case of `200`. - ```plaintext GET /projects/:id/merge_requests/:merge_request_iid/merge_ref ``` @@ -1790,21 +1809,24 @@ Supported attributes: | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +This API returns specific HTTP status codes: + +| HTTP Status | Message | Reason | +|-------------|----------------------------------|--------| +| `200` | _(none)_ | Success. Returns the HEAD commit of `refs/merge-requests/:iid/merge`. | +| `400` | `Merge request is not mergeable` | The merge request has conflicts. | +| `400` | `Merge ref cannot be updated` | | +| `400` | `Unsupported operation` | The GitLab database is in read-only mode. | + +Example response: + ```json { "commit_id": "854a3a7a17acbcc0bbbea170986df1eb60435f34" } ``` -## Cancel Merge When Pipeline Succeeds - -This API returns specific HTTP status codes on failure: - -| HTTP Status | Message | Reason | -|-------------|----------------------|-----------------------------------------------------------------------| -| `401` | `Unauthorized` | This user does not have permission to cancel this merge request. | -| `405` | `Method Not Allowed` | The merge request is already merged or closed. | -| `406` | `Not Acceptable` | The merge request is not set to be merged when the pipeline succeeds. | +## Cancel merge when pipeline succeeds ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds @@ -1817,6 +1839,17 @@ Supported attributes: | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +This API returns specific HTTP status codes: + +| HTTP Status | Message | Reason | +|-------------|----------|--------| +| `201` | _(none)_ | Success, or the merge request has already merged. | +| `406` | `Can't cancel the automatic merge` | The merge request is closed. | + +For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). + +Example response: + ```json { "id": 1, @@ -1955,16 +1988,11 @@ Supported attributes: } ``` -For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). - ## Rebase a merge request Automatically rebase the `source_branch` of the merge request against its `target_branch`. -If you don't have permissions to push to the merge request's source branch - -you receive a `403 Forbidden` response. - ```plaintext PUT /projects/:id/merge_requests/:merge_request_iid/rebase ``` @@ -1976,12 +2004,20 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase | `skip_ci` | boolean | No | Set to `true` to skip creating a CI pipeline. | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request PUT \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/rebase" ``` -This request is asynchronous. The API returns a `HTTP 202 Accepted` response -if the request is enqueued successfully, with a response containing: +This API returns specific HTTP status codes: + +| HTTP Status | Message | Reason | +|-------------|--------------------------------------------|--------| +| `202` | *(no message)* | Successfully enqueued. | +| `403` | <ul><li>`Source branch does not exist`</li><li>`Cannot push to source branch`</li><li>`Source branch is protected from force push`</li></ul> | You don't have permission to push to the merge request's source branch. | +| `409` | `Failed to enqueue the rebase operation` | A long-lived transaction might have blocked your request. | + +If the request is enqueued successfully, the response contains: ```json { @@ -2023,7 +2059,7 @@ If the rebase operation fails, the response includes the following: ## Comments on merge requests -Comments are done via the [notes](notes.md) resource. +Comments are created by the [notes](notes.md) resource. ## List issues that close on merge @@ -2103,8 +2139,7 @@ Example response when an external issue tracker (for example, Jira) is used: ## Subscribe to a merge request -Subscribes the authenticated user to a merge request to receive notification. If the user is already subscribed to the merge request, the -status code `HTTP 304 Not Modified` is returned. +Subscribes the authenticated user to a merge request to receive notification. ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/subscribe @@ -2115,8 +2150,12 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe | `id` | integer or string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +If the user is already subscribed to the merge request, the +status code `HTTP 304 Not Modified` is returned. + ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/17/subscribe" ``` @@ -2259,13 +2298,12 @@ Example response: } ``` -For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). +For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). ## Unsubscribe from a merge request Unsubscribes the authenticated user from a merge request to not receive -notifications from that merge request. If the user is -not subscribed to the merge request, the status code `HTTP 304 Not Modified` is returned. +notifications from that merge request. ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe @@ -2277,10 +2315,13 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/17/unsubscribe" ``` +If the user is not subscribed to the merge request, the status code `HTTP 304 Not Modified` is returned. + Example response: ```json @@ -2420,7 +2461,7 @@ Example response: } ``` -For important notes on response data, read [Single merge request response notes](#single-merge-request-response-notes). +For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). ## Create a to-do item @@ -2438,7 +2479,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/27/todo" ``` @@ -2554,8 +2596,7 @@ Example response: ## Get merge request diff versions -Get a list of merge request diff versions. For an explanation of the SHAs in the response, -read [SHAs in the API response](#shas-in-the-api-response). +Get a list of merge request diff versions. ```plaintext GET /projects/:id/merge_requests/:merge_request_iid/versions @@ -2566,6 +2607,9 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions | `id` | String | Yes | The ID of the project. | | `merge_request_iid` | integer | Yes | The internal ID of the merge request. | +For an explanation of the SHAs in the response, +see [SHAs in the API response](#shas-in-the-api-response). + ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions" @@ -2607,8 +2651,7 @@ Example response: ## Get a single merge request diff version -Get a single merge request diff version. For an explanation of the SHAs in the response, -read [SHAs in the API response](#shas-in-the-api-response). +Get a single merge request diff version. ```plaintext GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id @@ -2621,6 +2664,9 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id | `version_id` | integer | Yes | The ID of the merge request diff version. | | `unidiff` | boolean | No | Present diffs in the [unified diff](https://www.gnu.org/software/diffutils/manual/html_node/Detailed-Unified.html) format. Default is false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130610) in GitLab 16.5. | +For an explanation of the SHAs in the response, +see [SHAs in the API response](#shas-in-the-api-response). + ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions/1" @@ -2692,7 +2738,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate | `duration` | string | Yes | The duration in human format, such as `3h30m`. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_estimate?duration=3h30m" ``` @@ -2721,7 +2768,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate | `merge_request_iid` | integer | Yes | The internal ID of a project's merge request. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_time_estimate" ``` @@ -2752,7 +2800,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time | `summary` | string | No | A summary of how the time was spent. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/add_spent_time?duration=1h" ``` @@ -2781,7 +2830,8 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time | `merge_request_iid` | integer | Yes | The internal ID of a project's merge request. | ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +curl --request POST \ + --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_spent_time" ``` @@ -2825,7 +2875,7 @@ Example response: ## Approvals -For approvals, see [Merge request approvals](merge_request_approvals.md) +For approvals, see [Merge request approvals](merge_request_approvals.md). ## List merge request state events diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index 8ef6a318ced..dff65e5786b 100644 --- a/doc/api/merge_trains.md +++ b/doc/api/merge_trains.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge Trains API **(PREMIUM ALL)** diff --git a/doc/api/metadata.md b/doc/api/metadata.md index 88afc9719a7..82506cba905 100644 --- a/doc/api/metadata.md +++ b/doc/api/metadata.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metadata API **(FREE ALL)** diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index 37d19860e6a..cee41171dbe 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -1,8 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dashboard annotations API **(FREE ALL)** diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 6e839e75ae9..c04bc901a06 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -1,8 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User-starred metrics dashboards API **(FREE ALL)** diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 38c11216e4f..92268cece41 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project milestones API **(FREE ALL)** @@ -30,11 +30,12 @@ Parameters: | Attribute | Type | Required | Description | | ---------------------------- | ------ | -------- | ----------- | | `id` | integer or string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | -| `iids[]` | integer array | no | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) | +| `iids[]` | integer array | no | Return only the milestones having the given `iid`. Ignored if `include_ancestors` is `true`. | | `state` | string | no | Return only `active` or `closed` milestones | | `title` | string | no | Return only the milestones having the given `title` | | `search` | string | no | Return only milestones with a title or description matching the provided string | -| `include_parent_milestones` | boolean | no | Include group milestones from parent group and its ancestors. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) in GitLab 13.4 | +| `include_parent_milestones` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/433298) in GitLab 16.7. Use `include_ancestors` instead. | +| `include_ancestors` | boolean | no | Include milestones from all parent groups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) in GitLab 13.4. | | `updated_before` | datetime | no | Return only milestones updated before the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Introduced in GitLab 15.10 | | `updated_after` | datetime | no | Return only milestones updated after the given datetime. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Introduced in GitLab 15.10 | diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 794da9d8f96..4e285cde975 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Namespaces API **(FREE ALL)** @@ -53,6 +53,7 @@ Example response: "web_url": "https://gitlab.example.com/user1", "billable_members_count": 1, "plan": "default", + "end_date": null, "trial_ends_on": null, "trial": false, "root_repository_size": 100, @@ -70,6 +71,7 @@ Example response: "members_count_with_descendants": 2, "billable_members_count": 2, "plan": "default", + "end_date": null, "trial_ends_on": null, "trial": false, "root_repository_size": 100, @@ -87,6 +89,7 @@ Example response: "members_count_with_descendants": 5, "billable_members_count": 5, "plan": "default", + "end_date": null, "trial_ends_on": null, "trial": false, "root_repository_size": 100, @@ -168,6 +171,7 @@ Example response: "max_seats_used": 0, "seats_in_use": 0, "plan": "default", + "end_date": null, "trial_ends_on": null, "trial": false, "root_repository_size": 100, @@ -198,6 +202,7 @@ Example response: "max_seats_used": 0, "seats_in_use": 0, "plan": "default", + "end_date": null, "trial_ends_on": null, "trial": false, "root_repository_size": 100 diff --git a/doc/api/notes.md b/doc/api/notes.md index 18f2c08869e..40592566079 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Notes API **(FREE ALL)** diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index e498c3c91fb..3917d0b5f7e 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Notification settings API **(FREE ALL)** diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index ee6c32d8f60..2f8e030374f 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OAuth 2.0 identity provider API **(FREE ALL)** @@ -54,7 +53,7 @@ Refer to the [OAuth RFC](https://www.rfc-editor.org/rfc/rfc6749) to find out how all those flows work and pick the right one for your use case. Authorization code (with or without PKCE) flow requires `application` to be -registered first via the `/profile/applications` page in your user's account. +registered first via the `/user_settings/applications` page in your user's account. During registration, by enabling proper scopes, you can limit the range of resources which the `application` can access. Upon creation, you obtain the `application` credentials: _Application ID_ and _Client Secret_. The _Client Secret_ @@ -73,7 +72,7 @@ parameter, which are securely bound to the user agent", with each request to the ### Use HTTPS in production -For production, please use HTTPS for your `redirect_uri`. +For production, use HTTPS for your `redirect_uri`. For development, GitLab allows insecure HTTP redirect URIs. As OAuth 2.0 bases its security entirely on the transport layer, you should not use unprotected @@ -418,7 +417,7 @@ Standard OAuth 2.0 tokens support different degrees of access to GitLab registries, as they: - Do not allow users to authenticate to: - - The GitLab [Container registry](../user/packages/container_registry/authenticate_with_container_registry.md). + - The GitLab [container registry](../user/packages/container_registry/authenticate_with_container_registry.md). - Packages listed in the GitLab [Package registry](../user/packages/package_registry/index.md). - Allow users to get, list, and delete registries through - the [Container registry API](container_registry.md). + the [container registry API](container_registry.md). diff --git a/doc/api/openapi/openapi_interactive.md b/doc/api/openapi/openapi_interactive.md index 2185f5b493e..5f0c9a28589 100644 --- a/doc/api/openapi/openapi_interactive.md +++ b/doc/api/openapi/openapi_interactive.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Interactive API documentation diff --git a/doc/api/packages.md b/doc/api/packages.md index 7c8dfeb8710..0d69078d1a1 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Packages API **(FREE ALL)** @@ -91,7 +91,7 @@ GET /groups/:id/packages | Attribute | Type | Required | Description | |:----------------------|:---------------|:---------|:------------| | `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). | -| `exclude_subgroups` | boolean | false | If the parameter is included as true, packages from projects from subgroups are not listed. Default is `false`. | +| `exclude_subgroups` | boolean | no | If the parameter is included as true, packages from projects from subgroups are not listed. Default is `false`. | | `order_by` | string | no | The field to use as order. One of `created_at` (default), `name`, `version`, `type`, or `project_path`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | | `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, `helm`, or `golang`. | @@ -263,7 +263,7 @@ GET /projects/:id/packages/:package_id/package_files | `package_id` | integer | yes | ID of a package. | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/4/package_files" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/packages/:package_id/package_files" ``` Example response: diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md index ae986b082d6..33840b31a18 100644 --- a/doc/api/packages/composer.md +++ b/doc/api/packages/composer.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Composer API **(FREE ALL)** @@ -17,7 +17,7 @@ package registry, see the [Composer package registry documentation](../../user/p NOTE: These endpoints do not adhere to the standard API authentication methods. -See the [Composer package registry documentation](../../user/packages/composer_repository/index.md) +See the [Composer Package Registry documentation](../../user/packages/composer_repository/index.md) for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future. ## Base repository request diff --git a/doc/api/packages/conan.md b/doc/api/packages/conan.md index 92e9f687242..44e97f3861c 100644 --- a/doc/api/packages/conan.md +++ b/doc/api/packages/conan.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Conan API **(FREE ALL)** diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md index 267ebb59c19..30ac9175feb 100644 --- a/doc/api/packages/debian.md +++ b/doc/api/packages/debian.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Debian API **(FREE SELF)** @@ -94,7 +94,7 @@ GET projects/:id/packages/debian/pool/:distribution/:letter/:package_name/:packa | `letter` | string | yes | The Debian Classification (first-letter or lib-first-letter). | | `package_name` | string | yes | The source package name. | | `package_version` | string | yes | The source package version. | -| `file_name` | string | yes | The filename. | +| `file_name` | string | yes | The file name. | ```shell curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/debian/pool/my-distro/a/my-pkg/1.0.0/example_1.0.0~alpha2_amd64.deb" @@ -108,7 +108,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Route prefix @@ -166,7 +166,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Download a signed distribution Release file @@ -194,7 +194,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Download a release file signature @@ -222,7 +222,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Download a packages index @@ -252,7 +252,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Download a packages index by hash @@ -283,7 +283,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Download a Debian Installer packages index @@ -313,7 +313,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Download a Debian Installer packages index by hash @@ -343,7 +343,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Download a source packages index @@ -372,7 +372,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. ## Download a source packages index by hash @@ -401,4 +401,4 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote filename in the current directory. +This writes the downloaded file using the remote file name in the current directory. diff --git a/doc/api/packages/debian_group_distributions.md b/doc/api/packages/debian_group_distributions.md index 68763a197aa..01a8c714456 100644 --- a/doc/api/packages/debian_group_distributions.md +++ b/doc/api/packages/debian_group_distributions.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Debian group distributions API **(FREE SELF)** diff --git a/doc/api/packages/debian_project_distributions.md b/doc/api/packages/debian_project_distributions.md index 952b75ceb0a..ca6e3a63194 100644 --- a/doc/api/packages/debian_project_distributions.md +++ b/doc/api/packages/debian_project_distributions.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Debian project distributions API **(FREE SELF)** diff --git a/doc/api/packages/go_proxy.md b/doc/api/packages/go_proxy.md index 1cfc0f0b296..aeda947a0a8 100644 --- a/doc/api/packages/go_proxy.md +++ b/doc/api/packages/go_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Go Proxy API **(FREE SELF)** diff --git a/doc/api/packages/helm.md b/doc/api/packages/helm.md index 0a6bee6e55c..f4c5b315f24 100644 --- a/doc/api/packages/helm.md +++ b/doc/api/packages/helm.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Helm API **(FREE ALL)** @@ -63,7 +63,7 @@ GET projects/:id/packages/helm/:channel/charts/:file_name.tgz | ----------- | ------ | -------- | ----------- | | `id` | string | yes | The ID or full path of the project. | | `channel` | string | yes | Helm repository channel. | -| `file_name` | string | yes | Chart filename. | +| `file_name` | string | yes | Chart file name. | ```shell curl --user <username>:<personal_access_token> \ diff --git a/doc/api/packages/maven.md b/doc/api/packages/maven.md index fc81f41d52b..9bb3d2551e9 100644 --- a/doc/api/packages/maven.md +++ b/doc/api/packages/maven.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maven API **(FREE ALL)** diff --git a/doc/api/packages/npm.md b/doc/api/packages/npm.md index 0bfc39ab92b..b4147fca28d 100644 --- a/doc/api/packages/npm.md +++ b/doc/api/packages/npm.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # npm API **(FREE ALL)** @@ -13,7 +13,7 @@ This API is used by the [npm package manager client](https://docs.npmjs.com/) and is not meant for manual consumption. For instructions on how to upload and install npm packages from the GitLab -package registry, see the [npm package registry documentation](../../user/packages/npm_registry/index.md). +Package Registry, see the [npm package registry documentation](../../user/packages/npm_registry/index.md). NOTE: These endpoints do not adhere to the standard API authentication methods. diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index 794c14fb5bc..a946fa68943 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # NuGet API **(FREE ALL)** @@ -13,7 +13,7 @@ This API is used by the [NuGet package manager client](https://www.nuget.org/) and is generally not meant for manual consumption. For instructions on how to upload and install NuGet packages from the GitLab -package registry, see the [NuGet package registry documentation](../../user/packages/nuget_repository/index.md). +Package Registry, see the [NuGet package registry documentation](../../user/packages/nuget_repository/index.md). NOTE: These endpoints do not adhere to the standard API authentication methods. @@ -456,6 +456,41 @@ Possible request responses: | `403` | Forbidden | | `404` | Not found | +## Download a debugging symbol file `.pdb` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416178) in GitLab 16.7. + +Download a debugging symbol file (`.pdb`): + +```plaintext +GET <route-prefix>/symbolfiles/:file_name/:signature/:file_name +``` + +| Attribute | Type | Required | Description | +| ----------------- | ------ | -------- | ----------- | +| `file_name` | string | yes | The name of the file. | +| `signature` | string | yes | The signature of the file. | +| `Symbolchecksum` | string | yes | Required header. The checksum of the file. | + +```shell +curl --header "Symbolchecksum: SHA256:<file_checksum>" "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolfiles/:file_name/:signature/:file_name" +``` + +Write the output to a file: + +```shell +curl --header "Symbolchecksum: SHA256:<file_checksum>" "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolfiles/mynugetpkg.pdb/k813f89485474661234z7109cve5709eFFFFFFFF/mynugetpkg.pdb" > mynugetpkg.pdb +``` + +Possible request responses: + +| Status | Description | +| ------ | ----------- | +| `200` | File downloaded | +| `400` | Bad request | +| `403` | Forbidden | +| `404` | Not found | + ## V2 Feed Metadata Endpoints > Introduced in GitLab 16.3. diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index f13665f16c9..ee4ae4fff66 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PyPI API **(FREE ALL)** @@ -13,7 +13,7 @@ This API is used by the [PyPI package manager client](https://pypi.org/) and is generally not meant for manual consumption. For instructions on how to upload and install PyPI packages from the GitLab -package registry, see the [PyPI package registry documentation](../../user/packages/pypi_repository/index.md). +Package Registry, see the [PyPI package registry documentation](../../user/packages/pypi_repository/index.md). NOTE: These endpoints do not adhere to the standard API authentication methods. @@ -152,7 +152,7 @@ GET projects/:id/packages/pypi/files/:sha256/:file_identifier | --------- | ---- | -------- | ----------- | | `id` | string | yes | The ID or full path of the project. | | `sha256` | string | yes | PyPI package file sha256 check sum. | -| `file_identifier` | string | yes | The PyPI package filename. | +| `file_identifier` | string | yes | The PyPI package file name. | ```shell curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" diff --git a/doc/api/packages/rubygems.md b/doc/api/packages/rubygems.md index 17338161a7b..93675d9a6ae 100644 --- a/doc/api/packages/rubygems.md +++ b/doc/api/packages/rubygems.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Ruby gems API **(FREE SELF)** diff --git a/doc/api/packages/terraform-modules.md b/doc/api/packages/terraform-modules.md index 30775be5d28..3645fc03e9a 100644 --- a/doc/api/packages/terraform-modules.md +++ b/doc/api/packages/terraform-modules.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform Module Registry API **(FREE ALL)** @@ -228,3 +228,39 @@ To write the output to file: ```shell curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/file" --output hello-world-local.tgz ``` + +## Upload module + +```plaintext +PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file +``` + +| Attribute | Type | Required | Description | +|------------------|-------------------|----------|-------------| +| `id` | integer or string | yes | The ID or URL-encoded path of the project. | +| `module-name` | string | yes | The module name. | +| `module-system` | string | yes | The name of the module system or [provider](https://www.terraform.io/registry/providers). | +| `module-version` | string | yes | Specific module version to upload. | + +```shell +curl --fail-with-body \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --upload-file path/to/file.tgz \ + --url "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file" +``` + +Tokens that can be used to authenticate: + +| Header | Value | +|-----------------|-------| +| `PRIVATE-TOKEN` | A [personal access token](../../user/profile/personal_access_tokens.md) with `api` scope. | +| `DEPLOY-TOKEN` | A [deploy token](../../user/project/deploy_tokens/index.md) with `write_package_registry` scope. | +| `JOB-TOKEN` | A [job token](../../ci/jobs/ci_job_token.md). | + +Example response: + +```json +{ + "message": "201 Created" +} +``` diff --git a/doc/api/pages.md b/doc/api/pages.md index 1a1ccf4143d..69c96f2aeb9 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pages API **(FREE ALL)** @@ -12,7 +12,7 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a ## Unpublish Pages -Prerequisite: +Prerequisites: - You must have administrator access to the instance. diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index d66c2d9d567..93d01d3ebde 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pages domains API **(FREE ALL)** @@ -12,7 +12,7 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a ## List all Pages domains -Prerequisite: +Prerequisites: - You must have administrator access to the instance. diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 90390acc343..6cf3ee3d6b0 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Personal access tokens API **(FREE ALL)** @@ -211,13 +211,16 @@ Example response: Rotate a personal access token. Revokes the previous token and creates a new token that expires in one week. +In GitLab 16.6 and later, you can use the `expires_at` parameter to set a different expiry date. This non-default expiry date can be up to a maximum of one year from the rotation date. + ```plaintext POST /personal_access_tokens/:id/rotate ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer/string | yes | ID of personal access token | +| Attribute | Type | Required | Description | +|-----------|-----------|----------|---------------------| +| `id` | integer/string | yes | ID of personal access token | +| `expires_at` | date | no | Expiration date of the access token in ISO format (`YYYY-MM-DD`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6. | NOTE: Non-administrators can rotate their own tokens. Administrators can rotate tokens of any user. diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index bfcc4ee4613..9992231dc7f 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline schedules API **(FREE ALL)** diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index a3fbed600ff..c17227a3d41 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline trigger tokens API **(FREE ALL)** diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 50616974ae1..d8b4b4cf41f 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipelines API **(FREE ALL)** diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md index 383d7aa1966..46e0cc27a94 100644 --- a/doc/api/plan_limits.md +++ b/doc/api/plan_limits.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Plan limits API **(FREE SELF)** diff --git a/doc/api/product_analytics.md b/doc/api/product_analytics.md index efa9c637fea..ad92818f5ba 100644 --- a/doc/api/product_analytics.md +++ b/doc/api/product_analytics.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Product analytics API **(ULTIMATE ALL)** diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md index 2f386e22001..f8e7c0f3633 100644 --- a/doc/api/project_access_tokens.md +++ b/doc/api/project_access_tokens.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project access tokens API **(FREE ALL)** @@ -139,6 +139,8 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ Rotate a project access token. Revokes the previous token and creates a new token that expires in one week. +In GitLab 16.6 and later, you can use the `expires_at` parameter to set a different expiry date. This non-default expiry date can be up to a maximum of one year from the rotation date. + WARNING: When you rotate a project access token, the new token retains the expiry date of the old token. For more information, see [issue 423362](https://gitlab.com/gitlab-org/gitlab/-/issues/423362). @@ -146,10 +148,11 @@ When you rotate a project access token, the new token retains the expiry date of POST /projects/:id/access_tokens/:token_id/rotate ``` -| Attribute | Type | required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer or string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | -| `token_id` | integer or string | yes | ID of the project access token | +| Attribute | Type | required | Description | +|-----------|------------|----------|---------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) | +| `token_id` | integer/string | yes | ID of the project access token | +| `expires_at` | date | no | Expiration date of the access token in ISO format (`YYYY-MM-DD`). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416795) in GitLab 16.6. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>/rotate" diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index b8ca5c2674c..a52e094d821 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Project Aliases API **(PREMIUM SELF)** diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index d615df112cf..20654242467 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project badges API **(FREE ALL)** diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 6e61c0d56b3..1427b67a224 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project clusters API (certificate-based) (deprecated) **(FREE ALL)** diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 1a6b0ccc2c4..974694e0808 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project import and export API **(FREE ALL)** diff --git a/doc/api/project_job_token_scopes.md b/doc/api/project_job_token_scopes.md index 4117c8c4971..59374a8b89f 100644 --- a/doc/api/project_job_token_scopes.md +++ b/doc/api/project_job_token_scopes.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Project CI/CD job token scope API **(FREE ALL)** diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 7cc10816f5e..5031279d5bb 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project-level CI/CD variables API **(FREE ALL)** diff --git a/doc/api/project_relations_export.md b/doc/api/project_relations_export.md index 628bb467a02..5fe3923edc8 100644 --- a/doc/api/project_relations_export.md +++ b/doc/api/project_relations_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project relations export API **(FREE ALL)** @@ -75,6 +75,7 @@ The status can be one of the following: "error": null, "updated_at": "2021-05-04T11:25:20.423Z", "batched": true, + "batches_count": 1, "batches": [ { "status": 1, @@ -90,7 +91,8 @@ The status can be one of the following: "status": 1, "error": null, "updated_at": "2021-05-04T11:25:20.085Z", - "batched": false + "batched": false, + "batches_count": 0 } ] ``` diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index 925d3a46f45..2d400956f13 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project repository storage moves API **(FREE SELF)** diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 7a7f34046d2..100e161130d 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project snippets **(FREE ALL)** diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index adc977d7d73..f4a5c430fe9 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Project statistics API **(FREE ALL)** diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index f4fb17d8c57..3960dba3d76 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project templates API **(FREE ALL)** diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index 2b4d3ec50df..771ff4c2e8e 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -1,18 +1,22 @@ --- stage: Govern group: Threat Insights -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Project Vulnerabilities API **(ULTIMATE ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. +> - `last_edited_at` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. +> - `start_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. +> - `updated_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. +> - `last_edited_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. +> - `due_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. WARNING: 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. Please use the +across GitLab releases. Use the [GraphQL API](graphql/reference/index.md#queryvulnerabilities) instead. @@ -59,7 +63,6 @@ Example response: "description": null, "dismissed_at": null, "dismissed_by_id": null, - "due_date": null, "finding": { "confidence": "medium", "created_at": "2020-04-07T14:01:04.630Z", @@ -79,8 +82,6 @@ Example response: "vulnerability_id": 103 }, "id": 103, - "last_edited_at": null, - "last_edited_by_id": null, "project": { "created_at": "2020-04-07T13:54:25.634Z", "description": "", @@ -96,11 +97,9 @@ Example response: "resolved_by_id": null, "resolved_on_default_branch": false, "severity": "low", - "start_date": null, "state": "detected", "title": "Regular Expression Denial of Service in debug", - "updated_at": "2020-04-07T14:01:04.655Z", - "updated_by_id": null + "updated_at": "2020-04-07T14:01:04.655Z" } ] ``` @@ -147,7 +146,6 @@ Example response: "description": null, "dismissed_at": null, "dismissed_by_id": null, - "due_date": null, "finding": { "confidence": "medium", "created_at": "2020-04-07T14:01:04.630Z", @@ -167,8 +165,6 @@ Example response: "vulnerability_id": 103 }, "id": 103, - "last_edited_at": null, - "last_edited_by_id": null, "project": { "created_at": "2020-04-07T13:54:25.634Z", "description": "", @@ -184,11 +180,9 @@ Example response: "resolved_by_id": null, "resolved_on_default_branch": false, "severity": "low", - "start_date": null, "state": "detected", "title": "Regular Expression Denial of Service in debug", - "updated_at": "2020-04-07T14:01:04.655Z", - "updated_by_id": null + "updated_at": "2020-04-07T14:01:04.655Z" } ``` diff --git a/doc/api/projects.md b/doc/api/projects.md index f4a9e396930..3d3a11fc59e 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Projects API **(FREE ALL)** @@ -240,6 +240,7 @@ When the user is authenticated and `simple` is not set this returns something li "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_job_token_scope_enabled": false, "ci_separated_caches": true, + "ci_restrict_pipeline_cancellation_role": "developer", "public_jobs": true, "build_timeout": 3600, "auto_cancel_pending_pipelines": "enabled", @@ -280,6 +281,9 @@ When the user is authenticated and `simple` is not set this returns something li ] ``` +NOTE: +`last_activity_at` is updated based on [project activity](../user/project/working_with_projects.md#view-project-activity) and [project events](events.md). `updated_at` is updated whenever the project record is changed in the database. + You can filter by [custom attributes](custom_attributes.md) with: ```plaintext @@ -308,7 +312,7 @@ 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. -Prerequisite: +Prerequisites: - To view [certain attributes](https://gitlab.com/gitlab-org/gitlab/-/blob/520776fa8e5a11b8275b7c597d75246fcfc74c89/lib/api/entities/project.rb#L109-130), you must be an administrator or have the Owner role for the project. @@ -413,6 +417,7 @@ GET /users/:user_id/projects "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, + "ci_restrict_pipeline_cancellation_role": "developer", "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -532,6 +537,7 @@ GET /users/:user_id/projects "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, + "ci_restrict_pipeline_cancellation_role": "developer", "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -1202,6 +1208,7 @@ GET /projects/:id "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, + "ci_restrict_pipeline_cancellation_role": "developer", "public_jobs": true, "shared_with_groups": [ { @@ -1471,7 +1478,8 @@ Refer to the [Events API documentation](events.md#list-a-projects-visible-events ## Create project -> `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0. +> - `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0. +> - `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7. Creates a new project owned by the authenticated user. @@ -1510,7 +1518,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `build_timeout` | integer | No | The maximum amount of time, in seconds, that a job can run. | | `builds_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `ci_config_path` | string | No | The path to CI configuration file. | -| `container_expiration_policy_attributes` | hash | No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). See the [Container Registry](../user/packages/container_registry/reduce_container_registry_storage.md#use-the-cleanup-policy-api) documentation for more information on `cadence`, `keep_n` and `older_than` values. | +| `container_expiration_policy_attributes` | hash | No | Update the image cleanup policy for this project. Accepts: `cadence` (string), `keep_n` (integer), `older_than` (string), `name_regex` (string), `name_regex_delete` (string), `name_regex_keep` (string), `enabled` (boolean). See the [container registry](../user/packages/container_registry/reduce_container_registry_storage.md#use-the-cleanup-policy-api) documentation for more information on `cadence`, `keep_n` and `older_than` values. | | `container_registry_access_level` | string | No | Set visibility of container registry, for this project, to one of `disabled`, `private` or `enabled`. | | `container_registry_enabled` | boolean | No | _(Deprecated)_ Enable container registry for this project. Use `container_registry_access_level` instead. | | `default_branch` | string | No | The [default branch](../user/project/repository/branches/default.md) name. Requires `initialize_with_readme` to be `true`. | @@ -1547,6 +1555,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `infrastructure_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `monitor_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `model_experiments_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | +| `model_registry_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `remove_source_branch_after_merge` | boolean | No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | No | Which storage shard the repository is on. _(administrator only)_ | @@ -1570,7 +1579,8 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ ## Create project for user -> `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0. +> - `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0. +> - `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7. Creates a new project owned by the specified user. Available only for administrators. @@ -1636,6 +1646,7 @@ POST /projects/user/:user_id | `infrastructure_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `monitor_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `model_experiments_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | +| `model_registry_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `remove_source_branch_after_merge` | boolean | No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | No | Which storage shard the repository is on. _(administrators only)_ | @@ -1661,7 +1672,8 @@ POST /projects/user/:user_id ## Edit project -> `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0. +> - `operations_access_level` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/385798) in GitLab 16.0. +> - `model_registry_access_level` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412734) in GitLab 16.7. Updates an existing project. @@ -1743,6 +1755,7 @@ Supported attributes: | `packages_enabled` | boolean | No | Enable or disable packages repository feature. | | `pages_access_level` | string | No | One of `disabled`, `private`, `enabled`, or `public`. | | `path` | string | No | Custom repository name for the project. By default generated based on name. | +| `prevent_merge_without_jira_issue` **(PREMIUM ALL)** | boolean | No | Set whether merge requests require an associated issue from Jira. | `printing_merge_request_link_enabled` | boolean | No | Show link to create/view merge request when pushing from the command line. | | `public_builds` | boolean | No | If `true`, jobs can be viewed by non-project members. | | `releases_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | @@ -1750,6 +1763,7 @@ Supported attributes: | `feature_flags_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `infrastructure_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `monitor_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | +| `model_registry_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `remove_source_branch_after_merge` | boolean | No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | No | Which storage shard the repository is on. _(administrators only)_ | @@ -2311,6 +2325,7 @@ Example response: "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, + "ci_restrict_pipeline_cancellation_role": "developer", "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -2443,6 +2458,7 @@ Example response: "ci_forward_deployment_rollback_allowed": true, "ci_allow_fork_pipelines_to_run_in_parent_project": true, "ci_separated_caches": true, + "ci_restrict_pipeline_cancellation_role": "developer", "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -2481,7 +2497,7 @@ This endpoint: merge requests). - In [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) and later, on [Premium or Ultimate](https://about.gitlab.com/pricing/) tiers, - [delayed project deletion](../user/project/settings/index.md#delayed-project-deletion) + [delayed project deletion](../user/project/working_with_projects.md#delayed-project-deletion) is applied if enabled. - From [GitLab 15.11](https://gitlab.com/gitlab-org/gitlab/-/issues/396500) on [Premium or Ultimate](https://about.gitlab.com/pricing/) tiers, deletes a project immediately if the project is already @@ -2913,6 +2929,7 @@ GET /projects/:id/push_rule "file_name_regex": "", "max_file_size": 5, "commit_committer_check": false, + "commit_committer_name_check": false, "reject_unsigned_commits": false } ``` @@ -2931,10 +2948,11 @@ POST /projects/:id/push_rule | `author_email_regex` | string | No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | No | All branch names must match this, for example `(feature|hotfix)\/*`. | | `commit_committer_check` | boolean | No | Users can only push commits to this repository if the committer email is one of their own verified emails. | +| `commit_committer_name_check` | boolean | No | Users can only push commits to this repository if the commit author name is consistent with their GitLab account name. | | `commit_message_negative_regex` | string | No | No commit message is allowed to match this, for example `ssh\:\/\/`. | | `commit_message_regex` | string | No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | No | Deny deleting a tag. | -| `file_name_regex` | string | No | All committed filenames must **not** match this, for example `(jar|exe)$`. | +| `file_name_regex` | string | No | All committed file names must **not** match this, for example `(jar|exe)$`. | | `max_file_size` | integer | No | Maximum file size (MB). | | `member_check` | boolean | No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | No | GitLab rejects any files that are likely to contain secrets. | @@ -2954,10 +2972,11 @@ PUT /projects/:id/push_rule | `author_email_regex` | string | No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | No | All branch names must match this, for example `(feature|hotfix)\/*`. | | `commit_committer_check` | boolean | No | Users can only push commits to this repository if the committer email is one of their own verified emails. | +| `commit_committer_name_check` | boolean | No | Users can only push commits to this repository if the commit author name is consistent with their GitLab account name. | | `commit_message_negative_regex` | string | No | No commit message is allowed to match this, for example `ssh\:\/\/`. | | `commit_message_regex` | string | No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | No | Deny deleting a tag. | -| `file_name_regex` | string | No | All committed filenames must **not** match this, for example `(jar|exe)$`. | +| `file_name_regex` | string | No | All committed file names must **not** match this, for example `(jar|exe)$`. | | `max_file_size` | integer | No | Maximum file size (MB). | | `member_check` | boolean | No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | No | GitLab rejects any files that are likely to contain secrets. | @@ -2967,8 +2986,7 @@ PUT /projects/:id/push_rule > Moved to GitLab Premium in 13.9. -Removes a push rule from a project. This method is idempotent and can be -called multiple times. Either the push rule is available or not. +Removes a push rule from a project. ```plaintext DELETE /projects/:id/push_rule @@ -3026,7 +3044,7 @@ Example response: > The `_links.cluster_agents` attribute in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347047) in GitLab 14.10. -See the [Project documentation](../user/project/settings/index.md#transfer-a-project-to-another-namespace) +See the [Project documentation](../user/project/settings/migrate_projects.md#transfer-a-project-to-another-namespace) for prerequisites to transfer a project. ```plaintext diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 93a1280f7df..3e5a1d6f64e 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected branches API **(FREE ALL)** diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 8b502d78d0d..272c3d1c12b 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected environments API **(PREMIUM ALL)** diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index b996a6a8098..fff2a3d82a4 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected tags API **(FREE ALL)** diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index c5d1c596cfd..cd4ebf32083 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Releases API **(FREE ALL)** diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 67d948604df..2e14869d213 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release links API **(FREE ALL)** diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index 4808c317dc4..01ffd082d59 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Project remote mirrors API **(FREE ALL)** diff --git a/doc/api/repositories.md b/doc/api/repositories.md index e17044f1c38..55df12c132f 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Repositories API **(FREE ALL)** diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index cc0b4ea1972..6e538683fa4 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Repository files API **(FREE ALL)** diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 7ed8e0bd33a..78ed4be7974 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository submodules API **(FREE ALL)** diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md index df4c01404c7..8f0e1ad2f24 100644 --- a/doc/api/resource_groups.md +++ b/doc/api/resource_groups.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource group API **(FREE ALL)** diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md index e31081be4dc..0e353a703e1 100644 --- a/doc/api/resource_iteration_events.md +++ b/doc/api/resource_iteration_events.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource iteration events API **(PREMIUM ALL)** diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index 316abb67920..7aa3e893387 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource label events API **(FREE ALL)** diff --git a/doc/api/resource_milestone_events.md b/doc/api/resource_milestone_events.md index 9ffb15a8e63..bc98ade1f87 100644 --- a/doc/api/resource_milestone_events.md +++ b/doc/api/resource_milestone_events.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource milestone events API **(FREE ALL)** diff --git a/doc/api/resource_state_events.md b/doc/api/resource_state_events.md index 366c70e5206..1c8f743ca72 100644 --- a/doc/api/resource_state_events.md +++ b/doc/api/resource_state_events.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource state events API **(FREE ALL)** diff --git a/doc/api/resource_weight_events.md b/doc/api/resource_weight_events.md index ff3c470cbdf..c6d7ecde667 100644 --- a/doc/api/resource_weight_events.md +++ b/doc/api/resource_weight_events.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource weight events API **(FREE ALL)** diff --git a/doc/api/rest/deprecations.md b/doc/api/rest/deprecations.md index 154945977b2..4afd01813e9 100644 --- a/doc/api/rest/deprecations.md +++ b/doc/api/rest/deprecations.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # REST API deprecations and removals diff --git a/doc/api/rest/index.md b/doc/api/rest/index.md index fd98952185b..76db6273399 100644 --- a/doc/api/rest/index.md +++ b/doc/api/rest/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # REST API **(FREE ALL)** @@ -347,13 +347,10 @@ The following table shows the possible return codes for API requests. ## Redirects -> Introduced in GitLab 16.4 [with a flag](../../user/feature_flags.md) named `api_redirect_moved_projects`. Disabled by default. - -FLAG: -On GitLab.com, this feature is not available. -On self-managed GitLab, by default this feature is not available. To make it available, -an administrator can [enable the feature flag](../../user/feature_flags.md) named `api_redirect_moved_projects`. +> - Introduced in GitLab 16.4 [with a flag](../../user/feature_flags.md) named `api_redirect_moved_projects`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137578) in GitLab 16.7. Feature flag `api_redirect_moved_projects` removed. +After [path changes](../../user/project/repository/index.md#what-happens-when-a-repository-path-changes) the REST API can respond with a redirect and users should be able to handle such responses. The users should follow the redirect and repeat the request to the URI specified in the `Location` header. @@ -377,7 +374,7 @@ This resource has been moved permanently to https://gitlab.example.com/api/v4/pr GitLab supports the following pagination methods: - Offset-based pagination. The default method and available on all endpoints except, - in GitLab 16.5 and later, the `\users` endpoint. + in GitLab 16.5 and later, the `users` endpoint. - Keyset-based pagination. Added to selected endpoints but being [progressively rolled out](https://gitlab.com/groups/gitlab-org/-/epics/2039). @@ -386,7 +383,7 @@ For large collections, you should use keyset pagination ### Offset-based pagination -> The `\users` endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/426547) for offset-based pagination in GitLab 16.5 and is planned for removal in 17.0. This change is a breaking change. Use keyset-based pagination for this endpoint instead. +> The `users` endpoint was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/426547) for offset-based pagination in GitLab 16.5 and is planned for removal in 17.0. This change is a breaking change. Use keyset-based pagination for this endpoint instead. Sometimes, the returned result spans many pages. When listing resources, you can pass the following parameters: @@ -842,6 +839,10 @@ For questions about these integrations, use the [GitLab community forum](https:/ - [Ruby wrapper and CLI for the GitLab REST API](https://github.com/NARKOZ/gitlab) +### Rust + +- [`gitlab` crate](https://crates.io/crates/gitlab) + ### Swift - [`RxGitLabKit`](https://github.com/Qase/RxGitLabKit) diff --git a/doc/api/runners.md b/doc/api/runners.md index 372ce397332..ac854a477d3 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -1,11 +1,13 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Runners API **(FREE ALL)** +This page describes endpoints for runners registered to an instance. To create a runner linked to the current user, see [Create a runner](users.md#create-a-runner-linked-to-a-user). + [Pagination](rest/index.md#pagination) is available on the following API endpoints (they return 20 items by default): ```plaintext @@ -23,7 +25,7 @@ There are two tokens to take into account when connecting a runner with GitLab. | Token | Description | | ----- | ----------- | | Registration token | Token used to [register the runner](https://docs.gitlab.com/runner/register/). It can be [obtained through GitLab](../ci/runners/index.md). | -| Authentication token | Token used to authenticate the runner with the GitLab instance. It is obtained automatically when you [register a runner](https://docs.gitlab.com/runner/register/) or by the Runner API when you manually [register a runner](#register-a-new-runner) or [reset the authentication token](#reset-runners-authentication-token-by-using-the-runner-id). You can also obtain the authentication token using [Create a runner](users.md#create-a-runner) API method. | +| Authentication token | Token used to authenticate the runner with the GitLab instance. It is obtained automatically when you [register a runner](https://docs.gitlab.com/runner/register/) or by the Runner API when you manually [register a runner](#create-an-instance-runner) or [reset the authentication token](#reset-runners-authentication-token-by-using-the-runner-id). You can also obtain the authentication token using [Create a runner](users.md#create-a-runner-linked-to-a-user) API method. | Here's an example of how the two tokens are used in runner registration: @@ -393,7 +395,6 @@ Example response: [ { "id": 2, - "ip_address": "127.0.0.1", "status": "running", "stage": "test", "name": "test", @@ -404,6 +405,7 @@ Example response: "started_at": "2017-11-16T08:51:29.000Z", "finished_at": "2017-11-16T08:53:29.000Z", "duration": 120, + "queued_duration": 2, "user": { "id": 1, "name": "John Doe2", @@ -652,9 +654,9 @@ Example response: ] ``` -## Register a new runner +## Create an instance runner -Register a new runner for the instance. +Create a runner for the instance. ```plaintext POST /runners diff --git a/doc/api/saml.md b/doc/api/saml.md index 5c6eee2b73c..548ac17e4e7 100644 --- a/doc/api/saml.md +++ b/doc/api/saml.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAML API **(PREMIUM ALL)** diff --git a/doc/api/scim.md b/doc/api/scim.md index f3be1a479a8..ea8284c4c4e 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SCIM API **(PREMIUM SAAS)** diff --git a/doc/api/search.md b/doc/api/search.md index 4a271d9ebdc..f452d7f0398 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -299,7 +299,7 @@ Example response: ``` NOTE: -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: commits **(PREMIUM ALL)** @@ -375,7 +375,7 @@ Example response: ``` NOTE: -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: notes **(PREMIUM ALL)** @@ -690,7 +690,7 @@ Example response: ``` NOTE: -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: `commits` **(PREMIUM ALL)** @@ -766,7 +766,7 @@ Example response: ``` NOTE: -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: `notes` **(PREMIUM ALL)** @@ -1071,12 +1071,12 @@ Filters are available for this scope: To use a filter, include it in your query. For example: `a query filename:some_name*`. You may use wildcards (`*`) to use glob matching. -Wiki blobs searches are performed on both filenames and contents. Search +Wiki blobs searches are performed on both file names and contents. Search results: -- Found in filenames are displayed before results found in contents. +- Found in file names are displayed before results found in contents. - May contain multiple matches for the same blob because the search string - might be found in both the filename and content, or might appear multiple + might be found in both the file name and content, or might appear multiple times in the content. ```shell @@ -1103,7 +1103,7 @@ Example response: ``` NOTE: -`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` are intended to be only the filename and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +`filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` is intended to be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). ### Scope: `commits` **(PREMIUM ALL)** @@ -1155,11 +1155,11 @@ Filters are available for this scope: To use a filter, include it in your query. For example: `a query filename:some_name*`. You may use wildcards (`*`) to use glob matching. -Blobs searches are performed on both filenames and contents. Search results: +Blobs searches are performed on both file names and contents. Search results: -- Found in filenames are displayed before results found in contents. +- Found in file names are displayed before results found in contents. - May contain multiple matches for the same blob because the search string - might be found in both the filename and content, or might appear multiple + might be found in both the file name and content, or might appear multiple times in the content. ```shell diff --git a/doc/api/secure_files.md b/doc/api/secure_files.md index b3d59127fe6..2e133522cb9 100644 --- a/doc/api/secure_files.md +++ b/doc/api/secure_files.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project-level Secure Files API **(FREE ALL)** @@ -128,7 +127,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------------|----------------|----------|-------------| | `project_id` | integer/string | Yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | -| `name` | string | Yes | The name of the file being uploaded. The filename must be unique in the project. | +| `name` | string | Yes | The name of the file being uploaded. The file name must be unique in the project. | | `file` | file | Yes | The file being uploaded (5 MB limit). | Example request: diff --git a/doc/api/settings.md b/doc/api/settings.md index 9c0a1e8e4a8..cf34cf3d65e 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application settings API **(FREE SELF)** @@ -21,6 +21,7 @@ For information on how to control the application settings cache for an instance > - `delayed_project_deletion` and `delayed_group_deletion` attributes removed in GitLab 16.0. > - `in_product_marketing_emails_enabled` attribute [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/418137) in GitLab 16.6. > - `repository_storages` attribute [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/429675) in GitLab 16.6. +> - `user_email_lookup_limit` attribute [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136886) in GitLab 16.7. List the current [application settings](#list-of-settings-that-can-be-accessed-via-api-calls) of the GitLab instance. @@ -124,7 +125,9 @@ Example response: "silent_mode_enabled": false, "package_registry_allow_anyone_to_pull_option": true, "bulk_import_max_download_file_size": 5120, - "project_jobs_api_rate_limit": 600 + "project_jobs_api_rate_limit": 600, + "security_txt_content": null, + "bulk_import_concurrent_pipeline_batch_limit": 25 } ``` @@ -160,6 +163,7 @@ these parameters: > - `always_perform_delayed_deletion` feature flag [enabled](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113332) in GitLab 15.11. > - `delayed_project_deletion` and `delayed_group_deletion` attributes removed in GitLab 16.0. +> - `user_email_lookup_limit` attribute [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136886) in GitLab 16.7. Use an API call to modify GitLab instance [application settings](#list-of-settings-that-can-be-accessed-via-api-calls). @@ -268,7 +272,9 @@ Example response: "security_policy_global_group_approvers_enabled": true, "package_registry_allow_anyone_to_pull_option": true, "bulk_import_max_download_file_size": 5120, - "project_jobs_api_rate_limit": 600 + "project_jobs_api_rate_limit": 600, + "security_txt_content": null, + "bulk_import_concurrent_pipeline_batch_limit": 25 } ``` @@ -343,7 +349,7 @@ listed in the descriptions of the relevant settings. | `container_registry_delete_tags_service_timeout` | integer | no | The maximum time, in seconds, that the cleanup process can take to delete a batch of tags for [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | | `container_registry_expiration_policies_caching` | boolean | no | Caching during the execution of [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | | `container_registry_expiration_policies_worker_capacity` | integer | no | Number of workers for [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). | -| `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | +| `container_registry_token_expire_delay` | integer | no | Container registry token duration in minutes. | | `package_registry_cleanup_policies_worker_capacity` | integer | no | Number of workers assigned to the packages cleanup policies. | | `updating_name_disabled_for_users` | boolean | no | [Disable user profile name changes](../administration/settings/account_and_limit_settings.md#disable-user-profile-name-changes). | | `allow_account_deletion` | boolean | no | Enable [users to delete their accounts](../administration/settings/account_and_limit_settings.md#prevent-users-from-deleting-their-accounts). | @@ -526,7 +532,6 @@ listed in the descriptions of the relevant settings. | `push_event_hooks_limit` | integer | no | Maximum number of changes (branches or tags) in a single push above which webhooks and integrations are not triggered. Setting to `0` does not disable throttling. | | `rate_limiting_response_text` | string | no | When rate limiting is enabled via the `throttle_*` settings, send this plain text response when a rate limit is exceeded. 'Retry later' is sent if this is blank. | | `raw_blob_request_limit` | integer | no | Maximum number of requests per minute for each raw path (default is `300`). Set to `0` to disable throttling.| -| `user_email_lookup_limit` | integer | no | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80631/)** in GitLab 14.9 will be removed in 15.0. Replaced by `search_rate_limit`. Max number of requests per minute for email lookup. Default: 60. To disable throttling set to 0.| | `search_rate_limit` | integer | no | Max number of requests per minute for performing a search while authenticated. Default: 30. To disable throttling set to 0.| | `search_rate_limit_unauthenticated` | integer | no | Max number of requests per minute for performing a search while unauthenticated. Default: 10. To disable throttling set to 0.| | `recaptcha_enabled` | boolean | no | (**If enabled, requires:** `recaptcha_private_key` and `recaptcha_site_key`) Enable reCAPTCHA. | @@ -543,6 +548,7 @@ listed in the descriptions of the relevant settings. | `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. | | `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes. | | `security_policy_global_group_approvers_enabled` | boolean | no | Whether to look up scan result policy approval groups globally or within project hierarchies. | +| `security_txt_content` | string | no | [Public security contact information](../administration/settings/security_contact_information.md). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/433210) in GitLab 16.7. | | `service_access_tokens_expiration_enforced` | boolean | no | Flag to indicate if token expiry date can be optional for service account users | | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | | `shared_runners_minutes` **(PREMIUM ALL)** | integer | required by: `shared_runners_enabled` | Set the maximum number of compute minutes that a group can use on shared runners per month. | @@ -617,6 +623,7 @@ listed in the descriptions of the relevant settings. | `valid_runner_registrars` | array of strings | no | List of types which are allowed to register a GitLab Runner. Can be `[]`, `['group']`, `['project']` or `['group', 'project']`. | | `whats_new_variant` | string | no | What's new variant, possible values: `all_tiers`, `current_tier`, and `disabled`. | | `wiki_page_max_content_bytes` | integer | no | Maximum wiki page content size in **bytes**. Default: 52428800 Bytes (50 MB). The minimum value is 1024 bytes. | +| `bulk_import_concurrent_pipeline_batch_limit` | integer | no | Maximum simultaneous Direct Transfer batches to process. | ### Configure inactive project deletion @@ -651,7 +658,7 @@ to be set, or _all_ of these values to be set: ::EndTabs -### Package Registry: Package file size limits +### Package registry: Package file size limits The package file size limits are not part of the Application settings API. Instead, these settings can be accessed using the [Plan limits API](plan_limits.md). diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index a6422d8545a..0f05359d431 100644 --- a/doc/api/sidekiq_metrics.md +++ b/doc/api/sidekiq_metrics.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq Metrics API **(FREE SELF)** diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md index 37bbe6bbf49..99e259589b8 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Snippet repository storage moves API **(FREE SELF)** diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 84b1baab6c4..a580a11ce27 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Snippets API **(FREE ALL)** diff --git a/doc/api/statistics.md b/doc/api/statistics.md index da94a5ce740..8868f6d5190 100644 --- a/doc/api/statistics.md +++ b/doc/api/statistics.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application statistics API **(FREE SELF)** diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md index 70a1acdb939..8ba037f7e68 100644 --- a/doc/api/status_checks.md +++ b/doc/api/status_checks.md @@ -1,8 +1,7 @@ --- stage: Govern group: Compliance -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # External Status Checks API **(ULTIMATE ALL)** diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md index 3dd3ef3712c..023c7505a73 100644 --- a/doc/api/suggestions.md +++ b/doc/api/suggestions.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Suggest Changes API **(FREE ALL)** diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 446c91d7971..8ee30fcb938 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # System hooks API **(FREE SELF)** @@ -10,8 +10,7 @@ All methods require administrator authorization. You can configure the URL endpoint of the system hooks from the GitLab user interface: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **System Hooks** (`/admin/hooks`). Read more about [system hooks](../administration/system_hooks.md). diff --git a/doc/api/tags.md b/doc/api/tags.md index cc4ff7be577..2b6e90c90bd 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tags API **(FREE ALL)** diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index 0f20d38d9e8..fa863f5db95 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dockerfiles API **(FREE ALL)** diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index d22b9373ccd..76a49e9c418 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # .gitignore API **(FREE ALL)** diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index d436e6385a9..96b2247600d 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI YAML API **(FREE ALL)** diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index fc9af40a963..08415660a88 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.md @@ -1,8 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Licenses API **(FREE ALL)** diff --git a/doc/api/todos.md b/doc/api/todos.md index a529839fd30..d17074a92e7 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab To-Do List API **(FREE ALL)** diff --git a/doc/api/topics.md b/doc/api/topics.md index 0c729a95fe5..d26f0d10d6b 100644 --- a/doc/api/topics.md +++ b/doc/api/topics.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Topics API **(FREE ALL)** diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md index a8e6c6ac205..41a9901665d 100644 --- a/doc/api/usage_data.md +++ b/doc/api/usage_data.md @@ -1,8 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Data API **(FREE SELF)** diff --git a/doc/api/users.md b/doc/api/users.md index cb9951a1c45..31fe6234ad2 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Users API **(FREE ALL)** @@ -136,6 +136,7 @@ GET /users?without_project_bots=true > - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6. > - The `scim_identities` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324247) in GitLab 16.1. > - The `auditors` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418023) in GitLab 16.2. +> - The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7. ```plaintext GET /users @@ -197,7 +198,8 @@ You can use all [parameters available for everyone](#for-non-administrator-users "current_sign_in_ip": "196.165.1.102", "last_sign_in_ip": "172.127.2.22", "namespace_id": 1, - "created_by": null + "created_by": null, + "email_reset_offered_at": null }, { "id": 2, @@ -235,7 +237,8 @@ You can use all [parameters available for everyone](#for-non-administrator-users "current_sign_in_ip": "10.165.1.102", "last_sign_in_ip": "172.127.2.22", "namespace_id": 2, - "created_by": null + "created_by": null, + "email_reset_offered_at": null } ] ``` @@ -380,6 +383,7 @@ Parameters: > - The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. > - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6. +> - The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7. ```plaintext GET /users/:id @@ -445,7 +449,8 @@ Example Responses: "trial": true, "sign_in_count": 1337, "namespace_id": 1, - "created_by": null + "created_by": null, + "email_reset_offered_at": null } ``` @@ -569,7 +574,7 @@ Parameters: | `skip_confirmation` | No | Skip confirmation - true or false (default) | | `skype` | No | Skype ID | | `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#change-the-color-theme) for more information) | -| `twitter` | No | Twitter account | +| `twitter` | No | X (formerly Twitter) account | | `discord` | No | Discord account | | `username` | Yes | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | @@ -620,7 +625,7 @@ Parameters: | `skip_reconfirmation` | No | Skip reconfirmation - true or false (default) | | `skype` | No | Skype ID | | `theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](../user/profile/preferences.md#change-the-color-theme) for more information) | -| `twitter` | No | Twitter account | +| `twitter` | No | X (formerly Twitter) account | | `discord` | No | Discord account | | `username` | No | Username | | `view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page | @@ -728,6 +733,7 @@ Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also se > - The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. > - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6. +> - The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7. ```plaintext GET /user @@ -783,6 +789,7 @@ Parameters: "last_sign_in_ip": "172.127.2.22", "namespace_id": 1, "created_by": null, + "email_reset_offered_at": null, "note": null } ``` @@ -903,6 +910,11 @@ Example response: } ``` +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see these +preferences if `code_suggestions_used_by_default` feature flag is disabled: + +- `code_suggestions` + Parameters: - **none** @@ -933,6 +945,12 @@ Parameters: | `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. | | `pass_user_identities_to_ci_jwt` | Yes | Flag indicating the user passes their external identities as CI information. This attribute does not contain enough information to identify or authorize the user in an external system. The attribute is internal to GitLab, and must not be passed to third-party services. For more information and examples, see [Token Payload](../ci/secrets/id_token_authentication.md#token-payload). | +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also can update these parameters: + +| Attribute | Required | Description | +|:---------------------------------|:---------|:---------------------------------------------------| +| `code_suggestions` | No | Flag indicating the user allows code suggestions. Argument is experimental and can be removed in the future without notice. In GitLab 16.8 and later, this attribute is ignored if `code_suggestions_used_by_default` feature flag is enabled. | + ## User follow ### Follow and unfollow users @@ -1704,7 +1722,7 @@ Parameters: ## Delete email for given user **(FREE SELF)** -Prerequisite: +Prerequisites: - You must be an administrator of a self-managed GitLab instance. @@ -2328,7 +2346,7 @@ Returns: - `403 Forbidden` if not authenticated as an administrator. - `404 User Not Found` if user cannot be found. -## Create a runner **(FREE ALL)** +## Create a runner linked to a user **(FREE ALL)** Creates a runner linked to the current user. diff --git a/doc/api/version.md b/doc/api/version.md index 14875f96589..12f7a23ac34 100644 --- a/doc/api/version.md +++ b/doc/api/version.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Version API **(FREE ALL)** diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index 5b6cb07897d..5dbde8e5dbf 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index dc5e5c5f509..52a92f695bd 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -1,12 +1,17 @@ --- stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerabilities API **(ULTIMATE ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. +> - `last_edited_at` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. +> - `start_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. +> - `updated_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. +> - `last_edited_by_id` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. +> - `due_date` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/268154) in GitLab 16.7. NOTE: The former Vulnerabilities API was renamed to Vulnerability Findings API @@ -60,14 +65,9 @@ Example response: "full_name": "gitlab-examples / security / security-reports" }, "author_id": 1, - "updated_by_id": null, - "last_edited_by_id": null, "closed_by_id": null, - "start_date": null, - "due_date": null, "created_at": "2019-10-13T15:08:40.219Z", "updated_at": "2019-10-13T15:09:40.382Z", - "last_edited_at": null, "closed_at": null } ``` @@ -110,14 +110,9 @@ Example response: "full_name": "gitlab-examples / security / security-reports" }, "author_id": 1, - "updated_by_id": null, - "last_edited_by_id": null, "closed_by_id": null, - "start_date": null, - "due_date": null, "created_at": "2019-10-13T15:08:40.219Z", "updated_at": "2019-10-13T15:09:40.382Z", - "last_edited_at": null, "closed_at": null } ``` @@ -160,14 +155,9 @@ Example response: "full_name": "gitlab-examples / security / security-reports" }, "author_id": 1, - "updated_by_id": null, - "last_edited_by_id": null, "closed_by_id": null, - "start_date": null, - "due_date": null, "created_at": "2019-10-13T15:08:40.219Z", "updated_at": "2019-10-13T15:09:40.382Z", - "last_edited_at": null, "closed_at": null } ``` @@ -210,14 +200,9 @@ Example response: "full_name": "gitlab-examples / security / security-reports" }, "author_id": 1, - "updated_by_id": null, - "last_edited_by_id": null, "closed_by_id": null, - "start_date": null, - "due_date": null, "created_at": "2019-10-13T15:08:40.219Z", "updated_at": "2019-10-13T15:09:40.382Z", - "last_edited_at": null, "closed_at": null } ``` @@ -260,14 +245,9 @@ Example response: "full_name": "gitlab-examples / security / security-reports" }, "author_id": 1, - "updated_by_id": null, - "last_edited_by_id": null, "closed_by_id": null, - "start_date": null, - "due_date": null, "created_at": "2019-10-13T15:08:40.219Z", "updated_at": "2019-10-13T15:09:40.382Z", - "last_edited_at": null, "closed_at": null } ``` diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 0886db257dd..3be1dccea29 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -1,7 +1,7 @@ --- stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability export API **(ULTIMATE ALL)** diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index d2960bf17a6..c84a1e87164 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -1,7 +1,7 @@ --- stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability Findings API **(ULTIMATE ALL)** diff --git a/doc/api/wikis.md b/doc/api/wikis.md index 0b61d92177f..fba68d6c832 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project wikis API **(FREE ALL)** diff --git a/doc/architecture/blueprints/_template.md b/doc/architecture/blueprints/_template.md index 18f88322906..8577054db83 100644 --- a/doc/architecture/blueprints/_template.md +++ b/doc/architecture/blueprints/_template.md @@ -13,7 +13,7 @@ Before you start: - Copy this file to a sub-directory and call it `index.md` for it to appear in the blueprint directory. -- Please remove comment blocks for sections you've filled in. +- Remove comment blocks for sections you've filled in. When your blueprint ready for review, all of these comment blocks should be removed. diff --git a/doc/architecture/blueprints/ai_gateway/index.md b/doc/architecture/blueprints/ai_gateway/index.md index 8c5a13d2e76..c09f8aaa621 100644 --- a/doc/architecture/blueprints/ai_gateway/index.md +++ b/doc/architecture/blueprints/ai_gateway/index.md @@ -77,19 +77,25 @@ secret redaction at this level of the stack as well as in GitLab-rails. #### Protocol -We're choosing to use a simple JSON API for the AI-gateway -service. This allows us to re-use a lot of what is already in place in -the current model-gateway. It also allows us to make the endpoints -version agnostic. We could have an API that expects only a rudimentary -envelope that can contain dynamic information. We should make sure -that we make these APIs compatible with multiple versions of GitLab, -or other clients that use the gateway through GitLab. **This means -that all client versions talk to the same API endpoint, the AI-gateway -needs to support this, but we don't need to support different -endpoints per version**. - -We also considered gRPC as a the protocol for communication between -GitLab instances, they differ on these items: +The communication between the AI-Gateway service and its clients (including the GitLab Rails application) shall use a JSON-based API. + +The AI-Gateway API shall expose single-purpose endpoints responsible for providing access to different AI features. [A later section](#single-purpose-endpoints) of this document provides detailed guidelines for building specific endpoints. + +The AI Gateway communication protocol shall only expect a rudimentary envelope that wraps all feature-specific dynamic information. The proposed architecture of the protocol allows the API endpoints to be version agnostic, and the AI-Gateway APIs compatible with multiple versions of GitLab(or other clients that use the gateway through GitLab). + + **This means +that all clients regardless of their versions use the same set of AI-Gateway API feature endpoints. The AI-gateway feature endpoints have to support different client versions, instead of creating multiple feature endpoints per different supported client versions**. + +We can however add a version to the path in case we do want to evolve +a certain endpoint. It's not expected that we'll need to do this +often, but having a version in the path keeps the option open. The +benefit of this is that individual GitLab milestone releases will +continue pointing to the endpoint version it was tested against at the +time of release, while allowing us to iterate quickly by introducing +new endpoint versions. + +We also considered gRPC as a protocol for communication between +GitLab instances, JSON API, and gRPC differ on these items: | gRPC | REST + JSON | |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| @@ -138,37 +144,80 @@ one of the prompt payloads is no longer supported by the AI gateway. It allows us to potentially avoid breaking features in older GitLab installations as the AI landscape changes. -#### Cross version compatibility - -When building single purpose endpoints, we should be mindful that -these endpoints will be used by different GitLab instances indirectly -by external clients. To achieve this, we have a very simple envelope -to provide information. It has to have a series of `prompt_components` -that contain information the AI-gateway can use to build prompts and -query the model of it selects. - -Each prompt component contains 3 elements: - -- `type`: This is the kind of information that is being presented in - `payload`. The AI-gateway should ignore any types it does not know - about. -- `payload`: The actual information that can be used by the AI-gateway - to build the payload that is going to go out to AI providers. The - payload will be different depending on the type, and the version of - the client providing the payload. This means that the AI-gateway - needs to consider all fields optional. -- `metadata`: Information about the client that built this part of the - prompt. This may, or may not be used by GitLab for - telemetry. Nothing inside this field should be required. - -The only component in there that is likely to change often is the +### The AI-Gateway API protocol + +It is important to build each single-purpose endpoint, in a version-agnostic way so it can be used by different GitLab instances (and indirectly by external clients). To achieve this goal: + +**The AI-Gateway protocol shall rely on a simple JSON envelope wrapping all feature-specific information.** The AI-Gateway protocol can be seen as a transport layer protocol from [the OSI model](https://en.wikipedia.org/wiki/OSI_model) (eg: TCP, UDP) which defines how to transport information between nodes, without being aware of what information is being transported. + +The AI-Gateway protocol does not specify which information received by single-purpose endpoint should be processed and in which way. Providing endpoint with the freedom to decide if they will use data coming from each protocol envelope or ignore it. + +The AI-Gateway protocol defines each request in the following way: + +1. Each single-purpose endpoint shall accept requests containing a single JSON object with a single key: `prompt_components`. +1. The `prompt_components` key shall contain an array of JSON envelopes that are built according to the following rules: + +Each JSON envelope contains 3 elements: + +1. `type`: A string identifier specifying a type of information that is being presented in the envelopes + `payload`. The AI-gateway single-purpose endpoint may ignore any types it does not know about. +1. `payload`: The actual information that can be used by the AI-Gateway single-purpose endpoint to send requests to 3rd party AI services providers. The data inside the `payload` element can differ depending on the `type`, and the version of + the client providing the `payload`. This means that the AI-Gateway + single-purpose endpoint must consider the structure and the type of data present inside the `payload` optional, and gracefully handle missing or malformed information. +1. `metadata`: This field contains information about a client that built this `prompt_components` envelope. Information from the `metadata` field may, or may not be used by GitLab for + telemetry. The same as with the `payload` all fields inside the `metadata` shall be considered optional. + +The only envelope field that is expected to likely change often is the `payload` one. There we need to make sure that all fields are -optional, and avoid renaming, removing or repurposing fields. +optional and avoid renaming, removing, or repurposing fields. -When this is needed, we need to build support for the old versions of -a field in the gateway, and keep them around for at least 2 major -versions of GitLab. For example, we could consider adding 2 versions -of a prompt to the `prompt_components` payload: +To document and validate the content of `payload` we can specify their +format using [JSON-schema](https://json-schema.org/). + +An example request according to the AI-Gateway component looks as follows: + +```json +{ + "prompt_components": [ + { + "type": "prompt", + "metadata": { + "source": "GitLab EE", + "version": "16.7.0-pre", + }, + "payload": { + "content": "...", + "params": { + "temperature": 0.2, + "maxOutputTokens": 1024 + }, + "model": "code-gecko", + "provider": "vertex-ai" + } + }, + { + "type": "editor_content", + "metadata": { + "source": "vscode", + "version": "1.1.1" + }, + "payload": { + "filename": "application.rb", + "before_cursor": "require 'active_record/railtie'", + "after_cursor": "\nrequire 'action_controller/railtie'", + "open_files": [ + { + "filename": "app/controllers/application_controller.rb", + "content": "class ApplicationController < ActionController::Base..." + } + ] + } + } + ] +} +``` + +Another example use case includes 2 versions of a prompt passed in the `prompt_components` payload. Where each version is tailored for different 3rd party AI model provider: ```json { @@ -177,7 +226,7 @@ of a prompt to the `prompt_components` payload: "type": "prompt", "metadata": { "source": "GitLab EE", - "version": "16.3", + "version": "16.7.0-pre", }, "payload": { "content": "You can fetch information about a resource called an issue...", @@ -193,7 +242,7 @@ of a prompt to the `prompt_components` payload: "type": "prompt", "metadata": { "source": "GitLab EE", - "version": "16.3", + "version": "16.7.0-pre", }, "payload": { "content": "System: You can fetch information about a resource called an issue...\n\nHuman:", @@ -209,18 +258,20 @@ of a prompt to the `prompt_components` payload: } ``` -Allowing the API to direct the prompt to either provider, based on -what is in the payload. +#### Cross-version compatibility -To document and validate the content of `payload` we can specify their -format using [JSON-schema](https://json-schema.org/). +**When renaming, removing, or repurposing fields inside `payload` is needed, a single-purpose endpoint that uses the affected envelope type must build support for the old versions of +a field in the gateway, and keep them around for at least 2 major +versions of GitLab.** + +A good practise that might help support backwards compatibility is to provide building blocks for the prompt inside the `prompt_components` rather then a complete prompt. By moving responsibility of compiling prompt out of building blocks on the AI-Gateway, one can achive more flexibility in terms of prompt adjustments in the future. #### Example feature: Code Suggestions For example, a rough Code Suggestions service could look like this: ```plaintext -POST /internal/code-suggestions/completions +POST /v3/code/completions ``` ```json @@ -230,7 +281,7 @@ POST /internal/code-suggestions/completions "type": "prompt", "metadata": { "source": "GitLab EE", - "version": "16.3", + "version": "16.7.0-pre", }, "payload": { "content": "...", diff --git a/doc/architecture/blueprints/capacity_planning/index.md b/doc/architecture/blueprints/capacity_planning/index.md index ed014f545f9..31740d50368 100644 --- a/doc/architecture/blueprints/capacity_planning/index.md +++ b/doc/architecture/blueprints/capacity_planning/index.md @@ -13,21 +13,27 @@ approvers: [ "@swiskow", "@rnienaber", "@o-lluch" ] ## Summary -This document outlines how we plan to set up infrastructure capacity planning for GitLab Dedicated tenant environments, which is a [FY24-Q3 OKR](https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/3507). +This document outlines how we plan to set up infrastructure capacity planning for GitLab Dedicated tenant environments, which started as a [FY24-Q3 OKR](https://gitlab.com/gitlab-com/gitlab-OKRs/-/work_items/3507). -We make use of Tamland, a tool we built to provide saturation forecasting insights for GitLab.com infrastructure resources. We propose to include Tamland as a part of the GitLab Dedicated stack and execute forecasting from within the tenant environments. +We make use of [Tamland](https://gitlab.com/gitlab-com/gl-infra/tamland), a tool we build to provide saturation forecasting insights for GitLab.com infrastructure resources. +We propose to include Tamland as a part of the GitLab Dedicated stack and execute forecasting from within the tenant environments. -Tamland predicts SLO violations and their respective dates, which need to be reviewed and acted upon. In terms of team organisation, the Dedicated team is proposed to own the tenant-side setup for Tamland and to own the predicted SLO violations, with the help and guidance of the Scalability::Projections team, which drives further development, documentation and overall guidance for capacity planning, including for Dedicated. +Tamland predicts SLO violations and their respective dates, which need to be reviewed and acted upon. +In terms of team organisation, the Dedicated team is proposed to own the tenant-side setup for Tamland and to own the predicted SLO violations, with the help and guidance of the Scalability::Projections team, which drives further development, documentation and overall guidance for capacity planning, including for Dedicated. -With this setup, we aim to turn Tamland into a more generic tool, which can be used in various environments including but not limited to Dedicated tenants. Long-term, we think of including Tamland in self-managed installations and think of Tamland as a candidate for open source release. +With this setup, we aim to turn Tamland into a more generic tool, which can be used in various environments including but not limited to Dedicated tenants. +Long-term, we think of including Tamland in self-managed installations and think of Tamland as a candidate for open source release. ## Motivation ### Background: Capacity planning for GitLab.com -[Tamland](https://gitlab.com/gitlab-com/gl-infra/tamland) is an infrastructure resource forecasting project owned by the [Scalability::Projections](https://about.gitlab.com/handbook/engineering/infrastructure/team/scalability/projections.html) group. It implements [capacity planning](https://about.gitlab.com/handbook/engineering/infrastructure/capacity-planning/) for GitLab.com, which is a [controlled activity covered by SOC 2](https://gitlab.com/gitlab-com/gl-security/security-assurance/security-compliance-commercial-and-dedicated/observation-management/-/issues/604). As of today, it is used exclusively for GitLab.com to predict upcoming SLO violations across hundreds of monitored infrastructure components. +[Tamland](https://gitlab.com/gitlab-com/gl-infra/tamland) is an infrastructure resource forecasting project owned by the [Scalability::Observability](https://about.gitlab.com/handbook/engineering/infrastructure/team/scalability/#scalabilityobservability) group. +It implements [capacity planning](https://about.gitlab.com/handbook/engineering/infrastructure/capacity-planning/) for GitLab.com, which is a [controlled activity covered by SOC 2](https://gitlab.com/gitlab-com/gl-security/security-assurance/security-compliance-commercial-and-dedicated/observation-management/-/issues/604). +As of today, it is used exclusively for GitLab.com to predict upcoming SLO violations across hundreds of monitored infrastructure components. -Tamland produces a [report](https://gitlab-com.gitlab.io/gl-infra/tamland/intro.html) (hosted on GitLab Pages) containing forecast plots, information around predicted violations and other information around the components monitored. Any predicted SLO violation result in a capacity warning issue being created in the [issue tracker for capacity planning](https://gitlab.com/gitlab-com/gl-infra/capacity-planning/-/boards/2816983) on GitLab.com. +Tamland produces a [report](https://gitlab-com.gitlab.io/gl-infra/tamland/intro.html) (hosted on GitLab Pages) containing forecast plots, information around predicted violations and other information around the components monitored. +Any predicted SLO violation result in a capacity warning issue being created in the [issue tracker for capacity planning](https://gitlab.com/gitlab-com/gl-infra/capacity-planning/-/boards/2816983) on GitLab.com. At present, Tamland is quite tailor made and specific for GitLab.com: @@ -36,21 +42,28 @@ At present, Tamland is quite tailor made and specific for GitLab.com: [Turning Tamland into a tool](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/1106) we can use more generically and making it independent of GitLab.com specifics is subject of ongoing work. -For illustration, we can see a saturation forecast plot below for the `disk_space` resource for a PostgreSQL service called `patroni-ci`. Within the 90 days forecast horizon, we predict a violation of the `soft` SLO (set at 85% saturation) and this resulted in the creation of a [capacity planning issue](https://gitlab.com/gitlab-com/gl-infra/capacity-planning/-/issues/1219) for further review and potential actions. At present, the Scalability::Projections group reviews those issues and engages with the respective DRI for the service in question to remedy a saturation concern. +For illustration, we can see a saturation forecast plot below for the `disk_space` resource for a PostgreSQL service called `patroni-ci`. +Within the 90 days forecast horizon, we predict a violation of the `soft` SLO (set at 85% saturation) and this resulted in the creation of a [capacity planning issue](https://gitlab.com/gitlab-com/gl-infra/capacity-planning/-/issues/1219) for further review and potential actions. +At present, the Scalability::Projections group reviews those issues and engages with the respective DRI for the service in question to remedy a saturation concern. <img src="images/image-20230911144743188.png" alt="image-20230911144743188" style="zoom:67%;" /> -For GitLab.com capacity planning, we operate Tamland from a scheduled CI pipeline with access to the central Thanos, which provides saturation and utilization metrics for GitLab.com. The CI pipeline produces the desired report, exposes it on GitLab Pages and also creates capacity planning issues. Scalability::Projections runs a capacity planning triage rotation which entails reviewing and prioritizing any open issues and their respective saturation concerns. +For GitLab.com capacity planning, we operate Tamland from a scheduled CI pipeline with access to the central Thanos, which provides saturation and utilization metrics for GitLab.com. +The CI pipeline produces the desired report, exposes it on GitLab Pages and also creates capacity planning issues. +Scalability::Projections runs a capacity planning triage rotation which entails reviewing and prioritizing any open issues and their respective saturation concerns. ### Problem Statement -With the number of [GitLab Dedicated](https://about.gitlab.com/dedicated/) deployments increasing, we need to establish capacity planning processes for Dedicated tenants. This is going to help us notice any pending resource constraints soon enough to be able to upgrade the infrastructure for a given tenant before the resource saturates and causes an incident. +With the number of [GitLab Dedicated](https://about.gitlab.com/dedicated/) deployments increasing, we need to establish capacity planning processes for Dedicated tenants. +This is going to help us notice any pending resource constraints soon enough to be able to upgrade the infrastructure for a given tenant before the resource saturates and causes an incident. -Each Dedicated tenant is an isolated GitLab environment, with a full set of metrics monitored. These metrics are standardized in the [metrics catalog](https://gitlab.com/gitlab-com/runbooks/-/blob/master/reference-architectures/get-hybrid/src/gitlab-metrics-config.libsonnet?ref_type=heads) and on top of these, we have defined saturation metrics along with respective SLOs. +Each Dedicated tenant is an isolated GitLab environment, with a full set of metrics monitored. +These metrics are standardized in the [metrics catalog](https://gitlab.com/gitlab-com/runbooks/-/blob/master/reference-architectures/get-hybrid/src/gitlab-metrics-config.libsonnet?ref_type=heads) and on top of these, we have defined saturation metrics along with respective SLOs. In order to provide capacity planning and forecasts for saturation metrics for each tenant, we'd like to get Tamland set up for GitLab Dedicated. -While Tamland is developed by the Scalability::Projections and this team also owns the capacity planning process for GitLab.com, they don't have access to any of the Dedicated infrastructure as we have strong isolation implemented for Dedicated environments. As such, the technical design choices are going to affect how those teams interact and vice versa. We include this consideration into this documentation as we think the organisational aspect is a crucial part of it. +While Tamland is developed by the Scalability::Projections and this team also owns the capacity planning process for GitLab.com, they don't have access to any of the Dedicated infrastructure as we have strong isolation implemented for Dedicated environments. +As such, the technical design choices are going to affect how those teams interact and vice versa. We include this consideration into this documentation as we think the organisational aspect is a crucial part of it. ### Key questions @@ -70,25 +83,34 @@ While Tamland is developed by the Scalability::Projections and this team also ow ##### Reporting -As of today, it's not quite clear yet how we'd like to consume forecasting data across tenants. In contrast to GitLab.com, we generate forecasts across a potentially large number of tenants. At this point, we suspect that we're more interested in an aggregate report across tenants rather than individual, very detailed saturation forecasts. As such, this is subject to refinement in a further iteration once we have the underlying data available and gathered practical insight in how we consume this information. +As of today, it's not quite clear yet how we'd like to consume forecasting data across tenants. +In contrast to GitLab.com, we generate forecasts across a potentially large number of tenants. +At this point, we suspect that we're more interested in an aggregate report across tenants rather than individual, very detailed saturation forecasts. +As such, this is subject to refinement in a further iteration once we have the underlying data available and gathered practical insight in how we consume this information. ##### Issue management -While each predicted SLO violation results in the creation of a GitLab issue, this may not be the right mode of raising awareness for Dedicated. Similar to the reporting side, this is subject to further discussion once we have data to look at. +While each predicted SLO violation results in the creation of a GitLab issue, this may not be the right mode of raising awareness for Dedicated. +Similar to the reporting side, this is subject to further discussion once we have data to look at. ##### Customizing forecasting models -Forecasting models can and should be tuned and informed with domain knowledge to produce accurate forecasts. This information is a part of the Tamland manifest. In the first iteration, we don't support per-tenant customization, but this can be added later. +Forecasting models can and should be tuned and informed with domain knowledge to produce accurate forecasts. +This information is a part of the Tamland manifest. +In the first iteration, we don't support per-tenant customization, but this can be added later. ## Proposed Design for Dedicated: A part of the Dedicated stack -Dedicated environments are fully isolated and run their own Prometheus instance to capture metrics, including saturation metrics. Tamland will run from each individual Dedicated tenant environment, consume metrics from Prometheus and store the resulting data in S3. From there, we consume forecast data and act on it. +Dedicated environments are fully isolated and run their own Prometheus instance to capture metrics, including saturation metrics. +Tamland will run from each individual Dedicated tenant environment, consume metrics from Prometheus and store the resulting data in S3. +From there, we consume forecast data and act on it.  ### Storage for output and cache -Any data Tamland relies on is stored in a S3 bucket. We use one bucket per tenant to clearly separate data between tenants. +Any data Tamland relies on is stored in a S3 bucket. +We use one bucket per tenant to clearly separate data between tenants. 1. Resulting forecast data and other outputs 1. Tamland's internal cache for Prometheus metrics data @@ -97,9 +119,11 @@ There is no need for a persistent state across Tamland runs aside from the S3 bu ### Benefits of executing inside tenant environments -Each Tamland run for a single environment (tenant) can take a few hours to execute. With the number of tenants expected to increase significantly, we need to consider scaling the execution environment for Tamland. +Each Tamland run for a single environment (tenant) can take a few hours to execute. +With the number of tenants expected to increase significantly, we need to consider scaling the execution environment for Tamland. -In this design, Tamland becomes a part of the Dedicated stack and a component of the individual tenant environment. As such, scaling the execution environment for Tamland is solved by design, because tenant forecasts execute inherently parallel in their respective environments. +In this design, Tamland becomes a part of the Dedicated stack and a component of the individual tenant environment. +As such, scaling the execution environment for Tamland is solved by design, because tenant forecasts execute inherently parallel in their respective environments. ### Distribution model: Docker @@ -107,15 +131,18 @@ Tamland is released as a Docker image, see [Tamland's README](https://gitlab.com ### Tamland manifest -The manifest contains information about which saturation metrics to forecast on (see this [manifest example](https://gitlab.com/gitlab-com/gl-infra/tamland/-/blob/62854e1afbc2ed3160a55a738ea587e0cf7f994f/saturation.json) for GitLab.com). This will be generated from the metrics catalog and will be the same for all tenants for starters. +The manifest contains information about which saturation metrics to forecast on (see this [manifest example](https://gitlab.com/gitlab-com/gl-infra/tamland/-/blob/62854e1afbc2ed3160a55a738ea587e0cf7f994f/saturation.json) for GitLab.com). +This will be generated from the metrics catalog and will be the same for all tenants for starters. -In order to generate the manifest from the metrics catalog, we setup dedicated GitLab project `tamland-dedicated` . On a regular basis, a scheduled pipeline grabs the metrics catalog, generates the JSON manifest from it and commits this to the project. +In order to generate the manifest from the metrics catalog, we setup dedicated GitLab project `tamland-dedicated`. +On a regular basis, a scheduled pipeline grabs the metrics catalog, generates the JSON manifest from it and commits this to the project. On the Dedicated tenants, we download the latest version of the committed JSON manifest from `tamland-dedicated` and use this as input to execute Tamland. ### Acting on forecast insights -When Tamland forecast data is available for a tenant, the Dedicated teams consume this data and act on it accordingly. The Scalability::Projections group is going to support and guide this process to get started and help interpret data, along with implementing Tamland features required to streamline this process for Dedicated in further iterations. +When Tamland forecast data is available for a tenant, the Dedicated teams consume this data and act on it accordingly. +The Scalability::Observability group is going to support and guide this process to get started and help interpret data, along with implementing Tamland features required to streamline this process for Dedicated in further iterations. ## Alternative Solution @@ -125,11 +152,14 @@ An alternative design, we don't consider an option at this point, is to setup Ta  -In this design, a central Prometheus/Thanos instance is needed to provide the metrics data for Tamland. Dedicated tenants use remote-write to push their Prometheus data to the central Thanos instance. +In this design, a central Prometheus/Thanos instance is needed to provide the metrics data for Tamland. +Dedicated tenants use remote-write to push their Prometheus data to the central Thanos instance. -Tamland is set up to run on a regular basis and consume metrics data from the single Thanos instance. It stores its results and cache in S3, similar to the other design. +Tamland is set up to run on a regular basis and consume metrics data from the single Thanos instance. +It stores its results and cache in S3, similar to the other design. -In order to execute forecasts regularly, we need to provide an execution environment to run Tamland in. With an increasing number of tenants, we'd need to scale up resources for this cluster. +In order to execute forecasts regularly, we need to provide an execution environment to run Tamland in. +With an increasing number of tenants, we'd need to scale up resources for this cluster. This design **has not been chosen** because of both technical and organisational concerns: diff --git a/doc/architecture/blueprints/cells/cells-feature-admin-area.md b/doc/architecture/blueprints/cells/cells-feature-admin-area.md deleted file mode 100644 index 3f23e56c3af..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-admin-area.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/admin-area.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/admin-area.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-agent-for-kubernetes.md b/doc/architecture/blueprints/cells/cells-feature-agent-for-kubernetes.md deleted file mode 100644 index 050b3a922b1..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-agent-for-kubernetes.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/agent-for-kubernetes.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/agent-for-kubernetes.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-backups.md b/doc/architecture/blueprints/cells/cells-feature-backups.md deleted file mode 100644 index a0c38171ce6..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-backups.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/backups.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/backups.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-ci-runners.md b/doc/architecture/blueprints/cells/cells-feature-ci-runners.md deleted file mode 100644 index a14f2a47237..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-ci-runners.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/ci-runners.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/ci-runners.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-container-registry.md b/doc/architecture/blueprints/cells/cells-feature-container-registry.md deleted file mode 100644 index d9ff6da7f62..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-container-registry.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/container-registry.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/container-registry.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-contributions-forks.md b/doc/architecture/blueprints/cells/cells-feature-contributions-forks.md deleted file mode 100644 index a87e4ba3391..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-contributions-forks.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/contributions-forks.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/contributions-forks.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-data-migration.md b/doc/architecture/blueprints/cells/cells-feature-data-migration.md deleted file mode 100644 index 5638bb29dc5..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-data-migration.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/data-migration.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/data-migration.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-database-sequences.md b/doc/architecture/blueprints/cells/cells-feature-database-sequences.md deleted file mode 100644 index 9b426ed80a4..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-database-sequences.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/database-sequences.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/database-sequences.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-explore.md b/doc/architecture/blueprints/cells/cells-feature-explore.md deleted file mode 100644 index 95924e3d1e8..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-explore.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/explore.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/explore.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-git-access.md b/doc/architecture/blueprints/cells/cells-feature-git-access.md deleted file mode 100644 index 18fc2b61b1f..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-git-access.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/git-access.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/git-access.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-gitlab-pages.md b/doc/architecture/blueprints/cells/cells-feature-gitlab-pages.md deleted file mode 100644 index 964423334c1..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-gitlab-pages.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/gitlab-pages.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/gitlab-pages.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-global-search.md b/doc/architecture/blueprints/cells/cells-feature-global-search.md deleted file mode 100644 index 0a2a89b2d45..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-global-search.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/global-search.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/global-search.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-graphql.md b/doc/architecture/blueprints/cells/cells-feature-graphql.md deleted file mode 100644 index 69ce2128484..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-graphql.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/graphql.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/graphql.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-organizations.md b/doc/architecture/blueprints/cells/cells-feature-organizations.md deleted file mode 100644 index 6b589307404..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-organizations.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/organizations.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/organizations.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-personal-access-tokens.md b/doc/architecture/blueprints/cells/cells-feature-personal-access-tokens.md deleted file mode 100644 index 115af11e3a6..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-personal-access-tokens.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/personal-access-tokens.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/personal-access-tokens.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-personal-namespaces.md b/doc/architecture/blueprints/cells/cells-feature-personal-namespaces.md deleted file mode 100644 index 6d5ec0c9dd6..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-personal-namespaces.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/personal-namespaces.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/personal-namespaces.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-router-endpoints-classification.md b/doc/architecture/blueprints/cells/cells-feature-router-endpoints-classification.md deleted file mode 100644 index 0143ac6ffd9..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-router-endpoints-classification.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/router-endpoints-classification.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/router-endpoints-classification.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-schema-changes.md b/doc/architecture/blueprints/cells/cells-feature-schema-changes.md deleted file mode 100644 index bf78a4eae41..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-schema-changes.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/schema-changes.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/schema-changes.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-secrets.md b/doc/architecture/blueprints/cells/cells-feature-secrets.md deleted file mode 100644 index 1c4c79d96fc..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-secrets.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/secrets.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/secrets.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-snippets.md b/doc/architecture/blueprints/cells/cells-feature-snippets.md deleted file mode 100644 index 2963bbdec2c..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-snippets.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/snippets.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/snippets.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-template.md b/doc/architecture/blueprints/cells/cells-feature-template.md deleted file mode 100644 index c75cc88f46c..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-template.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/template.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/template.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-uploads.md b/doc/architecture/blueprints/cells/cells-feature-uploads.md deleted file mode 100644 index eab7a8a4fcd..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-uploads.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/uploads.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/uploads.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-user-profile.md b/doc/architecture/blueprints/cells/cells-feature-user-profile.md deleted file mode 100644 index 73f312f3762..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-user-profile.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/user-profile.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/user-profile.md). diff --git a/doc/architecture/blueprints/cells/cells-feature-your-work.md b/doc/architecture/blueprints/cells/cells-feature-your-work.md deleted file mode 100644 index 344037f2a76..00000000000 --- a/doc/architecture/blueprints/cells/cells-feature-your-work.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'impacted_features/your-work.md' -remove_date: '2023-11-17' ---- - -This document was moved to [another location](impacted_features/your-work.md). diff --git a/doc/architecture/blueprints/cells/deployment-architecture.md b/doc/architecture/blueprints/cells/deployment-architecture.md index 57dabd447b4..1ec8461b138 100644 --- a/doc/architecture/blueprints/cells/deployment-architecture.md +++ b/doc/architecture/blueprints/cells/deployment-architecture.md @@ -96,7 +96,7 @@ The differences compared to [Initial Cells deployment](#3-initial-cells-deployme The differences compared to [Hybrid Cells deployment](#4-hybrid-cells-deployment---initial-complete-cells-architecture) are: -- The Routing Service is expanded to support [GitLab Pages](../../../user/project/pages/index.md) and [GitLab Container Registry](../../../user/packages/container_registry/index.md). +- The Routing Service is expanded to support [GitLab Pages](../../../user/project/pages/index.md) and [GitLab container registry](../../../user/packages/container_registry/index.md). - Each Cell has all services isolated. - It is allowed that some Cells will follow a [hybrid architecture](#4-hybrid-cells-deployment---initial-complete-cells-architecture). @@ -134,7 +134,7 @@ As per the architecture, the above services are required to be run Cell-local: | Service | | Uses | Migrate from cluster-wide to Cell | Description | | ------------------- | --------------- | ------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | **GitLab Pages** | GitLab-built | Routing Service, Rails API | No problem | Serving CI generated pages under `.gitlab.io` or custom domains | -| **GitLab Registry** | GitLab-built | Object Storage, PostgreSQL | Non-trivial data migration in case of split | Service to provide GitLab Container Registry | +| **GitLab Registry** | GitLab-built | Object Storage, PostgreSQL | Non-trivial data migration in case of split | Service to provide GitLab container registry | | **Gitaly Cluster** | GitLab-built | Disk storage, PostgreSQL | No problem: Built-in migration routines to balance Gitaly nodes | Gitaly holds Git repository data. Many Gitaly clusters can be configured in application. | | **Elasticsearch** | Managed service | Many nodes required by sharding | Time consuming: Rebuild cluster from scratch | Search across all projects | | **Object Storage** | Managed service | | Not straightforward: Rather hard to selectively migrate between buckets | Holds all user and CI uploaded files that is served by GitLab | diff --git a/doc/architecture/blueprints/cells/glossary.md b/doc/architecture/blueprints/cells/glossary.md deleted file mode 100644 index 69824663867..00000000000 --- a/doc/architecture/blueprints/cells/glossary.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'goals.md#glossary' -remove_date: '2023-11-24' ---- - -This document was moved to [another location](goals.md#glossary). diff --git a/doc/architecture/blueprints/cells/impact.md b/doc/architecture/blueprints/cells/impact.md deleted file mode 100644 index 1f77b9056be..00000000000 --- a/doc/architecture/blueprints/cells/impact.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-11-22' ---- - -This document was removed due to being outdated. -Go to [index page](index.md) for the most recent content. diff --git a/doc/architecture/blueprints/cells/impacted_features/container-registry.md b/doc/architecture/blueprints/cells/impacted_features/container-registry.md index ea15dd52d94..4c6ac36a2af 100644 --- a/doc/architecture/blueprints/cells/impacted_features/container-registry.md +++ b/doc/architecture/blueprints/cells/impacted_features/container-registry.md @@ -19,22 +19,22 @@ GitLab [Container Registry](../../../../user/packages/container_registry/index.m ## 1. Definition -GitLab Container Registry is a complex service requiring usage of PostgreSQL, Redis and Object Storage dependencies. -Right now there's undergoing work to introduce [Container Registry Metadata](../../container_registry_metadata_database/index.md) to optimize data storage and image retention policies of Container Registry. +GitLab container registry is a complex service requiring usage of PostgreSQL, Redis and Object Storage dependencies. +Right now there's undergoing work to introduce [Container Registry Metadata](../../container_registry_metadata_database/index.md) to optimize data storage and image retention policies of container registry. -GitLab Container Registry is serving as a container for stored data, but on its own does not authenticate `docker login`. +GitLab container registry is serving as a container for stored data, but on its own does not authenticate `docker login`. The `docker login` is executed with user credentials (can be `personal access token`) or CI build credentials (ephemeral `ci_builds.token`). Container Registry uses data deduplication. It means that the same blob (image layer) that is shared between many Projects is stored only once. Each layer is hashed by `sha256`. -The `docker login` does request a JWT time-limited authentication token that is signed by GitLab, but validated by Container Registry service. +The `docker login` does request a JWT time-limited authentication token that is signed by GitLab, but validated by container registry service. The JWT token does store all authorized scopes (`container repository images`) and operation types (`push` or `pull`). A single JWT authentication token can have many authorized scopes. -This allows Container Registry and client to mount existing blobs from other scopes. +This allows container registry and client to mount existing blobs from other scopes. GitLab responds only with authorized scopes. -Then it is up to GitLab Container Registry to validate if the given operation can be performed. +Then it is up to GitLab container registry to validate if the given operation can be performed. The GitLab.com pages are always scoped to a Project. Each Project can have many container registry images attached. @@ -88,24 +88,24 @@ curl \ ## 3. Proposal -### 3.1. Shard Container Registry separately to Cells architecture +### 3.1. Shard container registry separately to Cells architecture -Due to its extensive and in general highly scalable horizontal architecture it should be evaluated if the GitLab Container Registry should be run not in Cell, but in a Cluster and be scaled independently. +Due to its extensive and in general highly scalable horizontal architecture it should be evaluated if the GitLab container registry should be run not in Cell, but in a Cluster and be scaled independently. This might be easier, but would definitely not offer the same amount of data isolation. -### 3.2. Run Container Registry within a Cell +### 3.2. Run container registry within a Cell -It appears that except `/jwt/auth` which would likely have to be processed by Router (to decode `scope`) the Container Registry could be run as a local service of a Cell. +It appears that except `/jwt/auth` which would likely have to be processed by Router (to decode `scope`) the container registry could be run as a local service of a Cell. The actual data at least in case of GitLab.com is not forwarded via registry, but rather served directly from Object Storage / CDN. Its design encodes container repository image in a URL that is easily routable. -It appears that we could re-use the same stateless Router service in front of Container Registry to serve manifests and blobs redirect. +It appears that we could re-use the same stateless Router service in front of container registry to serve manifests and blobs redirect. The only downside is increased complexity of managing standalone registry for each Cell, but this might be desired approach. ## 4. Evaluation -There do not seem to be any theoretical problems with running GitLab Container Registry in a Cell. +There do not seem to be any theoretical problems with running GitLab container registry in a Cell. It seems that the service can be easily made routable to work well. The practical complexities are around managing a complex service from an infrastructure side. diff --git a/doc/architecture/blueprints/cells/index.md b/doc/architecture/blueprints/cells/index.md index c9a03830a4a..3b800a54781 100644 --- a/doc/architecture/blueprints/cells/index.md +++ b/doc/architecture/blueprints/cells/index.md @@ -4,7 +4,7 @@ creation-date: "2022-09-07" authors: [ "@ayufan", "@fzimmer", "@DylanGriffith", "@lohrc", "@tkuah" ] coach: "@ayufan" approvers: [ "@lohrc" ] -owning-stage: "~devops::enablement" +owning-stage: "~devops::data stores" participating-stages: [] --- @@ -85,9 +85,8 @@ In some cases, a table with an ambiguous usage has to be broken down. For example: `uploads` are used to store user avatars, as well as uploaded attachments for comments. It would be expected that `uploads` is split into `uploads` (describing Group/Project-level attachments) and `global_uploads` (describing, for example, user avatars). -Except for the initial 2-3 quarters this work is highly parallel. It is expected that **group::tenant scale** will help other teams to fix their feature set to work with Cells. -The first 2-3 quarters are required to define a general split of data and build the required tooling. +The first 2-3 quarters are required to define a general split of data, and build the required tooling and development guidelines. 1. **Instance-wide settings are shared across cluster.** @@ -97,17 +96,21 @@ The first 2-3 quarters are required to define a general split of data and build The purpose is to make `users` cluster-wide. +1. **User can create Organization.** + + The purpose is to create Organizations that are isolated from each other. + 1. **User can create Group.** ✓ ([demo](https://www.youtube.com/watch?v=LUyV0ncfdRs)) The purpose is to perform a targeted decomposition of `users` and `namespaces`, because `namespaces` will be stored locally in the Cell. -1. **User can create Project.** +1. **User can create Project.** ✓ ([demo](https://www.youtube.com/watch?v=Z-2W8MfDwuI)) The purpose is to perform a targeted decomposition of `users` and `projects`, because `projects` will be stored locally in the Cell. -1. **User can create Organization on Cell 2.** +1. **User can create Project with a README file** - The purpose is to create Organizations that are isolated from each other. + The purpose is to allow `users` to create README files in a project. 1. **User can change profile avatar that is shared in cluster.** @@ -141,6 +144,28 @@ The first 2-3 quarters are required to define a general split of data and build The purpose is to have many Organizations per Cell, but never have a single Organization spanning across many Cells. This is required to ensure that information shown within an Organization is isolated, and does not require fetching information from other Cells. +#### Dependencies + +We have identified the following dependencies between the essential workflows. + +```mermaid +flowchart TD + A[Create Organization] --> B[Create Group] + B --> C[Create Project] + L --> D[Create Issue] + E --> F[Push to Git repo] + E --> G[Create Merge Request] + E --> H[Create CI Pipeline] + G --> J[Merge when Pipeline Succeeds] + H --> J + J --> K[Issue gets closed by the reference in MR description] + D --> K + A --> L[Manage members] + B --> L + C --> L + L --> E[Create file in repository] +``` + ### 3. Additional workflows Some of these additional workflows might need to be supported, depending on the group decision. @@ -157,43 +182,7 @@ This list is not exhaustive of work needed to be done. ### 4. Routing layer -The routing layer is meant to offer a consistent user experience where all Cells are presented under a single domain (for example, `gitlab.com`), instead of having to navigate to separate domains. - -The user will be able to use `https://gitlab.com` to access Cell-enabled GitLab. -Depending on the URL access, it will be transparently proxied to the correct Cell that can serve this particular information. -For example: - -- All requests going to `https://gitlab.com/users/sign_in` are randomly distributed to all Cells. -- All requests going to `https://gitlab.com/gitlab-org/gitlab/-/tree/master` are always directed to Cell 5, for example. -- All requests going to `https://gitlab.com/my-username/my-project` are always directed to Cell 1. - -1. **Technology.** - - We decide what technology the routing service is written in. - The choice is dependent on the best performing language, and the expected way and place of deployment of the routing layer. - If it is required to make the service multi-cloud it might be required to deploy it to the CDN provider. - Then the service needs to be written using a technology compatible with the CDN provider. - -1. **Cell discovery.** - - The routing service needs to be able to discover and monitor the health of all Cells. - -1. **User can use single domain to interact with many Cells.** - - The routing service will intelligently route all requests to Cells based on the resource being - accessed versus the Cell containing the data. - -1. **Router endpoints classification.** - - The stateless routing service will fetch and cache information about endpoints from one of the Cells. - We need to implement a protocol that will allow us to accurately describe the incoming request (its fingerprint), so it can be classified by one of the Cells, and the results of that can be cached. - We also need to implement a mechanism for negative cache and cache eviction. - -1. **GraphQL and other ambiguous endpoints.** - - Most endpoints have a unique sharding key: the Organization, which directly or indirectly (via a Group or Project) can be used to classify endpoints. - Some endpoints are ambiguous in their usage (they don't encode the sharding key), or the sharding key is stored deep in the payload. - In these cases, we need to decide how to handle endpoints like `/api/graphql`. +See [Cells: Routing Service](routing-service.md). ### 5. Cell deployment @@ -268,49 +257,48 @@ Expectations: The delivered iterations will focus on solving particular steps of a given key work stream. It is expected that initial iterations will be rather slow, because they require substantially more changes to prepare the codebase for data split. -One iteration describes one quarter's worth of work. - -1. [Iteration 1](https://gitlab.com/groups/gitlab-org/-/epics/9667) - FY24Q1 - Complete +### [Iteration 1](https://gitlab.com/groups/gitlab-org/-/epics/9667) (FY24Q1) - - Data access layer: Initial Admin Area settings are shared across cluster. - - Essential workflows: Allow to share cluster-wide data with database-level data access layer +- Data access layer: Initial Admin Area settings are shared across cluster. +- Essential workflows: Allow to share cluster-wide data with database-level data access layer. -1. [Iteration 2](https://gitlab.com/groups/gitlab-org/-/epics/9813) - Expected delivery: 16.2 FY24Q2, Actual delivery: 16.4 FY24Q3 - Complete +### [Iteration 2](https://gitlab.com/groups/gitlab-org/-/epics/9813) (FY24Q2-FY24Q3) - - Essential workflows: User accounts are shared across cluster. - - Essential workflows: User can create Group. +- Essential workflows: User accounts are shared across cluster. +- Essential workflows: User can create Group. -1. [Iteration 3](https://gitlab.com/groups/gitlab-org/-/epics/10997) - Expected delivery: 16.7 FY24Q4 - In Progress +### [Iteration 3](https://gitlab.com/groups/gitlab-org/-/epics/10997) (FY24Q4-FY25Q1) - - Essential workflows: User can create Project. - - Routing: Technology. - - Routing: Cell discovery. +- Essential workflows: User can create Project. +- Routing: Technology. +- Routing: Cell discovery. -1. [Iteration 4](https://gitlab.com/groups/gitlab-org/-/epics/10998) - Expected delivery: 16.10 FY25Q1 - Planned +### [Iteration 4](https://gitlab.com/groups/gitlab-org/-/epics/10998) (FY25Q1-FY25Q2) - - Essential workflows: User can create Organization on Cell 2. - - Data access layer: Cluster-unique identifiers. - - Data access layer: Evaluate the efficiency of database-level access vs. API-oriented access layer. - - Data access layer: Data access layer. - - Routing: User can use single domain to interact with many Cells. - - Cell deployment: Extend GitLab Dedicated to support GCP. +- Essential workflows: User can create Organization on Cell 2. -1. Iteration 5..N - starting FY25Q1 +### Iteration 5..N - starting FY25Q3 - - Essential workflows: User can push to Git repository. - - Essential workflows: User can run CI pipeline. - - Essential workflows: Instance-wide settings are shared across cluster. - - Essential workflows: User can change profile avatar that is shared in cluster. - - Essential workflows: User can create issue. - - Essential workflows: User can create merge request, and merge it after it is green. - - Essential workflows: User can manage Group and Project members. - - Essential workflows: User can manage instance-wide runners. - - Essential workflows: User is part of Organization and can only see information from the Organization. - - Routing: Router endpoints classification. - - Routing: GraphQL and other ambiguous endpoints. - - Data access layer: Allow to share cluster-wide data with database-level data access layer. - - Data access layer: Cluster-wide deletions. - - Data access layer: Database migrations. +- Data access layer: Cluster-unique identifiers. +- Data access layer: Evaluate the efficiency of database-level access vs. API-oriented access layer. +- Data access layer: Data access layer. +- Routing: User can use single domain to interact with many Cells. +- Cell deployment: Extend GitLab Dedicated to support GCP. +- Essential workflows: User can create Project with a README file. +- Essential workflows: User can push to Git repository. +- Essential workflows: User can run CI pipeline. +- Essential workflows: Instance-wide settings are shared across cluster. +- Essential workflows: User can change profile avatar that is shared in cluster. +- Essential workflows: User can create issue. +- Essential workflows: User can create merge request, and merge it after it is green. +- Essential workflows: User can manage Group and Project members. +- Essential workflows: User can manage instance-wide runners. +- Essential workflows: User is part of Organization and can only see information from the Organization. +- Routing: Router endpoints classification. +- Routing: GraphQL and other ambiguous endpoints. +- Data access layer: Allow to share cluster-wide data with database-level data access layer. +- Data access layer: Cluster-wide deletions. +- Data access layer: Database migrations. ## Technical proposals @@ -318,7 +306,7 @@ The Cells architecture has long lasting implications to data processing, locatio This section links all different technical proposals that are being evaluated. - [Stateless Router That Uses a Cache to Pick Cell and Is Redirected When Wrong Cell Is Reached](proposal-stateless-router-with-buffering-requests.md) -- [Stateless Router That Uses a Cache to Pick Cell and pre-flight `/api/v4/cells/learn`](proposal-stateless-router-with-routes-learning.md) +- [Stateless Router That Uses a Cache to Pick Cell and pre-flight `/api/v4/internal/cells/learn`](proposal-stateless-router-with-routes-learning.md) ## Impacted features diff --git a/doc/architecture/blueprints/cells/proposal-stateless-router-with-routes-learning.md b/doc/architecture/blueprints/cells/proposal-stateless-router-with-routes-learning.md index 962f71673df..cdcb5b8b21f 100644 --- a/doc/architecture/blueprints/cells/proposal-stateless-router-with-routes-learning.md +++ b/doc/architecture/blueprints/cells/proposal-stateless-router-with-routes-learning.md @@ -35,7 +35,7 @@ Organization can only be on a single Cell. ## Differences The main difference between this proposal and one [with buffering requests](proposal-stateless-router-with-buffering-requests.md) -is that this proposal uses a pre-flight API request (`/api/v4/cells/learn`) to redirect the request body to the correct Cell. +is that this proposal uses a pre-flight API request (`/pi/v4/internal/cells/learn`) to redirect the request body to the correct Cell. This means that each request is sent exactly once to be processed, but the URI is used to decode which Cell it should be directed. ## Summary in diagrams @@ -157,11 +157,11 @@ graph TD; 1. The `application_settings` (and probably a few other instance level tables) are decomposed into `gitlab_admin` schema 1. A new column `routes.cell_id` is added to `routes` table 1. A new Router service exists to choose which cell to route a request to. -1. If a router receives a new request it will send `/api/v4/cells/learn?method=GET&path_info=/group-org/project` to learn which Cell can process it +1. If a router receives a new request it will send `/api/v4/internal/cells/learn?method=GET&path_info=/group-org/project` to learn which Cell can process it 1. A new concept will be introduced in GitLab called an organization 1. We require all existing endpoints to be routable by URI, or be fixed to a specific Cell for processing. This requires changing ambiguous endpoints like `/dashboard` to be scoped like `/organizations/my-organization/-/dashboard` 1. Endpoints like `/admin` would be routed always to the specific Cell, like `cell_0` -1. Each Cell can respond to `/api/v4/cells/learn` and classify each endpoint +1. Each Cell can respond to `/api/v4/internal/cells/learn` and classify each endpoint 1. Writes to `gitlab_users` and `gitlab_routes` are sent to a primary PostgreSQL server in our `US` region but reads can come from replicas in the same region. This will add latency for these writes but we expect they are infrequent relative to the rest of GitLab. ## Pre-flight request learning @@ -174,7 +174,7 @@ the routable path. GitLab Rails will decode `path_info` and match it to an existing endpoint and find a routable entity (like project). The router will treat this as short-lived cache information. -1. Prefix match: `/api/v4/cells/learn?method=GET&path_info=/gitlab-org/gitlab-test/-/issues` +1. Prefix match: `/api/v4/internal/cells/learn?method=GET&path_info=/gitlab-org/gitlab-test/-/issues` ```json { @@ -184,7 +184,7 @@ treat this as short-lived cache information. } ``` -1. Some endpoints might require an exact match: `/api/v4/cells/learn?method=GET&path_info=/-/profile` +1. Some endpoints might require an exact match: `/api/v4/internal/cells/learn?method=GET&path_info=/-/profile` ```json { @@ -283,7 +283,7 @@ keeping settings in sync for all cells. to aggregate information from many Cells. 1. All unknown routes are sent to the latest deployment which we assume to be `Cell US0`. This is required as newly added endpoints will be only decodable by latest cell. - Likely this is not a problem for the `/cells/learn` is it is lightweight + Likely this is not a problem for the `/internal/cells/learn` is it is lightweight to process and this should not cause a performance impact. ## Example database configuration @@ -361,7 +361,7 @@ this limitation. 1. User is in Europe so DNS resolves to the router in Europe 1. They request `/my-company/my-project` without the router cache, so the router chooses randomly `Cell EU1` -1. The `/cells/learn` is sent to `Cell EU1`, which responds that resource lives on `Cell EU0` +1. The `/internal/cells/learn` is sent to `Cell EU1`, which responds that resource lives on `Cell EU0` 1. `Cell EU0` returns the correct response 1. The router now caches and remembers any request paths matching `/my-company/*` should go to `Cell EU0` @@ -372,7 +372,7 @@ sequenceDiagram participant cell_eu0 as Cell EU0 participant cell_eu1 as Cell EU1 user->>router_eu: GET /my-company/my-project - router_eu->>cell_eu1: /api/v4/cells/learn?method=GET&path_info=/my-company/my-project + router_eu->>cell_eu1: /api/v4/internal/cells/learn?method=GET&path_info=/my-company/my-project cell_eu1->>router_eu: {path: "/my-company", cell: "cell_eu0", source: "routable"} router_eu->>cell_eu0: GET /my-company/my-project cell_eu0->>user: <h1>My Project... @@ -382,9 +382,9 @@ sequenceDiagram 1. User is in Europe so DNS resolves to the router in Europe 1. The router does not have `/my-company/*` cached yet so it chooses randomly `Cell EU1` -1. The `/cells/learn` is sent to `Cell EU1`, which responds that resource lives on `Cell EU0` +1. The `/internal/cells/learn` is sent to `Cell EU1`, which responds that resource lives on `Cell EU0` 1. `Cell EU0` redirects them through a login flow -1. User requests `/users/sign_in`, uses random Cell to run `/cells/learn` +1. User requests `/users/sign_in`, uses random Cell to run `/internal/cells/learn` 1. The `Cell EU1` responds with `cell_0` as a fixed route 1. User after login requests `/my-company/my-project` which is cached and stored in `Cell EU0` 1. `Cell EU0` returns the correct response @@ -396,12 +396,12 @@ sequenceDiagram participant cell_eu0 as Cell EU0 participant cell_eu1 as Cell EU1 user->>router_eu: GET /my-company/my-project - router_eu->>cell_eu1: /api/v4/cells/learn?method=GET&path_info=/my-company/my-project + router_eu->>cell_eu1: /api/v4/internal/cells/learn?method=GET&path_info=/my-company/my-project cell_eu1->>router_eu: {path: "/my-company", cell: "cell_eu0", source: "routable"} router_eu->>cell_eu0: GET /my-company/my-project cell_eu0->>user: 302 /users/sign_in?redirect=/my-company/my-project user->>router_eu: GET /users/sign_in?redirect=/my-company/my-project - router_eu->>cell_eu1: /api/v4/cells/learn?method=GET&path_info=/users/sign_in + router_eu->>cell_eu1: /api/v4/internal/cells/learn?method=GET&path_info=/users/sign_in cell_eu1->>router_eu: {path: "/users", cell: "cell_eu0", source: "fixed"} router_eu->>cell_eu0: GET /users/sign_in?redirect=/my-company/my-project cell_eu0-->>user: <h1>Sign in... @@ -445,7 +445,7 @@ sequenceDiagram participant cell_eu0 as Cell EU0 participant cell_us0 as Cell US0 user->>router_eu: GET /gitlab-org/gitlab - router_eu->>cell_eu0: /api/v4/cells/learn?method=GET&path_info=/gitlab-org/gitlab + router_eu->>cell_eu0: /api/v4/internal/cells/learn?method=GET&path_info=/gitlab-org/gitlab cell_eu0->>router_eu: {path: "/gitlab-org", cell: "cell_us0", source: "routable"} router_eu->>cell_us0: GET /gitlab-org/gitlab cell_us0->>user: <h1>GitLab.org... @@ -569,7 +569,7 @@ sequenceDiagram router_us->>cell_us1: GET / cell_us1->>user: 302 /dashboard user->>router_us: GET /dashboard - router_us->>cell_us1: /api/v4/cells/learn?method=GET&path_info=/dashboard + router_us->>cell_us1: /api/v4/internal/cells/learn?method=GET&path_info=/dashboard cell_us1->>router_us: {path: "/dashboard", cell: "cell_us0", source: "routable"} router_us->>cell_us0: GET /dashboard cell_us0->>user: <h1>Dashboard... diff --git a/doc/architecture/blueprints/cells/routing-service.md b/doc/architecture/blueprints/cells/routing-service.md new file mode 100644 index 00000000000..9efdbdf3f91 --- /dev/null +++ b/doc/architecture/blueprints/cells/routing-service.md @@ -0,0 +1,196 @@ +--- +stage: core platform +group: Tenant Scale +description: 'Cells: Routing Service' +--- + +# Cells: Routing Service + +This document describes design goals and architecture of Routing Service +used by Cells. To better understand where the Routing Service fits +into architecture take a look at [Deployment Architecture](deployment-architecture.md). + +## Goals + +The routing layer is meant to offer a consistent user experience where all Cells are presented under a single domain (for example, `gitlab.com`), instead of having to navigate to separate domains. + +The user will be able to use `https://gitlab.com` to access Cell-enabled GitLab. +Depending on the URL access, it will be transparently proxied to the correct Cell that can serve this particular information. +For example: + +- All requests going to `https://gitlab.com/users/sign_in` are randomly distributed to all Cells. +- All requests going to `https://gitlab.com/gitlab-org/gitlab/-/tree/master` are always directed to Cell 5, for example. +- All requests going to `https://gitlab.com/my-username/my-project` are always directed to Cell 1. + +1. **Technology.** + + We decide what technology the routing service is written in. + The choice is dependent on the best performing language, and the expected way and place of deployment of the routing layer. + If it is required to make the service multi-cloud it might be required to deploy it to the CDN provider. + Then the service needs to be written using a technology compatible with the CDN provider. + +1. **Cell discovery.** + + The routing service needs to be able to discover and monitor the health of all Cells. + +1. **User can use single domain to interact with many Cells.** + + The routing service will intelligently route all requests to Cells based on the resource being + accessed versus the Cell containing the data. + +1. **Router endpoints classification.** + + The stateless routing service will fetch and cache information about endpoints from one of the Cells. + We need to implement a protocol that will allow us to accurately describe the incoming request (its fingerprint), so it can be classified by one of the Cells, and the results of that can be cached. + We also need to implement a mechanism for negative cache and cache eviction. + +1. **GraphQL and other ambiguous endpoints.** + + Most endpoints have a unique sharding key: the Organization, which directly or indirectly (via a Group or Project) can be used to classify endpoints. + Some endpoints are ambiguous in their usage (they don't encode the sharding key), or the sharding key is stored deep in the payload. + In these cases, we need to decide how to handle endpoints like `/api/graphql`. + +1. **Small.** + + The Routing Service is configuration-driven and rules-driven, and does not implement any business logic. + The maximum size of the project source code in initial phase is 1_000 lines without tests. + The reason for the hard limit is to make the Routing Service to not have any special logic, + and could be rewritten into any technology in a matter of a few days. + +## Requirements + +| Requirement | Description | Priority | +|---------------|-------------------------------------------------------------------|----------| +| Discovery | needs to be able to discover and monitor the health of all Cells. | high | +| Security | only authorized cells can be routed to | high | +| Single domain | e.g. GitLab.com | high | +| Caching | can cache routing information for performance | high | +| [50 ms of increased latency](#low-latency) | | high | +| Path-based | can make routing decision based on path | high | +| Complexity | the routing service should be configuration-driven and small | high | +| Stateless | does not need database, Cells provide all routing information | medium | +| Secrets-based | can make routing decision based on secret (e.g. JWT) | medium | +| Observability | can use existing observability tooling | low | +| Self-managed | can be eventually used by [self-managed](goals.md#self-managed) | low | +| Regional | can route requests to different [regions](goals.md#regions) | low | + +### Low Latency + +The target latency for routing service **should be less than 50 _ms_**. + +Looking at the `urgency: high` request we don't have a lot of headroom on the p50. +Adding an extra 50 _ms_ allows us to still be in or SLO on the p95 level. + +There is 3 primary entry points for the application; [`web`](https://gitlab.com/gitlab-com/runbooks/-/blob/5d8248314b343bef15a4c021ac33978525f809e3/services/service-catalog.yml#L492-537), [`api`](https://gitlab.com/gitlab-com/runbooks/-/blob/5d8248314b343bef15a4c021ac33978525f809e3/services/service-catalog.yml#L18-62), and [`git`](https://gitlab.com/gitlab-com/runbooks/-/blob/5d8248314b343bef15a4c021ac33978525f809e3/services/service-catalog.yml#L589-638). +Each service is assigned a Service Level Indicator (SLI) based on latency using the [apdex](https://www.apdex.org/wp-content/uploads/2020/09/ApdexTechnicalSpecificationV11_000.pdf) standard. +The corresponding Service Level Objectives (SLOs) for these SLIs require low latencies for large amount of requests. +It's crucial to ensure that the addition of the routing layer in front of these services does not impact the SLIs. +The routing layer is a proxy for these services, and we lack a comprehensive SLI monitoring system for the entire request flow (including components like the Edge network and Load Balancers) we use the SLIs for `web`, `git`, and `api` as a target. + +The main SLI we use is the [rails requests](../../../development/application_slis/rails_request.md). +It has multiple `satisfied` targets (apdex) depending on the [request urgency](../../../development/application_slis/rails_request.md#how-to-adjust-the-urgency): + +| Urgency | Duration in ms | +|------------|----------------| +| `:high` | 250 _ms_ | +| `:medium` | 500 _ms_ | +| `:default` | 1000 _ms_ | +| `:low` | 5000 _ms_ | + +#### Analysis + +The way we calculate the headroom we have is by using the following: + +```math +\mathrm{Headroom}\ {ms} = \mathrm{Satisfied}\ {ms} - \mathrm{Duration}\ {ms} +``` + +**`web`**: + +| Target Duration | Percentile | Headroom | +|-----------------|------------|-----------| +| 5000 _ms_ | p99 | 4000 _ms_ | +| 5000 _ms_ | p95 | 4500 _ms_ | +| 5000 _ms_ | p90 | 4600 _ms_ | +| 5000 _ms_ | p50 | 4900 _ms_ | +| 1000 _ms_ | p99 | 500 _ms_ | +| 1000 _ms_ | p95 | 740 _ms_ | +| 1000 _ms_ | p90 | 840 _ms_ | +| 1000 _ms_ | p50 | 900 _ms_ | +| 500 _ms_ | p99 | 0 _ms_ | +| 500 _ms_ | p95 | 60 _ms_ | +| 500 _ms_ | p90 | 100 _ms_ | +| 500 _ms_ | p50 | 400 _ms_ | +| 250 _ms_ | p99 | 140 _ms_ | +| 250 _ms_ | p95 | 170 _ms_ | +| 250 _ms_ | p90 | 180 _ms_ | +| 250 _ms_ | p50 | 200 _ms_ | + +_Analysis was done in <https://gitlab.com/gitlab-org/gitlab/-/issues/432934#note_1667993089>_ + +**`api`**: + +| Target Duration | Percentile | Headroom | +|-----------------|------------|-----------| +| 5000 _ms_ | p99 | 3500 _ms_ | +| 5000 _ms_ | p95 | 4300 _ms_ | +| 5000 _ms_ | p90 | 4600 _ms_ | +| 5000 _ms_ | p50 | 4900 _ms_ | +| 1000 _ms_ | p99 | 440 _ms_ | +| 1000 _ms_ | p95 | 750 _ms_ | +| 1000 _ms_ | p90 | 830 _ms_ | +| 1000 _ms_ | p50 | 950 _ms_ | +| 500 _ms_ | p99 | 450 _ms_ | +| 500 _ms_ | p95 | 480 _ms_ | +| 500 _ms_ | p90 | 490 _ms_ | +| 500 _ms_ | p50 | 490 _ms_ | +| 250 _ms_ | p99 | 90 _ms_ | +| 250 _ms_ | p95 | 170 _ms_ | +| 250 _ms_ | p90 | 210 _ms_ | +| 250 _ms_ | p50 | 230 _ms_ | + +_Analysis was done in <https://gitlab.com/gitlab-org/gitlab/-/issues/432934#note_1669995479>_ + +**`git`**: + +| Target Duration | Percentile | Headroom | +|-----------------|------------|-----------| +| 5000 _ms_ | p99 | 3760 _ms_ | +| 5000 _ms_ | p95 | 4280 _ms_ | +| 5000 _ms_ | p90 | 4430 _ms_ | +| 5000 _ms_ | p50 | 4900 _ms_ | +| 1000 _ms_ | p99 | 500 _ms_ | +| 1000 _ms_ | p95 | 750 _ms_ | +| 1000 _ms_ | p90 | 800 _ms_ | +| 1000 _ms_ | p50 | 900 _ms_ | +| 500 _ms_ | p99 | 280 _ms_ | +| 500 _ms_ | p95 | 370 _ms_ | +| 500 _ms_ | p90 | 400 _ms_ | +| 500 _ms_ | p50 | 430 _ms_ | +| 250 _ms_ | p99 | 200 _ms_ | +| 250 _ms_ | p95 | 230 _ms_ | +| 250 _ms_ | p90 | 240 _ms_ | +| 250 _ms_ | p50 | 240 _ms_ | + +_Analysis was done in <https://gitlab.com/gitlab-org/gitlab/-/issues/432934#note_1671385680>_ + +## Non-Goals + +Not yet defined. + +## Proposal + +TBD + +## Technology + +TBD + +## Alternatives + +TBD + +## Links + +- [Cells - Routing: Technology](https://gitlab.com/groups/gitlab-org/-/epics/11002) +- [Classify endpoints](https://gitlab.com/gitlab-org/gitlab/-/issues/430330) diff --git a/doc/architecture/blueprints/ci_gcp_secrets_manager/index.md b/doc/architecture/blueprints/ci_gcp_secrets_manager/index.md new file mode 100644 index 00000000000..1dc529d767d --- /dev/null +++ b/doc/architecture/blueprints/ci_gcp_secrets_manager/index.md @@ -0,0 +1,107 @@ +--- +status: proposed +creation-date: "2023-11-29" +authors: [ "@alberts-gitlab" ] +coach: "@grzesiek" +approvers: [ "@jocelynjane", "@shampton" ] +owning-stage: "~devops::verify" +participating-stages: [] +--- + +<!-- Blueprints often contain forward-looking statements --> +<!-- vale gitlab.FutureTense = NO --> + +# Support GCP Secrets Manager for CI External Secrets + +## Summary + +This blueprint describes the architecture to add GCP Secrets Manager as one of the +sources for CI External Secrets. + +## Motivation + +GitLab CI allows users to pull secrets from external sources into GitLab CI jobs. +Prior to this, the supported secret managers are HashiCorp Vault and Azure Key Vault. +GCP Secrets Manager is another major secret manager product and there has been +multiple requests and feedback to add GCP Secrets Manager to the list of +supported secret managers. + +### Goals + +The goal of this feature is to allow GitLab CI users to use secrets stored in +GCP Secrets Manager in their CI jobs. + +### Non-Goals + +This feature does not cover the following: + +- Using secrets from GCP Secrets Manager in other GitLab workloads. +- Managing secrets in GCP Secrets Manager or other secret managers through GitLab. + +## Proposal + +This feature requires a tight integration between GCP Secrets Manager, GitLab Rails and GitLab Runner. + +The solution to this feature involves three main parts: + +1. Authentication with GCP Secrets Manager +1. CI configuration on GitLab Rails +1. Secrets access by GitLab Runner + +### Authentication with GCP Secrets Manager + +GCP Secrets Manager needs to authenticate secret access requests coming from GitLab Runner. +Since GitLab Runner can operate in many modes (GitLab.com SaaS runners, SaaS with self-managed runner, GitLab Self-Managed, etc), +there is no direct correlation between the Runner instance and any GCP identities that can have access to the secrets. + +To solve this, we would use OIDC and GCP's Workload Identity Federation mechanism to authorize the requests. + +CI jobs already have support for OIDC through CI variables containing ID tokens issued by the GitLab instance. +These ID tokens already carry `claim`s that describe the context of the CI job. +For example, it includes details such as `group_id`, `group_path`, `project_id`, and `project_path`. + +On the GCP side, Workload Identity Federation allows the use of OIDC to grant GCP IAM roles to the external identities +represented by the ID tokens. Through Workload Identity Federation, the GCP user can grant specific IAM roles to +specific principals identified through the OIDC `claim`. For example, a particular `group_id` claim can be given an IAM role +to access a particular set of secrets in GCP Secrets Manager. This would allow the GCP user to grant granular +access to the secrets in GCP Secrets Manager. + +### CI configuration on GitLab Rails + +GitLab Rails will be the interface where users configure the CI jobs. For the GCP Secrets Manager integration, +there needs to be additional configuration to specify GCP Secrets Manager as a source for external secrets as well as +GCP specific information in order to enable authentication between GitLab Runner and GCP Secrets Manager. + +The proposed CI keyword would be the following: + +```yaml +job_name: + id_tokens: + GCP_SM_ID_TOKEN: + aud: my-GCP-workload-identity-federation-audience + secrets: + DATABASE_PASSWORD: + gcp_sm: + name: my-project-secret # This is the name of the secret defined in GCP Secrets Manager + version: 1 # optional: default to `latest`. + token: GCP_SM_ID_TOKEN +``` + +In addition, GitLab Runner needs to know the following in order to perform the authentication and access the secret. +These should be included as CI variables in the job. + +- GCP Project Number `GCP_PROJECT_NUMBER` +- GCP Workload Federation Pool ID `GCP_WORKLOAD_FEDERATION_POOL_ID` +- GCP Workload Federation Provider ID `GCP_WORKLOAD_FEDERATION_PROVIDER_ID` + +### Secrets access by GitLab Runner + +Based on the job specification defined above, GitLab Runner needs to implement the following: + +1. OIDC authentication with GCP Secure Token Service to obtain an access token. +1. Secret access requests to GCP Secrets Manager to obtain the payload of the desired secret version. +1. Adding the secrets to the build. + +## Alternative Solutions + +N/A. diff --git a/doc/architecture/blueprints/ci_pipeline_components/index.md b/doc/architecture/blueprints/ci_pipeline_components/index.md index 9fdbf8cb70b..9a225c9cd97 100644 --- a/doc/architecture/blueprints/ci_pipeline_components/index.md +++ b/doc/architecture/blueprints/ci_pipeline_components/index.md @@ -17,8 +17,6 @@ This document covers the future plans for the CI/CD Catalog feature. For informa ## Summary -## Goals - The goal of the CI/CD pipeline components catalog is to make the reusing pipeline configurations easier and more efficient. Providing a way to discover, understand and learn how to reuse pipeline constructs allows for a @@ -107,7 +105,9 @@ identifying abstract concepts and are subject to changes as we refine the design - **Template** is a type of component that contains a snippet of CI/CD configuration that can be [included](../../../ci/yaml/includes.md) in a project's pipeline configuration. - **Publishing** is the act of listing a version of the resource (for example, a project release) on the Catalog. -## Definition of pipeline component +## CI component + +### Definition of component A pipeline component is a reusable single-purpose building block that abstracts away a single pipeline configuration unit. Components are used to compose a part or entire pipeline configuration. @@ -155,7 +155,7 @@ predictable. The predictability, determinism, referential transparency and making CI components predictable is still important for us, but we may be unable to achieve it early iterations. -## Structure of a component +### Structure of a component A pipeline component is identified by a unique address in the form `<fqdn>/<component-path>@<version>` containing: @@ -165,12 +165,12 @@ A pipeline component is identified by a unique address in the form `<fqdn>/<comp For example: `gitlab.com/gitlab-org/dast@1.0`. -### The FQDN +#### The FQDN Initially we support only component addresses that point to the same GitLab instance, meaning that the FQDN matches the GitLab host. -### The component path +#### The component path The directory identified by the component path must contain at least the component YAML and optionally a related `README.md` documentation file. @@ -189,7 +189,7 @@ a file `mydir/file.yml` in `gitlab-org/dast` project would be expanded to: gitlab.com/gitlab-org/dast/mydir/path/to/component@<CURRENT_SHA> ``` -The component YAML file follows the filename convention `<type>.yml` where component type is one of: +The component YAML file follows the file name convention `<type>.yml` where component type is one of: | Component type | Context | | -------------- | ------- | @@ -206,7 +206,7 @@ For example: A component YAML file: - Must have a **name** to be referenced to. -- Must specify its **type** in the filename, which defines how it can be used (raw configuration to be `include`d, child pipeline workflow, job step). +- Must specify its **type** in the file name, which defines how it can be used (raw configuration to be `include`d, child pipeline workflow, job step). - Must define its **content** based on the type. - Must specify **input parameters** that it accepts. Components should depend on input parameters for dynamic values and not environment variables. - Should be **validated statically** (for example: using JSON schema validators). @@ -226,7 +226,7 @@ spec: # content of the component ``` -### The component version +#### The component version The version of the component can be (in order of highest priority first): @@ -244,86 +244,37 @@ As we want to be able to reference any revisions (even those not released), a co When referencing a component by local path (for example `./path/to/component`), its version is implicit and matches the commit SHA of the current pipeline context. -## Components repository - -A components repository is a GitLab project/repository that exclusively hosts one or more pipeline components. - -A components repository can be a catalog resource. For a components repository it's highly recommended to set -an appropriate avatar and project description to improve discoverability in the catalog. - -Components repositories that are released in the catalog must have a `README.md` file at the root directory of the repository. -The `README.md` represents the documentation of the components repository, hence it's recommended -even when not listing the repository in the catalog. - -### Structure of a components repository - -A components repository can host one or more components. The author can decide whether to define a single component -per repository or include multiple cohesive components in the same repository. +### Note about future resource types -A components repository is identified by the project full path. - -Let's imagine we are developing a component that runs RSpec tests for a Rails app. We create a project -called `myorg/rails-rspec`. - -The following directory structure would support 1 component per repository: - -```plaintext -. -├── template.yml -├── README.md -└── .gitlab-ci.yml -``` - -The `.gitlab-ci.yml` is recommended for the project to ensure changes are verified accordingly. - -The component is now identified by the path `gitlab.com/myorg/rails-rspec` which also maps to the -project path. We expect a `template.yml` file and `README.md` to be located in the root directory of the repository. - -The following directory structure would support multiple components per repository: +In the future, to support multiple types of resources in the Catalog we could +require a file `catalog-resource.yml` to be defined in the root directory of the project: -```plaintext -. -├── .gitlab-ci.yml -├── README.md -├── unit/ -│ └── template.yml -├── integration/ -│ └── template.yml -└── feature/ - └── template.yml +```yaml +name: DAST +description: Scan a web endpoint to find vulnerabilities +category: security +tags: [dynamic analysis, security scanner] +type: components_repository ``` -In this example we are defining multiple test profiles that are executed with RSpec. -The user could choose to use one or more of these. - -Each of these components are identified by their path `gitlab.com/myorg/rails-rspec/unit`, `gitlab.com/myorg/rails-rspec/integration` -and `gitlab.com/myorg/rails-rspec/feature`. - -This directory structure could also support both strategies: +This file could also be used for indexing metadata about the content of the resource. +For example, users could list the components in the repository and we can index +further data for search purpose: -```plaintext -. -├── template.yml # myorg/rails-rspec -├── README.md -├── LICENSE -├── .gitlab-ci.yml -├── unit/ -│ └── template.yml # myorg/rails-rspec/unit -├── integration/ -│ └── template.yml # myorg/rails-rspec/integration -└── feature/ - └── template.yml # myorg/rails-rspec/feature +```yaml +name: DAST +description: Scan a web endpoint to find vulnerabilities +category: security +tags: [dynamic analysis, security scanner] +type: components_repository +metadata: + components: + - all-scans + - scan-x + - scan-y ``` -With the above structure we could have a top-level component that can be used as the -default component. For example, `myorg/rails-rspec` could run all the test profiles together. -However, more specific test profiles could be used separately (for example `myorg/rails-rspec/integration`). - -NOTE: -Nesting of components is not permitted. -This limitation encourages cohesion at project level and keeps complexity low. - -## `spec:inputs:` parameters +## Input parameters If the component takes any input parameters they must be specified according to the following schema: @@ -521,6 +472,85 @@ spec: # rest of the pipeline config ``` +## Components repository + +A components repository is a GitLab project/repository that exclusively hosts one or more pipeline components. + +A components repository can be a catalog resource. For a components repository it's highly recommended to set +an appropriate avatar and project description to improve discoverability in the catalog. + +Components repositories that are released in the catalog must have a `README.md` file at the root directory of the repository. +The `README.md` represents the documentation of the components repository, hence it's recommended +even when not listing the repository in the catalog. + +### Structure of a components repository + +A components repository can host one or more components. The author can decide whether to define a single component +per repository or include multiple cohesive components in the same repository. + +A components repository is identified by the project full path. + +Let's imagine we are developing a component that runs RSpec tests for a Rails app. We create a project +called `myorg/rails-rspec`. + +The following directory structure would support 1 component per repository: + +```plaintext +. +├── template.yml +├── README.md +└── .gitlab-ci.yml +``` + +The `.gitlab-ci.yml` is recommended for the project to ensure changes are verified accordingly. + +The component is now identified by the path `gitlab.com/myorg/rails-rspec` which also maps to the +project path. We expect a `template.yml` file and `README.md` to be located in the root directory of the repository. + +The following directory structure would support multiple components per repository: + +```plaintext +. +├── .gitlab-ci.yml +├── README.md +├── unit/ +│ └── template.yml +├── integration/ +│ └── template.yml +└── feature/ + └── template.yml +``` + +In this example we are defining multiple test profiles that are executed with RSpec. +The user could choose to use one or more of these. + +Each of these components are identified by their path `gitlab.com/myorg/rails-rspec/unit`, `gitlab.com/myorg/rails-rspec/integration` +and `gitlab.com/myorg/rails-rspec/feature`. + +This directory structure could also support both strategies: + +```plaintext +. +├── template.yml # myorg/rails-rspec +├── README.md +├── LICENSE +├── .gitlab-ci.yml +├── unit/ +│ └── template.yml # myorg/rails-rspec/unit +├── integration/ +│ └── template.yml # myorg/rails-rspec/integration +└── feature/ + └── template.yml # myorg/rails-rspec/feature +``` + +With the above structure we could have a top-level component that can be used as the +default component. For example, `myorg/rails-rspec` could run all the test profiles together. +However, more specific test profiles could be used separately (for example `myorg/rails-rspec/integration`). + +NOTE: +Nesting of components is not permitted. +This limitation encourages cohesion at project level and keeps complexity low. + ## CI Catalog The CI Catalog is an index of resources that users can leverage in CI/CD. It initially @@ -546,7 +576,7 @@ Once a project is marked as a "catalog resource" it can eventually be displayed We could create a database record when the setting is enabled and modify the record's state when the same is disabled. -## Catalog resource +### Catalog resource Upon publishing, a catalog resource should have at least following attributes: @@ -574,7 +604,7 @@ be listed in the catalog resource's page for various reasons: To list a catalog resource in the Catalog we first need to create a release for the project. -## Releasing new resource versions to the Catalog +### Releasing new resource versions to the Catalog The versions that will be published for the resource should be the project [releases](../../../user/project/releases/index.md). Creating project releases is an official @@ -610,36 +640,6 @@ For example: index the content of `spec:` section for CI components. See an [example of development workflow](dev_workflow.md) for a components repository. -## Note about future resource types - -In the future, to support multiple types of resources in the Catalog we could -require a file `catalog-resource.yml` to be defined in the root directory of the project: - -```yaml -name: DAST -description: Scan a web endpoint to find vulnerabilities -category: security -tags: [dynamic analysis, security scanner] -type: components_repository -``` - -This file could also be used for indexing metadata about the content of the resource. -For example, users could list the components in the repository and we can index -further data for search purpose: - -```yaml -name: DAST -description: Scan a web endpoint to find vulnerabilities -category: security -tags: [dynamic analysis, security scanner] -type: components_repository -metadata: - components: - - all-scans - - scan-x - - scan-y -``` - ## Implementation guidelines - Start with the smallest user base. Dogfood the feature for `gitlab-org` and diff --git a/doc/architecture/blueprints/clickhouse_usage/index.md b/doc/architecture/blueprints/clickhouse_usage/index.md index 3febb09f0bf..bbe4132f833 100644 --- a/doc/architecture/blueprints/clickhouse_usage/index.md +++ b/doc/architecture/blueprints/clickhouse_usage/index.md @@ -4,7 +4,7 @@ creation-date: "2023-02-02" authors: [ "@nhxnguyen" ] coach: "@grzesiek" approvers: [ "@dorrino", "@nhxnguyen" ] -owning-stage: "~devops::data_stores" +owning-stage: "~devops::data stores" participating-stages: ["~section::ops", "~section::dev"] --- diff --git a/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md b/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md index 5b82716cb21..fc35cc0dd50 100644 --- a/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md +++ b/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md @@ -124,7 +124,7 @@ application layers. This list is not exhaustive, but shows a general list of the - Web GraphQL: provide a flexible API interface, allowing the Web frontend to fetch only the data needed thereby reducing the amount of compute and data transfer - Web ActionCable: provide bi-directional connection to enable real-time features for Users visiting web interface - Web Feature Flags Unleash Backend: provide an Unleash-compatible Server that uses GitLab API -- Web Packages API: provide a REST API compatible with the packaging tools: Debian, Maven, Container Registry Proxy, etc. +- Web Packages API: provide a REST API compatible with the packaging tools: Debian, Maven, container registry proxy, etc. - Git nodes: all code required to authorize `git pull/push` over `SSH` or `HTTPS` - Sidekiq: run background jobs - Services/Models/DB: all code required to maintain our database structure, data validation, business logic, and policies models that needs to be shared with other components diff --git a/doc/architecture/blueprints/consolidating_groups_and_projects/index.md b/doc/architecture/blueprints/consolidating_groups_and_projects/index.md index 2e0b4d40e13..89e7f0a8a88 100644 --- a/doc/architecture/blueprints/consolidating_groups_and_projects/index.md +++ b/doc/architecture/blueprints/consolidating_groups_and_projects/index.md @@ -5,7 +5,7 @@ authors: [ "@alexpooley", "@ifarkas" ] coach: "@grzesiek" approvers: [ "@m_gill", "@mushakov" ] author-stage: "~devops::plan" -owning-stage: "~devops::data_stores" +owning-stage: "~devops::data stores" participating-stages: [] --- @@ -230,7 +230,7 @@ We should strive to do the code clean up as we move through the phases. However, The initial iteration will provide a framework to house features under `Namespaces`. Stage groups will eventually need to migrate their own features and functionality over to `Namespaces`. This may impact these features in unexpected ways. Therefore, to minimize UX debt and maintain product consistency, stage groups will have to consider several factors when migrating their features over to `Namespaces`: 1. **Conceptual model**: What are the current and future state conceptual models of these features ([see object modeling for designers](https://hpadkisson.medium.com/object-modeling-for-designers-an-introduction-7871bdcf8baf))? These should be documented in Pajamas (example: [merge requests](https://design.gitlab.com/objects/merge-request/)). -1. **Merge conflicts**: What inconsistencies are there across project, group, and administrator levels? How might these be addressed? For an example of how we rationalized this for labels, please see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338820). +1. **Merge conflicts**: What inconsistencies are there across project, group, and administrator levels? How might these be addressed? For an example of how we rationalized this for labels, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338820). 1. **Inheritance & information flow**: How is information inherited across our container hierarchy currently? How might this be impacted if complying with the new [inheritance behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/343316) framework? 1. **Settings**: Where can settings for this feature be found currently? How will these be impacted by `Namespaces`? 1. **Access**: Who can access this feature and is that impacted by the new container structure? Are there any role or privacy considerations? diff --git a/doc/architecture/blueprints/container_registry_metadata_database/index.md b/doc/architecture/blueprints/container_registry_metadata_database/index.md index c9f7f1c0d27..66beac6cdb7 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database/index.md @@ -10,19 +10,19 @@ participating-stages: [] <!-- vale gitlab.FutureTense = NO --> -# Container Registry Metadata Database +# Container registry metadata database -## Usage of the GitLab Container Registry +## Usage of the GitLab container registry -With the [Container Registry](https://gitlab.com/gitlab-org/container-registry) integrated into GitLab, every GitLab project can have its own space to store its Docker images. You can use the registry to build, push and share images using the Docker client, CI/CD or the GitLab API. +With the [container registry](https://gitlab.com/gitlab-org/container-registry) integrated into GitLab, every GitLab project can have its own space to store its Docker images. You can use the registry to build, push and share images using the Docker client, CI/CD or the GitLab API. -Each day on GitLab.com, between [150k and 200k images are pushed to the registry](https://app.periscopedata.com/app/gitlab/527857/Package-GitLab.com-Stage-Activity-Dashboard?widget=9620193&udv=0), generating about [700k API events](https://app.periscopedata.com/app/gitlab/527857/Package-GitLab.com-Stage-Activity-Dashboard?widget=7601761&udv=0). It's also worth noting that although some customers use other registry vendors, [more than 96% of instances](https://app.periscopedata.com/app/gitlab/527857/Package-GitLab.com-Stage-Activity-Dashboard?widget=9832282&udv=0) are using the GitLab Container Registry. +Each day on GitLab.com, between [150k and 200k images are pushed to the registry](https://app.periscopedata.com/app/gitlab/527857/Package-GitLab.com-Stage-Activity-Dashboard?widget=9620193&udv=0), generating about [700k API events](https://app.periscopedata.com/app/gitlab/527857/Package-GitLab.com-Stage-Activity-Dashboard?widget=7601761&udv=0). It's also worth noting that although some customers use other registry vendors, [more than 96% of instances](https://app.periscopedata.com/app/gitlab/527857/Package-GitLab.com-Stage-Activity-Dashboard?widget=9832282&udv=0) are using the GitLab container registry. -For GitLab.com and for GitLab customers, the Container Registry is a critical component to building and deploying software. +For GitLab.com and for GitLab customers, the container registry is a critical component to building and deploying software. ## Current Architecture -The Container Registry is a single [Go](https://go.dev/) application. Its only dependency is the storage backend on which images and metadata are stored. +The container registry is a single [Go](https://go.dev/) application. Its only dependency is the storage backend on which images and metadata are stored. ```mermaid graph LR @@ -30,7 +30,7 @@ graph LR R -- Write/read metadata --> B ``` -Client applications (for example, GitLab Rails and Docker CLI) interact with the Container Registry through its [HTTP API](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/gitlab/api.md). The most common operations are pushing and pulling images to/from the registry, which require a series of HTTP requests in a specific order. The request flow for these operations is detailed in the [Request flow](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/push-pull-request-flow.md). +Client applications (for example, GitLab Rails and Docker CLI) interact with the container registry through its [HTTP API](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/gitlab/api.md). The most common operations are pushing and pulling images to/from the registry, which require a series of HTTP requests in a specific order. The request flow for these operations is detailed in the [Request flow](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/push-pull-request-flow.md). The registry supports multiple [storage backends](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/configuration.md#storage), including Google Cloud Storage (GCS) which is used for the GitLab.com registry. In the storage backend, images are stored as blobs, deduplicated, and shared across repositories. These are then linked (like a symlink) to each repository that relies on them, giving them access to the central storage location. @@ -38,22 +38,22 @@ The name and hierarchy of repositories, as well as image manifests and tags are ### Clients -The Container Registry has two main clients: the GitLab Rails application and the Docker client/CLI. +The container registry has two main clients: the GitLab Rails application and the Docker client/CLI. #### Docker -The Docker client (`docker` CLI) interacts with the GitLab Container Registry mainly using the [login](https://docs.docker.com/engine/reference/commandline/login/), [push](https://docs.docker.com/engine/reference/commandline/push/) and [pull](https://docs.docker.com/engine/reference/commandline/pull/) commands. +The Docker client (`docker` CLI) interacts with the GitLab container registry mainly using the [login](https://docs.docker.com/engine/reference/commandline/login/), [push](https://docs.docker.com/engine/reference/commandline/push/) and [pull](https://docs.docker.com/engine/reference/commandline/pull/) commands. ##### Login and Authentication -GitLab Rails is the default token-based authentication provider for the GitLab Container Registry. +GitLab Rails is the default token-based authentication provider for the GitLab container registry. Once the registry receives a request sent by an unauthenticated Docker client, it will reply with `401 Unauthorized` and instruct the client to obtain a token from the GitLab Rails API. The Docker client will then request a Bearer token and embed it in the `Authorization` header of all requests. The registry is responsible for determining if the user is authentication/authorized to perform those requests based on the provided token. ```mermaid sequenceDiagram participant C as Docker client - participant R as GitLab Container Registry + participant R as GitLab container registry participant G as GitLab Rails C->>R: docker login gitlab.example.com @@ -65,7 +65,7 @@ sequenceDiagram Note right of C: Bearer token included in the Authorization header ``` -Please refer to the [Docker documentation](https://docs.docker.com/registry/spec/auth/token/) for more details. +For more details, refer to the [Docker documentation](https://docs.docker.com/registry/spec/auth/token/). ##### Push and Pull @@ -81,7 +81,7 @@ The single entrypoint for the registry is the [HTTP API](https://gitlab.com/gitl | Operation | UI | Background | Observations | | ------------------------------------------------------------ | ------------------ | ------------------------ | ------------------------------------------------------------ | -| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | **{check-circle}** Yes | **{check-circle}** Yes | Used globally to ensure that the registry supports the Docker Distribution V2 API, as well as for identifying whether GitLab Rails is talking to the GitLab Container Registry or a third-party one (used to toggle features only available in the former). | +| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | **{check-circle}** Yes | **{check-circle}** Yes | Used globally to ensure that the registry supports the Docker Distribution V2 API, as well as for identifying whether GitLab Rails is talking to the GitLab container registry or a third-party one (used to toggle features only available in the former). | | [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | **{check-circle}** Yes | **{check-circle}** Yes | Used to list and show tags in the UI. Used to list tags in the background for [cleanup policies](../../../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy) and [Geo replication](../../../administration/geo/replication/container_registry.md). | | [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | **{check-circle}** Yes | **{dotted-circle}** No | Used to get the digest of a manifest by tag. This is then used to pull the manifest and show the tag details in the UI. | | [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | **{check-circle}** Yes | **{dotted-circle}** No | Used to show the image size and the manifest digest in the tag details UI. | @@ -164,7 +164,7 @@ Although blobs are shared across repositories, manifest and tag metadata are sco #### GitLab.com -Due to scale, performance and isolation concerns, for GitLab.com the registry database will be on a separate dedicated PostgreSQL cluster. Please see [#93](https://gitlab.com/gitlab-org/container-registry/-/issues/93) and [GitLab-com/gl-infra/reliability#10109](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/10109) for additional context. +Due to scale, performance and isolation concerns, for GitLab.com the registry database will be on a separate dedicated PostgreSQL cluster. See [#93](https://gitlab.com/gitlab-org/container-registry/-/issues/93) and [GitLab-com/gl-infra/reliability#10109](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/10109) for additional context. The diagram below illustrates the architecture of the database cluster: @@ -208,7 +208,7 @@ for self-managed instances. Customers not able to upgrade to PostgreSQL 12 have with security backports and bug fixes. Apart from online garbage collection, the metadata database's availability unblocks the -implementation of many requested features for the GitLab Container Registry. These features are only +implementation of many requested features for the GitLab container registry. These features are only available for instances using the new version backed by the metadata database. ### Availability @@ -238,7 +238,7 @@ This is a list of all the registry HTTP API operations and how they depend on th | [Complete blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#put-blob-upload) | `PUT` | `/v2/<name>/blobs/uploads/<uuid>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | | [Cancel blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#canceling-an-upload) | `DELETE` | `/v2/<name>/blobs/uploads/<uuid>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | -`*` Please refer to the [list of interactions between registry and Rails](#from-gitlab-rails-to-registry) to know why and how. +`*` Refer to the [list of interactions between registry and Rails](#from-gitlab-rails-to-registry) to know why and how. #### Failure Scenarios @@ -294,29 +294,29 @@ Together, these resources should provide an adequate level of insight into the r #### Third-Party Container Registries -GitLab ships with the GitLab Container Registry by default, but it's also compatible with third-party registries, as long as they comply with the [Docker Distribution V2 Specification](https://docs.docker.com/registry/spec/api/), now superseded by the [Open Container Initiative (OCI) Image Specification](https://github.com/opencontainers/image-spec/blob/master/spec.md). +GitLab ships with the GitLab container registry by default, but it's also compatible with third-party registries, as long as they comply with the [Docker Distribution V2 Specification](https://docs.docker.com/registry/spec/api/), now superseded by the [Open Container Initiative (OCI) Image Specification](https://github.com/opencontainers/image-spec/blob/master/spec.md). So far, we have tried to maintain full compatibility with third-party registries when adding new features. For example, in 12.8, we introduced a new [tag delete feature](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23325) to delete a single tag without deleting the underlying manifest. Because this feature is not part of the Docker or OCI specifications, we have kept the previous behavior as a fallback option to maintain compatibility with third-party registries. -However, this will likely change in the future. Apart from online garbage collection, and as described in [challenges](#challenges), the metadata database will unblock the implementation of many requested features for the GitLab Container Registry in the mid/long term. Most of these features will only be available for instances using the GitLab Container Registry. They are not part of the Docker Distribution or OCI specifications, neither we will be able to provide a compatible fallback option. +However, this will likely change in the future. Apart from online garbage collection, and as described in [challenges](#challenges), the metadata database will unblock the implementation of many requested features for the GitLab container registry in the mid/long term. Most of these features will only be available for instances using the GitLab container registry. They are not part of the Docker Distribution or OCI specifications, neither we will be able to provide a compatible fallback option. -For this reason, any features that require the use of the GitLab Container Registry will be disabled if using a third-party registry, for as long as third-party registries continue to be supported. +For this reason, any features that require the use of the GitLab container registry will be disabled if using a third-party registry, for as long as third-party registries continue to be supported. #### Synchronizing Changes With GitLab Rails -Currently, the GitLab Rails and GitLab Container Registry releases and deployments have been fully independent, as we have not introduced any new API features or breaking changes, apart from the described tag delete feature. +Currently, the GitLab Rails and GitLab container registry releases and deployments have been fully independent, as we have not introduced any new API features or breaking changes, apart from the described tag delete feature. The registry will remain independent from GitLab Rails changes, but in the mid/long term, the implementation of new features or breaking changes will imply a corresponding change in GitLab Rails, so the latter will depend on a specific minimum version of the registry. For example, to track the size of each repository, we may extend the metadata database to store that information and then propagate it to GitLab Rails by extending the HTTP API that it consumes. In GitLab Rails, this new information would likely be stored in its database and processed to offer a new feature at the UI/API level. -This kind of changes will require a synchronization between the GitLab Rails and the GitLab Container Registry releases and deployments, as the former will depend on a specific version of the latter. +This kind of changes will require a synchronization between the GitLab Rails and the GitLab container registry releases and deployments, as the former will depend on a specific version of the latter. ##### Feature Toggling All GitLab Rails features dependent on a specific version of the registry should be guarded by validating the registry vendor and version. -This is already done to determine whether a tag should be deleted using the new tag delete feature (only available in the GitLab Container Registry v2.8.1+) or the old method. In this case, GitLab Rails sends an `OPTIONS` request to the registry tag route to determine whether the `DELETE` method is supported or not. +This is already done to determine whether a tag should be deleted using the new tag delete feature (only available in the GitLab container registry v2.8.1+) or the old method. In this case, GitLab Rails sends an `OPTIONS` request to the registry tag route to determine whether the `DELETE` method is supported or not. Alternatively, and as the universal long-term solution, we need to determine the registry vendor, version, and supported features (the last two are only applicable if the vendor is GitLab) and persist it in the GitLab Rails database. This information can then be used in real time to toggle features or fallback to alternative methods, if possible. The initial implementation of this approach was introduced as part of [#204839](https://gitlab.com/gitlab-org/gitlab/-/issues/204839). Currently, it's only used for metrics purposes. Further improvements are required to guarantee that the version information is kept up to date in self-managed instances, where the registry may be hot swapped. @@ -324,7 +324,7 @@ Alternatively, and as the universal long-term solution, we need to determine the As described above, feature toggling offers a last line of defense against desynchronized releases and deployments, ensuring that GitLab Rails remains functional in case the registry version that supports new features is not yet available. -However, the release and deployment of GitLab Rails and the GitLab Container Registry should be synchronized to avoid any delays. Contrary to GitLab Rails, the registry release and deployment are manual processes, so special attention must be paid by maintainers to ensure that the GitLab Rails changes are only released and deployed after the corresponding registry changes. +However, the release and deployment of GitLab Rails and the GitLab container registry should be synchronized to avoid any delays. Contrary to GitLab Rails, the registry release and deployment are manual processes, so special attention must be paid by maintainers to ensure that the GitLab Rails changes are only released and deployed after the corresponding registry changes. As a solution to strengthen this process, a file can be added to the GitLab Rails codebase, containing the minimum required version of the registry. This file should be updated with every change that depends on a specific version of the registry. It should also be considered when releasing and deploying GitLab Rails, ensuring that the pipeline only goes through once the specified minimum required registry version is deployed. diff --git a/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md b/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md index d91f2fdddbf..bfc5c4a7133 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md @@ -11,11 +11,11 @@ participating-stages: [] <!-- Blueprints often contain forward-looking statements --> <!-- vale gitlab.FutureTense = NO --> -# Container Registry Self-Managed Database Rollout +# Container registry self-managed database rollout ## Summary -The latest iteration of the [Container Registry](https://gitlab.com/gitlab-org/container-registry) +The latest iteration of the [container registry](https://gitlab.com/gitlab-org/container-registry) has been rearchitected to use a PostgreSQL database and deployed on GitLab.com. Now we must bring the advantages provided by the database to self-managed users. While the container registry retains the capacity to run without the new database, @@ -45,12 +45,12 @@ of the container registry for both GitLab.com and for self-managed users. - Progressively rollout the new dependency of a PostgreSQL database instance for the registry for charts and omnibus deployments. - Progressively rollout automation for the registry PostgreSQL database instance for charts and omnibus deployments. - Develop processes and tools that self-managed admins can use to migrate existing registry deployments to the metadata database. -- Develop processes and tools that self-managed admins can use spin up fresh installs of the Container Registry which use the metadata database. +- Develop processes and tools that self-managed admins can use spin up fresh installs of the container registry which use the metadata database. - Create a plan which will eventually allow us to fully drop support for original object storage metadata subsystem. ### Non-Goals -- Developing new Container Registry features outside the scope of enabling admins to migrate to the metadata database. +- Developing new container registry features outside the scope of enabling admins to migrate to the metadata database. - Determining lifecycle support decisions, such as when to default to the database, and when to end support for non-database registries. ## Proposal @@ -88,7 +88,7 @@ The metadata database is in early beta for self-managed users. The core migratio process for existing registries has been implemented, and online garbage collection is fully implemented. Certain database enabled features are only enabled for GitLab.com and automatic database provisioning for the registry database is not available. -Please see the table below for the status of features related to the container +See the table below for the status of features related to the container registry database. | Feature | Description | Status | Link | @@ -161,7 +161,7 @@ import which would lead to greater consistency across all storage driver impleme ### The Import Tool The [import tool](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/database-import-tool.md) -is a well-validated component of the Container Registry project that we have used +is a well-validated component of the container registry project that we have used from the beginning as a way to perform local testing. This tool is a thin wrapper over the core import functionality — the code which handles the import logic has been extensively validated. diff --git a/doc/architecture/blueprints/database/automated_query_analysis/index.md b/doc/architecture/blueprints/database/automated_query_analysis/index.md index 40f6b2af412..cf136d7650e 100644 --- a/doc/architecture/blueprints/database/automated_query_analysis/index.md +++ b/doc/architecture/blueprints/database/automated_query_analysis/index.md @@ -4,7 +4,7 @@ creation-date: "2023-02-08" authors: [ "@mattkasa", "@jon_jenkins" ] coach: "@DylanGriffith" approvers: [ "@rogerwoo", "@alexives" ] -owning-stage: "~devops::data_stores" +owning-stage: "~devops::data stores" participating-stages: [] --- diff --git a/doc/architecture/blueprints/database/scalability/patterns/index.md b/doc/architecture/blueprints/database/scalability/patterns/index.md index d28734ce511..88f6914b01b 100644 --- a/doc/architecture/blueprints/database/scalability/patterns/index.md +++ b/doc/architecture/blueprints/database/scalability/patterns/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to scale the database through the use of best-of-class database scalability patterns' --- diff --git a/doc/architecture/blueprints/database/scalability/patterns/read_mostly.md b/doc/architecture/blueprints/database/scalability/patterns/read_mostly.md index 3a3fd2f33c2..562b62e1e44 100644 --- a/doc/architecture/blueprints/database/scalability/patterns/read_mostly.md +++ b/doc/architecture/blueprints/database/scalability/patterns/read_mostly.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to scale operating on read-mostly data at scale' --- diff --git a/doc/architecture/blueprints/database/scalability/patterns/time_decay.md b/doc/architecture/blueprints/database/scalability/patterns/time_decay.md index 24fc3f45717..a2fbcf35a01 100644 --- a/doc/architecture/blueprints/database/scalability/patterns/time_decay.md +++ b/doc/architecture/blueprints/database/scalability/patterns/time_decay.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to operate on large time-decay data' --- diff --git a/doc/architecture/blueprints/database_testing/index.md b/doc/architecture/blueprints/database_testing/index.md index 79560dd3959..8ad940d3e86 100644 --- a/doc/architecture/blueprints/database_testing/index.md +++ b/doc/architecture/blueprints/database_testing/index.md @@ -4,7 +4,7 @@ creation-date: "2021-02-08" authors: [ "@abrandl" ] coach: "@glopezfernandez" approvers: [ "@fabian", "@craig-gomes" ] -owning-stage: "~devops::data_stores" +owning-stage: "~devops::data stores" participating-stages: [] --- diff --git a/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md b/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md index 2bd121a34bb..f3335a0935e 100644 --- a/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md +++ b/doc/architecture/blueprints/gitaly_adaptive_concurrency_limit/index.md @@ -97,8 +97,8 @@ constraints and distinguishing features, including cgroup utilization and upload-pack RPC, among others. The proposed solution does not aim to replace the existing limits in Gitaly -for [RPC concurrency](../../../administration/gitaly/configure_gitaly.md#limit-rpc-concurrency) -and [pack object concurrency](../../../administration/gitaly/configure_gitaly.md#limit-pack-objects-concurrency), +for [RPC concurrency](../../../administration/gitaly/concurrency_limiting.md#limit-rpc-concurrency) +and [pack object concurrency](../../../administration/gitaly/concurrency_limiting.md#limit-pack-objects-concurrency), but automatically tweak the parameters. This means that other aspects, such as queuing, in-queue timeout, queue length, partitioning, and scoping, will remain unchanged. The proposed solution only diff --git a/doc/architecture/blueprints/gitaly_handle_upload_pack_in_http2_server/index.md b/doc/architecture/blueprints/gitaly_handle_upload_pack_in_http2_server/index.md index acee83b2649..897f9f97365 100644 --- a/doc/architecture/blueprints/gitaly_handle_upload_pack_in_http2_server/index.md +++ b/doc/architecture/blueprints/gitaly_handle_upload_pack_in_http2_server/index.md @@ -28,7 +28,7 @@ provided. We are looking for a solution that won't require us to completely rewr ### How Git data transfer works -Please skip this part if you are familiar with how Git data transfer architecture at GitLab. +Skip this part if you are familiar with how Git data transfer architecture at GitLab. Git data transfer is undeniably one of the crucial services that a Git server can offer. It is a fundamental feature of Git that was originally developed for Linux kernel development. As Git gained popularity, it continued to be recognized as a distributed system. However, the emergence of centralized Git services like GitHub or diff --git a/doc/architecture/blueprints/gitlab_services/img/architecture.png b/doc/architecture/blueprints/gitlab_services/img/architecture.png Binary files differindex 8ec0852e12b..3bcc18f1264 100644 --- a/doc/architecture/blueprints/gitlab_services/img/architecture.png +++ b/doc/architecture/blueprints/gitlab_services/img/architecture.png diff --git a/doc/architecture/blueprints/gitlab_services/index.md b/doc/architecture/blueprints/gitlab_services/index.md index c2f1d08a984..8acdae9f29e 100644 --- a/doc/architecture/blueprints/gitlab_services/index.md +++ b/doc/architecture/blueprints/gitlab_services/index.md @@ -22,15 +22,15 @@ As GitLab works towards providing a single platform for the whole DevSecOps cycl its offering should not stop at pipelines, but should include the deployment and release management, as well as observability of user-developed and third party applications. -While GitLab offers some concepts, like the `environment` syntax in GitLab pipelines, -it does not offer any concept on what is running in a given environment. While the environment might answer the "where" is +While GitLab offers some concepts, like the `environment` syntax in GitLab pipelines, +it does not offer any concept on what is running in a given environment. While the environment might answer the "where" is something running, it does not answer the question of "what" is running there. We should -introduce [service](https://about.gitlab.com/direction/delivery/glossary.html#service) and [release artifact](https://about.gitlab.com/direction/delivery/glossary.html#release) to answer this question. The [Delivery glossary](https://about.gitlab.com/direction/delivery/glossary.html#service) defines +introduce [service](https://about.gitlab.com/direction/delivery/glossary.html#service) and [release artifact](https://about.gitlab.com/direction/delivery/glossary.html#release) to answer this question. The [Delivery glossary](https://about.gitlab.com/direction/delivery/glossary.html#service) defines a service as > a logical concept that is a (mostly) independently deployable part of an application that is loosely coupled with other services to serve specific functionalities for the application. -A service would connect to the SCM, registry or issues through release artifacts and would be a focused view into the [environments](https://about.gitlab.com/direction/delivery/glossary.html#environment) where +A service would connect to the SCM, registry or issues through release artifacts and would be a focused view into the [environments](https://about.gitlab.com/direction/delivery/glossary.html#environment) where a specific version of the given release artifact is deployed (or being deployed). Having a concept of services allows our users to track their applications in production, not only in CI/CD pipelines. This opens up possibilities, like cost management. diff --git a/doc/architecture/blueprints/gitlab_steps/data.drawio.png b/doc/architecture/blueprints/gitlab_steps/data.drawio.png Binary files differnew file mode 100644 index 00000000000..59436093fb7 --- /dev/null +++ b/doc/architecture/blueprints/gitlab_steps/data.drawio.png diff --git a/doc/architecture/blueprints/gitlab_steps/decisions/001_initial_support.md b/doc/architecture/blueprints/gitlab_steps/decisions/001_initial_support.md new file mode 100644 index 00000000000..669e16ba625 --- /dev/null +++ b/doc/architecture/blueprints/gitlab_steps/decisions/001_initial_support.md @@ -0,0 +1,30 @@ +--- +owning-stage: "~devops::verify" +description: 'GitLab Steps ADR 001: Bootstrap Step Runner' +--- + +# GitLab Steps ADR 001: Bootstrap Step Runner + +## Context + +[GitLab Steps](../index.md) is a new feature that does not have any prior usage at GitLab. +We decided that there are two important objectives at this stage of the project: + +- Integrate the project into existing CI pipelines for the purpose of user evaluation as part of an [Experiment](../../../../policy/experiment-beta-support.md#experiment) phase. +- Provide a contribution framework for other developers in the form of a project with contribution guidelines. + +## Decision + +The [GitLab Steps: Iteration 1: Bootstrap Step Runner (MVC)](https://gitlab.com/groups/gitlab-org/-/epics/11736) +was created to achieve the following objectives: + +- We defined the initial plan to bootstrap the project. +- The project will be stored in [`gitlab-org/step-runner`](https://gitlab.com/gitlab-org/step-runner). +- We will implement the [Step Definition](../step-definition.md) as a [Protocol Buffer](https://protobuf.dev/). The initial implementation is described in the [Baseline Step Proto](../implementation.md). +- Usage of [Protocol Buffers](https://protobuf.dev/) will provide strong guards for the minimal required definition to be used by the project. +- We will provide documentation on how to use GitLab Steps in existing CI pipelines. + +## Alternatives + +No alternatives were considered at this phase, since there's no pre-existing work at GitLab +for that type of feature. diff --git a/doc/architecture/blueprints/gitlab_steps/implementation.md b/doc/architecture/blueprints/gitlab_steps/implementation.md new file mode 100644 index 00000000000..d8480cfb2be --- /dev/null +++ b/doc/architecture/blueprints/gitlab_steps/implementation.md @@ -0,0 +1,339 @@ +--- +owning-stage: "~devops::verify" +description: Implementation details for [CI Steps](index.md). +--- + +# Design and implementation details + +## Baseline Step Proto + +The internals of Step Runner operate on the baseline step definition +which is defined in Protocol Buffer. All GitLab CI steps (and other +supported formats such as GitHub Actions) compile / fold to baseline steps. +Both step invocations in `.gitlab-ci.yml` and step definitions +in `step.yml` files will be compiled to baseline structures. +The term "step" means "baseline step" for the remainder of this document. + +Each step includes a reference `ref` in the form of a URI. The method of +retrieval is determined by the protocol of the URI. + +Steps and step traces have fields for inputs, outputs, +environment variables and environment exports. +After steps are downloaded and the `step.yml` is parsed +a step definition `def` will be added. +If a step defines multiple additional steps then the +trace will include sub-traces for each sub-step. + +```protobuf +message Step { + string name = 1; + string step = 2; + map<string,string> env = 3; + map<string,google.protobuf.Value> inputs = 4; +} + +message Definition { + DefinitionType type = 1; + Exec exec = 2; + repeated Step steps = 3; + message Exec { + repeated string command = 1; + string work_dir = 2; + } +} + +enum DefinitionType { + definition_type_unspecified = 0; + exec = 1; + steps = 2; +} + +message Spec { + Content spec = 1; + message Content { + map<string,Input> inputs = 1; + message Input { + InputType type = 1; + google.protobuf.Value default = 2; + } + } +} + +enum InputType { + spec_type_unspecified = 0; + string = 1; + number = 2; + bool = 3; + struct = 4; + list = 5; +} + +message StepResult { + Step step = 1; + Spec spec = 2; + Definition def = 3; + enum Status { + unspecified = 0; + running = 1; + success = 2; + failure = 3; + } + Status status = 4; + map<string,Output> outputs = 5; + message Output { + string key = 1; + string value = 2; + bool masked = 3; + } + map<string,string> exports = 6; + int32 exit_code = 7; + repeated StepResult children_step_results = 8; +} +``` + +## Step Caching + +Steps are cached locally by a key comprised of `location` +(URL), `version` and `hash`. This prevents the exact same component +from being downloaded multiple times. The first time a step is +referenced it will be downloaded (unless local) and the cache will +return the path to the folder containing `step.yml` and the other +step files. If the same step is referenced again, the same folder +will be returned without downloading. + +If a step is referenced which differs by version or hash from another +cached step, it will be re-downloaded into a different folder and +cached separately. + +## Execution Context + +State is kept by Step Runner across all steps in the form of +an execution context. The context contains the output of each step, +environment variables and overall job and environment metadata. +The execution context can be referenced by expressions in +GitLab CI steps provided by the workflow author. + +Example of context available to expressions in `.gitlab-ci.yml`: + +```yaml +steps: + previous_step: + outputs: + name: "hello world" +env: + EXAMPLE_VAR: "bar" +job: + id: 1234 +``` + +Expressions in step definitions can also reference execution +context. However they can only access overall +job and environment metadata and the inputs defined in `step.yml`. +They cannot access the outputs of previous steps. In order to +provide the output of one step to the next, the step input +values should include an expression which references another +step's output. + +Example of context available to expressions in `step.yml`: + +```yaml +inputs: + name: "foo" +env: + EXAMPLE_VAR: "bar" +job: + id: 1234 +``` + +E.g. this is not allowed in a `step.yml file` because steps +should not couple to one another. + +```yaml +spec: + inputs: + name: +--- +type: exec +exec: + command: [echo, hello, ${{ steps.previous_step.outputs.name }}] +``` + +This is allowed because the GitLab CI steps syntax passes data +from one step to another: + +```yaml +spec: + inputs: + name: +--- +type: exec +exec: + command: [echo, hello, ${{ inputs.name }}] +``` + +```yaml +steps: +- name: previous_step + ... +- name: greeting + inputs: + name: ${{ steps.previous_step.outputs.name }} +``` + +Therefore evaluation of expressions will done in two different kinds +of context. One as a GitLab CI Step and one as a step definition. + +### Step Inputs + +Step inputs can be given in several ways. They can be embeded +directly into expressions in an `exec` command (as above). Or they +can be embedded in expressions for environment variables set during +exec: + +```yaml +spec: + inputs: + name: +--- +type: exec +exec: + command: [greeting.sh] +env: + NAME: ${{ inputs.name }} +``` + +### Input Types + +Input values are stored as strings. But they can also have a type +associated with them. Supported types are: + +- `string` +- `bool` +- `number` +- `object` + +String type values can be any string. Bool type values must be either `true` +or `false` when parsed as JSON. Number type values must a valid float64 +when parsed as JSON. Object types will be a JSON serialization of +the YAML input structure. + +For example, these would be valid inputs: + +```yaml +steps: +- name: my_step + inputs: + foo: bar + baz: true + bam: 1 +``` + +Given this step definition: + +```yaml +spec: + inputs: + foo: + type: string + baz: + type: bool + bam: + type: number +--- +type: exec +exec: + command: [echo, ${{ inputs.foo }}, ${{ inputs.baz }}, ${{ inputs.bam }}] +``` + +And it would output `bar true 1` + +For an object type, these would be valid inputs: + +```yaml +steps: + name: my_step + inputs: + foo: + steps: + - name: my_inner_step + inputs: + name: steppy +``` + +Given this step definition: + +```yaml +spec: + inputs: + foo: + type: object +--- +type: exec +exec: + command: [echo, ${{ inputs.foo }}] +``` + +And it would output `{"steps":[{"name":"my_inner_step","inputs":{"name":"steppy"}}]}` + +### Outputs + +Output files are created into which steps can write their +outputs and environment variable exports. The file locations are +provided in `OUTPUT_FILE` and `ENV_FILE` environment variables. + +After execution Step Runner will read the output and environment +variable files and populate the trace with their values. The +outputs will be stored under the context for the executed step. +And the exported environment variables will be merged with environment +provided to the next step. + +Some steps can be of type `steps` and be composed of a sequence +of GitLab CI steps. These will be compiled and executed in sequence. +Any environment variables exported by nested steps will be available +to subsequent steps. And will be available to high level steps +when the nested steps are complete. E.g. entering nested steps does +not create a new "scope" or context object. Environment variables +are global. + +## Containers + +We've tried a couple approaches to running steps in containers. +In end we've decided to delegate steps entirely to a step runner +in the container. + +Here are the options considered: + +### Delegation (chosen option) + +A provision is made for passing complex structures to steps, which +is to serialize them as JSON (see Inputs above). In this way the actual +step to be run can be merely a parameter to step running in container. +So the outer step is a `docker/run` step with a command that executes +`step-runner` with a `steps` input parameter. The `docker/run` step will +run the container and then extract the output files from the container +and re-emit them to the outer steps. + +This same technique will work for running steps in VMs or whatever. +Step Runner doesn't have to know anything about containerizing or +isolation steps. + +### Special Compilation (rejected option) + +When we see the `image` keyword in a GitLab CI step we would download +and compile the "target" step. Then manufacture a `docker/run` step +and pass the complied `exec` command as an input. Then we would compile +the `docker/run` step and execute it. + +However this requires Step Runner to know how to construct a `docker/run` +step. Which couples Step Runner with the method of isolation, making +isolation in VMs and other methods more complicated. + +### Native Docker (rejected option) + +The baseline step can include provisions for running a step in a +Docker container. For example the step could include a `ref` "target" +field and an `image` field. + +However this also couples Step Runner with Docker and expands the role +of Step Runner. It is preferable to make Docker an external step +that Step Runner execs in the same way as any other step. diff --git a/doc/architecture/blueprints/gitlab_steps/index.md b/doc/architecture/blueprints/gitlab_steps/index.md index 5e3becfec19..f43af46d3c7 100644 --- a/doc/architecture/blueprints/gitlab_steps/index.md +++ b/doc/architecture/blueprints/gitlab_steps/index.md @@ -1,7 +1,7 @@ --- status: proposed creation-date: "2023-08-23" -authors: [ "@ayufan" ] +authors: [ "@ayufan", "@josephburnett" ] coach: "@grzegorz" approvers: [ "@dhershkovitch", "@DarrenEastman", "@cheryl.li" ] owning-stage: "~devops::verify" @@ -57,7 +57,7 @@ have to be part of CI syntax. Instead, they can be provided in the form of reusa that are configured in a generic way in the CI config, and later downloaded and executed according to inputs and parameters. -The GitLab Steps is meant to fill that product-gap by following similar model to competitors +GitLab Steps is meant to fill that product-gap by following similar model to competitors and to some extent staying compatible with them. The GitLab Steps is meant to replace all purpose-specific syntax to handle specific features. By providing and using reusable components, that are build outside of `.gitlab-ci.yml`, that are versioned, and requested when needed @@ -131,19 +131,109 @@ TBD ## Proposal +Step Runner will be a new go binary which lives at `https://gitlab.com/gitlab-org/step-runner`. +It will be able to accept a number of input formats which are compiled to a standard proto format. +Output will be a standard proto trace which will include details for debugging and reproducing the build. + +### Capabilities + +- Read steps + - from environment variable + - from `.gitlab-ci.yml` file + - from gRPC server in step-runner + - from commandline JSON input +- Compile GitLab Steps and GitHub Actions to a baseline step definition + - explicit inputs and outputs + - explicit environment and exports + - baseline steps can be type `exec` or more steps +- Download and run steps from: + - Git repos + - zip files + - locally provided +- A job can be composed of different kinds of steps + - steps can come from different sources and be run in different ways + - steps can access environment exports and output of previous steps +- Produce a step-by-step trace of execution + - including final inputs and outputs + - including final environment and exports + - including logs of each step + - each step specifies the exact runtime and component used (hash) + - (optional) masking sensitive inputs, outputs, environment and exports +- Replaying a trace + - reuses the exact runtimes and components from trace + - output of trace will be the same trace if build is deterministic + +### Example invocations + +#### Command line + +- `STEPS=$(cat steps.yml) step-runner ci` +- `step-runner local .gitlab-ci.yml --format gitlab-ci --job-name hello-world --output-file trace.json` +- `step-runner replay trace.json` +- `step-runner ci --port 8080` + +#### GitLab CI + +```yaml +hello-world: + image: registry.gitlab.com/gitlab-org/step-runner + variables: + STEPS: | + - step: gitlab.com/josephburnett/component-hello-steppy@master + inputs: + greeting: "hello ${{ env.name }}" + env: + name: world + script: + - /step-runner ci + artifacts: + paths: + - trace.json +``` + +### Basic compilation and execution process + +Steps as expressed in GitLab CI are complied to the baseline step definition. +Referenced steps are loaded and compiled to produce an `exec` command, +or to produce an additional list of GitLab CI steps which are compiled recursively. +Each steps is executed immediately after compilation so its output will be available for subsequent compilations. + + + +Steps return outputs and exports via files which are collected by Step Runner after each step. +Finally all the compiled inputs and outputs for each step are collected in a step trace. + + + ### GitLab Steps definition and syntax - [Step Definition](step-definition.md). - [Syntactic Sugar extensions](steps-syntactic-sugar.md). -### Integration of GitLab Steps in `.gitlab-ci.yml` +### Integration of GitLab Steps - [Usage of the GitLab Steps with `.gitlab-ci.yml`](gitlab-ci.md). +- [Runner Integration](runner-integration.md). ## Design and implementation details -TBD +### 2023-11-28 - GitLab Steps ADR 001: Bootstrap Step Runner + +- See the [GitLab Steps ADR 001: Bootstrap Step Runner](decisions/001_initial_support.md). +- See the [Baseline Step Proto](implementation.md). ## References +- [GitLab Issue #215511](https://gitlab.com/gitlab-org/gitlab/-/issues/215511) +- [Step Runner Code](https://gitlab.com/josephburnett/step-runner/-/tree/blueprint2). + This is the exploratory code created during the writing of this blueprint. + It shows the structure of the Step Runner binary and how the pieces fit together. + It runs but doesn't quite do the right thing (see all the TODOs). +- [CI Steps / CI Events / Executors / Taskonaut (video)](https://youtu.be/nZoO547IISM). + Some high-level discussion about how these 4 blueprints relate to each other. + And a good prequel to the video about this MR. +- [Steps in Runner (video)](https://youtu.be/82WLQ4zHYts). + A walk through of the Step Runner details from the code perspective. +- [CI YAML keywords](https://gitlab.com/gitlab-org/gitlab/-/issues/398129#note_1324467337). + An inventory of affected keywords. - [GitLab Epic 11535](https://gitlab.com/groups/gitlab-org/-/epics/11535) diff --git a/doc/architecture/blueprints/gitlab_steps/runner-integration.md b/doc/architecture/blueprints/gitlab_steps/runner-integration.md new file mode 100644 index 00000000000..e5a635908bc --- /dev/null +++ b/doc/architecture/blueprints/gitlab_steps/runner-integration.md @@ -0,0 +1,116 @@ +--- +owning-stage: "~devops::verify" +description: Runner integration for [CI Steps](index.md). +--- + +# Runner Integration + +Steps are delivered to Step Runner as a YAML blob in the GitLab CI syntax. +Runner interacts with Step Runner over a gRPC service `StepRunner` +which is started on a local socket in the execution environment. This +is the same way that Nesting serves a gRPC service in a dedicated +Mac instance. The service has three RPCs, `run`, `follow` and `cancel`. + +Run is the initial delivery of the steps. Follow requests a streaming +response to step traces. And Cancel stops execution and cleans up +resources as soon as possible. + +Step Runner operating in gRPC mode will be able to executed multiple +step payloads at once. That is each call to `run` will start a new +goroutine and execute the steps until completion. Multiple calls to `run` +may be made simultaneously. This is also why components are cached by +`location`, `version` and `hash`. Because we cannot be changing which +ref we are on while multiple, concurrent executions are using the +underlying files. + +```proto +service StepRunner { + rpc Run(RunRequest) returns (RunResponse); + rpc Follow(FollowRequest) returns (stream FollowResponse); + rpc Cancel(CancelRequest) returns (CancelResponse); +} + +message RunRequest { + string id = 1; + oneof job_oneof { + string ci_job = 2; + Steps steps = 3; + } +} + +message RunResponse { +} + +message FollowRequest { + string id = 1; +} + +message FollowResponse { + StepResult result = 1; +} + +message CancelRequest { + string id = 1; +} + +message CancelResponse { +} +``` + +As steps are executed, traces are streamed back to GitLab Runner. +So execution can be followed at least at the step level. If a more +granular follow is required, we can introduce a gRPC step type which +can stream back logs as they are produced. + +Here is how we will connect to Step Runner in each runner executor: + +## Instance + +The Instance executor is accessed via SSH, the same as today. However +instead of starting a bash shell and piping in commands, it connects +to the Step Runner socket in a known location and makes gRPC +calls. This is the same as how Runner calls the Nesting server in +dedicated Mac instances to make VMs. + +This requires that Step Runner is present and started in the job +execution environment. + +## Docker + +The same requirement that Step Runner is present and started is true +for the Docker executor (and `docker-autoscaler`). However in order to +connect to the socket inside the container, we must `exec` a bridge +process in the container. This will be another command on the Step +Runner binary which proxies STDIN and STDOUT to the local socket in a +known location, allowing the caller of exec to make gRPC calls inside +the container. + +## Kubernetes + +The Kubelet on Kubernetes Nodes exposes an exec API which will start a +process in a container of a running Pod. We will use this exec create +a bridge process that will allow the caller to make gRPC calls inside +the Pod. Same as the Docker executor. + +In order to access to this protected Kubelet API we must use the +Kubernetes API which provides an exec sub-resource on Pod. A caller +can POST to the URL of a pod suffixed with `/exec` and then negotiate +the connection up to a SPDY protocol for bidirectional byte +streaming. So GitLab Runner can use the Kubernetes API to connect to +the Step Runner service and deliver job payloads. + +This is the same way that `kubectl exec` works. In fact most of the +internals such as SPDY negotiation are provided as `client-go` +libraries. So Runner can call the Kubernetes API directly by +importing the necessary libraries rather than shelling out to +Kubectl. + +Historically one of the weaknesses of the Kubernetes Executor was +running a whole job through a single exec. To mitigate this Runner +uses the attach command instead, which can "re-attach" to an existing +shell process and pick up where it left off. + +This is not necessary for Step Runner however, because the exec is +just establishing a bridge to the long-running gRPC process. If the +connection drops, Runner will just "re-attach" by exec'ing another +connection and continuing to make RPC calls like `follow`. diff --git a/doc/architecture/blueprints/gitlab_steps/step-runner-sequence.drawio.png b/doc/architecture/blueprints/gitlab_steps/step-runner-sequence.drawio.png Binary files differnew file mode 100644 index 00000000000..9f6a6dcad9f --- /dev/null +++ b/doc/architecture/blueprints/gitlab_steps/step-runner-sequence.drawio.png diff --git a/doc/architecture/blueprints/google_artifact_registry_integration/index.md b/doc/architecture/blueprints/google_artifact_registry_integration/index.md index ef66ae33b2a..0419601e266 100644 --- a/doc/architecture/blueprints/google_artifact_registry_integration/index.md +++ b/doc/architecture/blueprints/google_artifact_registry_integration/index.md @@ -18,9 +18,9 @@ As highlighted in the announcement, one key goal is the ability to "_use Google' ## Motivation -Please refer to the [announcement](https://about.gitlab.com/blog/2023/08/29/gitlab-google-partnership-s3c/) blog post for more details about the motivation and long-term goals of the GitLab and Google Cloud partnership. +Refer to the [announcement](https://about.gitlab.com/blog/2023/08/29/gitlab-google-partnership-s3c/) blog post for more details about the motivation and long-term goals of the GitLab and Google Cloud partnership. -Regarding the scope of this design document, our primary focus is to fulfill the Product requirement of providing users with visibility over their container images in GAR. The motivation for this specific goal is rooted in foundational research on the use of external registries as a complement to the GitLab Container Registry ([internal](https://gitlab.com/gitlab-org/ux-research/-/issues/2602)). +Regarding the scope of this design document, our primary focus is to fulfill the Product requirement of providing users with visibility over their container images in GAR. The motivation for this specific goal is rooted in foundational research on the use of external registries as a complement to the GitLab container registry ([internal](https://gitlab.com/gitlab-org/ux-research/-/issues/2602)). Since this marks the first step in the GAR integration, our aim is to achieve this goal in a way that establishes a foundation to facilitate reusability in the future. This groundwork could benefit potential future expansions, such as support for additional artifact formats (npm, Maven, etc.), and features beyond the Package stage (e.g., vulnerability scanning, deployments, etc.). @@ -74,7 +74,7 @@ As previously highlighted, access to the GAR integration features is restricted #### Resource Mapping -For the [GitLab Container Registry](../../../user/packages/container_registry/index.md), repositories within a specific project must have a path that matches the project full path. This is essentially how we establish a resource mapping between GitLab Rails and the registry, which serves multiple purposes, including granular authorization, scoping storage usage to a given project/group/namespace, and more. +For the [GitLab container registry](../../../user/packages/container_registry/index.md), repositories within a specific project must have a path that matches the project full path. This is essentially how we establish a resource mapping between GitLab Rails and the registry, which serves multiple purposes, including granular authorization, scoping storage usage to a given project/group/namespace, and more. Regarding the GAR integration, since there is no equivalent entities for GitLab project/group/namespace resources on the GAR side, we aim to simplify matters by allowing users to attach any [GAR repository](https://cloud.google.com/artifact-registry/docs/repositories) to any GitLab project, regardless of their respective paths. Similarly, we do not plan to restrict the attachment of a particular GAR repository to a single GitLab project. Ultimately, it is up to users to determine how to organize both datasets in the way that best suits their needs. @@ -82,13 +82,13 @@ Regarding the GAR integration, since there is no equivalent entities for GitLab GAR provides three APIs: Docker API, REST API, and RPC API. -The [Docker API](https://cloud.google.com/artifact-registry/docs/reference/docker-api) is based on the [Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api), now superseded by the [OCI Distribution Specification API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) (from now on referred to as OCI API). This API is used for pushing/pulling images to/from GAR and also provides some discoverability operations. Please refer to [Alternative Solutions](#alternative-solutions) for the reasons why we don't intend to use it. +The [Docker API](https://cloud.google.com/artifact-registry/docs/reference/docker-api) is based on the [Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api), now superseded by the [OCI Distribution Specification API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) (from now on referred to as OCI API). This API is used for pushing/pulling images to/from GAR and also provides some discoverability operations. Refer to [Alternative Solutions](#alternative-solutions) for the reasons why we don't intend to use it. Among the proprietary GAR APIs, the [REST API](https://cloud.google.com/artifact-registry/docs/reference/rest) provides basic functionality for managing repositories. This includes [`list`](https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories.dockerImages/list) and [`get`](https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories.dockerImages/get) operations for container image repositories, which could be used for this integration. Both operations return the same data structure, represented by the [`DockerImage`](https://cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories.dockerImages#DockerImage) object, so both provide the same level of detail. Last but not least, there is also an [RPC API](https://cloud.google.com/artifact-registry/docs/reference/rpc/google.devtools.artifactregistry.v1), backed by gRPC and Protocol Buffers. This API provides the most functionality, covering all GAR features. From the available operations, we can make use of the [`ListDockerImagesRequest`](https://cloud.google.com/artifact-registry/docs/reference/rpc/google.devtools.artifactregistry.v1#listdockerimagesrequest) and [`GetDockerImageRequest`](https://cloud.google.com/artifact-registry/docs/reference/rpc/google.devtools.artifactregistry.v1#google.devtools.artifactregistry.v1.GetDockerImageRequest) operations. As with the REST API, both responses are composed of [`DockerImage`](https://cloud.google.com/artifact-registry/docs/reference/rpc/google.devtools.artifactregistry.v1#google.devtools.artifactregistry.v1.DockerImage) objects. -Between the two proprietary API options, we chose the RPC one because it provides support not only for the operations we need today but also offers better coverage of all GAR features, which will be beneficial in future iterations. Finally, we do not intend to make direct use of this API but rather use it through the official Ruby client SDK. Please see [Client SDK](backend.md#client-sdk) below for more details. +Between the two proprietary API options, we chose the RPC one because it provides support not only for the operations we need today but also offers better coverage of all GAR features, which will be beneficial in future iterations. Finally, we do not intend to make direct use of this API but rather use it through the official Ruby client SDK. See [Client SDK](backend.md#client-sdk) below for more details. #### Backend Integration @@ -116,6 +116,6 @@ One alternative solution considered was to use the Docker/OCI API provided by GA - **Multiple Requests**: To retrieve all the required information about each image, multiple requests to different endpoints (listing tags, obtaining image manifests, and image configuration blobs) would have been necessary, leading to a `1+N` performance issue. -GitLab had previously faced significant challenges with the last two limitations, prompting the development of a custom [GitLab Container Registry API](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/gitlab/api.md) to address them. Additionally, GitLab decided to [deprecate support](../../../update/deprecations.md#use-of-third-party-container-registries-is-deprecated) for connecting to third-party container registries using the Docker/OCI API due to these same limitations and the increased cost of maintaining two solutions in parallel. As a result, there is an ongoing effort to replace the use of the Docker/OCI API endpoints with custom API endpoints for all container registry functionalities in GitLab. +GitLab had previously faced significant challenges with the last two limitations, prompting the development of a custom [GitLab container registry API](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/gitlab/api.md) to address them. Additionally, GitLab decided to [deprecate support](../../../update/deprecations.md#use-of-third-party-container-registries-is-deprecated) for connecting to third-party container registries using the Docker/OCI API due to these same limitations and the increased cost of maintaining two solutions in parallel. As a result, there is an ongoing effort to replace the use of the Docker/OCI API endpoints with custom API endpoints for all container registry functionalities in GitLab. Considering these factors, the decision was made to build the GAR integration from scratch using the proprietary GAR API. This approach provides more flexibility and control over the integration and can serve as a foundation for future expansions, such as support for other GAR artifact formats. diff --git a/doc/architecture/blueprints/google_artifact_registry_integration/ui_ux.md b/doc/architecture/blueprints/google_artifact_registry_integration/ui_ux.md index 5cb862d50e7..f82889b9ccf 100644 --- a/doc/architecture/blueprints/google_artifact_registry_integration/ui_ux.md +++ b/doc/architecture/blueprints/google_artifact_registry_integration/ui_ux.md @@ -8,9 +8,9 @@ description: 'UI/UX for Google Artifact Registry Integration' ## Structure and Organization -Unlike the GitLab Container Registry (and therefore the Docker Registry and OCI Distribution), GAR does not treat tags as the primary "artifacts" in a repository. Instead, the primary "artifacts" are the image manifests. For each manifest object (represented by [`DockerImage`](https://cloud.google.com/artifact-registry/docs/reference/rpc/google.devtools.artifactregistry.v1#google.devtools.artifactregistry.v1.DockerImage)), there is a list of assigned tags (if any). Consequently, when listing the contents of a repository through the GAR API, the response comprises a collection of manifest objects (along with their associated tags as properties), rather than a collection of tag objects. Additionally, due to this design choice, untagged manifests are also present in the response. +Unlike the GitLab container registry (and therefore the Docker Registry and OCI Distribution), GAR does not treat tags as the primary "artifacts" in a repository. Instead, the primary "artifacts" are the image manifests. For each manifest object (represented by [`DockerImage`](https://cloud.google.com/artifact-registry/docs/reference/rpc/google.devtools.artifactregistry.v1#google.devtools.artifactregistry.v1.DockerImage)), there is a list of assigned tags (if any). Consequently, when listing the contents of a repository through the GAR API, the response comprises a collection of manifest objects (along with their associated tags as properties), rather than a collection of tag objects. Additionally, due to this design choice, untagged manifests are also present in the response. -To maximize flexibility, extensibility, and maintain familiarity for GAR users, we plan to fully embrace the GAR API data structures while surfacing data in the GitLab UI. We won't attempt to emulate a "list of tags" response to match the UI/UX that we already have for the GitLab Container Registry. +To maximize flexibility, extensibility, and maintain familiarity for GAR users, we plan to fully embrace the GAR API data structures while surfacing data in the GitLab UI. We won't attempt to emulate a "list of tags" response to match the UI/UX that we already have for the GitLab container registry. Considering the above, there will be a view that provides a pageable and sortable list of all images in the configured GAR repository. Additionally, there will be a detail view to display more information about a single image. You can find a list of available image attributes documented [here](https://cloud.google.com/artifact-registry/docs/reference/rpc/google.devtools.artifactregistry.v1#google.devtools.artifactregistry.v1.DockerImage). diff --git a/doc/architecture/blueprints/google_cloud_platform_integration/index.md b/doc/architecture/blueprints/google_cloud_platform_integration/index.md new file mode 100644 index 00000000000..7fe2c1f655a --- /dev/null +++ b/doc/architecture/blueprints/google_cloud_platform_integration/index.md @@ -0,0 +1,34 @@ +--- +status: ongoing +creation-date: "2023-10-26" +authors: [ "@sgoldstein" ] +coaches: ["@jessieay", "@grzesiek"] +approvers: ["@sgoldstein", "@jreporter"] +owning-stage: "~section::ops" +participating-stages: ["~devops::verify", "~devops::package", "~devops::govern"] +--- + +# Google Cloud Platform Integration + +GitLab and Google Cloud Platform (GCP) provide complementary tooling which we +are integrating via our [partnership](https://about.gitlab.com/blog/2023/08/29/gitlab-google-partnership-s3c/). + +This design doc is not public at that time. The whole content is +available in [GitLab-internal project](https://gitlab.com/gitlab-org/architecture/gitlab-gcp-integration/design-doc). + +## Who + +<!-- vale gitlab.Spelling = NO --> + +| Who | Role +|------------------------|--------------------------------------------------| +| Sam Goldstein | Director of Engineering, Engineering DRI | +| Grzegorz Bizon | Distinguished Engineer - Technical Lead | +| Jessie Young | Principal Engineer | +| David Fernandez | Staff Engineer | +| Imre Farkas | Staff Engineer | +| João Pereira | Staff Engineer | +| Joe Burnett | Staff Engineer | +| Tomasz Maczukin | Senior Engineer | + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/architecture/blueprints/new_diffs.md b/doc/architecture/blueprints/new_diffs.md index af1e4679c14..d5768f6c914 100644 --- a/doc/architecture/blueprints/new_diffs.md +++ b/doc/architecture/blueprints/new_diffs.md @@ -1,132 +1,11 @@ --- -status: proposed -creation-date: "2023-10-10" -authors: [ "@iamphill" ] -coach: [ "@ntepluhina" ] -approvers: [ ] -owning-stage: "~devops::create" -participating-stages: [] +redirect_to: 'new_diffs/index.md' +remove_date: '2024-02-29' --- -<!-- Blueprints often contain forward-looking statements --> -<!-- vale gitlab.FutureTense = NO --> +This document was moved to [another location](new_diffs/index.md). -# New diffs - -## Summary - -Diffs at GitLab are spread across several places with each area using their own method. We are aiming -to develop a single, performant way for diffs to be rendered across the application. Our aim here is -to improve all areas of diff rendering, from the backend creation of diffs to the frontend rendering -the diffs. - -## Motivation - -### Goals - -- improved perceived performance -- improved maintainability -- consistent coverage of all scenarios - -### Non-Goals - -<!-- -Listing non-goals helps to focus discussion and make progress. This section is -optional. - -- What is out of scope for this blueprint? ---> - -### Priority of Goals - -In an effort to provide guidance on which goals are more important than others to assist in making -consistent choices, despite all goals being important, we defined the following order. - -**Perceived performance** is above **improved maintainability** is above **consistent coverage**. - -Examples: - -- a proposal improves maintainability at the cost of perceived performance: ❌ we should consider an alternative. -- a proposal removes a feature from certain contexts, hurting coverage, and has no impact on perceived performance or maintanability: ❌ we should re-consider. -- a proposal improves perceived performance but removes features from certain contexts of usage: ✅ it's valid and should be discussed with Product/UX. -- a proposal guarantees consistent coverage and has no impact on perceived performance or maintainability: ✅ it's valid. - -In essence, we'll strive to meet every goal at each decision but prioritise the higher ones. - -## Proposal - -<!-- -This is where we get down to the specifics of what the proposal actually is, -but keep it simple! This should have enough detail that reviewers can -understand exactly what you're proposing, but should not include things like -API designs or implementation. The "Design Details" section below is for the -real nitty-gritty. - -You might want to consider including the pros and cons of the proposed solution so that they can be -compared with the pros and cons of alternatives. ---> - -## Design and implementation details - -### Workspace & Artifacts - -- We will store implementation details like metrics, budgets, and development & architectural patterns here in the docs -- We will store large bodies of research, the results of audits, etc. in the [wiki](https://gitlab.com/gitlab-com/create-stage/new-diffs/-/wikis/home) of the [New Diffs project](https://gitlab.com/gitlab-com/create-stage/new-diffs) -- We will store audio & video recordings on the public Youtube channel in the Code Review / New Diffs playlist -- We will store drafts, meeting notes, and other temporary documents in public Google docs - -### Definitions - -#### Maintainability - -Maintainable projects are _simple_ projects. - -Simplicity is the opposite of complexity. This uses a definition of simple and complex [described by Rich Hickey in "Simple Made Easy"](https://www.infoq.com/presentations/Simple-Made-Easy/) (Strange Loop, 2011). - -- Maintainable code is simple (single task, single concept, separate from other things). -- Maintainable projects expand on simple code by having simple structure (folders define classes of behaviors, e.g. you can be assured that a component directory will never initiate a network call, because that would be complecting visual display with data access) -- Maintainable applications flow out of simple organization and simple code. The old saying is a cluttered desk is representative of a cluttered mind. Rigorous discipline on simplicity will be represented in our output (the product). By being strict about working simply, we will naturally produce applications where our users can more easily reason about their behavior. - -#### Done - -GitLab has an existing [definition of done](/ee/development/contributing/merge_request_workflow.md#definition-of-done) which is geared primarily toward identifying when an MR is ready to be merged. - -In addition to the items in the GitLab definition of done, work on new diffs should also adhere to the following requirements: - -- Meets or exceeds all metrics - - Meets or exceeds our minimum accessibility metrics (these are explicitly not part of our defined priorities, since they are non-negotiable) -- All work is fully documented for engineers (user documentation is a requirement of the standard definition of done) - -<!-- -This section should contain enough information that the specifics of your -change are understandable. This may include API specs (though not always -required) or even code snippets. If there's any ambiguity about HOW your -proposal will be implemented, this is the place to discuss them. - -If you are not sure how many implementation details you should include in the -blueprint, the rule of thumb here is to provide enough context for people to -understand the proposal. As you move forward with the implementation, you may -need to add more implementation details to the blueprint, as those may become -an important context for important technical decisions made along the way. A -blueprint is also a register of such technical decisions. If a technical -decision requires additional context before it can be made, you probably should -document this context in a blueprint. If it is a small technical decision that -can be made in a merge request by an author and a maintainer, you probably do -not need to document it here. The impact a technical decision will have is -another helpful information - if a technical decision is very impactful, -documenting it, along with associated implementation details, is advisable. - -If it's helpful to include workflow diagrams or any other related images. -Diagrams authored in GitLab flavored markdown are preferred. In cases where -that is not feasible, images should be placed under `images/` in the same -directory as the `index.md` for the proposal. ---> - -## Alternative Solutions - -<!-- -It might be a good idea to include a list of alternative solutions or paths considered, although it is not required. Include pros and cons for -each alternative solution/path. - -"Do nothing" and its pros and cons could be included in the list too. ---> +<!-- This redirect file can be deleted after <2024-02-29>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/architecture/blueprints/new_diffs/index.md b/doc/architecture/blueprints/new_diffs/index.md new file mode 100644 index 00000000000..2a3010259d5 --- /dev/null +++ b/doc/architecture/blueprints/new_diffs/index.md @@ -0,0 +1,431 @@ +--- +status: proposed +creation-date: "2023-10-10" +authors: [ "@thomasrandolph", "@patrickbajao", "@igor.drozdov", "@jerasmus", "@iamphill", "@slashmanov", "@psjakubowska" ] +coach: [ "@ntepluhina" ] +approvers: [ ] +owning-stage: "~devops::create" +participating-stages: [] +--- + +<!-- Blueprints often contain forward-looking statements --> +<!-- vale gitlab.FutureTense = NO --> + +# New diffs + +## Summary + +Diffs at GitLab are spread across several places with each area using their own method. We are aiming +to develop a single, performant way for diffs to be rendered across the application. Our aim here is +to improve all areas of diff rendering, from the backend creation of diffs to the frontend rendering +the diffs. + +## Motivation + +### Goals + +- improved perceived performance +- improved maintainability +- consistent coverage of all scenarios + +### Non-Goals + +<!-- +Listing non-goals helps to focus discussion and make progress. This section is +optional. + +- What is out of scope for this blueprint? +--> + +### Priority of Goals + +In an effort to provide guidance on which goals are more important than others to assist in making +consistent choices, despite all goals being important, we defined the following order. + +**Perceived performance** is above **improved maintainability** is above **consistent coverage**. + +Examples: + +- a proposal improves maintainability at the cost of perceived performance: ❌ we should consider an alternative. +- a proposal removes a feature from certain contexts, hurting coverage, and has no impact on perceived performance or maintainability: ❌ we should re-consider. +- a proposal improves perceived performance but removes features from certain contexts of usage: ✅ it's valid and should be discussed with Product/UX. +- a proposal guarantees consistent coverage and has no impact on perceived performance or maintainability: ✅ it's valid. + +In essence, we'll strive to meet every goal at each decision but prioritise the higher ones. + +## Proposal + +<!-- +This is where we get down to the specifics of what the proposal actually is, +but keep it simple! This should have enough detail that reviewers can +understand exactly what you're proposing, but should not include things like +API designs or implementation. The "Design Details" section below is for the +real nitty-gritty. + +You might want to consider including the pros and cons of the proposed solution so that they can be +compared with the pros and cons of alternatives. +--> + +### Accessibility + +New diffs should be displayed in a way that is compliant with [Web Content Accessibility Guidelines 2.1](https://www.w3.org/TR/WCAG21/) level AA for web-based content and [Authoring Tool Accessibility Guidelines 2.0](https://www.w3.org/TR/ATAG20/) level AA for user interface. + +We recognize that in order to have an accessible experience using diffs in the context of GitLab, we need to ensure the compliance both for displaying and interacting with diffs. That's why the accessibility +audit and further recommendation will also consider Content Editor used feature for reviewing changes. + +#### ATAG 2.0 AA + +Giving the nature of diffs, the following guidelines will be our main focus: + +1. [Guideline A.2.1: (For the authoring tool user interface) Make alternative content available to authors](https://www.w3.org/TR/ATAG20/#gl_a21) +1. [Guideline A.3.1: (For the authoring tool user interface) Provide keyboard access to authoring features](https://www.w3.org/TR/ATAG20/#gl_a31) +1. [Guideline A.3.4: (For the authoring tool user interface) Enhance navigation and editing via content structure](https://www.w3.org/TR/ATAG20/#gl_a34) +1. [Guideline A.3.6: (For the authoring tool user interface) Manage preference settings](https://www.w3.org/TR/ATAG20/#gl_a36) + +## Design and implementation details + +### Workspace & Artifacts + +- We will store implementation details like metrics, budgets, and development & architectural patterns here in the docs +- We will store large bodies of research, the results of audits, etc. in the [wiki](https://gitlab.com/gitlab-com/create-stage/new-diffs/-/wikis/home) of the [New Diffs project](https://gitlab.com/gitlab-com/create-stage/new-diffs) +- We will store audio & video recordings on the public YouTube channel in the Code Review / New Diffs playlist +- We will store drafts, meeting notes, and other temporary documents in public Google docs + +### Definitions + +#### Maintainability + +Maintainable projects are _simple_ projects. + +Simplicity is the opposite of complexity. This uses a definition of simple and complex [described by Rich Hickey in "Simple Made Easy"](https://www.infoq.com/presentations/Simple-Made-Easy/) (Strange Loop, 2011). + +- Maintainable code is simple (single task, single concept, separate from other things). +- Maintainable projects expand on simple code by having simple structure (folders define classes of behaviors, e.g. you can be assured that a component directory will never initiate a network call, because that would be conflating visual display with data access) +- Maintainable applications flow out of simple organization and simple code. The old saying is a cluttered desk is representative of a cluttered mind. Rigorous discipline on simplicity will be represented in our output (the product). By being strict about working simply, we will naturally produce applications where our users can more easily reason about their behavior. + +#### Done + +GitLab has an existing [definition of done](/ee/development/contributing/merge_request_workflow.md#definition-of-done) which is geared primarily toward identifying when an MR is ready to be merged. + +In addition to the items in the GitLab definition of done, work on new diffs should also adhere to the following requirements: + +- Meets or exceeds all metrics + - Meets or exceeds our minimum accessibility metrics (these are explicitly not part of our defined priorities, because they are non-negotiable) +- All work is fully documented for engineers (user documentation is a requirement of the standard definition of done) + +### Metrics + +To measure our success, we need to set meaningful metrics. These metrics should meaningfully and positively impact the end user. + +1. Meets or exceeds [WCAG 2.2 AA](https://www.w3.org/TR/WCAG22/). +1. Meets or exceeds [ATAG 2.0 AA](https://www.w3.org/TR/ATAG20/). +1. The new Diffs app loads less than or equal to 300 KiB of JavaScript (compressed / "across-the-wire")<sup>1</sup>. +1. The new Diffs app loads less than or equal to 150 KiB of markup, images, styles, fonts, etc. (compressed / "across-the-wire")<sup>1</sup>. +1. The new Diffs app can execute in total isolation from the rest of the GitLab product: + 1. "Execute" means the app can load, display data, and allows user interaction ("read-only"). + 1. If a part of the application is only used in merge requests or diffs, it is considered part of the Diffs application. + 1. If a part of the application must be brought in from the rest of the product, it is not considered part of the Diffs load (as defined in metrics 3 and 4). + 1. If a part of the application must be brought in from the rest of the product, it may not block functionality of the Diffs application. + 1. If a part of the application must be brought in from the rest of the product, it must be loaded asynchronously. + 1. If a part of the application meets 5.1-5.5 _(such as: the Markdown editor is loaded asynchronously when the user would like to leave a comment on a diff)_ and its inclusion causes a budget overflow: + - It must be added to a list of documented exceptions that we accept are out of bounds and out of our control. + - The exceptions list should be addressed on a regular basis to determine the ongoing value of overflowing our budget. + +--- +<sup>1</sup>: [The Performance Inequality Gap, 2023](https://infrequently.org/2022/12/performance-baseline-2023/) + +### Front end + +#### High-level implementation + +<!-- +This section should contain enough information that the specifics of your +change are understandable. This may include API specs (though not always +required) or even code snippets. If there's any ambiguity about HOW your +proposal will be implemented, this is the place to discuss them. + +If you are not sure how many implementation details you should include in the +blueprint, the rule of thumb here is to provide enough context for people to +understand the proposal. As you move forward with the implementation, you may +need to add more implementation details to the blueprint, as those may become +an important context for important technical decisions made along the way. A +blueprint is also a register of such technical decisions. If a technical +decision requires additional context before it can be made, you probably should +document this context in a blueprint. If it is a small technical decision that +can be made in a merge request by an author and a maintainer, you probably do +not need to document it here. The impact a technical decision will have is +another helpful information - if a technical decision is very impactful, +documenting it, along with associated implementation details, is advisable. + +If it's helpful to include workflow diagrams or any other related images. +Diagrams authored in GitLab flavored markdown are preferred. In cases where +that is not feasible, images should be placed under `images/` in the same +directory as the `index.md` for the proposal. +--> + +#### HTML structure + +The HTML structure of a diff should have support for assistive technology. +For this reason, a table could be a preferred solution as it allows to indicate +logical relationship between the presented data and is easier to navigate for +screen reader users with keyboard. Labeled columns will make sure that information +such as line numbers can be associated with the edited piece of code. + +Possible structure could include: + +```html +<table> + <caption class="gl-sr-only">Changes for file index.js. 10 lines changed: 5 deleted, 5 added.</caption> + <tr hidden> + <th>Original line number: </th> + <th>Diff line number: </th> + <th>Line change:</th> + </tr> + <tr> + <td>1234</td> + <td></td> + <td>.tree-time-ago ,</td> + </tr> + […] +</table> +``` + +See [WAI tutorial on tables](https://www.w3.org/WAI/tutorials/tables) for +more implementation guidelines. + +Each file table should include a short summary of changes that will read out: + +- total number of lines changed, +- number of added lines, +- number of removed lines. + +The summary of the table content can be placed either within `<caption>` element, or before the table within an element referred as `aria-describedby`. +See <abbr>WAI</abbr> (Web Accessibility Initiative) for more information on both approaches: + +- [Nesting summary inside the `<caption>` element](https://www.w3.org/WAI/tutorials/tables/caption-summary/#nesting-summary-inside-the-caption-element) +- [Using `aria-describedby` to provide a table summary](https://www.w3.org/WAI/tutorials/tables/caption-summary/#using-aria-describedby-to-provide-a-table-summary) + +However, if such a structure will compromise other functional aspects of displaying a diff, +more generic elements together with ARIA support can be used. + +#### Visual indicators + +It is important that each visual indicator should have a screen reader text +denoting the meaning of that indicator. When needed, use `gl-sr-only` or `gl-sr-only-focusable` +class to make the element accessible by screen readers, but not by sighted users. + +Some of the visual indicators that require alternatives for assistive technology are: + +- `+` or red highlighting to be read as `added` +- `-` or green highlighting to be read as `removed` + +## Alternative Solutions + +<!-- +It might be a good idea to include a list of alternative solutions or paths considered, although it is not required. Include pros and cons for +each alternative solution/path. + +"Do nothing" and its pros and cons could be included in the list too. +--> + +## Proposed changes + +These changes (indicated by an arbitrary name like "Design A") suggest a proposed final path forward for this blueprint, but have not yet been accepted as the authoritative content. + +- Mark the highest hierarchical heading with your design name. If you are changing multiple headings at the same level, make sure to mark them all with the same name. This will create a high-level table of contents that is easier to reason about. + +### Front end (Design A) + +NOTE: +This draft proposal suggests one potential front end architecture which may not be chosen. It is not necessarily mutually exclusive with other proposed designs. + +Ideally, we would meet our definition of done and our accountability metrics on our first try. +We also need to continue to stay within those boundaries as we move forward. To ensure this, +we need to design an application architecture that: + +1. Is: + 1. Scalable. + 1. Malleable. + 1. Flexible. +1. Considers itself a mission-critical part of the overall GitLab product. +1. Treats itself as a complex, unique application with concerns that cannot be addressed + as side effects of other parts of the product. +1. Can handle data access/format changes without making UI changes. +1. Can handle UI changes without making data access/format changes. +1. Provides a hookable, inspectable API and avoids code coupling. +1. Separates: + - State and application data. + - Application behavior and UI. + - Data access and network access. + +#### High-level implementation + +NOTE: +This draft proposal suggests one potential front end architecture which may not be chosen. It is not necessarily mutually exclusive with other proposed designs. + +(See [New Diffs: Technical Architecture Design](https://gitlab.com/gitlab-org/gitlab/-/issues/431276) for nicer visuals of this chart) + +```mermaid +flowchart TB + classDef sticky fill:#d0cabf, color:black + stickyMetricsA>"Metrics 3, 4, & 5 apply to<br>the entire front end application"] + + stickyMetricsA -.- fe + fe + + Socket((WebSocket)) + + be + +subgraph fe [Front End] + stickyMetricsB>"Metrics 1 & 2 apply<br>to all UI elements"] + stickyInbound>"All data is formatted precisely<br>how the UI needs to interact with it"] + stickyOutbound>"All data is formatted precisely<br>how the back end expects it"] + stickyIdb>"Long-term. + + e.g. diffs, MRs, emoji, notes, drafts, user-only data<br>like file reviews, collapse states, etc."] + stickySession>"Session-term. + + e.g. selected tab, scroll position,<br>temporary changes to user settings, etc."] + + Events([Event Hub]) + UI[UI] + uiState((Local State)) + Logic[Application Logic] + Normalizer[Data Normalizer] + Inbound{{Inbound Contract}} + Outbound{{Outbound Contract}} + Data[Data Access] + idb((indexedDB)) + session((sessionStorage)) + Network[Network Access] +end + +subgraph be [Back End] + stickyApi>"A large list of defined actions a<br>Diffs/Merge Request UI could perform. + + e.g.: <code>mergeRequest:notes:saveDraft</code> or<br><code>mergeRequest:changeStatus</code> (with <br><code>status: 'draft'</code> or <code>status: 'ready'</code>, etc.). + + Must not expose any implementation detail,<br>like models, storage structure, etc."] + API[Activities API] + unk[\"?"/] + + API -.- stickyApi +end + + %% Make stickies look like paper sort of? + class stickyMetricsA,stickyMetricsB,stickyInbound,stickyOutbound,stickyIdb,stickySession,stickyApi sticky + + UI <--> uiState + stickyMetricsB -.- UI + Network ~~~ stickyMetricsB + + Logic <--> Normalizer + + Normalizer --> Outbound + Outbound --> Data + Inbound --> Normalizer + Data --> Inbound + + Inbound -.- stickyInbound + Outbound -.- stickyOutbound + + Data <--> idb + Data <--> session + idb -.- stickyIdb + session -.- stickySession + + Events <--> UI + Events <--> Logic + Events <--> Data + Events <--> Network + + Network --> Socket --> API --> unk +``` + +## Proposal (Design B) + +NOTE: +This draft proposal suggests one potential front end architecture which may not be chosen. It is not necessarily mutually exclusive with other proposed designs. + +New diffs introduce a paradigm shift in our approach to rendering diffs. +Previously, we had two different approaches to rendering diffs: + +1. Merge requests heavily utilized client-side rendering. +1. All other pages used server-side rendering with sprinkles of JavaScript. + +In merge requests, most of the rendering work was done on the client: + +- The backend would only generate a JSON response with diffs data. +- The client would be responsible for both drawing the diffs and reacting to user input. + +This led to us adopting a +[virtualized scrolling solution](https://github.com/Akryum/vue-virtual-scroller/tree/v1/packages/vue-virtual-scroller) +for client-side rendering, which sped up drawing large diff file lists significantly. + +Unfortunately, this came with downsides of a very high maintenance cost and +[constant bugs](https://gitlab.com/gitlab-org/gitlab/-/issues/427155#note_1607184794). +The user experience also suffered because we couldn't show diffs right away +when you visited a page, and had to wait for the JSON response first. +Lastly, this approach went completely parallel to the server-rendered diffs used on other pages, +which resulted in two completely separate codebases for the diffs. + +The new-diffs approach changes that by doing the following: + +1. Stop using virtualized scrolling for rendering diffs. +1. Move most of the rendering work to the server. +1. Enhance server-rendered HTML on the client. +1. Unify diffs codebase across merge requests and other pages. + +## Design & Implementation Details (Design B) + +NOTE: +This draft proposal suggests one potential front end architecture which may not be chosen. It is not necessarily mutually exclusive with other proposed designs. + +### Metrics + +1. _(no change)_ +1. _(no change)_ +1. _(no change)_ +1. _(no change)_ +1. _(no change)_ +1. When rendering diffs on the server: + - The total server-rendered count should not exceed 5 files. + - It should not try to render empty diffs. (It should render at least 1 file.) + - The total lines of diff code rendered should not exceed 1000 lines. + +### Overview + +New diffs introduce a change in responsibilities for both frontend and backend. + +The backend will: + +1. Prepare diffs data. +1. Highlight diff lines. +1. Render diffs as HTML. +1. Embed diffs metadata into the final response. + +The frontend will: + +1. Enhance existing and future diffs HTML. +1. Fetch and render additional diffs HTML that didn't fit into the page document. + +#### Static and dynamic separation + +To achieve the separation of concerns, we should distinguish between static and dynamic UI on the page: + +- Everything that is static should always be rendered on the server. +- Everything dynamic should be enhanced on the client. + +As an example: a highlighted diff line doesn't change with user input, so we should consider rendering it on the server. + +#### Performance optimizations + +To improve the perceived performance of the page we should implement the following techniques: + +1. Limit the number of diffs rendered on the page at first. +1. Use [HTML streaming](https://gitlab.com/gitlab-org/frontend/rfcs/-/issues/101) + to render the rest of the diffs. + 1. Use Web Components to hook into diff files appearing on the page. +1. Apply `content-visibility` whenever possible to reduce redraw overhead. +1. Render diff discussions asynchronously. diff --git a/doc/architecture/blueprints/object_storage/index.md b/doc/architecture/blueprints/object_storage/index.md index 3f649960554..daafc03941b 100644 --- a/doc/architecture/blueprints/object_storage/index.md +++ b/doc/architecture/blueprints/object_storage/index.md @@ -4,7 +4,7 @@ creation-date: "2021-11-18" authors: [ "@nolith" ] coach: "@glopezfernandez" approvers: [ "@marin" ] -owning-stage: "~devops::data_stores" +owning-stage: "~devops::data stores" participating-stages: [] --- diff --git a/doc/architecture/blueprints/observability_logging/index.md b/doc/architecture/blueprints/observability_logging/index.md index d8259e0a736..bbe15cde58e 100644 --- a/doc/architecture/blueprints/observability_logging/index.md +++ b/doc/architecture/blueprints/observability_logging/index.md @@ -121,7 +121,7 @@ Hence the decision to only support Log objects seems like a boring and simple so Similar to traces, logging data ingestion will be done at the Ingress level. As part of [the forward-auth](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) flow, Traefik will forward the request to Gatekeeper which in turn leverages Redis for counting. This is currently done only for [the ingestion path](https://gitlab.com/gitlab-org/opstrace/opstrace/-/merge_requests/2236). -Please check the MR description for more details on how it works. +Check the MR description for more details on how it works. The read path rate limiting implementation is tracked [here](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/2356). ### Database schema @@ -629,4 +629,4 @@ Long-term, we will need a way to monitor the number of user queries that failed ## Iterations -Please refer to [Observability Group planning epic](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/92) and its linked issues for up-to-date information. +Refer to [Observability Group planning epic](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/92) and its linked issues for up-to-date information. diff --git a/doc/architecture/blueprints/observability_logging/system_overview.png b/doc/architecture/blueprints/observability_logging/system_overview.png Binary files differindex 30c6510c3dc..57299e89512 100644 --- a/doc/architecture/blueprints/observability_logging/system_overview.png +++ b/doc/architecture/blueprints/observability_logging/system_overview.png diff --git a/doc/architecture/blueprints/organization/index.md b/doc/architecture/blueprints/organization/index.md index 49bf18442e9..f9a250e1205 100644 --- a/doc/architecture/blueprints/organization/index.md +++ b/doc/architecture/blueprints/organization/index.md @@ -300,7 +300,7 @@ We are conducting deeper research around this specific problem in [issue 420804] The following iteration plan outlines how we intend to arrive at the Organization MVC. We are following the guidelines for [Experiment, Beta, and Generally Available features](../../../policy/experiment-beta-support.md). -### Iteration 1: Organization Prototype (FY24Q4) +### Iteration 1: [Organization Prototype](https://gitlab.com/groups/gitlab-org/-/epics/10018) (FY24Q2-FY25Q1) In iteration 1, we introduce the concept of an Organization as a way to group top-level Groups together. Support for Organizations does not require any [Cells](../cells/index.md) work, but having them will make all subsequent iterations of Cells simpler. The goal of iteration 1 will be to generate a prototype that can be used by GitLab teams to test basic functionality within an Organization. The prototype contains the following functionality: @@ -314,8 +314,9 @@ In iteration 1, we introduce the concept of an Organization as a way to group to - A User can be part of multiple Organizations. - Users can navigate between the different Organizations they are part of. - Any User within or outside of an Organization can be invited to Groups and Projects contained by the Organization. +- Organizations are not fully isolated. We aim to complete [phase 1 of Organization isolation](https://gitlab.com/groups/gitlab-org/-/epics/11837), with the goal to `define sharding_key` and `desired_sharding_key` rules. -### Iteration 2: Organization MVC Experiment (FY25Q1) +### Iteration 2: [Organization MVC Experiment](https://gitlab.com/groups/gitlab-org/-/epics/10650) (FY25Q2) In iteration 2, an Organization MVC Experiment will be released. We will test the functionality with a select set of customers and improve the MVC based on these learnings. The MVC Experiment contains the following functionality: @@ -325,7 +326,7 @@ In iteration 2, an Organization MVC Experiment will be released. We will test th - Forking across Organizations will be defined. - [Organization Isolation](isolation.md) will be finished to meet the requirements of the initial set of customers -### Iteration 3: Organization MVC Beta (FY25Q1) +### Iteration 3: [Organization MVC Beta](https://gitlab.com/groups/gitlab-org/-/epics/10651) (FY25Q3) In iteration 3, the Organization MVC Beta will be released. @@ -334,9 +335,9 @@ In iteration 3, the Organization MVC Beta will be released. - Organization Owners can create, edit and delete Groups from the Groups overview. - Organization Owners can create, edit and delete Projects from the Projects overview. - The Organization URL path can be changed. -- [Organization Isolation](isolation.md) is available. +- Organizations are fully isolated. We aim to complete [phase 2 of Organization isolation](https://gitlab.com/groups/gitlab-org/-/epics/11838), with the goal to implement isolation constraints. -### Iteration 4: Organization MVC GA (FY25Q2) +### Iteration 4: [Organization MVC GA](https://gitlab.com/groups/gitlab-org/-/epics/10652) (FY25Q3) In iteration 4, the Organization MVC will be rolled out. @@ -346,6 +347,7 @@ After the initial rollout of Organizations, the following functionality will be 1. [Users can transfer existing top-level Groups into Organizations](https://gitlab.com/groups/gitlab-org/-/epics/11711). 1. [Organizations can invite Users](https://gitlab.com/gitlab-org/gitlab/-/issues/420166). +1. Complete [phase 3 of Organization isolation](https://gitlab.com/groups/gitlab-org/-/epics/11839), with the goal to allow customers to move existing namespaces out of the default Organization into a new Organization. 1. Internal visibility will be made available on Organizations that are part of GitLab.com. 1. Restrict inviting Users outside of the Organization. 1. Enterprise Users will be made available at the Organization level. @@ -368,12 +370,14 @@ We propose the following steps to successfully roll out Organizations: - Phase 1: Rollout - Organizations will be rolled out using the concept of a `default Organization`. All existing top-level groups on GitLab.com are already part of this `default Organization`. The Organization UI is feature flagged and can be enabled for a specific set of users initially, and the global user pool at the end of this phase. This way, users will already become familiar with the concept of an Organization and the Organization UI. No features would be impacted by enabling the `default Organization`. See issue [#418225](https://gitlab.com/gitlab-org/gitlab/-/issues/418225) for more details. -- Phase 2: Migrations - - GitLab, the organization, will be the first one to bud off into a separate Organization. We move all top-level groups that belong to GitLab into the new GitLab Organization, including the `gitLab-org` and `gitLab-com` top-level Groups. See issue [#418228](https://gitlab.com/gitlab-org/gitlab/-/issues/418228) for more details. - - Existing customers can create their own Organization. Creation of an Organization remains optional. -- Phase 3: Onboarding changes - - New customers will only have the option to start their journey by creating an Organization. -- Phase 4: Targeted efforts +- Phase 2: Temporary onboarding changes + - New customers who were identified to not need personal namespaces and forking can create new Organizations from scratch. Top-level Groups cannot be migrated yet into a new Organization, so all content must be newly created in an Organization. +- Phase 3: Migration of existing customers + - GitLab, the organization, will be the first one to bud off into a separate Organization. We move all top-level Groups that belong to GitLab into the new GitLab Organization, including the `gitLab-org` and `gitLab-com` top-level Groups. See issue [#418228](https://gitlab.com/gitlab-org/gitlab/-/issues/418228) for more details. + - Once top-level Group transfer from the default Organization to another Organization becomes available, existing customers can create their own Organization and migrate their top-level Groups into it. Creation of an Organization remains optional. +- Phase 4: Permanent onboarding changes + - All new customers will only have the option to start their journey by creating a new Organization. +- Phase 5: Targeted efforts - Organizations are promoted, e.g. via a banner message, targeted conversations with large customers via the CSMs. Creating a separate Organization will remain a voluntary action. - We increase the value proposition of the Organization, for instance by moving billing to the Organization level to provide incentives for more customers to move to a separate Organization. Adoption will be monitored. diff --git a/doc/architecture/blueprints/organization/isolation.md b/doc/architecture/blueprints/organization/isolation.md index 238269c4329..467bd1932bd 100644 --- a/doc/architecture/blueprints/organization/isolation.md +++ b/doc/architecture/blueprints/organization/isolation.md @@ -65,7 +65,7 @@ These are: The major constraint these POCs were trying to overcome was that there is no standard way in the GitLab application or database to even determine what Organization (or Project or namespace) a piece of data belongs to. This means that the first step is to implement a standard way to efficiently find the parent Organization for any model or row in the database. -The proposed solution is ensuring that every single table that exists in the `gitlab_main_cell` and `gitlab_ci_cell` (Cell-local) databases must include a valid sharding key that is either `project_id` or `namespace_id`. +The proposed solution is ensuring that every single table that exists in the `gitlab_main_cell`, `gitlab_ci` and `gitlab_pm` (Cell-local) databases must include a valid sharding key that is a reference to `projects`, `namespaces` or `organizations`. At first we considered enforcing everything to have an `organization_id`, but we determined that this would be too expensive to update for customers that need to migrate large Groups out of the default Organization. The added benefit is that more than half of our tables already have one of these columns. Additionally, if we can't consistently attribute data to a top-level Group, then we won't be able to validate if a top-level Group is safe to be moved to a new Organization. @@ -79,7 +79,7 @@ We can also use these sharding keys to help us decide whether: ## Detailed steps -1. Implement developer facing documentation explaining the requirement to add these sharding keys and how they should choose between `project_id` and `namespace_id`. +1. Implement developer facing documentation explaining the requirement to add these sharding keys and how they should choose. 1. Add a way to declare a sharding key in `db/docs` and automatically populate it for all tables that already have a sharding key 1. Implement automation in our CI pipelines and/or DB migrations that makes it impossible to create new tables without a sharding key. 1. Implement a way for people to declare a desired sharding key in `db/docs` as @@ -107,7 +107,7 @@ We can also use these sharding keys to help us decide whether: automated MRs for the sharding keys that can be automatically inferred and automate creating issues for all the sharding keys that can't be automatically inferred -1. Validate that all existing `project_id` and `namespace_id` columns on all Cell-local tables can reliably be assumed to be the sharding key. This requires assigning issues to teams to confirm that these columns aren't used for some other purpose that would actually not be suitable. If there is an issue with a table we need to migrate and rename these columns, and then add a new `project_id` or `namespace_id` column with the correct sharding key. +1. Validate that all existing sharding key columns on all Cell-local tables can reliably be assumed to be the sharding key. This requires assigning issues to teams to confirm that these columns aren't used for some other purpose that would actually not be suitable. 1. We allow customers to create new Organizations without the option to migrate namespaces into them. All namespaces need to be newly created in their new Organization. 1. Implement new functionality in GitLab similar to the [POC](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131968), which allows a namespace owner to see if their namespace is fully isolated. 1. Implement functionality that allows namespace owners to migrate an existing namespace from one Organization to another. Most likely this will be existing customers that want to migrate their namespace out of the default Organization into a newly created Organization. Only isolated namespaces as implemented in the previous step will be allowed to move. diff --git a/doc/architecture/blueprints/rate_limiting/index.md b/doc/architecture/blueprints/rate_limiting/index.md index 7af50097e97..94a36d721e9 100644 --- a/doc/architecture/blueprints/rate_limiting/index.md +++ b/doc/architecture/blueprints/rate_limiting/index.md @@ -218,7 +218,7 @@ communicate how the responsible usage is defined at a given moment. Because of how GitLab architecture has been built, GitLab Rails application, in most cases, behaves as a central enterprise service bus (ESB) and there are a -few satellite services communicating with it. Services like Container Registry, +few satellite services communicating with it. Services like container registry, GitLab Runners, Gitaly, Workhorse, KAS could use the API to receive a set of application limits those are supposed to enforce. This will still allow us to define all of them in a single place. diff --git a/doc/architecture/blueprints/repository_backups/index.md b/doc/architecture/blueprints/repository_backups/index.md index afd86e4979c..3b79f3fbe96 100644 --- a/doc/architecture/blueprints/repository_backups/index.md +++ b/doc/architecture/blueprints/repository_backups/index.md @@ -59,7 +59,7 @@ This should relieve the major pain points of the existing two strategies: Snapshots rely on cloud platforms to be able to take physical snapshots of the disks that Gitaly and Praefect use to store data. While never officially -recommended this strategy tends to be used once creating or restoring backups +recommended, this strategy tends to be used once creating or restoring backups using `backup.rake` takes too long. Gitaly and Git use lock files and fsync in order to prevent repository diff --git a/doc/architecture/blueprints/runner_tokens/index.md b/doc/architecture/blueprints/runner_tokens/index.md index 7e5ce57dcdc..f2e9d624d20 100644 --- a/doc/architecture/blueprints/runner_tokens/index.md +++ b/doc/architecture/blueprints/runner_tokens/index.md @@ -97,7 +97,7 @@ token in the `--registration-token` argument: | Token type | Behavior | | ---------- | -------- | -| [Registration token](../../../security/token_overview.md#runner-authentication-tokens) | Leverages the `POST /api/v4/runners` REST endpoint to create a new runner, creating a new entry in `config.toml`. | +| [Registration token](../../../security/token_overview.md#runner-authentication-tokens) | Leverages the `POST /api/v4/runners` REST endpoint to create a new runner, creating a new entry in `config.toml` and a `system_id` value in a sidecar file if missing (`.runner_system_id`). | | [Runner authentication token](../../../security/token_overview.md#runner-authentication-tokens) | Leverages the `POST /api/v4/runners/verify` REST endpoint to ensure the validity of the authentication token. Creates an entry in `config.toml` file and a `system_id` value in a sidecar file if missing (`.runner_system_id`). | ### Transition period @@ -329,9 +329,7 @@ enum column created in the `ci_runners` table. ### Runner creation through API Automated runner creation is possible through a new GraphQL mutation and the existing -[`POST /runners` REST API endpoint](../../../api/runners.md#register-a-new-runner). -The difference in the REST API endpoint is that it is modified to accept a request from an -authorized user with a scope (instance, a group, or a project) instead of the registration token. +[`POST /user/runners` REST API endpoint](../../../api/users.md#create-a-runner-linked-to-a-user). These endpoints are only available to users that are [allowed](../../../user/permissions.md#gitlab-cicd-permissions) to create runners at the specified scope. @@ -361,8 +359,9 @@ scope. | Component | Milestone | Issue | Changes | |------------------|----------:|-------|---------| -|GitLab Runner Helm Chart| `%15.10` | Update the Runner Helm Chart to support registration with the authentication token. | -|GitLab Runner Operator| `%15.10` | Update the Runner Operator to support registration with the authentication token. | +| GitLab Runner Helm Chart | `%15.10` | Update the Runner Helm Chart to support registration with the authentication token. | +| GitLab Runner Operator | `%15.10` | Update the Runner Operator to support registration with the authentication token. | +| GitLab Runner Helm Chart | `%16.2` | Add `systemID` to Runner Helm Chart. | ### Stage 3 - Database changes @@ -414,7 +413,7 @@ scope. | Component | Milestone | Changes | |------------------|----------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | GitLab Rails app | `%16.0` | Adapt `register_{group|project}_runner` permissions to take [application setting](https://gitlab.com/gitlab-org/gitlab/-/issues/386712) in consideration. | -| GitLab Rails app | `%16.1` | Make [`POST /api/v4/runners` endpoint](../../../api/runners.md#register-a-new-runner) permanently return `HTTP 410 Gone` if either `allow_runner_registration_token` setting disables registration tokens.<br/>A future v5 version of the API should return `HTTP 404 Not Found`. | +| GitLab Rails app | `%16.1` | Make [`POST /api/v4/runners` endpoint](../../../api/runners.md#create-an-instance-runner) permanently return `HTTP 410 Gone` if either `allow_runner_registration_token` setting disables registration tokens.<br/>A future v5 version of the API should return `HTTP 404 Not Found`. | | GitLab Rails app | `%16.1` | Add runner group metadata to the runner list. | | GitLab Rails app | | Add UI to allow disabling use of registration tokens in top-level group settings. | | GitLab Rails app | | Hide legacy UI showing registration with a registration token, if it disabled on in top-level group settings or by admins. | @@ -441,7 +440,7 @@ scope. ## FAQ -Please follow [the user documentation](../../../ci/runners/new_creation_workflow.md). +Follow [the user documentation](../../../ci/runners/new_creation_workflow.md). ## Status diff --git a/doc/architecture/blueprints/secret_detection/decisions/001_use_ruby_push_check_approach_within_monolith.md b/doc/architecture/blueprints/secret_detection/decisions/001_use_ruby_push_check_approach_within_monolith.md new file mode 100644 index 00000000000..c81e6748e70 --- /dev/null +++ b/doc/architecture/blueprints/secret_detection/decisions/001_use_ruby_push_check_approach_within_monolith.md @@ -0,0 +1,32 @@ +--- +owning-stage: "~devops::secure" +description: "GitLab Secret Detection ADR 001: Use Ruby Push Check approach within monolith" +--- + +# GitLab Secret Detection ADR 001: Use Ruby Push Check approach within monolith + +## Context + +There are a number of concerns around the performance of secret detection using a regex-based approach at scale. The primary considerations include transfer latency between nodes and both CPU and memory bloat. These concerns manifested in two ways: the language to be used for performing regex matching and the deployment architecture. + +The original discussion in [the exploration issue](https://gitlab.com/gitlab-org/gitlab/-/issues/428499) covers many of these concerns and background. + +### Implementation language + +The two primary languages considered were Ruby and Go. + +The choice to use other languages (such as C++) for implementation was discarded in favour of Ruby and Go due to team familiarity, speed of deployment, and portability. See [this benchmarking issue](https://gitlab.com/gitlab-org/gitlab/-/issues/423832) for performance comparisons between the two. + +### Deployment architecture + +Several options were considered for deployments: directly embedding the logic within the Rails monolith's Push Check execution path, placement as a sidecar within a Rails node deployment, placement as a sidecar within a Gitaly node as a [server-side hook](../../../../administration/server_hooks.md), and deployment as a standalone service. + +## Decision + +For the initial iteration around blocking push events using a prereceive integration, the decision was made to proceed with Ruby-based approach, leveraging `re2` for performant regex processing. Additionally, the decision was made to integrate the logic directly into the monolith rather than as a discrete service or server-side hook within Gitaly. + +A Gitaly server-side hook would have performance benefits around minimal transfer latency for Git blobs between scanning service and Gitaly blob storage. However, an extra request would be needed between Gitaly and the Rails application to contextualize the scan. Additionally, the current hook architecture is [discouraged and work is planned to migrate towards a new plugin architecture in the near future](https://gitlab.com/gitlab-org/gitaly/-/issues/5642). + +The Ruby Push Check approach follows a clear execution plan to achieve delivery by anticipated timeline and is more closely aligned with the long-term direction of platform-wide scanning. For example, future scanning of issuables will require execution within the trust boundary of the Rails application rather than Gitaly context. This approach, however, has raised concerns around elevated memory usage within the Rails application leading to availability concerns. This direction may also require migrating towards Gitaly's new plugin architecture in the future once the timeline is known. + +A standalone service may be considered in the future but requires considerations of a technical approach that should be better informed by data gathered during [pre-production profiling](https://gitlab.com/gitlab-org/gitlab/-/issues/428499). diff --git a/doc/architecture/blueprints/secret_detection/index.md b/doc/architecture/blueprints/secret_detection/index.md index 76bf6dd4088..fb77fffee40 100644 --- a/doc/architecture/blueprints/secret_detection/index.md +++ b/doc/architecture/blueprints/secret_detection/index.md @@ -61,10 +61,47 @@ As a long-term priority we should consider unifying the management of the two secret types however that work is out of scope for the current blueprints goals, which remain focused on active detection. +### Target types + +Target object types refer to the scanning targets prioritized for detection of leaked secrets. + +In order of priority this includes: + +1. non-binary Git blobs +1. job logs +1. issuable creation (issues, MRs, epics) +1. issuable updates (issues, MRs, epics) +1. issuable comments (issues, MRs, epics) + +Targets out of scope for the initial phases include: + +- Media types (JPEG, PDF, ...) +- Snippets +- Wikis +- Container images + +### Token types + +The existing Secret Detection configuration covers ~100 rules across a variety +of platforms. To reduce total cost of execution and likelihood of false positives +the dedicated service targets only well-defined tokens. A well-defined token is +defined as a token with a precise definition, most often a fixed substring prefix or +suffix and fixed length. + +Token types to identify in order of importance: + +1. Well-defined GitLab tokens (including Personal Access Tokens and Pipeline Trigger Tokens) +1. Verified Partner tokens (including AWS) +1. Remainder tokens currently included in Secret Detection CI configuration + ## Proposal +### Decisions + +- [001: Use Ruby Push Check approach within monolith](decisions/001_use_ruby_push_check_approach_within_monolith.md) + The first iteration of the experimental capability will feature a blocking -pre-receive hook implemented within the Rails application. This iteration +pre-receive hook implemented in the Rails application. This iteration will be released in an experimental state to select users and provide opportunity for the team to profile the capability before considering extraction into a dedicated service. @@ -89,10 +126,41 @@ as self-managed instances. - Performance of scanning against volume of domain objects (such as push frequency) - Queueing of scan requests +### Transfer optimizations for large Git data blobs + +As described in [Gitaly's upload-pack traffic blueprint](../gitaly_handle_upload_pack_in_http2_server/index.md#git-data-transfer-optimization-with-sidechannel), we have faced problems in the past handling large data transfers over gRPC. This could be a concern as we expand secret detection to large blob sizes to increase coverage over leaked secrets. We expect to rollout pre-receive scanning with a 1 megabyte blob size limit which should be well within boundaries. From [Protobuffers' documentation](https://protobuf.dev/programming-guides/techniques/#large-data): + +> As a general rule of thumb, if you are dealing in messages larger than a megabyte each, it may be time to consider an alternate strategy. + +In expansion phases we must explore chunking or alternative strategies like the optimized sidechannel approach used by Gitaly. + ## Design and implementation details +The implementation of the secret scanning service is highly dependent on the outcomes of our benchmarking +and capacity planning against both GitLab.com and our +[Reference Architectures](../../../administration/reference_architectures/index.md). +As the scanning capability must be an on-by-default component of both our SaaS and self-managed +instances [the PoC](#iterations), the deployment characteristics must be considered to determine whether +this is a standalone component or executed as a subprocess of the existing Sidekiq worker fleet +(similar to the implementation of our Elasticsearch indexing service). + +Similarly, the scan target volume will require a robust and scalable enqueueing system to limit resource consumption. + +The detection capability relies on a multiphase rollout, from an experimental component implemented directly in the monolith to a standalone service capable of scanning text blobs generically. + +See [technical discovery](https://gitlab.com/gitlab-org/gitlab/-/issues/376716) +for further background exploration. + +See [this thread](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105142#note_1194863310) +for past discussion around scaling approaches. + +### Phase 1 - Ruby pushcheck pre-receive integration + The critical paths as outlined under [goals above](#goals) cover two major object -types: Git blobs (corresponding to push events) and arbitrary text blobs. +types: Git text blobs (corresponding to push events) and arbitrary text blobs. In Phase 1, +we focus entirely on Git text blobs. + +This phase will be considered "Experimental" with limited availability for customer opt-in, through instance level application settings. The detection flow for push events relies on subscribing to the PreReceive hook to scan commit data using the [PushCheck interface](https://gitlab.com/gitlab-org/gitlab/blob/3f1653f5706cd0e7bbd60ed7155010c0a32c681d/lib/gitlab/checks/push_check.rb). This `SecretScanningService` @@ -100,6 +168,185 @@ service fetches the specified blob contents from Gitaly, scans the commit contents, and rejects the push when a secret is detected. See [Push event detection flow](#push-event-detection-flow) for sequence. +In the case of a push detection, the commit is rejected inline and error returned to the end user. + +#### High-Level Architecture + +The Phase 1 architecture involves no additional components and is entirely encapsulated in the Rails application server. This provides a rapid deployment with tight integration within auth boundaries and no distribution coordination. + +The primary drawback relies on resource utilization, adding additional CPU, memory, transfer volume, and request latency to existing application nodes. + +```plantuml +@startuml Phase2 +skinparam linetype ortho + +card "**External Load Balancer**" as elb #6a9be7 + +together { + card "**GitLab Rails**" as gitlab #32CD32 + card "**Gitaly**" as gitaly #FF8C00 + card "**PostgreSQL**" as postgres #4EA7FF + card "**Redis**" as redis #FF6347 + card "**Sidekiq**" as sidekiq #ff8dd1 +} +} + +gitlab -[#32CD32]--> gitaly +gitlab -[#32CD32]--> postgres +gitlab -[#32CD32]--> redis +gitlab -[#32CD32]--> sidekiq + +elb -[#6a9be7]-> gitlab + +gitlab .[#32CD32]----> postgres +sidekiq .[#ff8dd1]----> postgres + +@enduml +``` + +#### Push event detection flow + +```mermaid +sequenceDiagram + autonumber + actor User + User->>+Workhorse: git push with-secret + Workhorse->>+Gitaly: tcp + Gitaly->>+Rails: PreReceive + Rails->>-Gitaly: ListAllBlobs + Gitaly->>-Rails: ListAllBlobsResponse + + Rails->>+GitLabSecretDetection: Scan(blob) + GitLabSecretDetection->>-Rails: found + + Rails->>User: rejected: secret found + + User->>+Workhorse: git push without-secret + Workhorse->>+Gitaly: tcp + Gitaly->>+Rails: PreReceive + Rails->>-Gitaly: ListAllBlobs + Gitaly->>-Rails: ListAllBlobsResponse + + Rails->>+GitLabSecretDetection: Scan(blob) + GitLabSecretDetection->>-Rails: not_found + + Rails->>User: accepted +``` + +### Phase 2 - Standalone pre-receive service + +The critical paths as outlined under [goals above](#goals) cover two major object +types: Git text blobs (corresponding to push events) and arbitrary text blobs. In Phase 2, +we focus entirely on Git text blobs. + +This phase emphasizes scaling the service outside of the monolith for general availability and to allow +an on-by-default behavior. The architecture is adapted to provide an isolated and independently +scalable service outside of the Rails monolith. + +In the case of a push detection, the commit is rejected inline and error returned to the end user. + +#### High-Level Architecture + +The Phase 2 architecture involves extracting the secret detection logic into a standalone service +which communicates directly with both the Rails application and Gitaly. This provides a means to scale +the secret detection nodes independently, and reduce resource usage overhead on the rails application. + +Scans still runs synchronously as a (potentially) blocking pre-receive transaction. + +Note that the node count is purely illustrative, but serves to emphasize the independent scaling requirements for the scanning service. + +```plantuml + +@startuml Phase2 +skinparam linetype ortho + +card "**External Load Balancer**" as elb #6a9be7 +card "**Internal Load Balancer**" as ilb #9370DB + +together { + collections "**GitLab Rails** x3" as gitlab #32CD32 + collections "**Sidekiq** x3" as sidekiq #ff8dd1 +} + +together { + collections "**Consul** x3" as consul #e76a9b +} + +card "SecretScanningService Cluster" as prsd_cluster { + collections "**SecretScanningService** x5" as prsd #FF8C00 +} + +card "Gitaly Cluster" as gitaly_cluster { + collections "**Gitaly** x3" as gitaly #FF8C00 +} + +card "Database" as database { + collections "**PGBouncer** x3" as pgbouncer #4EA7FF +} + +elb -[#6a9be7]-> gitlab + +gitlab -[#32CD32,norank]--> ilb +gitlab .[#32CD32]----> database +gitlab -[hidden]-> consul + +sidekiq -[#ff8dd1,norank]--> ilb +sidekiq .[#ff8dd1]----> database +sidekiq -[hidden]-> consul + +ilb -[#9370DB]--> prsd_cluster +ilb -[#9370DB]--> gitaly_cluster +ilb -[#9370DB]--> database +ilb -[hidden]u-> consul + +consul .[#e76a9b]u-> gitlab +consul .[#e76a9b]u-> sidekiq +consul .[#e76a9b]-> database +consul .[#e76a9b]-> gitaly_cluster +consul .[#e76a9b]-> prsd_cluster + +@enduml +``` + +#### Push event detection flow + +```mermaid +sequenceDiagram + autonumber + actor User + User->>+Workhorse: git push with-secret + Workhorse->>+Gitaly: tcp + Gitaly->>+GitLabSecretDetection: PreReceive + GitLabSecretDetection->>-Gitaly: ListAllBlobs + Gitaly->>-GitLabSecretDetection: ListAllBlobsResponse + + Gitaly->>+GitLabSecretDetection: PreReceive + + GitLabSecretDetection->>GitLabSecretDetection: Scan(blob) + GitLabSecretDetection->>-Gitaly: found + + Gitaly->>+Rails: PreReceive + + Rails->>User: rejected: secret found + + User->>+Workhorse: git push without-secret + Workhorse->>+Gitaly: tcp + Gitaly->>+GitLabSecretDetection: PreReceive + GitLabSecretDetection->>-Gitaly: ListAllBlobs + Gitaly->>-GitLabSecretDetection: ListAllBlobsResponse + + Gitaly->>+GitLabSecretDetection: PreReceive + + GitLabSecretDetection->>GitLabSecretDetection: Scan(blob) + GitLabSecretDetection->>-Gitaly: not_found + + Gitaly->>+Rails: PreReceive + + Rails->>User: accepted +``` + +### Phase 3 - Expansion beyond pre- + The detection flow for arbitrary text blobs, such as issue comments, relies on subscribing to `Notes::PostProcessService` (or equivalent service) to enqueue Sidekiq requests to the `SecretScanningService` to process the text blob by object type @@ -117,8 +364,44 @@ In any other case of detection, the Rails application manually creates a vulnera using the `Vulnerabilities::ManuallyCreateService` to surface the finding in the existing Vulnerability Management UI. -See [technical discovery](https://gitlab.com/gitlab-org/gitlab/-/issues/376716) -for further background exploration. +#### Architecture + +There is no change to the architecture defined in Phase 2, however the individual load requirements may require scaling up the node counts for the detection service. + +#### Detection flow + +There is no change to the push event detection flow defined in Phase 2, however the added capability to scan +arbitary text blobs directly from Rails allows us to emulate a pre-receive behavior for issuable creations, +as well (see [target types](#target-types) for priority object types). + +```mermaid +sequenceDiagram + autonumber + actor User + User->>+Workhorse: git push with-secret + Workhorse->>+Gitaly: tcp + Gitaly->>+GitLabSecretDetection: PreReceive + GitLabSecretDetection->>-Gitaly: ListAllBlobs + Gitaly->>-GitLabSecretDetection: ListAllBlobsResponse + + Gitaly->>+GitLabSecretDetection: PreReceive + + GitLabSecretDetection->>GitLabSecretDetection: Scan(blob) + GitLabSecretDetection->>-Gitaly: found + + Gitaly->>+Rails: PreReceive + + Rails->>User: rejected: secret found + + User->>+Workhorse: POST issuable with-secret + Workhorse->>+Rails: tcp + Rails->>+GitLabSecretDetection: PreReceive + + GitLabSecretDetection->>GitLabSecretDetection: Scan(blob) + GitLabSecretDetection->>-Rails: found + + Rails->>User: rejected: secret found +``` ### Target types @@ -151,7 +434,7 @@ Token types to identify in order of importance: 1. Well-defined GitLab tokens (including Personal Access Tokens and Pipeline Trigger Tokens) 1. Verified Partner tokens (including AWS) -1. Remainder tokens currently included in Secret Detection CI configuration +1. Remainder tokens included in Secret Detection CI configuration ### Detection engine @@ -160,57 +443,13 @@ for all secret scanning in pipeline contexts. By using its `--no-git` configurat we can scan arbitrary text blobs outside of a repository context and continue to use it for non-pipeline scanning. -In the case of PreReceive detection, we rely on a combination of keyword/substring matches +In the case of pre-receive detection, we rely on a combination of keyword/substring matches for pre-filtering and `re2` for regex detections. See [spike issue](https://gitlab.com/gitlab-org/gitlab/-/issues/423832) for initial benchmarks Changes to the detection engine are out of scope until benchmarking unveils performance concerns. Notable alternatives include high-performance regex engines such as [Hyperscan](https://github.com/intel/hyperscan) or it's portable fork [Vectorscan](https://github.com/VectorCamp/vectorscan). -### High-level architecture - -The implementation of the secret scanning service is highly dependent on the outcomes of our benchmarking -and capacity planning against both GitLab.com and our -[Reference Architectures](../../../administration/reference_architectures/index.md). -As the scanning capability must be an on-by-default component of both our SaaS and self-managed -instances [the PoC](#iterations), the deployment characteristics must be considered to determine whether -this is a standalone component or executed as a subprocess of the existing Sidekiq worker fleet -(similar to the implementation of our Elasticsearch indexing service). - -Similarly, the scan target volume will require a robust and scalable enqueueing system to limit resource consumption. - -See [this thread](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105142#note_1194863310) -for past discussion around scaling approaches. - -### Push event detection flow - -```mermaid -sequenceDiagram - autonumber - actor User - User->>+Workhorse: git push with-secret - Workhorse->>+Gitaly: tcp - Gitaly->>+Rails: PreReceive - Rails->>-Gitaly: ListAllBlobs - Gitaly->>-Rails: ListAllBlobsResponse - - Rails->>+GitLabSecretDetection: Scan(blob) - GitLabSecretDetection->>-Rails: found - - Rails->>User: rejected: secret found - - User->>+Workhorse: git push without-secret - Workhorse->>+Gitaly: tcp - Gitaly->>+Rails: PreReceive - Rails->>-Gitaly: ListAllBlobs - Gitaly->>-Rails: ListAllBlobsResponse - - Rails->>+GitLabSecretDetection: Scan(blob) - GitLabSecretDetection->>-Rails: not_found - - Rails->>User: OK -``` - ## Iterations - ✓ Define [requirements for detection coverage and actions](https://gitlab.com/gitlab-org/gitlab/-/issues/376716) diff --git a/doc/architecture/blueprints/secret_manager/secrets-manager-overview.png b/doc/architecture/blueprints/secret_manager/secrets-manager-overview.png Binary files differindex 4e3985cc30e..c6c51b05164 100644 --- a/doc/architecture/blueprints/secret_manager/secrets-manager-overview.png +++ b/doc/architecture/blueprints/secret_manager/secrets-manager-overview.png diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index f690dd3ca24..55f18987490 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Caching in GitLab CI/CD **(FREE ALL)** @@ -45,7 +45,7 @@ can't link to files outside it. To ensure maximum availability of the cache, do one or more of the following: -- [Tag your runners](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) and use the tag on jobs +- [Tag your runners](../runners/configure_runners.md#control-jobs-that-a-runner-can-run) and use the tag on jobs that share the cache. - [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-project-runner-from-being-enabled-for-other-projects). - [Use a `key`](../yaml/index.md#cachekey) that fits your workflow. For example, @@ -505,7 +505,7 @@ is stored on the machine where GitLab Runner is installed. The location also dep | Runner executor | Default path of the cache | | ---------------------- | ------------------------- | | [Shell](https://docs.gitlab.com/runner/executors/shell.html) | Locally, under the `gitlab-runner` user's home directory: `/home/gitlab-runner/cache/<user>/<project>/<cache-key>/cache.zip`. | -| [Docker](https://docs.gitlab.com/runner/executors/docker.html) | Locally, under [Docker volumes](https://docs.gitlab.com/runner/executors/docker.html#the-builds-and-cache-storage): `/var/lib/docker/volumes/<volume-id>/_data/<user>/<project>/<cache-key>/cache.zip`. | +| [Docker](https://docs.gitlab.com/runner/executors/docker.html) | Locally, under [Docker volumes](https://docs.gitlab.com/runner/executors/docker.html#configure-directories-for-the-container-build-and-cache): `/var/lib/docker/volumes/<volume-id>/_data/<user>/<project>/<cache-key>/cache.zip`. | | [Docker Machine](https://docs.gitlab.com/runner/executors/docker_machine.html) (autoscale runners) | The same as the Docker executor. | If you use cache and artifacts to store the same path in your jobs, the cache might @@ -633,7 +633,7 @@ The next time the pipeline runs, the cache is stored in a different location. You can clear the cache in the GitLab UI: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Build > Pipelines**. +1. Select **Build > Pipelines**. 1. In the upper-right corner, select **Clear runner caches**. On the next commit, your CI/CD jobs use a new cache. diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index 454266942f6..d84ff3550bd 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab ChatOps **(FREE ALL)** @@ -103,7 +102,7 @@ ls: ## Trigger a CI/CD job using ChatOps -Prerequisite: +Prerequisites: - You must have at least the Developer role for the project. - The project is configured to use a slash command integration. diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index 1820cf77841..0dbc165e5ee 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitLab CI/CD with a Bitbucket Cloud repository **(PREMIUM ALL)** @@ -15,9 +14,8 @@ GitLab CI/CD can be used with Bitbucket Cloud by: To use GitLab CI/CD with a Bitbucket Cloud repository: 1. In GitLab, create a project: - 1. On the left sidebar, select **Search or go to**. - 1. Select **View all my projects**. - 1. On the right of the page, select **New project**. + + 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Run CI/CD for external repository**. 1. Select **Repository by URL**. 1. Fill in the fields with information from the repository in Bitbucket: diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index bc61990fcd8..5c57cb1d393 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitLab CI/CD with a GitHub repository **(PREMIUM ALL)** @@ -34,9 +33,7 @@ repositories: `repo` and `admin:repo_hook` so that GitLab can access your project, update commit statuses, and create a web hook to notify GitLab of new commits. 1. In GitLab, create a project: - 1. On the left sidebar, select **Search or go to**. - 1. Select **View all my projects**. - 1. On the right of the page, select **New project**. + 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Run CI/CD for external repository**. 1. Select **GitHub**. 1. For **Personal access token**, paste the token. @@ -63,9 +60,7 @@ To manually enable GitLab CI/CD for your repository: 1. Enter a **Token description** and update the scope to allow `repo` so that GitLab can access your project and update commit statuses. 1. In GitLab, create a project: - 1. On the left sidebar, select **Search or go to**. - 1. Select **View all my projects**. - 1. Select **New project**. + 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Run CI/CD for external repository** and **Repository by URL**. 1. In the **Git repository URL** field, enter the HTTPS URL for your GitHub repository. If your project is private, use the personal access token you just created for authentication. diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 76996294a96..dbe56edce7e 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD for external repositories **(PREMIUM ALL)** @@ -18,15 +17,13 @@ external repository to get the benefits of GitLab CI/CD. Connecting an external repository sets up [repository mirroring](../../user/project/repository/mirror/index.md) and creates a lightweight project with issues, merge requests, wiki, and snippets disabled. These features -[can be re-enabled later](../../user/project/settings/index.md#configure-project-features-and-permissions). +[can be re-enabled later](../../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions). ## Connect to an external repository To connect to an external repository: -1. On the left sidebar, select **Search or go to**. -1. Select **View all my projects**. -1. Select **New project**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Run CI/CD for external repository**. 1. Select **GitHub** or **Repository by URL**. 1. Complete the fields. diff --git a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md index 2a73184eb7f..b80bbbc5c98 100644 --- a/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md +++ b/doc/ci/cloud_deployment/ecs/deploy_to_aws_ecs.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to Amazon Elastic Container Service **(FREE ALL)** @@ -39,32 +39,26 @@ For the first step here, you create a demo application from a project template. Use a GitLab project template to get started. As the name suggests, these projects provide a bare-bones application built on some well-known frameworks. -1. In GitLab, select the plus icon (**{plus-square}**) at the top of the navigation bar, and select - **New project**. - +1. In GitLab on the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create from template**, where you can choose from a Ruby on Rails, Spring, or NodeJS Express project. For this guide, use the Ruby on Rails template. - -  - 1. Give your project a name. In this example, it's named `ecs-demo`. Make it public so that you can take advantage of the features available in the [GitLab Ultimate plan](https://about.gitlab.com/pricing/). - 1. Select **Create project**. Now that you created a demo project, you must containerize the application and push it to the container registry. -### Push a containerized application image to GitLab Container Registry +### Push a containerized application image to GitLab container registry [ECS](https://aws.amazon.com/ecs/) is a container orchestration service, meaning that you must provide a containerized application image during the infrastructure build. To do so, you can use GitLab [Auto Build](../../../topics/autodevops/stages.md#auto-build) and [Container Registry](../../../user/packages/container_registry/index.md). -1. Go to **ecs-demo** project on GitLab. -1. Select **Setup up CI/CD**. It brings you to a `.gitlab-ci.yml` +1. On the left sidebar, select **Search or go to** and find your `ecs-demo` project. +1. Select **Set up CI/CD**. It brings you to a `.gitlab-ci.yml` creation form. 1. Copy and paste the following content into the empty `.gitlab-ci.yml`. This defines a pipeline for continuous deployment to ECS. @@ -75,7 +69,7 @@ and [Container Registry](../../../user/packages/container_registry/index.md). ``` 1. Select **Commit Changes**. It automatically triggers a new pipeline. In this pipeline, the `build` - job containerizes the application and pushes the image to [GitLab Container Registry](../../../user/packages/container_registry/index.md). + job containerizes the application and pushes the image to [GitLab container registry](../../../user/packages/container_registry/index.md).  @@ -106,7 +100,7 @@ is a specification about how the application image is started by an [ECS service 1. Select **Container Definitions > Add container**. This opens a container registration form. 1. Set `web` to **Container name**. 1. Set `registry.gitlab.com/<your-namespace>/ecs-demo/master:latest` to **Image**. - Alternatively, you can copy and paste the image path from the [GitLab Container Registry page](#push-a-containerized-application-image-to-gitlab-container-registry). + Alternatively, you can copy and paste the image path from the [GitLab container registry page](#push-a-containerized-application-image-to-gitlab-container-registry).  @@ -184,7 +178,7 @@ Now, the demo application is accessible from the internet. In this guide, HTTPS/SSL is **not** configured. You can access to the application through HTTP only (for example, `http://<ec2-ipv4-address>`). -## Setup Continuous Deployment from GitLab +## Set up Continuous Deployment from GitLab Now that you have an application running on ECS, you can set up continuous deployment from GitLab. @@ -213,7 +207,7 @@ Do not share the secret access key in a public place. You must save it in a secu You can register the access information in [GitLab CI/CD Variables](../../variables/index.md). These variables are injected into the pipeline jobs and can access the ECS API. -1. Go to **ecs-demo** project on GitLab. +1. On the left sidebar, select **Search or go to** and find your `ecs-demo` project. 1. Go to **Settings > CI/CD > Variables**. 1. Select **Add Variable** and set the following key-value pairs. @@ -230,8 +224,8 @@ These variables are injected into the pipeline jobs and can access the ECS API. Change a file in the project and see if it's reflected in the demo application on ECS: -1. Go to **ecs-demo** project on GitLab. -1. Open the file at **app > views > welcome > `index.html.erb`**. +1. On the left sidebar, select **Search or go to** and find your `ecs-demo` project. +1. Open the `app/views/welcome/index.html.erb` file. 1. Select **Edit**. 1. Change the text to `You're on ECS!`. 1. Select **Commit Changes**. This automatically triggers a new pipeline. Wait until it finishes. diff --git a/doc/ci/cloud_deployment/ecs/img/rails-template.png b/doc/ci/cloud_deployment/ecs/img/rails-template.png Binary files differdeleted file mode 100644 index 02c67f8dd21..00000000000 --- a/doc/ci/cloud_deployment/ecs/img/rails-template.png +++ /dev/null diff --git a/doc/ci/cloud_deployment/heroku.md b/doc/ci/cloud_deployment/heroku.md index 5cb6682debd..43a3b1f57e6 100644 --- a/doc/ci/cloud_deployment/heroku.md +++ b/doc/ci/cloud_deployment/heroku.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitLab CI/CD to deploy to Heroku diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index 16bfced9c34..14149aa6446 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to AWS from GitLab CI/CD **(FREE ALL)** @@ -61,7 +60,7 @@ deploy: GitLab provides a Docker image that includes the AWS CLI: -- Images are hosted in the GitLab Container Registry. The latest image is +- Images are hosted in the GitLab container registry. The latest image is `registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest`. - [Images are stored in a GitLab repository](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws). @@ -102,7 +101,7 @@ To deploy to your ECS cluster: | `CI_AWS_ECS_CLUSTER` | The name of the AWS ECS cluster that you're targeting for your deployments. | | `CI_AWS_ECS_SERVICE` | The name of the targeted service tied to your AWS ECS cluster. Ensure that this variable is scoped to the appropriate environment (`production`, `staging`, `review/*`). | | `CI_AWS_ECS_TASK_DEFINITION` | If the task definition is in ECS, the name of the task definition tied to the service. | - | `CI_AWS_ECS_TASK_DEFINITION_FILE` | If the task definition is a JSON file in GitLab, the filename, including the path. For example, `ci/aws/my_task_definition.json`. If the name of the task definition in your JSON file is the same name as an existing task definition in ECS, then a new revision is created when CI/CD runs. Otherwise, a brand new task definition is created, starting at revision 1. | + | `CI_AWS_ECS_TASK_DEFINITION_FILE` | If the task definition is a JSON file in GitLab, the file name, including the path. For example, `ci/aws/my_task_definition.json`. If the name of the task definition in your JSON file is the same name as an existing task definition in ECS, then a new revision is created when CI/CD runs. Otherwise, a brand new task definition is created, starting at revision 1. | WARNING: If you define both `CI_AWS_ECS_TASK_DEFINITION_FILE` and `CI_AWS_ECS_TASK_DEFINITION`, @@ -120,7 +119,7 @@ To deploy to your ECS cluster: 1. Commit and push your updated `.gitlab-ci.yml` to your project's repository. -Your application Docker image is rebuilt and pushed to the GitLab Container Registry. +Your application Docker image is rebuilt and pushed to the GitLab container registry. If your image is located in a private registry, make sure your task definition is [configured with a `repositoryCredentials` attribute](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html). diff --git a/doc/ci/cloud_services/aws/index.md b/doc/ci/cloud_services/aws/index.md index dd36da86cca..b6086ed3543 100644 --- a/doc/ci/cloud_services/aws/index.md +++ b/doc/ci/cloud_services/aws/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect in AWS to retrieve temporary credentials **(FREE ALL)** diff --git a/doc/ci/cloud_services/azure/index.md b/doc/ci/cloud_services/azure/index.md index b26533562f4..d3bd8e187ba 100644 --- a/doc/ci/cloud_services/azure/index.md +++ b/doc/ci/cloud_services/azure/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect in Azure to retrieve temporary credentials **(FREE ALL)** diff --git a/doc/ci/cloud_services/google_cloud/index.md b/doc/ci/cloud_services/google_cloud/index.md index fd8aca7045c..b38566309c9 100644 --- a/doc/ci/cloud_services/google_cloud/index.md +++ b/doc/ci/cloud_services/google_cloud/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect with GCP Workload Identity Federation **(FREE ALL)** diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md index 87984c424c4..17d967e7a0d 100644 --- a/doc/ci/cloud_services/index.md +++ b/doc/ci/cloud_services/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect to cloud services **(FREE ALL)** @@ -95,13 +95,12 @@ The condition is validated against the JWT to create a trust specifically agains - Subject or `sub`: A concatenation of metadata describing the GitLab CI/CD workflow including the group, project, branch, and tag. The `sub` field is in the following format: - `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` -| Filter type | Example | -|--------------------------------------|---------| -| Filter to main branch | `project_path:mygroup/myproject:ref_type:branch:ref:main` | -| Filter to any branch | Wildcard supported. `project_path:mygroup/myproject:ref_type:branch:ref:*` | -| Filter to specific project | `project_path:mygroup/myproject:ref_type:branch:ref:main` | -| Filter to all projects under a group | Wildcard supported. `project_path:mygroup/*:ref_type:branch:ref:main` | -| Filter to a Git tag | Wildcard supported. `project_path:mygroup/*:ref_type:tag:ref:1.0` | +| Filter type | Example | +|----------------------------------------------------|---------| +| Filter to any branch | Wildcard supported. `project_path:mygroup/myproject:ref_type:branch:ref:*` | +| Filter to specific project, main branch | `project_path:mygroup/myproject:ref_type:branch:ref:main` | +| Filter to all projects under a group | Wildcard supported. `project_path:mygroup/*:ref_type:branch:ref:main` | +| Filter to a Git tag | Wildcard supported. `project_path:mygroup/*:ref_type:tag:ref:1.0` | ## OIDC authorization with your cloud provider diff --git a/doc/ci/components/catalog.md b/doc/ci/components/catalog.md index 36ed7065e1c..8a7c333b5db 100644 --- a/doc/ci/components/catalog.md +++ b/doc/ci/components/catalog.md @@ -1,49 +1,11 @@ --- -stage: Verify -group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '/ee/ci/components/#cicd-catalog' +remove_date: '2024-02-24' --- -# CI/CD catalog **(PREMIUM ALL EXPERIMENT)** +This document was moved to [CI/CD components](index.md#cicd-catalog). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407249) in GitLab 16.1. - -The CI/CD catalog is a list of [components repositories](index.md#components-repository), -each containing resources that you can add to your CI/CD pipelines. - -Each top level namespace has its own catalog, which contains all the releases from -components repositories hosted under it. You can create components repositories anywhere -under the desired top level namespace and the released components are available to -all projects in that namespace. - -## Add a components repository to the Catalog - -After components are added to a components repository, they can immediately be [used](index.md#use-a-component-in-a-cicd-configuration) -to build pipelines in other projects. - -However, the repository is not discoverable. You must set the project as a catalog resource -for it to be visible in the CI/CD Catalog, then other users can discover it. You should only set a repository as a catalog resource when the components are ready for usage. - -To set a project as a catalog resource: - -1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Scroll down to **CI/CD Catalog resource** and select the toggle to mark the project as a catalog resource. - -Ensure the project has a clear [description](../../user/project/settings/index.md#edit-project-name-and-description), -as the project description is displayed in the component list in the catalog. - -NOTE: -This action is not reversible, and the -component is always visible in the Catalog unless the repository is deleted. If a component has a bug or other issue, you can [create a new release](index.md#release-a-component) with an updated version. - -After the repository is set as a components repository, it appears in the CI/CD Catalog of the namespace. - -## View available components in the CI/CD Catalog - -To view the components available to your project from the CI/CD Catalog: - -1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Build > Pipeline Editor**. -1. Select **Browse CI/CD Catalog**. +<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/ci/components/index.md b/doc/ci/components/index.md index 3d46ec5bbd5..e7c286a507b 100644 --- a/doc/ci/components/index.md +++ b/doc/ci/components/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD components **(FREE ALL BETA)** @@ -11,31 +11,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Feature flag `ci_namespace_catalog_experimental` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/394772) in GitLab 16.3. > - [Moved](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/130824) to [Beta status](../../policy/experiment-beta-support.md) in GitLab 16.6. -A CI/CD component is a reusable single pipeline configuration unit. Use them to compose an entire pipeline configuration or a small part of a larger pipeline. +A CI/CD component is a reusable single pipeline configuration unit. Use components +to create a small part of a larger pipeline, or even to compose a complete pipeline configuration. -A component can optionally take [input parameters](../yaml/inputs.md). +A component can be configured with [input parameters](../yaml/inputs.md) for more +dynamic behavior. -CI/CD components are similar to the other kinds of [configuration added with the `include` keyword](../yaml/includes.md), but have several advantages: +CI/CD components are similar to the other kinds of [configuration added with the `include` keyword](../yaml/includes.md), +but have several advantages: +- Components can be listed in the [CI/CD Catalog](#cicd-catalog). - Components can be released and used with a specific version. -- Multiple components can be combined in the same project and released with a single tag. -- Components are discoverable in the [CI/CD Catalog](catalog.md). +- Multiple components can be defined in the same project and versioned together. -## Components repository +Instead of creating your own components, you can also search for published components +that have the functionality you need in the [CI/CD Catalog](#cicd-catalog). -A components repository is a GitLab project with a repository that hosts one or more pipeline components. All components in the project are versioned and released together. +## Component project -If a component requires different versioning from other components, the component should be migrated to its own components repository. +A component project is a GitLab project with a repository that hosts one or more components. +All components in the project are versioned together, with a maximum of 10 components per project. -One component repository can have a maximum of 10 components. +If a component requires different versioning from other components, the component should be moved +to a dedicated component project. -## Create a components repository +### Create a component project -To create a components repository, you must: +To create a component project, you must: 1. [Create a new project](../../user/project/index.md#create-a-blank-project) with a `README.md` file. 1. Add a YAML configuration file for each component, following the [required directory structure](#directory-structure). - For example: ```yaml @@ -49,210 +54,256 @@ To create a components repository, you must: stage: $[[ inputs.stage ]] ``` +You can [use the component](#use-a-component) immediately, but you might want to consider +publishing the component to the [CI/CD catalog](#cicd-catalog). + ### Directory structure -A components repository can host one or more components, and must follow a mandatory file structure. +The repository must contain: -Component configurations can be saved through the following directory structure, containing: +- A `README.md` Markdown file documenting the details of all the components in the repository. +- A top level `templates/` directory that contains all the component configurations. + You can define components in this directory: + - In single files ending in `.yml` for each component, like `templates/secret-detection.yml`. + - In sub-directories containing `template.yml` files as entry points, for components + that bundle together multiple related files. For example, `templates/secret-detection/template.yml`. -- A `templates` directory at the top level of your components repository. All component configuration files - should be saved under this directory. -- Files ending in `.yml` containing the component configurations, one file per component. -- A Markdown `README.md` file explaining the details of all the components in the repository. +You should also: -For example, if the project contains a single component and a pipeline to test the component, -the file structure should be similar to: +- Configure the project's `.gitlab-ci.yml` to [test the components](#test-the-component) + and [release new versions](#publish-a-new-release). +- Add a `LICENSE.md` file with a license of your choice that covers the usage of your component. + For example the [MIT](https://opensource.org/license/mit/) or [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0#apply) + open source licenses. -```plaintext -├── templates/ -│ └── secret-detection.yml -├── README.md -└── .gitlab-ci.yml -``` +For example: -This example component could be referenced with a path similar to `gitlab.com/my-namespace/my-project/secret-detection@<version>`, -if the project is: +- If the project contains a single component, the directory structure should be similar to: -- On GitLab.com -- Named `my-project` -- In a personal namespace or group named `my-namespace` + ```plaintext + ├── templates/ + │ └── my-component.yml + ├── LICENSE.md + ├── README.md + └── .gitlab-ci.yml + ``` -The templates directory and the suffix of the configuration file should be excluded from the referenced path. +- If the project contains multiple components, then the directory structure should be similar to: -If the project contains multiple components, then the file structure should be similar to: + ```plaintext + ├── templates/ + │ ├── my-simple-component.yml + │ └── my-complex-component/ + │ ├── template.yml + │ ├── Dockerfile + │ └── test.sh + ├── LICENSE.md + ├── README.md + └── .gitlab-ci.yml + ``` -```plaintext -├── README.md -├── .gitlab-ci.yml -└── templates/ - ├── all-scans.yml - └── secret-detection.yml + In this example: + + - The `my-simple-component` component's configuration is defined in a single file. + - The `my-complex-component` component's configuration contains multiple files in a directory. + +## Use a component + +To add a component to a project's CI/CD configuration, use the [`include: component`](../yaml/index.md#includecomponent) +keyword. The component reference is formatted as `<fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>`, +for example: + +```yaml +include: + - component: gitlab.example.com/my-org/security-components/secret-detection@1.0 + inputs: + stage: build ``` -These components would be referenced with these paths: +In this example: -- `gitlab.com/my-namespace/my-project/all-scans@<version>` -- `gitlab.com/my-namespace/my-project/secret-detection@<version>` +- `gitlab.example.com` is the Fully Qualified Domain Name (FQDN) matching the GitLab host. + You can only reference components in the same GitLab instance as your project. +- `my-org/security-components` is the full path of the project containing the component. +- `secret-detection` is the component name that is defined as either a single file `templates/secret-detection.yml` + or as a directory `templates/secret-detection/` containing a `template.yml`. +- `1.0` is the [version](#component-versions) of the component. -You can also have components defined as a directory if you want to bundle together multiple related files. -In this case GitLab expects a `template.yml` file to be present: +When GitLab creates a new pipeline, the component's configuration is fetched and added to +the pipeline's configuration. -For example: +### Component versions -```plaintext -├── README.md -├── .gitlab-ci.yml -└── templates/ - └── dast - ├── docs.md - ├── Dockerfile - └── template.yml -``` +In order of highest priority first, the component version can be: -In this example, the component could be referenced with `gitlab.com/my-namespace/my-project/dast@<version>`. +- A commit SHA, for example `e3262fdd0914fa823210cdb79a8c421e2cef79d8`. +- A tag, for example: `1.0`. If a tag and commit SHA exist with the same name, + the commit SHA takes precedence over the tag. +- A branch name, for example `main`. If a branch and tag exist with the same name, + the tag takes precedence over the branch. +- `~latest`, which is a special version that always points to the most recent + [release published in the CI/CD Catalog](#publish-a-new-release). -#### Component configurations saved in any directory (deprecated) +NOTE: +The `~latest` version keyword always returns the most recent published release, not the release with +the latest semantic version. For example, if you first release `2.0.0`, and later release +a patch fix like `1.5.1`, then `~latest` returns the `1.5.1` release. +[Issue #427286](https://gitlab.com/gitlab-org/gitlab/-/issues/427286) proposes to +change this behavior. -WARNING: -Saving component configurations through this directory structure is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/415855) and should be avoided. +## CI/CD Catalog **(FREE ALL BETA)** -Components configurations can be saved through the following directory structure, containing: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/407249) in GitLab 16.1 as an [experiment](../../policy/experiment-beta-support.md#experiment). +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/432045) to [beta](../../policy/experiment-beta-support.md#beta) in GitLab 16.7. -- `template.yml`: The component configuration, one file per component. If there is - only one component, this file can be in the root of the project. If there are multiple - components, each file must be in a separate subdirectory. -- `README.md`: A documentation file explaining the details of all the components in the repository. +The CI/CD Catalog is a list of projects with published CI/CD components you can use +to extend your CI/CD workflow. -For example, if the project is on GitLab.com, named `my-project`, and in a personal -namespace named `my-namespace`: +Anyone can [create a component project](#create-a-component-project) and add it to +the CI/CD Catalog, or contribute to an existing project to improve the available components. -- Containing a single component and a simple pipeline to test the component, then - the file structure might be: +### View the CI/CD Catalog - ```plaintext - ├── template.yml - ├── README.md - └── .gitlab-ci.yml - ``` +To access the CI/CD Catalog and view the published components that are available to you: - The `.gitlab-ci.yml` file is not required for a CI/CD component to work, but - [testing the component](#test-the-component) in a pipeline in the project is recommended. +1. On the left sidebar, select **Search or go to**. +1. Select **Explore**. +1. Select **CI/CD Catalog**. - This component is referenced with the path `gitlab.com/my-namespace/my-project@<version>`. +Alternatively, if you are already in the [pipeline editor](../pipeline_editor/index.md) +in your project, you can select **Browse CI/CD Catalog**. -- Containing one default component and multiple sub-components, then the file structure - might be: +NOTE: +Only public and internal projects are discoverable in the CI/CD Catalog. - ```plaintext - ├── template.yml - ├── README.md - ├── .gitlab-ci.yml - ├── unit/ - │ └── template.yml - └── integration/ - └── template.yml - ``` +### Publish a component project - These components are identified by these paths: +To publish a component project in the CI/CD catalog, you must: - - `gitlab.com/my-namespace/my-project` - - `gitlab.com/my-namespace/my-project/unit` - - `gitlab.com/my-namespace/my-project/integration` +1. Set the project as a catalog resource. +1. Publish a new release. -It is possible to have a components repository with no default component, by having -no `template.yml` in the root directory. +#### Set a component project as a catalog resource -**Additional notes:** +To make published versions of a component project visible in the CI/CD catalog, +you must set the project as a catalog resource. -Nesting of components is not possible. For example: +Prerequisites: -```plaintext -├── unit/ -│ └── template.yml -│ └── another_folder/ -│ └── nested_template.yml -``` +- You must have the Owner role in the project. -## Release a component +To set the project as a catalog resource: -To create a release for a CI/CD component, use the [`release`](../yaml/index.md#release) -keyword in a CI/CD pipeline. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Turn on the **CI/CD Catalog resource** toggle. -For example: +The project only becomes findable in the catalog after you publish a new release. -```yaml -create-release: - stage: deploy - image: registry.gitlab.com/gitlab-org/release-cli:latest - rules: - - if: $CI_COMMIT_TAG =~ /^v\d+/ - script: echo "Creating release $CI_COMMIT_TAG" - release: - tag_name: $CI_COMMIT_TAG - description: "Release $CI_COMMIT_TAG of components repository $CI_PROJECT_PATH" -``` +#### Publish a new release -In this example, the job runs only for tags formatted as `v` + version number. -If all previous jobs succeed, the release is created. +CI/CD components can be [used](#use-a-component) without being listed in the CI/CD catalog. +However, publishing a component's releases in the catalog makes it discoverable to other users. -Like in the [component testing example](#test-the-component), you can set a component to automatically -be released after all tests pass in pipelines for new tags. +Prerequisites: -All released versions of the components repositories are displayed in the [CI/CD Catalog](catalog.md), -providing users with information about official releases. +- The project must: + - Be set as a [catalog resource](#set-a-component-project-as-a-catalog-resource). + - Have a [project description](../../user/project/working_with_projects.md#edit-project-name-and-description) defined. + - Have a `README.md` file in the root directory for the commit SHA of the tag being released. + - Have at least one [CI/CD component in the `templates/` directory](#directory-structure) + for the commit SHA of the tag being released. -Components [can be used](#use-a-component-in-a-cicd-configuration) without being released, -by using the commit SHA or ref. However, the `~latest` version keyword can only be used with released tags. +To publish a new version of the component to the catalog: -NOTE: -The `~latest` keyword always returns the most recent release, not the release with -the latest semantic version. For example, if you first release `v2.0.0`, and later release -a patch fix like `v1.5.1`, then `~latest` returns the `v1.5.1` release. -[Issue #427286](https://gitlab.com/gitlab-org/gitlab/-/issues/427286) proposes to -change this behavior. +1. Add a job to the project's `.gitlab-ci.yml` file that uses the [`release`](../yaml/index.md#release) + keyword to create the new release. For example: + + ```yaml + create-release: + stage: deploy + image: registry.gitlab.com/gitlab-org/release-cli:latest + script: echo "Creating release $CI_COMMIT_TAG" + rules: + - if: $CI_COMMIT_TAG + release: + tag_name: $CI_COMMIT_TAG + description: "Release $CI_COMMIT_TAG of components in $CI_PROJECT_PATH" + ``` + +1. Create a [new tag](../../user/project/repository/tags/index.md#create-a-tag) for the release, + which should trigger a tag pipeline that contains the job responsible for creating the release. + You should configure the tag pipeline to [test the components](#test-the-component) before + running the release job. -## Use a component in a CI/CD configuration +After the release job completes successfully, the release is created and the new version +is published to the CI/CD catalog. + +### Unpublish a component project + +To remove a component project from the catalog, turn off the [**CI/CD Catalog resource**](#set-a-component-project-as-a-catalog-resource) +toggle in the project settings. + +WARNING: +This action destroys the metadata about the component project and its versions published +in the catalog. The project and its repository still exist, but are not visible in the catalog. + +To publish the component project in the catalog again, you need to [publish a new release](#publish-a-new-release). + +## Best practices + +This section describes some best practices for creating high quality component projects. + +### Test the component + +Testing CI/CD components as part of the development workflow is strongly recommended +and helps ensure consistent behavior. + +Test changes in a CI/CD pipeline (like any other project) by creating a `.gitlab-ci.yml` +in the root directory. Make sure to test both the behavior and potential side-effects +of the component. You can use the [GitLab API](../../api/rest/index.md) if needed. -You can add a component to a CI/CD configuration with the `include: component` keyword. For example: ```yaml include: - - component: gitlab.example.com/my-namespace/my-project@1.0 + # include the component located in the current project from the current SHA + - component: gitlab.com/$CI_PROJECT_PATH/my-component@$CI_COMMIT_SHA inputs: stage: build -``` -The component is identified by a unique address in the form `<fully-qualified-domain-name>/<component-path>@<specific-version>`, -where: - -- `<fully-qualified-domain-name>` matches the GitLab host. You can only reference components - in the same GitLab instance as your project. -- `<component-path>` is the component project's full path and directory where the - component YAML file is located. -- `<specific-version>` is the version of the component. In order of highest priority first, - the version can be: - - A branch name, for example `main`. - - A commit SHA, for example `e3262fdd0914fa823210cdb79a8c421e2cef79d8`. - - A tag, for example: `1.0`. If a tag and branch exist with the same name, the tag - takes precedence over the branch. If a tag and commit SHA exist with the same name, - the commit SHA takes precedence over the tag. - - `~latest`, which is a special version that always points to the most recent released tag. - Available only if the component has been [released](#release-a-component). - -For example, for a component repository located at `gitlab-org/dast` on `gitlab.com`, -the path: - -- `gitlab.com/gitlab-org/dast@main` targets the `template.yml` in the root directory - on the `main` branch. -- `gitlab.com/gitlab-org/dast@e3262fdd0914fa823210cdb79a8c421e2cef79d8` targets the same file - for the specified commit SHA. -- `gitlab.com/gitlab-org/dast@1.0` targets the same file for the `1.0` tag. -- `gitlab.com/gitlab-org/dast@~latest` targets the same file for the latest release. -- `gitlab.com/gitlab-org/dast/api-scan@main` targets a different file, the `template.yml` - in the `/api-scan` directory in the component repository, for the `main` branch. +stages: [build, test, release] + +# Check if `component-job` is added. +# This example job could also test that the included component works as expected. +# You can inspect data generated by the component, use GitLab API endpoints, or third-party tools. +ensure-job-added: + stage: test + image: badouralix/curl-jq + script: + - | + route="https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/pipelines/$CI_PIPELINE_ID/jobs" + count=`curl --silent --header "PRIVATE-TOKEN: $API_TOKEN" $route | jq 'map(select(.name | contains("component-job"))) | length'` + if [ "$count" != "1" ]; then + exit 1 + fi -## Best practices +# If the pipeline is for a new tag with a semantic version, and all previous jobs succeed, +# create the release. +create-release: + stage: release + image: registry.gitlab.com/gitlab-org/release-cli:latest + rules: + - if: $CI_COMMIT_TAG =~ /\d+/ + script: echo "Creating release $CI_COMMIT_TAG" + release: + tag_name: $CI_COMMIT_TAG + description: "Release $CI_COMMIT_TAG of components repository $CI_PROJECT_PATH" +``` + +After committing and pushing changes, the pipeline tests the component, then creates +a release if the earlier jobs pass. ### Avoid using global keywords @@ -260,13 +311,15 @@ Avoid using [global keywords](../yaml/index.md#global-keywords) in a component. Using these keywords in a component affects all jobs in a pipeline, including jobs directly defined in the main `.gitlab-ci.yml` or in other included components. -As an alternative to global keywords, instead: +As an alternative to global keywords: - Add the configuration directly to each job, even if it creates some duplication in the component configuration. -- Use the [`extends`](../yaml/index.md#extends) keyword in the component. +- Use the [`extends`](../yaml/index.md#extends) keyword in the component, but use + unique names that reduce the risk of naming conflicts when the component is merged + into the configuration. -For example, using the `default` keyword is not recommended: +For example, avoid using the `default` global keyword: ```yaml # Not recommended @@ -282,7 +335,7 @@ rspec-2: Instead, you can: -- Add the configuration to each job: +- Add the configuration to each job explicitly: ```yaml rspec-1: @@ -311,21 +364,21 @@ Instead, you can: script: bundle exec rspec dir2/ ``` -### Replace hard-coded values with inputs +### Replace hardcoded values with inputs -Avoid hard-coding values in CI/CD components. Hard-coded values might force +Avoid using hardcoded values in CI/CD components. Hardcoded values might force component users to need to review the component's internal details and adapt their pipeline to work with the component. A common keyword with problematic hard-coded values is `stage`. If a component job's -stage is set to a specific value, the pipeline using the component **must** define -the exact same stage. Additionally, if the component user wants to use a different stage, -they must [override](../yaml/includes.md#override-included-configuration-values) the configuration. +stage is hardcoded, all pipelines using the component **must** either define +the exact same stage, or [override](../yaml/includes.md#override-included-configuration-values) +the configuration. -The preferred method is to use the [`input` keyword](../yaml/inputs.md). -The component user can specify the exact value they need. +The preferred method is to use the [`input` keyword](../yaml/inputs.md) for dynamic +component configuration. The component user can specify the exact value they need. -For example: +For example, to create a component with `stage` configuration that can be defined by users: - In the component configuration: @@ -344,28 +397,28 @@ For example: script: echo integration tests ``` -- In the project using the component: +- In a project using the component: ```yaml + stages: [verify, deploy] + include: - component: gitlab.com/gitlab-org/ruby-test@1.0 inputs: stage: verify - - stages: [verify, deploy] ``` ### Replace custom CI/CD variables with inputs When using CI/CD variables in a component, evaluate if the `inputs` keyword -should be used instead. Avoid requiring a user to define custom variables to change a component's -behavior. You should try to use `inputs` for any component customization. +should be used instead. Avoid asking users to define custom variables to configure +components when `inputs` is a better solution. -Inputs are explicitly defined in the component's specs, and are better validated than variables. +Inputs are explicitly defined in the component's specs, and have better validation than variables. For example, if a required input is not passed to the component, GitLab returns a pipeline error. By contrast, if a variable is not defined, its value is empty, and there is no error. -For example, use `inputs` instead of variables to let users change a scanner's output format: +For example, use `inputs` instead of variables to configure a scanner's output format: - In the component configuration: @@ -388,17 +441,17 @@ For example, use `inputs` instead of variables to let users change a scanner's o scanner-output: yaml ``` -In other cases, CI/CD variables are still preferred, including: +In other cases, CI/CD variables might still be preferred. For example: -- Using [predefined variables](../variables/predefined_variables.md) to automatically configure +- Use [predefined variables](../variables/predefined_variables.md) to automatically configure a component to match a user's project. -- Requiring tokens or other sensitive values to be stored as [masked or protected variables in project settings](../variables/index.md#define-a-cicd-variable-in-the-ui). +- Ask users to store sensitive values as [masked or protected CI/CD variables in project settings](../variables/index.md#define-a-cicd-variable-in-the-ui). ### Use semantic versioning -When tagging and releasing new versions of components, you should use [semantic versioning](https://semver.org). -Semantic versioning is the standard for communicating that a change is a major, minor, patch, -or other kind of change. +When tagging and [releasing new versions](#publish-a-new-release) of components, +you should use [semantic versioning](https://semver.org). Semantic versioning is the standard +for communicating that a change is a major, minor, patch, or other kind of change. You should use at least the `major.minor` format, as this is widely understood. For example, `2.0` or `2.1`. @@ -410,66 +463,32 @@ Other examples of semantic versioning: - `1.0.0-alpha` - `3.0.0-rc1` -### Test the component - -Testing CI/CD components as part of the development workflow is strongly recommended -and helps ensure consistent behavior. - -Test changes in a CI/CD pipeline (like any other project) by creating a `.gitlab-ci.yml` -in the root directory. - -For example: - -```yaml -include: - # include the component located in the current project from the current SHA - - component: gitlab.com/$CI_PROJECT_PATH/my-project@$CI_COMMIT_SHA - inputs: - stage: build - -stages: [build, test, release] - -# Expect `component-job` is added. -# This example tests that the included component works as expected. -# You can inspect data generated by the component, use GitLab API endpoints or third-party tools. -ensure-job-added: - stage: test - image: badouralix/curl-jq - script: - - | - route="https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/pipelines/$CI_PIPELINE_ID/jobs" - count=`curl --silent --header "PRIVATE-TOKEN: $API_TOKEN" $route | jq 'map(select(.name | contains("component-job"))) | length'` - if [ "$count" != "1" ]; then - exit 1 - fi - -# If we are tagging a release with a specific convention ("v" + number) and all -# previous checks succeeded, we proceed with creating a release automatically. -create-release: - stage: release - image: registry.gitlab.com/gitlab-org/release-cli:latest - rules: - - if: $CI_COMMIT_TAG =~ /^v\d+/ - script: echo "Creating release $CI_COMMIT_TAG" - release: - tag_name: $CI_COMMIT_TAG - description: "Release $CI_COMMIT_TAG of components repository $CI_PROJECT_PATH" -``` - -After committing and pushing changes, the pipeline tests the component, then releases it if the test passes. - ## Convert a CI/CD template to a component Any existing CI/CD template that you use in projects by using the `include:` syntax can be converted to a CI/CD component: -1. Decide if you want the component to be part of an existing [components repository](index.md#components-repository) - to be grouped with other components, or create and set up a new components repository. -1. Create a YAML file in the components repository according to the expected [directory structure](index.md#directory-structure). +1. Decide if you want the component to be grouped with other components as part of + an existing [component project](index.md#component-project), or [create a new component project](#create-a-component-project). +1. Create a YAML file in the component project according to the [directory structure](index.md#directory-structure). 1. Copy the content of the original template YAML file into the new component YAML file. 1. Refactor the new component's configuration to: - Follow the [best practices](index.md#best-practices) for components. - Improve the configuration, for example by enabling [merge request pipelines](../pipelines/merge_request_pipelines.md) or making it [more efficient](../pipelines/pipeline_efficiency.md). 1. Leverage the `.gitlab-ci.yml` in the components repository to [test changes to the component](index.md#test-the-component). -1. Tag and [release the component](index.md#release-a-component). +1. Tag and [release the component](#publish-a-new-release). + +## Troubleshooting + +### `content not found` message + +You might receive an error message similar to the following when using the `~latest` +version qualifier to reference a component hosted by a [catalog resource](#set-a-component-project-as-a-catalog-resource): + +```plaintext +This GitLab CI configuration is invalid: component 'gitlab.com/my-namespace/my-project/my-component@~latest' - content not found` +``` + +The `~latest` behavior [was updated](https://gitlab.com/gitlab-org/gitlab/-/issues/429707) +in GitLab 16.7. It now refers to the latest published version of the catalog resource. To resolve this issue, [create a new release](#publish-a-new-release). diff --git a/doc/ci/debugging.md b/doc/ci/debugging.md index 5bcf834b61d..8a60b5f649e 100644 --- a/doc/ci/debugging.md +++ b/doc/ci/debugging.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Debugging CI/CD pipelines **(FREE ALL)** @@ -163,7 +162,7 @@ For help with a specific area, see: - [Caching](caching/index.md#troubleshooting). - [CI/CD job tokens](jobs/ci_job_token.md). -- [Container Registry](../user/packages/container_registry/troubleshoot_container_registry.md). +- [Container registry](../user/packages/container_registry/troubleshoot_container_registry.md). - [Docker](docker/using_docker_build.md#troubleshooting). - [Downstream pipelines](pipelines/downstream_pipelines.md#troubleshooting). - [Environments](environments/deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time). @@ -293,3 +292,8 @@ These errors can happen if the following are both true: To resolve this issue, add any projects with CI/CD jobs that fetch images from the container registry to the target project's [job token allowlist](jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token). + +These errors might also happen when trying to use a [project access token](../user/project/settings/project_access_tokens.md) +to access images in another project. Project access tokens are scoped to one project, +and therefore cannot access images in other projects. You must use [a different token type](../security/token_overview.md) +with wider scope. diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index a1163a3acff..fab784783f6 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Directed Acyclic Graph **(FREE ALL)** diff --git a/doc/ci/docker/authenticate_registry.md b/doc/ci/docker/authenticate_registry.md index 28edb5140dd..fbf05e9ef7a 100644 --- a/doc/ci/docker/authenticate_registry.md +++ b/doc/ci/docker/authenticate_registry.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Authenticate with registry in Docker-in-Docker diff --git a/doc/ci/docker/buildah_rootless_tutorial.md b/doc/ci/docker/buildah_rootless_tutorial.md index fdb33fd4a8b..0a094374fd0 100644 --- a/doc/ci/docker/buildah_rootless_tutorial.md +++ b/doc/ci/docker/buildah_rootless_tutorial.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Use Buildah in a rootless container with GitLab Runner Operator on OpenShift **(FREE)** @@ -52,8 +51,8 @@ We start by preparing a custom image based on the `quay.io/buildah/stable:v1.23. EOF ``` -1. Build and push the Buildah image to a Container Registry. Let's push to the - [GitLab Container Registry](../../user/packages/container_registry/index.md): +1. Build and push the Buildah image to a container registry. Let's push to the + [GitLab container registry](../../user/packages/container_registry/index.md): ```shell docker build -f Containerfile-buildah -t registry.example.com/group/project/buildah:1.23.1 . diff --git a/doc/ci/docker/docker_layer_caching.md b/doc/ci/docker/docker_layer_caching.md index b34b58ce964..e8f2636db0a 100644 --- a/doc/ci/docker/docker_layer_caching.md +++ b/doc/ci/docker/docker_layer_caching.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Make Docker-in-Docker builds faster with Docker layer caching diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md index 49a9e1f8eea..f4e7587f02e 100644 --- a/doc/ci/docker/index.md +++ b/doc/ci/docker/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Docker integration **(FREE ALL)** @@ -15,7 +14,7 @@ There are two primary ways to incorporate [Docker](https://www.docker.com) into an application. These jobs can run in Docker containers. For example, you can tell GitLab CI/CD to use a Node image that's hosted on Docker Hub - or in the GitLab Container Registry. Your job then runs in a container that's based on the image. + or in the GitLab container registry. Your job then runs in a container that's based on the image. The container has all the Node dependencies you need to build your app. - **Use [Docker](using_docker_build.md) or [kaniko](using_kaniko.md) to build Docker images.** diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 2505089e4be..beaa2291eea 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Docker to build Docker images **(FREE ALL)** @@ -319,6 +318,63 @@ To use Docker-in-Docker with TLS enabled in Kubernetes: - docker run my-docker-image /script/to/run/tests ``` +##### Docker-in-Docker with TLS disabled in Kubernetes + +To use Docker-in-Docker with TLS disabled in Kubernetes, you must adapt the example above to: + +- Remove the `[[runners.kubernetes.volumes.empty_dir]]` section from the `values.yml` file. +- Change the port from `2376` to `2375` with `DOCKER_HOST: tcp://docker:2375`. +- Instruct Docker to start with TLS disabled with `DOCKER_TLS_CERTDIR: ""`. + +For example: + +1. Using the + [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html), update the + [`values.yml` file](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/00c1a2098f303dffb910714752e9a981e119f5b5/values.yaml#L133-137): + + ```yaml + runners: + config: | + [[runners]] + [runners.kubernetes] + image = "ubuntu:20.04" + privileged = true + ``` + +1. You can now use `docker` in the job script. You should include the + `docker:24.0.5-dind` service: + + ```yaml + default: + image: docker:24.0.5 + services: + - docker:24.0.5-dind + before_script: + - docker info + + variables: + # When using dind service, you must instruct Docker to talk with + # the daemon started inside of the service. The daemon is available + # with a network connection instead of the default + # /var/run/docker.sock socket. + DOCKER_HOST: tcp://docker:2375 + # + # The 'docker' hostname is the alias of the service container as described at + # https://docs.gitlab.com/ee/ci/services/#accessing-the-services. + # If you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier, + # the variable must be set to tcp://localhost:2376 because of how the + # Kubernetes executor connects services to the job container + # DOCKER_HOST: tcp://localhost:2376 + # + # This instructs Docker not to start over TLS. + DOCKER_TLS_CERTDIR: "" + build: + stage: build + script: + - docker build -t my-docker-image . + - docker run my-docker-image /script/to/run/tests + ``` + #### Known issues with Docker-in-Docker Docker-in-Docker is the recommended configuration, but you should be aware of the following issues: @@ -651,11 +707,11 @@ of the following executors: In this example, you use Buildah to: 1. Build a Docker image. -1. Push it to [GitLab Container Registry](../../user/packages/container_registry/index.md). +1. Push it to [GitLab container registry](../../user/packages/container_registry/index.md). In the last step, Buildah uses the `Dockerfile` under the root directory of the project to build the Docker image. Finally, it pushes the image to the -project's Container Registry: +project's container registry: ```yaml build: @@ -671,7 +727,7 @@ build: BUILDAH_FORMAT: docker FQ_IMAGE_NAME: "$CI_REGISTRY_IMAGE/test" before_script: - # GitLab Container Registry credentials taken from the + # GitLab container registry credentials taken from the # [predefined CI/CD variables](../variables/index.md#predefined-cicd-variables) # to authenticate to the registry. - echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY @@ -685,10 +741,10 @@ build: If you are using GitLab Runner Operator deployed to an OpenShift cluster, try the [tutorial for using Buildah to build images in rootless container](buildah_rootless_tutorial.md). -## Use the GitLab Container Registry +## Use the GitLab container registry After you've built a Docker image, you can push it to the -[GitLab Container Registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd). +[GitLab container registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd). ## Troubleshooting diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index dd6cd2099a9..7e24016a455 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run your CI/CD jobs in Docker containers **(FREE ALL)** @@ -203,7 +202,7 @@ Look for the `[runners.docker]` section: The image and services defined this way are added to all jobs run by that runner. -## Access an image from a private Container Registry +## Access an image from a private container registry To access private container registries, the GitLab Runner process can use: @@ -534,11 +533,11 @@ and update Docker images on Amazon ECR, without using manual credential manageme build-image: stage: build script: - - echo "Logging into GitLab Container Registry..." + - echo "Logging into GitLab container registry..." - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - echo "Building Docker image..." - docker build --build-arg GITLAB_RUNNER_VERSION=${GITLAB_RUNNER_VERSION} --build-arg AWS_CLI_VERSION=${AWS_CLI_VERSION} -t ${IMAGE_NAME} . - - echo "Pushing Docker image to GitLab Container Registry..." + - echo "Pushing Docker image to GitLab container registry..." - docker push ${IMAGE_NAME} rules: - changes: diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 8ab13c7154d..97cdbf79d02 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use kaniko to build Docker images **(FREE ALL)** @@ -43,16 +42,16 @@ few important details: In the following example, kaniko is used to: 1. Build a Docker image. -1. Then push it to [GitLab Container Registry](../../user/packages/container_registry/index.md). +1. Then push it to [GitLab container registry](../../user/packages/container_registry/index.md). The job runs only when a tag is pushed. A `config.json` file is created under -`/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the +`/kaniko/.docker` with the needed GitLab container registry credentials taken from the [predefined CI/CD variables](../variables/index.md#predefined-cicd-variables) GitLab CI/CD provides. These are automatically read by the Kaniko tool. In the last step, kaniko uses the `Dockerfile` under the root directory of the project, builds the Docker image and pushes it to the -project's Container Registry while tagging it with the Git tag: +project's container registry while tagging it with the Git tag: ```yaml build: diff --git a/doc/ci/environments/configure_kubernetes_deployments.md b/doc/ci/environments/configure_kubernetes_deployments.md index e618aae7cae..715942985e7 100644 --- a/doc/ci/environments/configure_kubernetes_deployments.md +++ b/doc/ci/environments/configure_kubernetes_deployments.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Kubernetes deployments (deprecated) diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md index b14ee5eb3eb..f1c7b412c6f 100644 --- a/doc/ci/environments/deployment_approvals.md +++ b/doc/ci/environments/deployment_approvals.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Require approvals prior to deploying to a Protected Environment --- @@ -23,7 +23,7 @@ require approvals for deployments to production environments. You can require approvals for deployments to protected environments in a project. -Prerequisite: +Prerequisites: - To update an environment, you must have at least the Maintainer role. @@ -215,11 +215,7 @@ The approval status details are shown: ## View blocked deployments -Use the UI or API to review the status of your deployments, including whether a deployment is blocked. - -::Tabs - -:::TabTitle With the UI +Review the status of your deployments, including whether a deployment is blocked. To view your deployments: @@ -229,16 +225,9 @@ To view your deployments: A deployment with the **blocked** label is blocked. -:::TabTitle With the API - -To view your deployments: - -- Using the [deployments API](../../api/deployments.md#get-a-specific-deployment), get a specific deployment, or a list of all deployments in a project. - +To view your deployments, you can also [use the API](../../api/deployments.md#get-a-specific-deployment). The `status` field indicates whether a deployment is blocked. -::EndTabs - ## Related topics - [Deployment approvals feature epic](https://gitlab.com/groups/gitlab-org/-/epics/6832) diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index b34fc61ba66..ec6d2c482cd 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deployment safety **(FREE ALL)** diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index 0beaf2b8888..24a619d9f10 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Environments Dashboard **(PREMIUM ALL)** diff --git a/doc/ci/environments/external_deployment_tools.md b/doc/ci/environments/external_deployment_tools.md index ac31d196887..29c811b68be 100644 --- a/doc/ci/environments/external_deployment_tools.md +++ b/doc/ci/environments/external_deployment_tools.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Track deployments of an external deployment tool **(FREE ALL)** diff --git a/doc/ci/environments/img/kubernetes_summary_ui.png b/doc/ci/environments/img/kubernetes_summary_ui.png Binary files differnew file mode 100644 index 00000000000..ce51cd8e96f --- /dev/null +++ b/doc/ci/environments/img/kubernetes_summary_ui.png diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index 309e311e252..9dd5e676924 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incremental rollouts with GitLab CI/CD **(FREE ALL)** diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 8306746dd1f..03c9a152d98 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Environments and deployments **(FREE ALL)** diff --git a/doc/ci/environments/kubernetes_dashboard.md b/doc/ci/environments/kubernetes_dashboard.md index 42fa560ad76..9f5be975cdf 100644 --- a/doc/ci/environments/kubernetes_dashboard.md +++ b/doc/ci/environments/kubernetes_dashboard.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dashboard for Kubernetes **(FREE ALL BETA)** @@ -15,6 +14,8 @@ Use the Dashboard for Kubernetes to understand the status of your clusters with The dashboard works with every connected Kubernetes cluster, whether you deployed them with CI/CD or GitOps. + + ## Configure a dashboard > - Filtering resources by namespace [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/403618) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `kubernetes_namespace_for_environment`. Disabled by default. @@ -31,7 +32,9 @@ Prerequisites: - The agent for Kubernetes must be shared with the environment's project, or its parent group, using the [`user_access`](../../user/clusters/agent/user_access.md) keyword. - Self-managed only. KAS is running on the GitLab subdomain. For example, `kas.example.com` and `example.com`. -### The environment already exists +::Tabs + +:::TabTitle The environment already exists 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Environments**. @@ -42,7 +45,7 @@ Prerequisites: 1. Optional. From the **Flux resource** dropdown list, select a Flux resource. 1. Select **Save**. -### The environment doesn't exist +:::TabTitle The environment doesn't exist 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Environments**. @@ -53,18 +56,16 @@ Prerequisites: 1. Optional. From the **Flux resource** dropdown list, select a Flux resource. 1. Select **Save**. -## View a dashboard +::EndTabs -> Kubernetes watch API integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422945) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `k8s_watch_api`. Disabled by default. +## View a dashboard -FLAG: -On self-managed GitLab, by default the Kubernetes watch API integration is not available. -To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `k8s_watch_api`. -On GitLab.com, this feature is not available. +> - Kubernetes watch API integration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422945) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `k8s_watch_api`. Disabled by default. +> - Kubernetes watch API integration [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136831) in GitLab 16.7. View a dashboard to see the status of any connected clusters. If the `k8s_watch_api` feature flag is enabled, the status of your -pods and Flux reconciliation updates in real time. +Kubernetes resources and Flux reconciliation updates in real time. To view a configured dashboard: diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index e594ff725a4..69f7c558b8b 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected environments **(PREMIUM ALL)** @@ -27,6 +27,7 @@ Maintainer role. Prerequisites: - When granting the **Allowed to deploy** permission to a group or subgroup, the user configuring the protected environment must be a **direct member** of the group or subgroup to be added. Otherwise, the group or subgroup does not show up in the dropdown list. For more information see [issue #345140](https://gitlab.com/gitlab-org/gitlab/-/issues/345140). +- When granting **Allowed to deploy** and **Approvers** permissions to a group or project by using the settings UI, only direct members of the group or project receive these permissions. To grant these permissions to inherited members also, [use the API](../../api/protected_environments.md#group-inheritance-types). For more information see [issue #422392](https://gitlab.com/gitlab-org/gitlab/-/issues/422392). To protect an environment: diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index f494ff6dffb..ed891b46999 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Authenticating and reading secrets with HashiCorp Vault **(PREMIUM ALL)** @@ -191,14 +190,6 @@ This example uses [bound claims](https://developer.hashicorp.com/vault/api-docs/ Combined with [protected branches](../../../user/project/protected_branches.md), you can restrict who is able to authenticate and read the secrets. -To use the same policy for a list of projects, use `namespace_id`: - -```json -"bound_claims": { - "namespace_id": ["12", "22", "37"] -} -``` - Any of the claims [included in the JWT](#how-it-works) can be matched against a list of values in the bound claims. For example: @@ -212,10 +203,17 @@ in the bound claims. For example: } "bound_claims": { + "namespace_id": ["10", "20", "30"] +} + +"bound_claims": { "project_id": ["12", "22", "37"] } ``` +- If only `namespace_id` is used, all projects in the namespace are allowed. +- If both `namespace_id` and `project_id` are used, Vault first checks if the project's namespace is in `namespace_id`. If not, it then checks if the project is in `project_id`. + [`token_explicit_max_ttl`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#token_explicit_max_ttl) specifies that the token issued by Vault, upon successful authentication, has a hard lifetime limit of 60 seconds. [`user_claim`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#user_claim) specifies the name for the Identity alias created by Vault upon a successful login. diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index dfdaa1866c3..149f99e8a66 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Running Composer and npm scripts with deployment via SCP in GitLab CI/CD **(FREE ALL)** diff --git a/doc/ci/examples/deployment/index.md b/doc/ci/examples/deployment/index.md index 2be800efcbb..0ffc09c8646 100644 --- a/doc/ci/examples/deployment/index.md +++ b/doc/ci/examples/deployment/index.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using Dpl as a deployment tool **(FREE ALL)** diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 10ec18a6147..556af355b1a 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments author: Vincent Tunru author_gitlab: Vinnl description: 'Confidence checking your entire app every time a new feature is added can quickly become repetitive. Learn how to automate it with GitLab CI/CD.' diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index aa3be8f2ab0..f618b6beec9 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD examples **(FREE ALL)** @@ -27,7 +26,7 @@ The following table lists examples with step-by-step tutorials that are containe | GitLab Pages | See the [GitLab Pages](../../user/project/pages/index.md) documentation for a complete example of deploying a static site. | | End-to-end testing | [End-to-end testing with GitLab CI/CD and WebdriverIO](end_to_end_testing_webdriverio/index.md). | | Multi project pipeline | [Build, test deploy using multi project pipeline](https://gitlab.com/gitlab-examples/upstream-project). | -| npm with semantic-release | [Publish npm packages to the GitLab Package Registry using semantic-release](semantic-release.md). | +| npm with semantic-release | [Publish npm packages to the GitLab package registry using semantic-release](semantic-release.md). | | PHP with Laravel, Envoy | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md). | | PHP with npm, SCP | [Running Composer and npm scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md). | | PHP with PHPUnit, `atoum` | [Testing PHP projects](php.md). | @@ -150,7 +149,7 @@ For examples of others who have implemented GitLab CI/CD, see: - [Test all the things in GitLab CI with Docker by example](https://about.gitlab.com/blog/2018/02/05/test-all-the-things-gitlab-ci-docker-examples/) - [A Craftsman looks at continuous integration](https://about.gitlab.com/blog/2018/01/17/craftsman-looks-at-continuous-integration/) - [Go tools and GitLab: How to do continuous integration like a boss](https://about.gitlab.com/blog/2017/11/27/go-tools-and-gitlab-how-to-do-continuous-integration-like-a-boss/) -- [GitBot – automating boring Git operations with CI](https://about.gitlab.com/blog/2017/11/02/automating-boring-git-operations-gitlab-ci/) +- [GitBot - automating boring Git operations with CI](https://about.gitlab.com/blog/2017/11/02/automating-boring-git-operations-gitlab-ci/) - [How to use GitLab CI for Vue.js](https://about.gitlab.com/blog/2017/09/12/vuejs-app-gitlab/) - Video: [GitLab CI/CD Deep Dive](https://youtu.be/pBe4t1CD8Fc?t=195) - [Dockerizing GitLab Review Apps](https://about.gitlab.com/blog/2017/07/11/dockerizing-review-apps/) diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index ea936b66d31..25a0750e5eb 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments author: Mehran Rasulian author_gitlab: mehranrasulian --- @@ -430,19 +430,19 @@ We added the [official PHP 7.4 Docker image](https://hub.docker.com/_/php), whic We used `docker-php-ext-install` (provided by the official PHP Docker image) to install the PHP extensions we need. -#### Setting Up GitLab Container Registry +#### Setting Up GitLab container registry -Now that we have our `Dockerfile` let's build and push it to our [GitLab Container Registry](../../../user/packages/container_registry/index.md). +Now that we have our `Dockerfile` let's build and push it to our [GitLab container registry](../../../user/packages/container_registry/index.md). -> The registry is the place to store and tag images for later use. Developers may want to maintain their own registry for private, company images, or for throw-away images used only in testing. Using GitLab Container Registry means you don't need to set up and administer yet another service or use a public registry. +> The registry is the place to store and tag images for later use. Developers may want to maintain their own registry for private, company images, or for throw-away images used only in testing. Using GitLab container registry means you don't need to set up and administer yet another service or use a public registry. On your GitLab project repository navigate to the **Registry** tab.  -You may need to enable the Container Registry for your project to see this tab. You'll find it under your project's **Settings > General > Visibility, project features, permissions**. +You may need to enable the container registry for your project to see this tab. You'll find it under your project's **Settings > General > Visibility, project features, permissions**. -To start using Container Registry on our machine, we first need to sign in to the GitLab registry using our GitLab username and password. +To start using container registry on our machine, we first need to sign in to the GitLab registry using our GitLab username and password. Make sure you have [Docker](https://docs.docker.com/engine/install/) installed on our machine, then run the following commands: diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 0e0d40f12f6..12d3cf32d98 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Testing PHP projects **(FREE ALL)** diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md index 356a3d1d63e..6a21b6d3d83 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -1,19 +1,19 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Publish npm packages to the GitLab Package Registry using semantic-release **(FREE ALL)** +# Publish npm packages to the GitLab package registry using semantic-release **(FREE ALL)** -This guide demonstrates how to automatically publish npm packages to the [GitLab Package Registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release). +This guide demonstrates how to automatically publish npm packages to the [GitLab package registry](../../user/packages/npm_registry/index.md) by using [semantic-release](https://github.com/semantic-release/semantic-release). You can also view or fork the complete [example source](https://gitlab.com/gitlab-examples/semantic-release-npm). ## Initialize the module 1. Open a terminal and navigate to the project's repository. -1. Run `npm init`. Name the module according to [the Package Registry's naming conventions](../../user/packages/npm_registry/index.md#naming-convention). For example, if the project's path is `gitlab-examples/semantic-release-npm`, name the module `@gitlab-examples/semantic-release-npm`. +1. Run `npm init`. Name the module according to [the package registry's naming conventions](../../user/packages/npm_registry/index.md#naming-convention). For example, if the project's path is `gitlab-examples/semantic-release-npm`, name the module `@gitlab-examples/semantic-release-npm`. 1. Install the following npm packages: @@ -82,7 +82,7 @@ publish: This example configures the pipeline with a single job, `publish`, which runs `semantic-release`. The semantic-release library publishes new versions of the npm package and creates new GitLab releases (if necessary). -The default `before_script` generates a temporary `.npmrc` that is used to authenticate to the Package Registry during the `publish` job. +The default `before_script` generates a temporary `.npmrc` that is used to authenticate to the package registry during the `publish` job. ## Set up CI/CD variables diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 2561ab6465e..747c2abb61a 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using Git submodules with GitLab CI/CD **(FREE ALL)** diff --git a/doc/ci/index.md b/doc/ci/index.md index c0c63d13d3a..beb7fffeb8a 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -1,9 +1,8 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Integration, Continuous Deployment, and Continuous Delivery toolset to build, test, and deploy your application." -type: index --- # Get started with GitLab CI/CD **(FREE ALL)** @@ -105,6 +104,6 @@ A CI/CD component is a reusable single pipeline configuration unit. Use them to - [Five teams that made the switch to GitLab CI/CD](https://about.gitlab.com/blog/2019/04/25/5-teams-that-made-the-switch-to-gitlab-ci-cd/). - [Make the case for CI/CD in your organization](https://about.gitlab.com/why-gitlab/). - Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) from 30 days to under 8 hours with GitLab. -- Use the [GitLab Workflow VS Code extension](../user/project/repository/vscode.md) to +- Use the [GitLab Workflow VS Code extension](../editor_extensions/visual_studio_code/index.md) to [validate your configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration) and [view your pipeline status](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 1125061d830..4108ab93797 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Interactive web terminals **(FREE ALL)** diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md deleted file mode 100644 index 57731a96a90..00000000000 --- a/doc/ci/introduction/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../index.md' -remove_date: '2023-11-24' ---- - -This document was moved to [another location](../index.md). - -<!-- This redirect file can be deleted after <2023-11-24>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index cf8b4ccd092..ba2d63c12e4 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD job token **(FREE ALL)** @@ -12,11 +12,11 @@ When a pipeline job is about to run, GitLab generates a unique token and injects You can use a GitLab CI/CD job token to authenticate with specific API endpoints: - Packages: - - [Package Registry](../../user/packages/package_registry/index.md#to-build-packages). + - [Package registry](../../user/packages/package_registry/index.md#to-build-packages). - [Packages API](../../api/packages.md) (project-level). - - [Container Registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) + - [Container registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). - - [Container Registry API](../../api/container_registry.md) + - [Container registry API](../../api/container_registry.md) (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled). - [Get job artifacts](../../api/job_artifacts.md#get-job-artifacts). - [Get job token's job](../../api/jobs.md#get-job-tokens-job). @@ -120,12 +120,12 @@ the following actions without being added to the allowlist: To limit access to these actions to only the projects on the allowlist, set the visibility of each feature to be only accessible to project members: -Prerequisite: +Prerequisites: - You must have the Maintainer role for the project. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Set the visibility to **Only project members** for the features you want to restrict access to. - The ability to fetch artifacts is controlled by the CI/CD visibility setting. @@ -145,7 +145,7 @@ your maintainers, the job token could be used in an attempt to access your proje You can disable the job token scope allowlist for testing or a similar reason, but you should enable it again as soon as possible. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. @@ -166,7 +166,7 @@ You can also disable the allowlist [with the API](../../api/graphql/reference/in You can add projects to the allowlist for a project. Projects added to the allowlist can make API calls from running pipelines by using the CI/CD job token. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role in the current project. If the allowed project is internal or private, you must have at least the Guest role in that project. @@ -210,7 +210,7 @@ to make an API request to project `B`, then `B` must be added to the allowlist f > **Limit CI_JOB_TOKEN access** setting [renamed to **Limit access _from_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3. -Prerequisite: +Prerequisites: - You must not have more than 200 projects added to the token's scope. diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index b5fc32e69dc..f4836f93234 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs **(FREE ALL)** @@ -375,6 +375,14 @@ job1: - echo -e "\e[0Ksection_end:`date +%s`:my_first_section\r\e[0K" ``` +### Full screen mode + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363617) in GitLab 16.7. + +You can view the contents of a job log in full screen mode by clicking **Show full screen**. + +To use full screen mode, your web browser must also support it. If your web browser does not support full screen mode, then the option is not available. + ## Deployment jobs Deployment jobs are a specific kind of CI job in that they deploy code to diff --git a/doc/ci/jobs/job_artifacts.md b/doc/ci/jobs/job_artifacts.md index b6269918ed9..f93068faf01 100644 --- a/doc/ci/jobs/job_artifacts.md +++ b/doc/ci/jobs/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Job artifacts **(FREE ALL)** @@ -67,6 +67,8 @@ is used. To prevent artifacts from expiring, you can select **Keep** from the job details page. The option is not available when an artifact has no expiry set. +By default, the [latest artifacts are always kept](#keep-artifacts-from-most-recent-successful-jobs). + ### With a dynamically defined name You can use [CI/CD variables](../variables/index.md) to dynamically define the @@ -227,17 +229,21 @@ unless the report is added as a regular artifact with `artifacts:paths`. You can download the artifacts archive for a specific job with a publicly accessible URL for the [job artifacts API](../../api/job_artifacts.md#download-the-artifacts-archive). -For example, to download the latest artifacts of a job named `build` in the `main` branch of a project on GitLab.com: +For example: -```plaintext -https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build -``` +- To download the latest artifacts of a job named `build` in the `main` branch of a project on GitLab.com: -For example, to download the file `review/index.html` from the latest job named `build` in the `main` branch of a project on GitLab.com: + ```plaintext + https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build + ``` -```plaintext -https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/raw/review/index.html?job=build -``` +- To download the file `review/index.html` from the latest job named `build` in the `main` branch of a project on GitLab.com: + + ```plaintext + https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/raw/review/index.html?job=build + ``` + + Files returned by this endpoint always have the `plain/text` content type. In both examples, replace `<project-id>` with a valid project ID, found at the top of the project details page. @@ -327,15 +333,21 @@ With this configuration, GitLab adds **artifact 1** as a link to `file.txt` to t > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4. > - [Made optional with a CI/CD setting](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8. +> - Artifacts for [blocked](https://gitlab.com/gitlab-org/gitlab/-/issues/387087) or [failed](https://gitlab.com/gitlab-org/gitlab/-/issues/266958) pipelines no longer kept indefinitely in GitLab 16.7. + +By default artifacts are always kept for successful pipelines for the most recent commit on each ref. +Any [`expire_in`](#with-an-expiry) configuration does not apply to the most recent artifacts. -By default artifacts are always kept for successful pipelines for the most recent commit on -each ref. This means that the latest artifacts do not immediately expire according -to the `expire_in` configuration. +A pipeline's artifacts are only deleted according to the `expire_in` configuration +if a new pipeline runs for the same ref and: -If a pipeline for a new commit on the same ref completes successfully, the previous pipeline's -artifacts are deleted according to the `expire_in` configuration. The artifacts -of the new pipeline are kept automatically. If multiple pipelines run for the most -recent commit on the ref, all artifacts are kept. +- Succeeds. +- Fails. +- Stops running due to being blocked by a manual job. + +Additionally, artifacts are kept for the ref's last successful pipeline even if it +is not the latest pipeline. As a result, if a new pipeline run fails, the last successful pipeline's +artifacts are still kept. Keeping the latest artifacts can use a large amount of storage space in projects with a lot of jobs or large artifacts. If the latest artifacts are not needed in @@ -352,7 +364,3 @@ Then the artifacts in the earlier pipeline for that ref are allowed to expire to You can disable this behavior for all projects on a self-managed instance in the [instance's CI/CD settings](../../administration/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). - -When **Keep artifacts from most recent successful jobs** is enabled, artifacts are always kept for [blocked](job_control.md#types-of-manual-jobs) -pipelines. These artifacts expire only after the blocking job is triggered and the pipeline completes. -[Issue 387087](https://gitlab.com/gitlab-org/gitlab/-/issues/387087) proposes to change this behavior. diff --git a/doc/ci/jobs/job_artifacts_troubleshooting.md b/doc/ci/jobs/job_artifacts_troubleshooting.md index f2efa8da9eb..0b7777d2d82 100644 --- a/doc/ci/jobs/job_artifacts_troubleshooting.md +++ b/doc/ci/jobs/job_artifacts_troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting job artifacts @@ -29,7 +29,7 @@ If job artifacts are using too much disk space, see the This message appears in job logs when a the runner can't find the file to upload. Either the path to the file is incorrect, or the file was not created. You can check the job -log for other errors or warnings that specify the filename and why it wasn't +log for other errors or warnings that specify the file name and why it wasn't generated. For more detailed job logs, you can [enable CI/CD debug logging](../variables/index.md#enable-debug-logging) diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index 0c8e4fc593f..b432106a2d8 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Choose when to run jobs **(FREE ALL)** @@ -1080,6 +1080,14 @@ produce an `invalid expression syntax` error. Pattern matching is case-sensitive by default. Use the `i` flag modifier to make a pattern case-insensitive. For example: `/pattern/i`. +NOTE: +When using the `=~` character, make sure the right side of the comparison always contains +a valid regular expression. If the right side of the comparison is not a valid regular expression +enclosed with `/` characters, the expression evaluates in an unexpected way. In that case, +the comparison checks if the left side is a substring of the right side. For example, +`"23" =~ "1234"` evaluates to true, which is the opposite of `"23" =~ /1234/`, which evaluates to false. +You should not configure your pipeline to rely on this behavior. + #### Store the regex pattern in a variable > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35438) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `ci_fix_rules_if_comparison_with_regexp_variable`, disabled by default. diff --git a/doc/ci/lint.md b/doc/ci/lint.md index 2b54c645807..88ea4cd05d7 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Validate GitLab CI/CD configuration **(FREE ALL)** @@ -15,7 +15,7 @@ If you use the [pipeline editor](pipeline_editor/index.md), it verifies configur syntax automatically. If you use VS Code, you can validate your CI/CD configuration with the -[GitLab Workflow VS Code extension](../user/project/repository/vscode.md). +[GitLab Workflow VS Code extension](../editor_extensions/visual_studio_code/index.md). ## Check CI/CD syntax diff --git a/doc/ci/migration/bamboo.md b/doc/ci/migration/bamboo.md index 93091d2a30a..ea9dd666176 100644 --- a/doc/ci/migration/bamboo.md +++ b/doc/ci/migration/bamboo.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from Bamboo **(FREE ALL)** diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 5b171a646f5..f397a1cf733 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -1,13 +1,12 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from CircleCI **(FREE ALL)** -If you are currently using CircleCI, you can migrate your CI/CD pipelines to [GitLab CI/CD](../introduction/index.md), +If you are currently using CircleCI, you can migrate your CI/CD pipelines to [GitLab CI/CD](../index.md), and start making use of all its powerful features. We have collected several resources that you may find useful before starting to migrate. diff --git a/doc/ci/migration/examples/jenkins-maven.md b/doc/ci/migration/examples/jenkins-maven.md index 0ed08357eef..858f0272502 100644 --- a/doc/ci/migration/examples/jenkins-maven.md +++ b/doc/ci/migration/examples/jenkins-maven.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate a Maven build from Jenkins to GitLab CI/CD diff --git a/doc/ci/migration/github_actions.md b/doc/ci/migration/github_actions.md index 46d15f506ac..ec55f129c1e 100644 --- a/doc/ci/migration/github_actions.md +++ b/doc/ci/migration/github_actions.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from GitHub Actions **(FREE ALL)** @@ -467,7 +466,7 @@ Some key details about runners: - Runners can be [configured](../runners/runners_scope.md) to be shared across an instance, a group, or dedicated to a single project. -- You can use the [`tags` keyword](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) +- You can use the [`tags` keyword](../runners/configure_runners.md#control-jobs-that-a-runner-can-run) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. - GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 4352b495e7b..f430b1ac7b9 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from Jenkins **(FREE ALL)** @@ -483,7 +482,7 @@ Some key details about runners: - Runners can be [configured](../runners/runners_scope.md) to be shared across an instance, a group, or dedicated to a single project. -- You can use the [`tags` keyword](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) +- You can use the [`tags` keyword](../runners/configure_runners.md#control-jobs-that-a-runner-can-run) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. - GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). diff --git a/doc/ci/migration/plan_a_migration.md b/doc/ci/migration/plan_a_migration.md index 22c4645d6c2..c6e4baabb92 100644 --- a/doc/ci/migration/plan_a_migration.md +++ b/doc/ci/migration/plan_a_migration.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Plan a migration from another tool to GitLab CI/CD diff --git a/doc/ci/mobile_devops.md b/doc/ci/mobile_devops.md index 4e1a0f4683c..e871a95d29f 100644 --- a/doc/ci/mobile_devops.md +++ b/doc/ci/mobile_devops.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mobile DevOps **(EXPERIMENT)** diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 1dc6bc05e71..cc7b032a487 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline editor **(FREE ALL)** @@ -45,7 +44,11 @@ The **Lint** tab is replaced with the **Validate** tab in GitLab 15.3. The lint in a successful [pipeline simulation](#simulate-a-cicd-pipeline). To test the validity of your GitLab CI/CD configuration before committing the changes, -you can use the CI lint tool. To access it, go to **Build > Pipeline editor** and select the **Lint** tab. +you can use the CI lint tool: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Build > Pipeline editor**. +1. Select the **Lint** tab. This tool checks for syntax and logical errors but goes into more detail than the automatic [validation](#validate-ci-configuration) in the editor. diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index a6b2774dbde..699136ccf97 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compute quota **(PREMIUM ALL)** @@ -53,15 +52,14 @@ By default, GitLab instances do not have a compute quota. The default value for the quota is `0`, which is unlimited. However, you can change this default value. -Prerequisite: +Prerequisites: - You must be a GitLab administrator. To change the default quota that applies to all namespaces: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. In the **Compute quota** box, enter a limit. 1. Select **Save changes**. @@ -75,15 +73,14 @@ If a quota is already defined for a specific namespace, this value does not chan You can override the global value and set a compute quota for a specific namespace. -Prerequisite: +Prerequisites: - You must be a GitLab administrator. To set a compute quota for a namespace: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Groups**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Groups**. 1. For the group you want to update, select **Edit**. 1. In the **Compute quota** box, enter the maximum number of compute minutes. 1. Select **Save changes**. @@ -97,7 +94,7 @@ If you set a quota for a subgroup, it is not used. ## View compute usage -Prerequisite: +Prerequisites: - You must have access to the build to view the total usage and quota summary for a namespace associated with a build. - Access to **Usage Quotas** page is based on your role in the associated namespace or group. @@ -106,7 +103,7 @@ Prerequisite: > Displaying shared runners duration per project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355666) in GitLab 15.0. -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -125,7 +122,7 @@ subgroups, sorted in descending order of compute usage. > Displaying shared runners duration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345795) in GitLab 15.0. -Prerequisite: +Prerequisites: - The namespace must be your personal namespace. @@ -164,7 +161,7 @@ You can find pricing for additional compute minutes on the ### Purchase compute minutes for a group **(FREE SAAS)** -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -183,7 +180,7 @@ namespace. ### Purchase compute minutes for a personal namespace **(FREE SAAS)** -Prerequisite: +Prerequisites: - The namespace must be your personal namespace. diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 21ed66ef939..61862a20436 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Downstream pipelines **(FREE ALL)** @@ -671,9 +671,7 @@ the ones defined in the upstream project take precedence. ### Pass dotenv variables created in a job **(PREMIUM ALL)** -You can pass variables to a downstream job with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job) -and [`needs:project`](../yaml/index.md#needsproject). These variables are only available in -the script of the job and can't be used to configure it, for example with `rules` or `artifact:paths`. +You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job). For example, in a [multi-project pipeline](#multi-project-pipelines): diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index f0f0f6d29d2..957e0e0de27 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD pipelines **(FREE ALL)** @@ -126,7 +125,7 @@ you can filter the pipeline list by: pipeline column to display the pipeline ID or the pipeline IID. If you use VS Code to edit your GitLab CI/CD configuration, the -[GitLab Workflow VS Code extension](../../user/project/repository/vscode.md) helps you +[GitLab Workflow VS Code extension](../../editor_extensions/visual_studio_code/index.md) helps you [validate your configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration) and [view your pipeline status](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). @@ -263,18 +262,11 @@ In the example below, the `production` stage has a job with a manual action:  -#### Start multiple manual actions in a stage +#### Start all manual jobs in a stage -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27188) in GitLab 11.11. - -Multiple manual actions in a single stage can be started at the same time using the "Play all manual" -After you select this action, each individual manual action is triggered and refreshed -to an updated status. - -This functionality is only available: - -- For users with at least the Developer role. -- If the stage contains [manual actions](#add-manual-interaction-to-your-pipeline). +If a stage contains only manual jobs, you can start all the jobs at the same time +by selecting **Play all manual** (**{play}**) above the stage. If the stage contains +non-manual jobs, the option is not displayed. ### Skip a pipeline diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index fb1c19d8770..0de55d2a488 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -39,19 +39,20 @@ Both of these types of pipelines can appear on the **Pipelines** tab of a merge ## Types of merge request pipelines +> - The `detached` label was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352939) to `merge request` in GitLab 14.9. +> - The `merged results` label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132975) in GitLab 16.5. + The three types of merge request pipelines are: - Merge request pipelines, which run on the changes in the merge request's - source branch. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352939) - in GitLab 14.9, these pipelines display a `merge request` label to indicate that the - pipeline ran only on the contents of the source branch, ignoring the target branch. - In GitLab 14.8 and earlier, the label is `detached`. + source branch, ignoring the target branch. These pipelines display a `merge request` label in pipeline lists. - [Merged results pipelines](merged_results_pipelines.md), which run on the result of combining the source branch's changes with the target branch. + These pipelines display a `merged results` label in pipeline lists. - [Merge trains](merge_trains.md), which run when merging multiple merge requests at the same time. The changes from each merge request are combined into the target branch with the changes in the earlier enqueued merge requests, to ensure - they all work together. + they all work together. These pipelines display a `merge train` label in pipeline lists. ## Prerequisites @@ -136,7 +137,7 @@ Pipelines for forks display with the **fork** badge in the parent project:  -### Run pipelines in the parent project **(PREMIUM ALL)** +### Run pipelines in the parent project Project members in the parent project can trigger a merge request pipeline for a merge request submitted from a fork project. This pipeline: diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index a54087262e7..45d9e548d6a 100644 --- a/doc/ci/pipelines/merge_trains.md +++ b/doc/ci/pipelines/merge_trains.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge trains **(PREMIUM ALL)** @@ -162,13 +162,15 @@ When you remove a merge request from a merge train: ## Skip the merge train and merge immediately If you have a high-priority merge request, like a critical patch that must -be merged urgently, select **Merge Immediately**. +be merged urgently, you can select **Merge Immediately**. When you merge a merge request immediately: -- The current merge train is recreated. -- All pipelines restart. -- Redundant pipelines [are cancelled](#automatic-pipeline-cancellation). +- The commits from the merge request are merged, ignoring the status of the merge train. +- The merge train pipelines for all other merge requests on the train [are cancelled](#automatic-pipeline-cancellation). +- A new merge train starts and all the merge requests from the original merge train are added to this new merge train, + with a new merge train pipeline for each. These new merge train pipelines now contain + the commits added by the merge request that was merged immediately. WARNING: Merging immediately can use a lot of CI/CD resources. Use this option diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md index afe7a450370..213a07f49c4 100644 --- a/doc/ci/pipelines/merged_results_pipelines.md +++ b/doc/ci/pipelines/merged_results_pipelines.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merged results pipelines **(PREMIUM ALL)** @@ -32,8 +32,6 @@ To use merged results pipelines: [run jobs in merge request pipelines](merge_request_pipelines.md#prerequisites). - Your repository must be a GitLab repository, not an [external repository](../ci_cd_for_external_repos/index.md). -- You must not be using [fast forward merges](../../user/project/merge_requests/methods/index.md). - [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/26996) to change this behavior. ## Enable merged results pipelines diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index 305e48ca9f5..9ca2bf26e59 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline architecture **(FREE ALL)** diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 3d24be0f8e1..4a548c8c0af 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline efficiency **(FREE ALL)** @@ -19,7 +18,7 @@ and improve their configuration over time through trial and error. A better proc to use pipeline features that improve efficiency right away, and get a faster software development lifecycle earlier. -First ensure you are familiar with [GitLab CI/CD fundamentals](../introduction/index.md) +First ensure you are familiar with [GitLab CI/CD fundamentals](../index.md) and understand the [quick start guide](../quick_start/index.md). ## Identify bottlenecks and common failures diff --git a/doc/ci/pipelines/pipeline_security.md b/doc/ci/pipelines/pipeline_security.md index d499da21b88..cecc1789946 100644 --- a/doc/ci/pipelines/pipeline_security.md +++ b/doc/ci/pipelines/pipeline_security.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline security diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 1003c03bebf..f83868952f5 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Scheduled pipelines **(FREE ALL)** @@ -61,7 +60,7 @@ To trigger a pipeline schedule manually, so that it runs immediately instead of the next scheduled time: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Build > Pipeline schedules**. +1. Select **Build > Pipeline schedules**. 1. On the right of the list, for the pipeline you want to run, select **Play** (**{play}**). @@ -80,7 +79,7 @@ including [protected environments](../environments/protected_environments.md) an To take ownership of a pipeline created by a different user: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Build > Pipeline schedules**. +1. Select **Build > Pipeline schedules**. 1. On the right of the list, for the pipeline you want to become owner of, select **Take ownership**. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 321eae183eb..09bfe3ac195 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customize pipeline configuration **(FREE ALL)** @@ -103,19 +102,37 @@ To avoid this scenario: For more information, see [Deployment safety](../environments/deployment_safety.md#prevent-outdated-deployment-jobs). +## Restrict roles that can cancel pipelines or jobs **(PREMIUM ALL)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137301) in GitLab 16.7. + +You can customize which roles have permission to cancel pipelines or jobs. + +By default, users with at least the Developer role can cancel pipelines or jobs. +You can restrict cancellation permission to only users with at least the Maintainer role, +or completely prevent cancellation of any pipelines or jobs. + +To change the permissions to cancel pipelines or jobs: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > CI/CD**. +1. Expand **General pipelines**. +1. Select an option from **Minimum role required to cancel a pipeline or job**. +1. Select **Save changes**. + ## Specify a custom CI/CD configuration file > Support for external `.gitlab-ci.yml` locations [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14376) in GitLab 12.6. GitLab expects to find the CI/CD configuration file (`.gitlab-ci.yml`) in the project's root -directory. However, you can specify an alternate filename path, including locations outside the project. +directory. However, you can specify an alternate file name path, including locations outside the project. To customize the path: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **General pipelines**. -1. In the **CI/CD configuration file** field, enter the filename. If the file: +1. In the **CI/CD configuration file** field, enter the file name. If the file: - Is not in the root directory, include the path. - Is in a different project, include the group and project name. - Is on an external site, enter the full URL. @@ -208,7 +225,7 @@ You can define how long a job can run before it times out. Jobs that exceed the timeout are marked as failed. -You can override this value [for individual runners](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). +You can override this value [for individual runners](../runners/configure_runners.md#set-the-maximum-job-timeout). ## Pipeline badges diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 1f8c33a9700..3da4e5ad023 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create and run your first GitLab CI/CD pipeline **(FREE ALL)** diff --git a/doc/ci/quick_start/tutorial.md b/doc/ci/quick_start/tutorial.md index 41239615590..389309538e9 100644 --- a/doc/ci/quick_start/tutorial.md +++ b/doc/ci/quick_start/tutorial.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create a complex pipeline diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md index bf41d325ac2..b7b9c216b14 100644 --- a/doc/ci/resource_groups/index.md +++ b/doc/ci/resource_groups/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Control the job concurrency in GitLab CI/CD --- @@ -259,33 +259,40 @@ Sometimes, a job hangs with the message `Waiting for resource: <resource_group>` first check that the resource group is working correctly: 1. Go to the job details page. -1. Select **View job currently using resource**. -1. Check the job status: - - If the status is `running` or `pending`, the feature is working correctly. Wait until the job finishes and releases the resource. - - If the status is `created` and the [process mode](#process-modes) is either **Oldest first** or **Newest first**, the feature is working correctly. +1. If the resource is assigned to a job, select **View job currently using resource** and check the job status. + + - If the status is `running` or `pending`, the feature is working correctly. Wait until the job finishes and releases the resource. + - If the status is `created` and the [process mode](#process-modes) is either **Oldest first** or **Newest first**, the feature is working correctly. Visit the pipeline page of the job and check which upstream stage or job is blocking the execution. - - If none of the above conditions are met, the feature might not be working correctly. - [Open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) with the following information: - - The job ID. - - The job status. - - How often the problem occurs. - - Steps to reproduce the problem. + - If none of the above conditions are met, the feature might not be working correctly. [Report the issue to GitLab](#report-an-issue). + +1. If **View job currently using resource** is not available, the resource is not assigned to a job. Instead, check the resource's upcoming jobs. + + 1. Get the resource's upcoming jobs with the [REST API](../../api/resource_groups.md#list-upcoming-jobs-for-a-specific-resource-group). + 1. Verify that the job's [process mode](#process-modes) is **Oldest first**. + 1. Find the first job in the list of upcoming jobs, and get the job details [with GraphQL](#get-job-details-through-graphql). + 1. If the first job's pipeline is an older pipeline, try to cancel the pipeline or the job itself. + 1. Optional. Repeat this process if the next upcoming job is still in an older pipeline that should no longer run. + 1. If the problem persists, [report the issue to GitLab](#report-an-issue). + +#### Get job details through GraphQL -You can also get job information from the GraphQL API. You should use the GraphQL API if you use [pipeline-level concurrency control with cross-project/parent-child pipelines](#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines) because the trigger jobs are not accessible from the UI. +You can get job information from the GraphQL API. You should use the GraphQL API if you use [pipeline-level concurrency control with cross-project/parent-child pipelines](#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines) because the trigger jobs are not accessible from the UI. To get job information from the GraphQL API: 1. Go to the pipeline details page. 1. Select the **Jobs** tab and find the ID of the stuck job. -1. Go to [GraphiQL explorer](../../api/graphql/index.md#graphiql). +1. Go to the [interactive GraphQL explorer](../../api/graphql/index.md#interactive-graphql-explorer). 1. Run the following query: ```graphql { project(fullPath: "<fullpath-to-your-project>") { name - job(id: "gid://gitlab/Ci::Bridge/<job-id>") { + job(id: "gid://gitlab/Ci::Build/<job-id>") { name + status detailedStatus { action { path @@ -305,7 +312,7 @@ To get job information from the GraphQL API: { project(fullPath: "<fullpath-to-your-project>") { name - job(id: "gid://gitlab/Ci::Bridge/<job-id-currently-using-the-resource>") { + job(id: "gid://gitlab/Ci::Build/<job-id-currently-using-the-resource>") { name status pipeline { @@ -316,4 +323,13 @@ To get job information from the GraphQL API: } ``` - If the status is not `running` or `pending`, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and [contact support](https://about.gitlab.com/support/#contact-support) so they can apply the correct labels to the issue. +### Report an issue + +[Open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) with the following information: + +- The ID of the affected job. +- The job status. +- How often the problem occurs. +- Steps to reproduce the problem. + + You can also [contact support](https://about.gitlab.com/support/#contact-support) for further assistance, or to get in touch with the development team. diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index f831c53c024..3ff25cc8bab 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review apps **(FREE ALL)** @@ -70,7 +70,7 @@ as mentioned above. To facilitate this, and if you are using Kubernetes, you can **Enable review apps** and GitLab prompts you with a template code block that you can copy and paste into `.gitlab-ci.yml` as a starting point. -Prerequisite: +Prerequisites: - You need at least the Developer role for the project. diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index bca0b50563a..3b21d865d8b 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring runners **(FREE ALL)** @@ -11,53 +11,79 @@ If you have installed your own runners, you can configure and secure them in Git If you need to configure runners on the machine where you installed GitLab Runner, see [the GitLab Runner documentation](https://docs.gitlab.com/runner/configuration/). -## Manually clear the runner cache +## Set the maximum job timeout -Read [clearing the cache](../caching/index.md#clearing-the-cache). +You can specify a maximum job timeout for each runner to prevent projects +with longer job timeouts from using the runner. The maximum job timeout is +used of it is shorter than the job timeout defined in the project. -## Set maximum job timeout for a runner +### For a shared runner -For each runner, you can specify a *maximum job timeout*. This timeout, -if smaller than the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run), takes precedence. +Prerequisites: + +- You must be an administrator. + +On GitLab.com, you cannot override the job timeout for shared runners and must use the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) instead. + +To set the maximum job timeout: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner, you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). +1. Select **Save changes**. + +### For a group runner + +Prerequisites: + +- You must have the Owner role for the group. -This feature can be used to prevent your shared runner from being overwhelmed -by a project that has jobs with a long timeout (for example, one week). +To set the maximum job timeout: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). +1. Select **Save changes**. -On GitLab.com, you cannot override the job timeout for shared runners and must use the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run). +### For a project runner + +Prerequisites: + +- You must have the Owner role for the project. To set the maximum job timeout: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. -1. Select your project runner to edit the settings. -1. Enter a value under **Maximum job timeout**. Must be 10 minutes or more. If not - defined, the [project's job timeout setting](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) - is used. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. In the **Maximum job timeout** field, enter a value in seconds. The minimum amount is 600 seconds (10 minutes). If not defined, the [job timeout for the project](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) is used instead. 1. Select **Save changes**. -How this feature works: +## How maximum job timeout works **Example 1 - Runner timeout bigger than project timeout** -1. You set the _maximum job timeout_ for a runner to 24 hours -1. You set the _CI/CD Timeout_ for a project to **2 hours** -1. You start a job -1. The job, if running longer, times out after **2 hours** +1. You set the _maximum job timeout_ for a runner to 24 hours. +1. You set the _CI/CD Timeout_ for a project to **2 hours**. +1. You start a job. +1. The job, if running longer, times out after **2 hours**. **Example 2 - Runner timeout not configured** -1. You remove the _maximum job timeout_ configuration from a runner -1. You set the _CI/CD Timeout_ for a project to **2 hours** -1. You start a job -1. The job, if running longer, times out after **2 hours** +1. You remove the _maximum job timeout_ configuration from a runner. +1. You set the _CI/CD Timeout_ for a project to **2 hours**. +1. You start a job. +1. The job, if running longer, times out after **2 hours**. **Example 3 - Runner timeout smaller than project timeout** -1. You set the _maximum job timeout_ for a runner to **30 minutes** -1. You set the _CI/CD Timeout_ for a project to 2 hours -1. You start a job -1. The job, if running longer, times out after **30 minutes** +1. You set the _maximum job timeout_ for a runner to **30 minutes**. +1. You set the _CI/CD Timeout_ for a project to 2 hours. +1. You start a job. +1. The job, if running longer, times out after **30 minutes**. ## Set `script` and `after_script` timeouts @@ -66,7 +92,7 @@ How this feature works: To control the amount of time `script` and `after_script` runs before it terminates, you can set specify a timeout. For example, you can specify a timeout to terminate a long-running `script` early, so that artifacts and caches can still be uploaded -before the [job timeout](#set-maximum-job-timeout-for-a-runner) is exceeded. +before the job timeout is exceeded. - To set a timeout for `script`, use the job variable `RUNNER_SCRIPT_TIMEOUT`. - To set a timeout for `after_script`, and override the default of 5 minutes, use the job variable `RUNNER_AFTER_SCRIPT_TIMEOUT`. @@ -105,26 +131,11 @@ of shared runners on large GitLab instances. This ensures that you control access to your GitLab instances and secure [runner executors](https://docs.gitlab.com/runner/executors/). If certain executors run a job, the file system, the code the runner executes, -and the runner authentication token may be exposed. This means that anyone that runs jobs +and the runner authentication token may be exposed. This means that anyone who runs jobs on a _shared runner_ can access another user's code that runs on the runner. Users with access to the runner authentication token can use it to create a clone of a runner and submit false jobs in a vector attack. For more information, see [Security Considerations](https://docs.gitlab.com/runner/security/). -### Prevent runners from revealing sensitive information - -To ensure runners don't reveal sensitive information, you can configure them to only run jobs -on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md). - -To prevent runners from revealing sensitive information: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > CI/CD**. -1. Expand **Runners**. -1. Find the runner you want to protect or unprotect. Make sure the runner is enabled. -1. Select **Edit** (**{pencil}**). -1. Select the **Protected** checkbox. -1. Select **Save changes**. - ### Using shared runners in forked projects When a project is forked, the job settings related to jobs are copied. If you have shared runners @@ -163,6 +174,23 @@ After you reset the registration token, it is no longer valid and does not regis any new runners to the project. You should also update the registration token in tools you use to provision and register new values. +## Authentication token security + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/377902) in GitLab 15.5. Feature flag `enforce_runner_token_expires_at` removed. + +Each runner has an [runner authentication token](../../api/runners.md#registration-and-authentication-tokens) +to connect with the GitLab instance. + +To help prevent the token from being compromised, you can have the +token rotate automatically at specified intervals. When the tokens are rotated, +they are updated for each runner, regardless of the runner's status (`online` or `offline`). + +No manual intervention should be required, and no running jobs should be affected. + +If you need to manually update the runner authentication token, you can run a +command to [reset the token](https://docs.gitlab.com/runner/commands/#gitlab-runner-reset-token). + ### Reset the runner authentication token If a runner authentication token is revealed, an attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). @@ -179,37 +207,131 @@ To reset the runner authentication token: - [Create a project runner](runners_scope.md#create-a-project-runner-with-a-runner-authentication-token). 1. Optional. To verify that the previous runner authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). -## Use tags to control which jobs a runner can run +### Automatically rotate runner authentication tokens + +You can specify an interval for runner authentication tokens to rotate. +This rotation helps ensure the security of the tokens assigned to your runners. + +Prerequisites: + +- Runners must use [GitLab Runner 15.3 or later](https://docs.gitlab.com/runner/#gitlab-runner-versions). +- You must be an administrator. + +To automatically rotate runner authentication tokens: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD**. +1. Expand **Continuous Integration and Deployment**. +1. Set a **Runners expiration** time for runners, leave empty for no expiration. +1. Select **Save changes**. + +Before the interval expires, runners automatically request a new runner authentication token. + +## Prevent runners from revealing sensitive information + +To ensure runners don't reveal sensitive information, you can configure them to only run jobs +on [protected branches](../../user/project/protected_branches.md), or jobs that have [protected tags](../../user/project/protected_tags.md). + +Runners configured to run jobs on protected branches cannot run jobs in [merge request pipelines](../pipelines/merge_request_pipelines.md). + +### For a shared runner + +Prerequisites: + +- You must be an administrator. + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +### For a group runner + +Prerequisites: + +- You must have the Owner role for the group. + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +### For a project runner + +Prerequisites: + +- You must have the Owner role for the project. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > CI/CD**. +1. Expand **Runners**. +1. To the right of the runner you want to protect, select **Edit** (**{pencil}**). +1. Select the **Protected** checkbox. +1. Select **Save changes**. + +## Control jobs that a runner can run -You can use [tags](../yaml/index.md#tags) to ensure that runners only run the jobs they are equipped -to run. For example, you can specify the `rails` tag for runners that have the dependencies to run +You can use [tags](../yaml/index.md#tags) to control the jobs a runner can run. +For example, you can specify the `rails` tag for runners that have the dependencies to run Rails test suites. GitLab CI/CD tags are different to Git tags. GitLab CI/CD tags are associated with runners. Git tags are associated with commits. -### Set a runner to run untagged jobs +### For a shared runner + +Prerequisites: + +- You must be an administrator. + +To set the maximum job timeout: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `rails`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. +1. Select **Save changes**. + +### For a group runner -When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** -[tagged jobs](../yaml/index.md#tags). -To change this, you must have the Owner role for the project. +Prerequisites: + +- You must have the Owner role for the group. + +To set the maximum job timeout: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Build > Runners**. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `ruby`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. +1. Select **Save changes**. + +### For a project runner + +Prerequisites: -To make a runner pick untagged jobs: +- You must have the Owner role for the project. + +To set a runner to run tagged jobs: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. 1. Expand **Runners**. -1. Find the runner you want to pick untagged jobs and make sure it's enabled. -1. Select **Edit** (**{pencil}**). -1. Select the **Run untagged jobs** checkbox. +1. To the right of the runner you want to edit, select **Edit** (**{pencil}**). +1. Set the runner to run tagged or untagged jobs: + - To run tagged jobs, in the **Tags** field, enter the job tags separated with a comma. For example, `macos`, `ruby`. + - To run untagged jobs, select the **Run untagged jobs** checkbox. 1. Select **Save changes**. -NOTE: -The runner tags list cannot be empty when it's not allowed to pick untagged jobs. - -Below are some example scenarios of different variations. +### How the runner uses tags -### Runner runs only tagged jobs +#### Runner runs only tagged jobs The following examples illustrate the potential impact of the runner being set to run only tagged jobs. @@ -229,7 +351,7 @@ Example 3: 1. The runner is configured to run only tagged jobs and has the `docker` tag. 1. A job that has no tags defined is executed and stuck. -### Runner is allowed to run untagged jobs +#### Runner is allowed to run untagged jobs The following examples illustrate the potential impact of the runner being set to run tagged and untagged jobs. @@ -246,7 +368,7 @@ Example 2: 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is stuck. -### A runner and a job have multiple tags +#### A runner and a job have multiple tags The selection logic that matches the job and runner is based on the list of `tags` defined in the job. @@ -273,7 +395,9 @@ Example 3: You can use tags to run different jobs on different platforms. For example, if you have an OS X runner with tag `osx` and a Windows runner with tag -`windows`, you can run a job on each platform: +`windows`, you can run a job on each platform. + +Update the `tags` field in the `config.toml`: ```yaml windows job: @@ -295,7 +419,7 @@ osx job: > Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/35742). -You can use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: +In the `.gitlab-ci.yml` file, use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: ```yaml variables: @@ -786,7 +910,7 @@ variables: NOTE: Zip archives are the only supported artifact type. Follow [the issue for details](https://gitlab.com/gitlab-org/gitlab/-/issues/367203). -GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The filename is as follows: `{ARTIFACT_NAME}-metadata.json` where `ARTIFACT_NAME` is what was defined as the [name for the artifact](../jobs/job_artifacts.md#with-a-dynamically-defined-name) in the CI file. The filename, however, defaults to `artifacts-metadata.json` if no name was given to the build artifacts. +GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The file name is as follows: `{ARTIFACT_NAME}-metadata.json` where `ARTIFACT_NAME` is what was defined as the [name for the artifact](../jobs/job_artifacts.md#with-a-dynamically-defined-name) in the CI file. The file name, however, defaults to `artifacts-metadata.json` if no name was given to the build artifacts. ### Attestation format @@ -795,7 +919,7 @@ The attestation metadata is generated in the [in-toto attestation format](https: | Field | Value | | ------ | ------ | | `_type` | `https://in-toto.io/Statement/v0.1` | -| `subject.name` | The filename of the artifact. | +| `subject.name` | The file name of the artifact. | | `subject.digest.sha256` | The artifact's `sha256` checksum. | | `predicateType` | `https://slsa.dev/provenance/v0.2` | | `predicate.buildType` | `https://gitlab.com/gitlab-org/gitlab-runner/-/blob/{GITLAB_RUNNER_VERSION}/PROVENANCE.md`. For example v15.0.0 | @@ -911,40 +1035,3 @@ setting. `FASTZIP_EXTRACTOR_CONCURRENCY` controls how many files are decompressed at once. Files from a zip archive can natively be read from concurrency, so no additional memory is allocated in addition to what the decompressor requires. This defaults to the number of CPUs available. - -## Authentication token security - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/377902) in GitLab 15.5. Feature flag `enforce_runner_token_expires_at` removed. - -Each runner has an [runner authentication token](../../api/runners.md#registration-and-authentication-tokens) -to connect with the GitLab instance. - -To help prevent the token from being compromised, you can have the -token rotate automatically at specified intervals. When the tokens are rotated, -they are updated for each runner, regardless of the runner's status (`online` or `offline`). - -No manual intervention should be required, and no running jobs should be affected. - -If you need to manually update the runner authentication token, you can run a -command to [reset the token](https://docs.gitlab.com/runner/commands/#gitlab-runner-reset-token). - -### Automatically rotate runner authentication tokens - -You can specify an interval for runner authentication tokens to rotate. -This rotation helps ensure the security of the tokens assigned to your runners. - -Prerequisites: - -- Ensure your runners are using [GitLab Runner 15.3 or later](https://docs.gitlab.com/runner/#gitlab-runner-versions). - -To automatically rotate runner authentication tokens: - -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **Continuous Integration and Deployment** -1. Set a **Runners expiration** time for runners, leave empty for no expiration. -1. Select **Save**. - -Before the interval expires, runners automatically request a new runner authentication token. diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 7e597264e1e..1df93ed8896 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner SaaS -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Runner SaaS **(FREE SAAS)** @@ -21,7 +20,7 @@ For more information about the cost factor applied to the machine type based on The number of minutes you can use on these runners depends on the [maximum number of units of compute](../pipelines/cicd_minutes.md) in your [subscription plan](https://about.gitlab.com/pricing/). -[Untagged](../../ci/runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) jobs automatically run in containers +[Untagged](../../ci/runners/configure_runners.md#control-jobs-that-a-runner-can-run) jobs automatically run in containers on the `small` Linux runners. The objective is to make 90% of CI/CD jobs start executing in 120 seconds or less. The error rate should be less than 0.5%. diff --git a/doc/ci/runners/new_creation_workflow.md b/doc/ci/runners/new_creation_workflow.md index 022f7af11ec..c870a89a77a 100644 --- a/doc/ci/runners/new_creation_workflow.md +++ b/doc/ci/runners/new_creation_workflow.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating to the new runner registration workflow **(FREE ALL)** @@ -29,7 +29,7 @@ you can let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab For the new runner registration workflow, you: -1. [Create a runner](register_runner.md) directly in the GitLab UI. +1. [Create a runner](runners_scope.md) directly in the GitLab UI. 1. Receive a runner authentication token. 1. Use the runner authentication token instead of the registration token when you register a runner with this configuration. Runner managers registered in multiple hosts appear @@ -141,7 +141,7 @@ process is started. ## Creating runners programmatically -In GitLab 15.11 and later, you can use the [POST /user/runners REST API](../../api/users.md#create-a-runner) +In GitLab 15.11 and later, you can use the [POST /user/runners REST API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner as an authenticated user. This should only be used if the runner configuration is dynamic or not reusable. If the runner configuration is static, you should reuse the runner authentication token of an existing runner. diff --git a/doc/ci/runners/register_runner.md b/doc/ci/runners/register_runner.md deleted file mode 100644 index bca11682258..00000000000 --- a/doc/ci/runners/register_runner.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'runners_scope.md' -remove_date: '2023-09-21' ---- - -This document was moved to [another location](runners_scope.md). - -<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 6b6493db2c4..48f6a22e9b3 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage runners **(FREE ALL)** @@ -40,7 +39,7 @@ If you are using GitLab.com: > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/389269) in GitLab 16.0. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed. -Prerequisite: +Prerequisites: - You must be an administrator. @@ -48,9 +47,8 @@ When you create a runner, it is assigned a runner authentication token that you To create a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Select **New instance runner**. 1. Select the operating system where GitLab Runner is installed. 1. In the **Tags** section, in the **Tags** field, enter the job tags to specify jobs the runner can run. @@ -65,7 +63,7 @@ To create a shared runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for a limited period of time during registration. After you register the runner, @@ -78,14 +76,13 @@ The ability to pass a runner registration token, and support for certain configu [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). -Prerequisite: +Prerequisites: - You must be an administrator. To create a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. Select **Register an instance runner**. 1. Copy the registration token. @@ -93,14 +90,13 @@ To create a shared runner: ### Pause or resume a shared runner -Prerequisite: +Prerequisites: - You must be an administrator. You can pause a runner so that it does not accept jobs from groups and projects in the GitLab instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or filter the runner list. 1. In the runner list, to the right of the runner: @@ -109,7 +105,7 @@ You can pause a runner so that it does not accept jobs from groups and projects ### Delete shared runners -Prerequisite: +Prerequisites: - You must be an administrator. @@ -119,8 +115,7 @@ jobs, you can [pause](#pause-or-resume-a-shared-runner) the runner instead. To delete a single or multiple shared runners: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or filter the list of runners. 1. Delete the shared runner: @@ -263,7 +258,7 @@ To create a group runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for only a short period of time during registration. @@ -295,7 +290,7 @@ how to [register a runner](https://docs.gitlab.com/runner/register/#register-wit > Ability for users with the Maintainer role to view group runners [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384179) in GitLab 16.4. -Prerequisite: +Prerequisites: - You must have the Maintainer or Owner role for the group. @@ -324,7 +319,7 @@ those in other groups: ### Pause or resume a group runner -Prerequisite: +Prerequisites: - You must be an administrator or have the Owner role for the group. @@ -342,7 +337,7 @@ instance. If you pause a group runner that is used by multiple projects, the run > Multiple runner deletion [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/361721/) in GitLab 15.6. -Prerequisite: +Prerequisites: - You must be an administrator or have the Owner role for the group. @@ -365,7 +360,7 @@ To delete a single or multiple group runners: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363012) in GitLab 15.1. -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -457,7 +452,7 @@ To create a project runner: - For the `executor`, enter the type of [executor](https://docs.gitlab.com/runner/executors/). The executor is the environment where the runner executes the job. -You can also [use the API](../../api/users.md#create-a-runner) to create a runner. +You can also [use the API](../../api/users.md#create-a-runner-linked-to-a-user) to create a runner. NOTE: The runner authentication token displays in the UI for only a short period of time during registration. @@ -469,7 +464,7 @@ The ability to pass a runner registration token, and support for certain configu [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 18.0. Runner authentication tokens should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. @@ -487,7 +482,7 @@ The runner is now enabled for the project. ### Pause or resume a project runner -Prerequisite: +Prerequisites: - You must be an administrator, or have the Maintainer role for the project. @@ -588,9 +583,8 @@ runners are considered. queued for longer than the median value, and half of the jobs queued for less than the median value. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Select **View metrics**. ## Determine which runners need to be upgraded **(ULTIMATE ALL)** @@ -607,8 +601,7 @@ To determine which runners need to be upgraded: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Build > Runners**. - For the instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **CI/CD > Runners**. 1. Above the list of runners, view the status: @@ -631,15 +624,14 @@ different places. ### Determine the IP address of a shared runner -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To determine the IP address of a shared runner: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. Find the runner in the table and view the **IP Address** column.  diff --git a/doc/ci/runners/saas/gpu_saas_runner.md b/doc/ci/runners/saas/gpu_saas_runner.md index 6dc9d8c9534..e9313c65f11 100644 --- a/doc/ci/runners/saas/gpu_saas_runner.md +++ b/doc/ci/runners/saas/gpu_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GPU-enabled SaaS runners **(PREMIUM SAAS)** diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index 23a9b26a8d7..2534db79795 100644 --- a/doc/ci/runners/saas/linux_saas_runner.md +++ b/doc/ci/runners/saas/linux_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Linux **(FREE SAAS)** diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index b503fea4f2f..03c23680c1c 100644 --- a/doc/ci/runners/saas/macos_saas_runner.md +++ b/doc/ci/runners/saas/macos_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on macOS **(PREMIUM SAAS BETA)** @@ -36,11 +36,11 @@ GitLab SaaS provides a set of VM images for macOS. You can execute your build in one of the following images, which you specify in your `.gitlab-ci.yml` file. Each image runs a specific version of macOS and Xcode. -| VM image | Status | -|----------------------------|--------| -| `macos-12-xcode-14` | `GA` | -| `macos-13-xcode-14` | `GA` | -| `macos-14-xcode-15` | `Beta` | +| VM image | Status | | +|----------------------------|--------|--------------| +| `macos-12-xcode-14` | `GA` | | +| `macos-13-xcode-14` | `GA` | [Preinstalled Software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/blob/main/toolchain/macos-13.yml) | +| `macos-14-xcode-15` | `Beta` | [Preinstalled Software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/blob/main/toolchain/macos-14.yml) | If no image is specified, the macOS runner uses `macos-13-xcode-14`. @@ -48,7 +48,7 @@ If no image is specified, the macOS runner uses `macos-13-xcode-14`. macOS and Xcode follow a yearly release cadence, during which GitLab increments its versions synchronously. GitLab typically supports multiple versions of preinstalled tools. For more information, see the [full list of preinstalled software](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/job-images/-/tree/main/toolchain). -When Apple releases a new macOS version, GitLab releases a new `stable` image based on the OS in the next release, +When Apple releases a new macOS version, GitLab releases a new `stable` image based on the OS in the next release, which is in Beta. With the release of the first patch to macOS, the `stable` image becomes Generally Available (GA). As only two GA images are supported at a time, the prior OS version becomes deprecated and is deleted after three months in accordance with the [supported image lifecycle](../index.md#supported-image-lifecycle). diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index 108388f22c8..fd1d5ba1ab7 100644 --- a/doc/ci/runners/saas/windows_saas_runner.md +++ b/doc/ci/runners/saas/windows_saas_runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Windows **(FREE SAAS BETA)** diff --git a/doc/ci/secrets/azure_key_vault.md b/doc/ci/secrets/azure_key_vault.md index d8a511e8bdf..6eefd0da74c 100644 --- a/doc/ci/secrets/azure_key_vault.md +++ b/doc/ci/secrets/azure_key_vault.md @@ -1,16 +1,13 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Azure Key Vault secrets in GitLab CI/CD **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab and GitLab Runner 16.3. - -NOTE: -A [bug was discovered](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) and this feature might not work as expected or at all. A fix is scheduled for a future release. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271271) in GitLab and GitLab Runner 16.3. Due to [issue 424746](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) this feature did not work as expected. +> - [Issue 424746](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) resolved and this feature made generally available in GitLab Runner 16.6. You can use secrets stored in the [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault/) in your GitLab CI/CD pipelines. @@ -69,8 +66,8 @@ RESPONSE 400 Bad Request AADSTS50027: JWT token is invalid or malformed. ``` -This occurs due to a known issue in GitLab Runner where the JWT token isn't parsed correctly. -A fix is [scheduled for a future GitLab Runner release](https://gitlab.com/gitlab-org/gitlab/-/issues/424746). +This occurs due to a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/424746) in GitLab Runner where the JWT token isn't parsed correctly. +To resolve this, upgrade to GitLab Runner 16.6 or later. ### `Caller is not authorized to perform action on resource` message @@ -83,7 +80,7 @@ Caller is not authorized to perform action on resource.\r\nIf role assignments, ForbiddenByRbac ``` -If your Azure Key Vault is using RBAC, you must add the **Key Vault Secrets User** to your Azure AD +If your Azure Key Vault is using RBAC, you must add the **Key Vault Secrets User** role assignment to your Azure AD application. For example: diff --git a/doc/ci/secrets/convert-to-id-tokens.md b/doc/ci/secrets/convert-to-id-tokens.md index 20eae01f45b..80d1a1febd2 100644 --- a/doc/ci/secrets/convert-to-id-tokens.md +++ b/doc/ci/secrets/convert-to-id-tokens.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Update HashiCorp Vault configuration to use ID Tokens **(PREMIUM ALL)** diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md index 325972e06c2..1b3a6b837a5 100644 --- a/doc/ci/secrets/id_token_authentication.md +++ b/doc/ci/secrets/id_token_authentication.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OpenID Connect (OIDC) Authentication Using ID Tokens **(FREE ALL)** diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index e663d8d5c14..e452b26d8a9 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using external secrets in CI **(FREE ALL)** diff --git a/doc/ci/secure_files/index.md b/doc/ci/secure_files/index.md index d2ce98ad048..ee074c2a99c 100644 --- a/doc/ci/secure_files/index.md +++ b/doc/ci/secure_files/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project-level Secure Files **(FREE ALL)** @@ -61,3 +60,26 @@ WARNING: The content of files loaded with the `download-secure-files` tool are not [masked](../variables/index.md#mask-a-cicd-variable) in the job log output. Make sure to avoid outputting secure file contents in the job log, especially when logging output that could contain sensitive information. + +## Security details + +Project-level Secure Files are encrypted on upload using the [Lockbox](https://github.com/ankane/lockbox) +Ruby gem by using the [`Ci::SecureFileUploader`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/uploaders/ci/secure_file_uploader.rb) +interface. This interface generates a SHA256 checksum of the source file during upload +that is persisted with the record in the database so it can be used to verify the contents +of the file when downloaded. + +A [unique encryption key](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/secure_file.rb#L27) +is generated for each file when it is created and persisted in the database. The encrypted uploaded files +are stored in either local storage or object storage depending on the [GitLab instance configuration](../../administration/secure_files.md). + +Individual files can be retrieved with the [secure files download API](../../api/secure_files.md#download-secure-file). +Metadata can be retrieved with the [list](../../api/secure_files.md#list-project-secure-files) +or [show](../../api/secure_files.md#show-secure-file-details) API endpoints. Files can also be retrieved +with the [`download-secure-files`](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files) +tool. This tool automatically verifies the checksum of each file as it is downloaded. + +Any project member with at least the Developer role can access Project-level secure files. +Interactions with Project-level secure files are not included in Audit Events, but +[issue 117](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/readme/-/issues/117). +proposes adding this functionality. diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 54fc664ef12..94fba9cff98 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitLab as a microservice **(FREE ALL)** diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index d0481482d00..9a624f88339 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Services **(FREE ALL)** @@ -27,7 +26,7 @@ than to install `mysql`, for example, every time the project is built. You're not limited to only database services. You can add as many services you need to `.gitlab-ci.yml` or manually modify the [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). -Any image found at [Docker Hub](https://hub.docker.com/) or your private Container Registry can be +Any image found at [Docker Hub](https://hub.docker.com/) or your private container registry can be used as a service. Services inherit the same DNS servers, search domains, and additional hosts as @@ -436,54 +435,48 @@ See [Mask a CI/CD Variable](../variables/index.md#mask-a-cicd-variable) ## Debug a job locally -The following commands are run without root privileges. You should be -able to run Docker with your user account. +The following commands are run without root privileges. You should be able to run Docker with your user account. -First start with creating a file named `build_script`: +First start by creating a file named `build_script`: ```shell cat <<EOF > build_script git clone https://gitlab.com/gitlab-org/gitlab-runner.git /builds/gitlab-org/gitlab-runner cd /builds/gitlab-org/gitlab-runner -make +make runner-bin-host EOF ``` -Here we use as an example the GitLab Runner repository which contains a -Makefile, so running `make` executes the commands defined in the Makefile. -Instead of `make`, you could run the command which is specific to your project. +Here we use as an example the GitLab Runner repository which contains a Makefile, so running `make` executes the target +defined in the Makefile. Instead of `make runner-bin-host`, you could run the command which is specific to your project. -Then create some service containers: +Then create a service container: ```shell -docker run -d --name service-mysql mysql:latest -docker run -d --name service-postgres postgres:latest +docker run -d --name service-redis redis:latest ``` -The previous commands create two service containers. The service container named `service-mysql` uses the latest MySQL image. The one named `service-postgres` uses the latest PostgreSQL image. Both service containers run in the background (`-d`). +The previous command creates a service container named `service-redis` using the latest Redis image. The service +container runs in the background (`-d`). -Finally, create a build container by executing the `build_script` file we -created earlier: +Finally, create a build container by executing the `build_script` file we created earlier: ```shell -docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.6 /bin/bash < build_script +docker run --name build -i --link=service-redis:redis golang:latest /bin/bash < build_script ``` -The above command creates a container named `build` that's spawned from -the `ruby:2.6` image and has two services linked to it. The `build_script` is -piped using `stdin` to the bash interpreter which in turn executes the +The above command creates a container named `build` that is spawned from the `golang:latest` image and has one service +linked to it. The `build_script` is piped using `stdin` to the bash interpreter which in turn executes the `build_script` in the `build` container. -When you finish testing and no longer need the containers, you can remove them -with: +When you finish testing and no longer need the containers, you can remove them with: ```shell -docker rm -f -v build service-mysql service-postgres +docker rm -f -v build service-redis ``` -This forcefully (`-f`) removes the `build` container, the two service -containers, and all volumes (`-v`) that were created with the container -creation. +This forcefully (`-f`) removes the `build` container, the service container, and all volumes (`-v`) that were created +with the container creation. ## Security when using services containers diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index d02df1faf55..a5a87c2a199 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using MySQL **(FREE ALL)** diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index b491786b4a1..7a3ad0ee804 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using PostgreSQL **(FREE ALL)** diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index d86ffdfabd6..94c0603f31f 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -1,8 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using Redis **(FREE ALL)** diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md index ad45345fa38..b848f436e34 100644 --- a/doc/ci/ssh_keys/index.md +++ b/doc/ci/ssh_keys/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using SSH keys with GitLab CI/CD **(FREE ALL)** @@ -25,12 +24,15 @@ environment by extending your `.gitlab-ci.yml`, and it's a solution that works with any type of [executor](https://docs.gitlab.com/runner/executors/) (like Docker or shell, for example). -## How it works +## Create and use an SSH key + +To create and use an SSH key in GitLab CI/CD: 1. Create a new SSH key pair locally with [`ssh-keygen`](https://linux.die.net/man/1/ssh-keygen) -1. Add the private key as a [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables) to - your project -1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) during job to load +1. Add the private key as a [file type CI/CD variable](../variables/index.md#for-a-project) to + your project. The variable value must end in a newline (`LF` character). To add a newline, press <kbd>Enter</kbd> or <kbd>Return</kbd> + at the end of the last line of the SSH key before saving it in the CI/CD settings. +1. Run the [`ssh-agent`](https://linux.die.net/man/1/ssh-agent) in the job, which loads the private key. 1. Copy the public key to the servers you want to have access to (usually in `~/.ssh/authorized_keys`) or add it as a [deploy key](../../user/project/deploy_keys/index.md) @@ -52,9 +54,11 @@ to access it. In this case, you can use an SSH key pair. **Do not** add a passphrase to the SSH key, or the `before_script` will prompt for it. -1. Create a new [file type CI/CD variable](../variables/index.md). - As **Key** enter the name `SSH_PRIVATE_KEY` and in the **Value** field paste - the content of your _private_ key that you created earlier. +1. Create a new [file type CI/CD variable](../variables/index.md#for-a-project). + - In the **Key** field, enter `SSH_PRIVATE_KEY`. + - In the **Value** field, paste the content of your _private_ key from the key pair that you created earlier. + Make sure the file ends with a newline. To add a newline, press + <kbd>Enter</kbd> or <kbd>Return</kbd> at the end of the last line of the SSH key before saving your changes. 1. Modify your `.gitlab-ci.yml` with a `before_script` action. In the following example, a Debian based image is assumed. Edit to your needs: @@ -161,6 +165,8 @@ ssh-keyscan 10.0.2.2 Create a new [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables) with `SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`. +Make sure the file ends with a newline. To add a newline, press <kbd>Enter</kbd> or <kbd>Return</kbd> +at the end of the last line of the SSH key before saving your changes. If you must connect to multiple servers, all the server host keys must be collected in the **Value** of the variable, one key per line. @@ -202,11 +208,19 @@ before_script: # - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" >> ~/.ssh/config' ``` -## Example project +## Use SSH key without a file type CI/CD variable + +If you do not want to use a file type CI/CD variable, the [example SSH Project](https://gitlab.com/gitlab-examples/ssh-private-key/) +shows an alternative method. This method uses a regular CI/CD variable instead of +the file type variable recommended above. + +## Troubleshooting + +### `Error loading key "/builds/path/SSH_PRIVATE_KEY": error in libcrypto` message -We have set up an [Example SSH Project](https://gitlab.com/gitlab-examples/ssh-private-key/) for your convenience -that runs on [GitLab.com](https://gitlab.com) using our publicly available -[shared runners](../runners/index.md). +This message can be returned if there is a formatting error with the SSH key. -Want to hack on it? Fork it, commit, and push your changes. In a few -moments the changes is picked by a public runner and the job starts. +When saving the SSH key as a [file type CI/CD variable](../variables/index.md#use-file-type-cicd-variables), +the value must end with a newline (`LF` character). To add a newline, press <kbd>Enter</kbd> or <kbd>Return</kbd> +at the end of the `-----END OPENSSH PRIVATE KEY-----` line of the SSH key before saving +the variable. diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md index 071884f2bed..56c4c475294 100644 --- a/doc/ci/test_cases/index.md +++ b/doc/ci/test_cases/index.md @@ -1,9 +1,8 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Test cases in GitLab can help your teams create testing scenarios in their existing development platform. -type: reference --- # Test cases **(ULTIMATE ALL)** @@ -21,7 +20,7 @@ For more information, see [Product Stage Direction - Plan](https://about.gitlab. ## Create a test case -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -91,7 +90,7 @@ or editing an existing one. When you want to stop using a test case, you can archive it. You can [reopen an archived test case](#reopen-an-archived-test-case) later. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. diff --git a/doc/ci/testing/accessibility_testing.md b/doc/ci/testing/accessibility_testing.md index 783e787f8a7..f8faaeec8f8 100644 --- a/doc/ci/testing/accessibility_testing.md +++ b/doc/ci/testing/accessibility_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Accessibility testing **(FREE ALL)** diff --git a/doc/ci/testing/browser_performance_testing.md b/doc/ci/testing/browser_performance_testing.md index d8c66c2d4d5..2988cfedce5 100644 --- a/doc/ci/testing/browser_performance_testing.md +++ b/doc/ci/testing/browser_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Browser Performance Testing **(PREMIUM ALL)** @@ -49,7 +49,8 @@ If the Browser Performance report has no data to compare, such as when you add t Browser Performance job in your `.gitlab-ci.yml` for the very first time, the Browser Performance report widget doesn't display. It must have run at least once on the target branch (`main`, for example), before it displays in a -merge request targeting that branch. +merge request targeting that branch. Additionally, the widget only displays if the +job ran in the latest pipeline for the Merge request.  @@ -134,11 +135,11 @@ be extended for dynamic environments, but a few extra steps are required: 1. The `browser_performance` job should run after the dynamic environment has started. 1. In the `review` job: - 1. Generate a URL list file with the dynamic URL. - 1. Save the file as an artifact, for example with `echo $CI_ENVIRONMENT_URL > environment_url.txt` - in your job's `script`. - 1. Pass the list as the URL environment variable (which can be a URL or a file containing URLs) - to the `browser_performance` job. + 1. Generate a URL list file with the dynamic URL. + 1. Save the file as an artifact, for example with `echo $CI_ENVIRONMENT_URL > environment_url.txt` + in your job's `script`. + 1. Pass the list as the URL environment variable (which can be a URL or a file containing URLs) + to the `browser_performance` job. 1. You can now run the sitespeed.io container against the desired hostname and paths. diff --git a/doc/ci/testing/code_coverage.md b/doc/ci/testing/code_coverage.md index a39586a9eb0..43df79c44f5 100644 --- a/doc/ci/testing/code_coverage.md +++ b/doc/ci/testing/code_coverage.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code coverage **(FREE ALL)** @@ -76,7 +76,7 @@ To see the evolution of your project code coverage over time, you can view a graph or download a CSV file with this data. 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Analyze > Repository analytics**. +1. Select **Analyze > Repository analytics**. The historic data for each job is listed in the dropdown list above the graph. diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index 6b4275d8055..23ae615eeb2 100644 --- a/doc/ci/testing/code_quality.md +++ b/doc/ci/testing/code_quality.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Quality **(FREE ALL)** @@ -51,7 +51,9 @@ Code Quality results are shown in the: Code Quality analysis results display in the merge request widget area if a report from the target branch is available for comparison. The merge request widget displays Code Quality findings and resolutions that -were introduced by the changes made in the merge request. +were introduced by the changes made in the merge request. Multiple Code Quality findings with identical +fingerprints display as a single entry in the merge request widget, each individual finding is available in the +full report available in the **Pipeline** details view.  @@ -63,9 +65,9 @@ were introduced by the changes made in the merge request. > - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. Code Quality results display in the merge request **Changes** view. Lines containing Code Quality -issues are marked by an indicator beside the gutter. Hover over the marker for details of the issue. +issues are marked by a symbol beside the gutter. Select the symbol to see the list of issues, then select an issue to see its details. - + ### Pipeline details view **(PREMIUM ALL)** @@ -350,7 +352,7 @@ the nested method of container execution. The following variables can address all of the required image pulls: - `CODE_QUALITY_IMAGE`: A fully prefixed image name that can be located anywhere - accessible from your job environment. GitLab Container Registry can be used here + accessible from your job environment. GitLab container registry can be used here to host your own copy. - `CODECLIMATE_PREFIX`: The domain of your intended container image registry. This is a configuration option supported by [CodeClimate CLI](https://github.com/codeclimate/codeclimate/pull/948). @@ -420,7 +422,7 @@ code_quality: You can use a Dependency Proxy to reduce the time taken to download dependencies. -Prerequisite: +Prerequisites: - [Dependency Proxy](../../user/packages/dependency_proxy/index.md) enabled in the project's group. @@ -518,15 +520,15 @@ Code Quality functionality can be extended by using Code Climate For example, to use the [SonarJava analyzer](https://docs.codeclimate.com/docs/sonar-java): 1. Add a file named `.codeclimate.yml` to the root of your repository -1. Add to the `.codeclimate.yml` the [enablement code](https://docs.codeclimate.com/docs/sonar-java#enable-the-plugin) - for the plugin to the root of your repository: +1. Add the [enablement code](https://docs.codeclimate.com/docs/sonar-java#enable-the-plugin) + for the plugin to the root of your repository to the `.codeclimate.yml` file: - ```yaml - version: "2" - plugins: - sonar-java: - enabled: true - ``` + ```yaml + version: "2" + plugins: + sonar-java: + enabled: true + ``` This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) @@ -550,7 +552,7 @@ You should configure Code Quality checks to run on your worker as documented in A common issue is that the terms `Code Quality` (GitLab specific) and `Code Climate` (Engine used by GitLab) are very similar. You must add a **`.codeclimate.yml`** file to change the default configuration, **not** a `.codequality.yml` file. If you use -the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) +the wrong file name, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) is still used. ### No Code Quality report is displayed in a merge request @@ -718,7 +720,7 @@ To gain insight into the errors, you can execute a GraphQL query using the follo 1. Go to the pipeline details page. 1. Append `.json` to the URL. 1. Copy the `iid` of the pipeline. -1. Go to [GraphiQL explorer](../../api/graphql/index.md#graphiql). +1. Go to the [interactive GraphQL explorer](../../api/graphql/index.md#interactive-graphql-explorer). 1. Run the following query: ```graphql diff --git a/doc/ci/testing/fail_fast_testing.md b/doc/ci/testing/fail_fast_testing.md index d47053fa971..22ce9bb52d8 100644 --- a/doc/ci/testing/fail_fast_testing.md +++ b/doc/ci/testing/fail_fast_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Fail Fast Testing **(PREMIUM ALL)** diff --git a/doc/ci/testing/img/code_quality_inline_indicator_v16_7.png b/doc/ci/testing/img/code_quality_inline_indicator_v16_7.png Binary files differnew file mode 100644 index 00000000000..0d7d5bb3062 --- /dev/null +++ b/doc/ci/testing/img/code_quality_inline_indicator_v16_7.png diff --git a/doc/ci/testing/img/code_quality_mr_diff_report_v15_7.png b/doc/ci/testing/img/code_quality_mr_diff_report_v15_7.png Binary files differdeleted file mode 100644 index b45124e0e5d..00000000000 --- a/doc/ci/testing/img/code_quality_mr_diff_report_v15_7.png +++ /dev/null diff --git a/doc/ci/testing/index.md b/doc/ci/testing/index.md index dadbc3821cc..2909bac4d0b 100644 --- a/doc/ci/testing/index.md +++ b/doc/ci/testing/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test with GitLab CI/CD and generate reports in merge requests **(FREE ALL)** diff --git a/doc/ci/testing/load_performance_testing.md b/doc/ci/testing/load_performance_testing.md index 6b16f15a9d9..a79136c0083 100644 --- a/doc/ci/testing/load_performance_testing.md +++ b/doc/ci/testing/load_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Load Performance Testing **(PREMIUM ALL)** diff --git a/doc/ci/testing/metrics_reports.md b/doc/ci/testing/metrics_reports.md index 0f1eaedfb78..faa7add64b3 100644 --- a/doc/ci/testing/metrics_reports.md +++ b/doc/ci/testing/metrics_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metrics Reports **(PREMIUM ALL)** diff --git a/doc/ci/testing/test_coverage_visualization.md b/doc/ci/testing/test_coverage_visualization.md index 56d42a30ca7..ff55f37e1ff 100644 --- a/doc/ci/testing/test_coverage_visualization.md +++ b/doc/ci/testing/test_coverage_visualization.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test coverage visualization **(FREE ALL)** diff --git a/doc/ci/testing/unit_test_report_examples.md b/doc/ci/testing/unit_test_report_examples.md index fb11467cd7d..bade653bf18 100644 --- a/doc/ci/testing/unit_test_report_examples.md +++ b/doc/ci/testing/unit_test_report_examples.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit test report examples **(FREE ALL)** diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md index b37dd54e96b..59401449b63 100644 --- a/doc/ci/testing/unit_test_reports.md +++ b/doc/ci/testing/unit_test_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit test reports **(FREE ALL)** @@ -94,6 +94,10 @@ To copy the name of a single failed test: If a test failed in the project's default branch in the last 14 days, a message like `Failed {n} time(s) in {default_branch} in the last 14 days` is displayed for that test. +The calculation includes failed tests in completed pipelines, but not [blocked pipelines](../jobs/job_control.md#types-of-manual-jobs). +[Issue 431265](https://gitlab.com/gitlab-org/gitlab/-/issues/431265) proposes to +also include blocked pipelines in the calculation. + ## How to set it up To enable the Unit test reports in merge requests, you must add diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index ee1e05c4fc9..4eee34af402 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Trigger pipelines by using the API **(FREE ALL)** @@ -10,6 +9,10 @@ type: tutorial To trigger a pipeline for a specific branch or tag, you can use an API call to the [pipeline triggers API endpoint](../../api/pipeline_triggers.md). +If you are [migrating to GitLab CI/CD](../migration/plan_a_migration.md), you can +trigger GitLab CI/CD pipelines by calling the API endpoint from the other provider's jobs. +For example, as part of a migration from [Jenkins](../migration/jenkins.md) or [CircleCI](../migration/circleci.md). + When authenticating with the API, you can use: - A [pipeline trigger token](#create-a-pipeline-trigger-token) to trigger a branch or tag pipeline. @@ -21,7 +24,7 @@ When authenticating with the API, you can use: You can trigger a pipeline for a branch or tag by generating a pipeline trigger token and using it to authenticate an API call. The token impersonates a user's project access and permissions. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index 0c05129fb1e..f247d9609fe 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD variables **(FREE ALL)** @@ -130,7 +129,7 @@ all variables become available to the pipeline. You can add CI/CD variables to a project's settings. -Prerequisite: +Prerequisites: - You must be a project member with the Maintainer role. @@ -159,7 +158,7 @@ or in [job scripts](#use-cicd-variables-in-job-scripts). You can make a CI/CD variable available to all projects in a group. -Prerequisite: +Prerequisites: - You must be a group member with the Owner role. @@ -188,14 +187,13 @@ are recursively inherited. You can make a CI/CD variable available to all projects and groups in a GitLab instance. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To add an instance variable: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD** and expand the **Variables** section. 1. Select **Add variable** and fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. @@ -262,7 +260,7 @@ to prevent commands such as `env`/`printenv` from printing secret variables. You can mask a project, group, or instance CI/CD variable so the value of the variable does not display in job logs. -Prerequisite: +Prerequisites: - You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). @@ -306,7 +304,7 @@ temporary merge commit, not a branch or tag, do not have access to these variabl [Merge request pipelines](../pipelines/merge_request_pipelines.md), which do not use a temporary merge commit, can access these variables if the branch is a protected branch. -Prerequisite: +Prerequisites: - You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). @@ -626,7 +624,7 @@ Expanded variables treat values with the `$` character as a reference to another CI/CD variables are expanded by default. To treat variables with a `$` character as raw strings, disable variable expansion for the variable -Prerequisite: +Prerequisites: - You must have the same role or access level as required to [define a CI/CD variable in the UI](#define-a-cicd-variable-in-the-ui). @@ -640,12 +638,15 @@ To disable variable expansion for the variable: ## CI/CD variable precedence +> Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. + You can use CI/CD variables with the same name in different places, but the values can overwrite each other. The type of variable and where they are defined determines which variables take precedence. The order of precedence for variables is (from highest to lowest): +1. [Scan Execution Policies variables](../../user/application_security/policies/scan-execution-policies.md). 1. These variables all have the same (highest) precedence: - [Trigger variables](../triggers/index.md#pass-cicd-variables-in-the-api-call). - [Scheduled pipeline variables](../pipelines/schedules.md#add-a-pipeline-schedule). diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index cd23b903d30..e8ed47cedd0 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -1,150 +1,154 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Predefined variables reference **(FREE ALL)** +# Predefined CI/CD variables reference **(FREE ALL)** Predefined [CI/CD variables](index.md) are available in every GitLab CI/CD pipeline. -Some variables are only available with more recent versions of [GitLab Runner](https://docs.gitlab.com/runner/). +Predefined variables become available at two different phases of pipeline execution. +Some variables are available when GitLab creates the pipeline, and can be used to configure +the pipeline or in job scripts. The other variables become available when a runner runs the job, +and can only be used in job scripts. -You can [output the values of all variables available for a job](index.md#list-all-variables) -with a `script` command. +Predefined variables made available by the runner cannot be used with [trigger jobs](../pipelines/downstream_pipelines.md#trigger-a-downstream-pipeline-from-a-job-in-the-gitlab-ciyml-file) +or these keywords: -There are also a number of [variables you can use to configure runner behavior](../runners/configure_runners.md#configure-runner-behavior-with-variables) globally or for individual jobs. +- [`workflow`](../yaml/index.md#workflow) +- [`include`](../yaml/index.md#include) +- [`rules`](../yaml/index.md#rules) NOTE: -You should avoid [overriding](index.md#override-a-defined-cicd-variable) predefined variables, +Avoid [overriding](index.md#override-a-defined-cicd-variable) predefined variables, as it can cause the pipeline to behave unexpectedly. -| Variable | GitLab | Runner | Description | -|------------------------------------------|--------|--------|-------------| -| `CHAT_CHANNEL` | 10.6 | all | The Source chat channel that triggered the [ChatOps](../chatops/index.md) command. | -| `CHAT_INPUT` | 10.6 | all | The additional arguments passed with the [ChatOps](../chatops/index.md) command. | -| `CHAT_USER_ID` | 14.4 | all | The chat service's user ID of the user who triggered the [ChatOps](../chatops/index.md) command. | -| `CI` | all | 0.4 | Available for all jobs executed in CI/CD. `true` when available. | -| `CI_API_V4_URL` | 11.7 | all | The GitLab API v4 root URL. | -| `CI_API_GRAPHQL_URL` | 15.11 | all | The GitLab API GraphQL root URL. | -| `CI_BUILDS_DIR` | all | 11.10 | The top-level directory where builds are executed. | -| `CI_COMMIT_AUTHOR` | 13.11 | all | The author of the commit in `Name <email>` format. | -| `CI_COMMIT_BEFORE_SHA` | 11.2 | all | The previous latest commit present on a branch or tag. Is always `0000000000000000000000000000000000000000` for merge request pipelines, the first commit in pipelines for branches or tags, or when manually running a pipeline. | -| `CI_COMMIT_BRANCH` | 12.6 | 0.5 | The commit branch name. Available in branch pipelines, including pipelines for the default branch. Not available in merge request pipelines or tag pipelines. | -| `CI_COMMIT_DESCRIPTION` | 10.8 | all | The description of the commit. If the title is shorter than 100 characters, the message without the first line. | -| `CI_COMMIT_MESSAGE` | 10.8 | all | The full commit message. | -| `CI_COMMIT_REF_NAME` | 9.0 | all | The branch or tag name for which project is built. | -| `CI_COMMIT_REF_PROTECTED` | 11.11 | all | `true` if the job is running for a protected reference, `false` otherwise. | -| `CI_COMMIT_REF_SLUG` | 9.0 | all | `CI_COMMIT_REF_NAME` in lowercase, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. | -| `CI_COMMIT_SHA` | 9.0 | all | The commit revision the project is built for. | -| `CI_COMMIT_SHORT_SHA` | 11.7 | all | The first eight characters of `CI_COMMIT_SHA`. | -| `CI_COMMIT_TAG` | 9.0 | 0.5 | The commit tag name. Available only in pipelines for tags. | -| `CI_COMMIT_TAG_MESSAGE` | 15.5 | all | The commit tag message. Available only in pipelines for tags. | -| `CI_COMMIT_TIMESTAMP` | 13.4 | all | The timestamp of the commit in the [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. | -| `CI_COMMIT_TITLE` | 10.8 | all | The title of the commit. The full first line of the message. | -| `CI_CONCURRENT_ID` | all | 11.10 | The unique ID of build execution in a single executor. | -| `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | The unique ID of build execution in a single executor and project. | -| `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | -| `CI_DEBUG_TRACE` | all | 1.7 | `true` if [debug logging (tracing)](index.md#enable-debug-logging) is enabled. | -| `CI_DEBUG_SERVICES` | 15.7 | 15.7 | `true` if [service container logging](../services/index.md#capturing-service-container-logs) is enabled. | -| `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the project's default branch. | -| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | -| `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` | 14.3 | all | The direct group image prefix for pulling images through the Dependency Proxy. | -| `CI_DEPENDENCY_PROXY_PASSWORD` | 13.7 | all | The password to pull images through the Dependency Proxy. | -| `CI_DEPENDENCY_PROXY_SERVER` | 13.7 | all | The server for logging in to the Dependency Proxy. This is equivalent to `$CI_SERVER_HOST:$CI_SERVER_PORT`. | -| `CI_DEPENDENCY_PROXY_USER` | 13.7 | all | The username to pull images through the Dependency Proxy. | -| `CI_DEPLOY_FREEZE` | 13.2 | all | Only available if the pipeline runs during a [deploy freeze window](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze). `true` when available. | -| `CI_DEPLOY_PASSWORD` | 10.8 | all | The authentication password of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | -| `CI_DEPLOY_USER` | 10.8 | all | The authentication username of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | -| `CI_DISPOSABLE_ENVIRONMENT` | all | 10.1 | Only available if the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). `true` when available. | -| `CI_ENVIRONMENT_NAME` | 8.15 | all | The name of the environment for this job. Available if [`environment:name`](../yaml/index.md#environmentname) is set. | -| `CI_ENVIRONMENT_SLUG` | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/index.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). A random suffix is automatically added to [uppercase environment names](https://gitlab.com/gitlab-org/gitlab/-/issues/415526). | -| `CI_ENVIRONMENT_URL` | 9.3 | all | The URL of the environment for this job. Available if [`environment:url`](../yaml/index.md#environmenturl) is set. | -| `CI_ENVIRONMENT_ACTION` | 13.11 | all | The action annotation specified for this job's environment. Available if [`environment:action`](../yaml/index.md#environmentaction) is set. Can be `start`, `prepare`, or `stop`. | -| `CI_ENVIRONMENT_TIER` | 14.0 | all | The [deployment tier of the environment](../environments/index.md#deployment-tier-of-environments) for this job. | -| `CI_RELEASE_DESCRIPTION` | 15.5 | all | The description of the release. Available only on pipelines for tags. Description length is limited to first 1024 characters.| -| `CI_GITLAB_FIPS_MODE` | 14.10 | all | Only available if [FIPS mode](../../development/fips_compliance.md) is enabled in the GitLab instance. `true` when available. | -| `CI_HAS_OPEN_REQUIREMENTS` | 13.1 | all | Only available if the pipeline's project has an open [requirement](../../user/project/requirements/index.md). `true` when available. | -| `CI_JOB_ID` | 9.0 | all | The internal ID of the job, unique across all jobs in the GitLab instance. | -| `CI_JOB_IMAGE` | 12.9 | 12.9 | The name of the Docker image running the job. | -| `CI_JOB_JWT` (Deprecated) | 12.10 | all | A RS256 JSON web token to authenticate with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | -| `CI_JOB_JWT_V1` (Deprecated) | 14.6 | all | The same value as `CI_JOB_JWT`. [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | -| `CI_JOB_JWT_V2` (Deprecated) | 14.6 | all | A newly formatted RS256 JSON web token to increase compatibility. Similar to `CI_JOB_JWT`, except the issuer (`iss`) claim is changed from `gitlab.com` to `https://gitlab.com`, `sub` has changed from `job_id` to a string that contains the project path, and an `aud` claim is added. The `aud` field is a constant value. Trusting JWTs in multiple relying parties can lead to [one RP sending a JWT to another one and acting maliciously as a job](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72555#note_769112331). [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | -| `CI_JOB_MANUAL` | 8.12 | all | Only available if the job was started manually. `true` when available. | -| `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job. | -| `CI_JOB_NAME_SLUG` | 15.4 | all | `CI_JOB_NAME_SLUG` in lowercase, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in paths. | -| `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the job's stage. | -| `CI_JOB_STATUS` | all | 13.5 | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/index.md#after_script). Can be `success`, `failed`, or `canceled`. | -| `CI_JOB_TIMEOUT` | 15.7 | 15.7 | The job timeout, in seconds. | -| `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../jobs/ci_job_token.md). The token is valid as long as the job is running. | -| `CI_JOB_URL` | 11.1 | 0.5 | The job details URL. | -| `CI_JOB_STARTED_AT` | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. | -| `CI_KUBERNETES_ACTIVE` | 13.0 | all | Only available if the pipeline has a Kubernetes cluster available for deployments. `true` when available. | -| `CI_NODE_INDEX` | 11.5 | all | The index of the job in the job set. Only available if the job uses [`parallel`](../yaml/index.md#parallel). | -| `CI_NODE_TOTAL` | 11.5 | all | The total number of instances of this job running in parallel. Set to `1` if the job does not use [`parallel`](../yaml/index.md#parallel). | -| `CI_OPEN_MERGE_REQUESTS` | 13.8 | all | A comma-separated list of up to four merge requests that use the current branch and project as the merge request source. Only available in branch and merge request pipelines if the branch has an associated merge request. For example, `gitlab-org/gitlab!333,gitlab-org/gitlab-foss!11`. | -| `CI_PAGES_DOMAIN` | 11.8 | all | The configured domain that hosts GitLab Pages. | -| `CI_PAGES_URL` | 11.8 | all | The URL for a GitLab Pages site. Always a subdomain of `CI_PAGES_DOMAIN`. | -| `CI_PIPELINE_ID` | 8.10 | all | The instance-level ID of the current pipeline. This ID is unique across all projects on the GitLab instance. | -| `CI_PIPELINE_IID` | 11.0 | all | The project-level IID (internal ID) of the current pipeline. This ID is unique only within the current project. | -| `CI_PIPELINE_SOURCE` | 10.0 | all | How the pipeline was triggered. Can be `push`, `web`, `schedule`, `api`, `external`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, [`trigger`, or `pipeline`](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). For a description of each value, see [Common `if` clauses for `rules`](../jobs/job_control.md#common-if-clauses-for-rules), which uses this variable to control when jobs run. | -| `CI_PIPELINE_TRIGGERED` | all | all | `true` if the job was [triggered](../triggers/index.md). | -| `CI_PIPELINE_URL` | 11.1 | 0.5 | The URL for the pipeline details. | -| `CI_PIPELINE_CREATED_AT` | 13.10 | all | The UTC datetime when the pipeline was created, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. | -| `CI_PIPELINE_NAME` | 16.3 | all | The pipeline name defined in [`workflow:name`](../yaml/index.md#workflowname) | -| `CI_PROJECT_DIR` | all | all | The full path the repository is cloned to, and where the job runs from. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see the [Advanced GitLab Runner configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | -| `CI_PROJECT_ID` | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | -| `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | -| `CI_PROJECT_NAMESPACE` | 8.10 | 0.5 | The project namespace (username or group name) of the job. | -| `CI_PROJECT_NAMESPACE_ID` | 15.7 | 0.5 | The project namespace ID of the job. | -| `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-` and shortened to 63 bytes. Use in URLs and domain names. | -| `CI_PROJECT_PATH` | 8.10 | 0.5 | The project namespace with the project name included. | -| `CI_PROJECT_REPOSITORY_LANGUAGES` | 12.3 | all | A comma-separated, lowercase list of the languages used in the repository. For example `ruby,javascript,html,css`. The maximum number of languages is limited to 5. An issue [proposes to increase the limit](https://gitlab.com/gitlab-org/gitlab/-/issues/368925). | -| `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The root project namespace (username or group name) of the job. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` is `root-group`. | -| `CI_PROJECT_TITLE` | 12.4 | all | The human-readable project name as displayed in the GitLab web interface. | -| `CI_PROJECT_DESCRIPTION` | 15.1 | all | The project description as displayed in the GitLab web interface. | -| `CI_PROJECT_URL` | 8.10 | 0.5 | The HTTP(S) address of the project. | -| `CI_PROJECT_VISIBILITY` | 10.3 | all | The project visibility. Can be `internal`, `private`, or `public`. | -| `CI_PROJECT_CLASSIFICATION_LABEL` | 14.2 | all | The project [external authorization classification label](../../administration/settings/external_authorization.md). | -| `CI_REGISTRY` | 8.10 | 0.5 | Address of the [Container Registry](../../user/packages/container_registry/index.md) server, formatted as `<host>[:<port>]`. For example: `registry.gitlab.example.com`. Only available if the Container Registry is enabled for the GitLab instance. | -| `CI_REGISTRY_IMAGE` | 8.10 | 0.5 | Base address for the container registry to push, pull, or tag project's images, formatted as `<host>[:<port>]/<project_full_path>`. For example: `registry.gitlab.example.com/my_group/my_project`. Image names must follow the [container registry naming convention](../../user/packages/container_registry/index.md#naming-convention-for-your-container-images). Only available if the Container Registry is enabled for the project. | -| `CI_REGISTRY_PASSWORD` | 9.0 | all | The password to push containers to the project's GitLab Container Registry. Only available if the Container Registry is enabled for the project. This password value is the same as the `CI_JOB_TOKEN` and is valid only as long as the job is running. Use the `CI_DEPLOY_PASSWORD` for long-lived access to the registry | -| `CI_REGISTRY_USER` | 9.0 | all | The username to push containers to the project's GitLab Container Registry. Only available if the Container Registry is enabled for the project. | -| `CI_REPOSITORY_URL` | 9.0 | all | The full path to Git clone (HTTP) the repository with a [CI/CD job token](../jobs/ci_job_token.md), in the format `https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.example.com/my-group/my-project.git`. | -| `CI_RUNNER_DESCRIPTION` | 8.10 | 0.5 | The description of the runner. | -| `CI_RUNNER_EXECUTABLE_ARCH` | all | 10.6 | The OS/architecture of the GitLab Runner executable. Might not be the same as the environment of the executor. | -| `CI_RUNNER_ID` | 8.10 | 0.5 | The unique ID of the runner being used. | -| `CI_RUNNER_REVISION` | all | 10.6 | The revision of the runner running the job. | -| `CI_RUNNER_SHORT_TOKEN` | all | 12.3 | The runner's unique ID, used to authenticate new job requests. In [GitLab 14.9](https://gitlab.com/gitlab-org/security/gitlab/-/merge_requests/2251) and later, the token contains a prefix, and the first 17 characters are used. Prior to 14.9, the first eight characters are used. | -| `CI_RUNNER_TAGS` | 8.10 | 0.5 | A comma-separated list of the runner tags. | -| `CI_RUNNER_VERSION` | all | 10.6 | The version of the GitLab Runner running the job. | -| `CI_SERVER_HOST` | 12.1 | all | The host of the GitLab instance URL, without protocol or port. For example `gitlab.example.com`. | -| `CI_SERVER_NAME` | all | all | The name of CI/CD server that coordinates jobs. | -| `CI_SERVER_PORT` | 12.8 | all | The port of the GitLab instance URL, without host or protocol. For example `8080`. | -| `CI_SERVER_PROTOCOL` | 12.8 | all | The protocol of the GitLab instance URL, without host or port. For example `https`. | -| `CI_SERVER_SHELL_SSH_HOST` | 15.11 | all | The SSH host of the GitLab instance, used for access to Git repositories via SSH. For example `gitlab.com`. | -| `CI_SERVER_SHELL_SSH_PORT` | 15.11 | all | The SSH port of the GitLab instance, used for access to Git repositories via SSH. For example `22`. | -| `CI_SERVER_REVISION` | all | all | GitLab revision that schedules jobs. | -| `CI_SERVER_TLS_CA_FILE` | all | all | File containing the TLS CA certificate to verify the GitLab server when `tls-ca-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | -| `CI_SERVER_TLS_CERT_FILE` | all | all | File containing the TLS certificate to verify the GitLab server when `tls-cert-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | -| `CI_SERVER_TLS_KEY_FILE` | all | all | File containing the TLS key to verify the GitLab server when `tls-key-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | -| `CI_SERVER_URL` | 12.7 | all | The base URL of the GitLab instance, including protocol and port. For example `https://gitlab.example.com:8080`. | -| `CI_SERVER_VERSION_MAJOR` | 11.4 | all | The major version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_MAJOR` is `13`. | -| `CI_SERVER_VERSION_MINOR` | 11.4 | all | The minor version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_MINOR` is `6`. | -| `CI_SERVER_VERSION_PATCH` | 11.4 | all | The patch version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_PATCH` is `1`. | -| `CI_SERVER_VERSION` | all | all | The full version of the GitLab instance. | -| `CI_SERVER` | all | all | Available for all jobs executed in CI/CD. `yes` when available. | -| `CI_SHARED_ENVIRONMENT` | all | 10.1 | Only available if the job is executed in a shared environment (something that is persisted across CI/CD invocations, like the `shell` or `ssh` executor). `true` when available. | -| `CI_TEMPLATE_REGISTRY_HOST` | 15.3 | all | The host of the registry used by CI/CD templates. Defaults to `registry.gitlab.com`. | -| `GITLAB_CI` | all | all | Available for all jobs executed in CI/CD. `true` when available. | -| `GITLAB_FEATURES` | 10.6 | all | The comma-separated list of licensed features available for the GitLab instance and license. | -| `GITLAB_USER_EMAIL` | 8.12 | all | The email of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the email of the user who started the job. | -| `GITLAB_USER_ID` | 8.12 | all | The numeric ID of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the ID of the user who started the job. | -| `GITLAB_USER_LOGIN` | 10.0 | all | The username of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the username of the user who started the job. | -| `GITLAB_USER_NAME` | 10.0 | all | The display name of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the name of the user who started the job. | -| `KUBECONFIG` | 14.2 | all | The path to the `kubeconfig` file with contexts for every shared agent connection. Only available when a [GitLab agent is authorized to access the project](../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent). | -| `TRIGGER_PAYLOAD` | 13.9 | all | The webhook payload. Only available when a pipeline is [triggered with a webhook](../triggers/index.md#access-webhook-payload). | +| Variable | Defined for | GitLab | Runner | Description | +|-----------------------------------|-------------|--------|--------|-------------| +| `CHAT_CHANNEL` | Pipeline | 10.6 | all | The Source chat channel that triggered the [ChatOps](../chatops/index.md) command. | +| `CHAT_INPUT` | Pipeline | 10.6 | all | The additional arguments passed with the [ChatOps](../chatops/index.md) command. | +| `CHAT_USER_ID` | Pipeline | 14.4 | all | The chat service's user ID of the user who triggered the [ChatOps](../chatops/index.md) command. | +| `CI` | Pipeline | all | 0.4 | Available for all jobs executed in CI/CD. `true` when available. | +| `CI_API_V4_URL` | Pipeline | 11.7 | all | The GitLab API v4 root URL. | +| `CI_API_GRAPHQL_URL` | Pipeline | 15.11 | all | The GitLab API GraphQL root URL. | +| `CI_BUILDS_DIR` | Jobs only | all | 11.10 | The top-level directory where builds are executed. | +| `CI_COMMIT_AUTHOR` | Pipeline | 13.11 | all | The author of the commit in `Name <email>` format. | +| `CI_COMMIT_BEFORE_SHA` | Pipeline | 11.2 | all | The previous latest commit present on a branch or tag. Is always `0000000000000000000000000000000000000000` for merge request pipelines, the first commit in pipelines for branches or tags, or when manually running a pipeline. | +| `CI_COMMIT_BRANCH` | Pipeline | 12.6 | 0.5 | The commit branch name. Available in branch pipelines, including pipelines for the default branch. Not available in merge request pipelines or tag pipelines. | +| `CI_COMMIT_DESCRIPTION` | Pipeline | 10.8 | all | The description of the commit. If the title is shorter than 100 characters, the message without the first line. | +| `CI_COMMIT_MESSAGE` | Pipeline | 10.8 | all | The full commit message. | +| `CI_COMMIT_REF_NAME` | Pipeline | 9.0 | all | The branch or tag name for which project is built. | +| `CI_COMMIT_REF_PROTECTED` | Pipeline | 11.11 | all | `true` if the job is running for a protected reference, `false` otherwise. | +| `CI_COMMIT_REF_SLUG` | Pipeline | 9.0 | all | `CI_COMMIT_REF_NAME` in lowercase, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. | +| `CI_COMMIT_SHA` | Pipeline | 9.0 | all | The commit revision the project is built for. | +| `CI_COMMIT_SHORT_SHA` | Pipeline | 11.7 | all | The first eight characters of `CI_COMMIT_SHA`. | +| `CI_COMMIT_TAG` | Pipeline | 9.0 | 0.5 | The commit tag name. Available only in pipelines for tags. | +| `CI_COMMIT_TAG_MESSAGE` | Pipeline | 15.5 | all | The commit tag message. Available only in pipelines for tags. | +| `CI_COMMIT_TIMESTAMP` | Pipeline | 13.4 | all | The timestamp of the commit in the [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. For example, `2022-01-31T16:47:55Z`. | +| `CI_COMMIT_TITLE` | Pipeline | 10.8 | all | The title of the commit. The full first line of the message. | +| `CI_CONCURRENT_ID` | Jobs only | all | 11.10 | The unique ID of build execution in a single executor. | +| `CI_CONCURRENT_PROJECT_ID` | Jobs only | all | 11.10 | The unique ID of build execution in a single executor and project. | +| `CI_CONFIG_PATH` | Pipeline | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | +| `CI_DEBUG_TRACE` | Pipeline | all | 1.7 | `true` if [debug logging (tracing)](index.md#enable-debug-logging) is enabled. | +| `CI_DEBUG_SERVICES` | Pipeline | 15.7 | 15.7 | `true` if [service container logging](../services/index.md#capturing-service-container-logs) is enabled. | +| `CI_DEFAULT_BRANCH` | Pipeline | 12.4 | all | The name of the project's default branch. | +| `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX`| Pipeline | 14.3 | all | The direct group image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | Pipeline | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_PASSWORD` | Pipeline | 13.7 | all | The password to pull images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_SERVER` | Pipeline | 13.7 | all | The server for logging in to the Dependency Proxy. This is equivalent to `$CI_SERVER_HOST:$CI_SERVER_PORT`. | +| `CI_DEPENDENCY_PROXY_USER` | Pipeline | 13.7 | all | The username to pull images through the Dependency Proxy. | +| `CI_DEPLOY_FREEZE` | Pipeline | 13.2 | all | Only available if the pipeline runs during a [deploy freeze window](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze). `true` when available. | +| `CI_DEPLOY_PASSWORD` | Jobs only | 10.8 | all | The authentication password of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | +| `CI_DEPLOY_USER` | Jobs only | 10.8 | all | The authentication username of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | +| `CI_DISPOSABLE_ENVIRONMENT` | Pipeline | all | 10.1 | Only available if the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). `true` when available. | +| `CI_ENVIRONMENT_NAME` | Pipeline | 8.15 | all | The name of the environment for this job. Available if [`environment:name`](../yaml/index.md#environmentname) is set. | +| `CI_ENVIRONMENT_SLUG` | Pipeline | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/index.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). A random suffix is automatically added to [uppercase environment names](https://gitlab.com/gitlab-org/gitlab/-/issues/415526). | +| `CI_ENVIRONMENT_URL` | Pipeline | 9.3 | all | The URL of the environment for this job. Available if [`environment:url`](../yaml/index.md#environmenturl) is set. | +| `CI_ENVIRONMENT_ACTION` | Pipeline | 13.11 | all | The action annotation specified for this job's environment. Available if [`environment:action`](../yaml/index.md#environmentaction) is set. Can be `start`, `prepare`, or `stop`. | +| `CI_ENVIRONMENT_TIER` | Pipeline | 14.0 | all | The [deployment tier of the environment](../environments/index.md#deployment-tier-of-environments) for this job. | +| `CI_RELEASE_DESCRIPTION` | Pipeline | 15.5 | all | The description of the release. Available only on pipelines for tags. Description length is limited to first 1024 characters. | +| `CI_GITLAB_FIPS_MODE` | Pipeline | 14.10 | all | Only available if [FIPS mode](../../development/fips_compliance.md) is enabled in the GitLab instance. `true` when available. | +| `CI_HAS_OPEN_REQUIREMENTS` | Pipeline | 13.1 | all | Only available if the pipeline's project has an open [requirement](../../user/project/requirements/index.md). `true` when available. | +| `CI_JOB_ID` | Jobs only | 9.0 | all | The internal ID of the job, unique across all jobs in the GitLab instance. | +| `CI_JOB_IMAGE` | Pipeline | 12.9 | 12.9 | The name of the Docker image running the job. | +| `CI_JOB_JWT` (Deprecated) | Pipeline | 12.10 | all | A RS256 JSON web token to authenticate with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | +| `CI_JOB_JWT_V1` (Deprecated) | Pipeline | 14.6 | all | The same value as `CI_JOB_JWT`. [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | +| `CI_JOB_JWT_V2` (Deprecated) | Pipeline | 14.6 | all | A newly formatted RS256 JSON web token to increase compatibility. Similar to `CI_JOB_JWT`, except the issuer (`iss`) claim is changed from `gitlab.com` to `https://gitlab.com`, `sub` has changed from `job_id` to a string that contains the project path, and an `aud` claim is added. The `aud` field is a constant value. Trusting JWTs in multiple relying parties can lead to [one RP sending a JWT to another one and acting maliciously as a job](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72555#note_769112331). [Deprecated in GitLab 15.9](../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) and scheduled to be removed in GitLab 17.0. Use [ID tokens](../yaml/index.md#id_tokens) instead. | +| `CI_JOB_MANUAL` | Pipeline | 8.12 | all | Only available if the job was started manually. `true` when available. | +| `CI_JOB_NAME` | Pipeline | 9.0 | 0.5 | The name of the job. | +| `CI_JOB_NAME_SLUG` | Pipeline | 15.4 | all | `CI_JOB_NAME` in lowercase, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in paths. | +| `CI_JOB_STAGE` | Pipeline | 9.0 | 0.5 | The name of the job's stage. | +| `CI_JOB_STATUS` | Jobs only | all | 13.5 | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/index.md#after_script). Can be `success`, `failed`, or `canceled`. | +| `CI_JOB_TIMEOUT` | Jobs only | 15.7 | 15.7 | The job timeout, in seconds. | +| `CI_JOB_TOKEN` | Jobs only | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../jobs/ci_job_token.md). The token is valid as long as the job is running. | +| `CI_JOB_URL` | Jobs only | 11.1 | 0.5 | The job details URL. | +| `CI_JOB_STARTED_AT` | Jobs only | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. For example, `2022-01-31T16:47:55Z`. | +| `CI_KUBERNETES_ACTIVE` | Pipeline | 13.0 | all | Only available if the pipeline has a Kubernetes cluster available for deployments. `true` when available. | +| `CI_NODE_INDEX` | Pipeline | 11.5 | all | The index of the job in the job set. Only available if the job uses [`parallel`](../yaml/index.md#parallel). | +| `CI_NODE_TOTAL` | Pipeline | 11.5 | all | The total number of instances of this job running in parallel. Set to `1` if the job does not use [`parallel`](../yaml/index.md#parallel). | +| `CI_OPEN_MERGE_REQUESTS` | Pipeline | 13.8 | all | A comma-separated list of up to four merge requests that use the current branch and project as the merge request source. Only available in branch and merge request pipelines if the branch has an associated merge request. For example, `gitlab-org/gitlab!333,gitlab-org/gitlab-foss!11`. | +| `CI_PAGES_DOMAIN` | Pipeline | 11.8 | all | The configured domain that hosts GitLab Pages. | +| `CI_PAGES_URL` | Pipeline | 11.8 | all | The URL for a GitLab Pages site. Always a subdomain of `CI_PAGES_DOMAIN`. | +| `CI_PIPELINE_ID` | Jobs only | 8.10 | all | The instance-level ID of the current pipeline. This ID is unique across all projects on the GitLab instance. | +| `CI_PIPELINE_IID` | Pipeline | 11.0 | all | The project-level IID (internal ID) of the current pipeline. This ID is unique only within the current project. | +| `CI_PIPELINE_SOURCE` | Pipeline | 10.0 | all | How the pipeline was triggered. Can be `push`, `web`, `schedule`, `api`, `external`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, [`trigger`, or `pipeline`](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). For a description of each value, see [Common `if` clauses for `rules`](../jobs/job_control.md#common-if-clauses-for-rules), which uses this variable to control when jobs run. | +| `CI_PIPELINE_TRIGGERED` | Pipeline | all | all | `true` if the job was [triggered](../triggers/index.md). | +| `CI_PIPELINE_URL` | Jobs only | 11.1 | 0.5 | The URL for the pipeline details. | +| `CI_PIPELINE_CREATED_AT` | Pipeline | 13.10 | all | The UTC datetime when the pipeline was created, in [ISO 8601](https://www.rfc-editor.org/rfc/rfc3339#appendix-A) format. For example, `2022-01-31T16:47:55Z`. | +| `CI_PIPELINE_NAME` | Pipeline | 16.3 | all | The pipeline name defined in [`workflow:name`](../yaml/index.md#workflowname) | +| `CI_PROJECT_DIR` | Jobs only | all | all | The full path the repository is cloned to, and where the job runs from. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see the [Advanced GitLab Runner configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | +| `CI_PROJECT_ID` | Pipeline | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | +| `CI_PROJECT_NAME` | Pipeline | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | +| `CI_PROJECT_NAMESPACE` | Pipeline | 8.10 | 0.5 | The project namespace (username or group name) of the job. | +| `CI_PROJECT_NAMESPACE_ID` | Pipeline | 15.7 | 0.5 | The project namespace ID of the job. | +| `CI_PROJECT_PATH_SLUG` | Pipeline | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-` and shortened to 63 bytes. Use in URLs and domain names. | +| `CI_PROJECT_PATH` | Pipeline | 8.10 | 0.5 | The project namespace with the project name included. | +| `CI_PROJECT_REPOSITORY_LANGUAGES` | Pipeline | 12.3 | all | A comma-separated, lowercase list of the languages used in the repository. For example `ruby,javascript,html,css`. The maximum number of languages is limited to 5. An issue [proposes to increase the limit](https://gitlab.com/gitlab-org/gitlab/-/issues/368925). | +| `CI_PROJECT_ROOT_NAMESPACE` | Pipeline | 13.2 | 0.5 | The root project namespace (username or group name) of the job. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` is `root-group`. | +| `CI_PROJECT_TITLE` | Pipeline | 12.4 | all | The human-readable project name as displayed in the GitLab web interface. | +| `CI_PROJECT_DESCRIPTION` | Pipeline | 15.1 | all | The project description as displayed in the GitLab web interface. | +| `CI_PROJECT_URL` | Pipeline | 8.10 | 0.5 | The HTTP(S) address of the project. | +| `CI_PROJECT_VISIBILITY` | Pipeline | 10.3 | all | The project visibility. Can be `internal`, `private`, or `public`. | +| `CI_PROJECT_CLASSIFICATION_LABEL` | Pipeline | 14.2 | all | The project [external authorization classification label](../../administration/settings/external_authorization.md). | +| `CI_REGISTRY` | Pipeline | 8.10 | 0.5 | Address of the [container registry](../../user/packages/container_registry/index.md) server, formatted as `<host>[:<port>]`. For example: `registry.gitlab.example.com`. Only available if the container registry is enabled for the GitLab instance. | +| `CI_REGISTRY_IMAGE` | Pipeline | 8.10 | 0.5 | Base address for the container registry to push, pull, or tag project's images, formatted as `<host>[:<port>]/<project_full_path>`. For example: `registry.gitlab.example.com/my_group/my_project`. Image names must follow the [container registry naming convention](../../user/packages/container_registry/index.md#naming-convention-for-your-container-images). Only available if the container registry is enabled for the project. | +| `CI_REGISTRY_PASSWORD` | Jobs only | 9.0 | all | The password to push containers to the GitLab project's container registry. Only available if the container registry is enabled for the project. This password value is the same as the `CI_JOB_TOKEN` and is valid only as long as the job is running. Use the `CI_DEPLOY_PASSWORD` for long-lived access to the registry | +| `CI_REGISTRY_USER` | Jobs only | 9.0 | all | The username to push containers to the project's GitLab container registry. Only available if the container registry is enabled for the project. | +| `CI_REPOSITORY_URL` | Jobs only | 9.0 | all | The full path to Git clone (HTTP) the repository with a [CI/CD job token](../jobs/ci_job_token.md), in the format `https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.example.com/my-group/my-project.git`. | +| `CI_RUNNER_DESCRIPTION` | Jobs only | 8.10 | 0.5 | The description of the runner. | +| `CI_RUNNER_EXECUTABLE_ARCH` | Jobs only | all | 10.6 | The OS/architecture of the GitLab Runner executable. Might not be the same as the environment of the executor. | +| `CI_RUNNER_ID` | Jobs only | 8.10 | 0.5 | The unique ID of the runner being used. | +| `CI_RUNNER_REVISION` | Jobs only | all | 10.6 | The revision of the runner running the job. | +| `CI_RUNNER_SHORT_TOKEN` | Jobs only | all | 12.3 | The runner's unique ID, used to authenticate new job requests. In [GitLab 14.9](https://gitlab.com/gitlab-org/security/gitlab/-/merge_requests/2251) and later, the token contains a prefix, and the first 17 characters are used. Prior to 14.9, the first eight characters are used. | +| `CI_RUNNER_TAGS` | Jobs only | 8.10 | 0.5 | A comma-separated list of the runner tags. | +| `CI_RUNNER_VERSION` | Jobs only | all | 10.6 | The version of the GitLab Runner running the job. | +| `CI_SERVER_HOST` | Pipeline | 12.1 | all | The host of the GitLab instance URL, without protocol or port. For example `gitlab.example.com`. | +| `CI_SERVER_NAME` | Pipeline | all | all | The name of CI/CD server that coordinates jobs. | +| `CI_SERVER_PORT` | Pipeline | 12.8 | all | The port of the GitLab instance URL, without host or protocol. For example `8080`. | +| `CI_SERVER_PROTOCOL` | Pipeline | 12.8 | all | The protocol of the GitLab instance URL, without host or port. For example `https`. | +| `CI_SERVER_SHELL_SSH_HOST` | Pipeline | 15.11 | all | The SSH host of the GitLab instance, used for access to Git repositories via SSH. For example `gitlab.com`. | +| `CI_SERVER_SHELL_SSH_PORT` | Pipeline | 15.11 | all | The SSH port of the GitLab instance, used for access to Git repositories via SSH. For example `22`. | +| `CI_SERVER_REVISION` | Pipeline | all | all | GitLab revision that schedules jobs. | +| `CI_SERVER_TLS_CA_FILE` | Pipeline | all | all | File containing the TLS CA certificate to verify the GitLab server when `tls-ca-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | +| `CI_SERVER_TLS_CERT_FILE` | Pipeline | all | all | File containing the TLS certificate to verify the GitLab server when `tls-cert-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | +| `CI_SERVER_TLS_KEY_FILE` | Pipeline | all | all | File containing the TLS key to verify the GitLab server when `tls-key-file` set in [runner settings](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). | +| `CI_SERVER_URL` | Pipeline | 12.7 | all | The base URL of the GitLab instance, including protocol and port. For example `https://gitlab.example.com:8080`. | +| `CI_SERVER_VERSION_MAJOR` | Pipeline | 11.4 | all | The major version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_MAJOR` is `13`. | +| `CI_SERVER_VERSION_MINOR` | Pipeline | 11.4 | all | The minor version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_MINOR` is `6`. | +| `CI_SERVER_VERSION_PATCH` | Pipeline | 11.4 | all | The patch version of the GitLab instance. For example, if the GitLab version is `13.6.1`, the `CI_SERVER_VERSION_PATCH` is `1`. | +| `CI_SERVER_VERSION` | Pipeline | all | all | The full version of the GitLab instance. | +| `CI_SERVER` | Jobs only | all | all | Available for all jobs executed in CI/CD. `yes` when available. | +| `CI_SHARED_ENVIRONMENT` | Pipeline | all | 10.1 | Only available if the job is executed in a shared environment (something that is persisted across CI/CD invocations, like the `shell` or `ssh` executor). `true` when available. | +| `CI_TEMPLATE_REGISTRY_HOST` | Pipeline | 15.3 | all | The host of the registry used by CI/CD templates. Defaults to `registry.gitlab.com`. | +| `GITLAB_CI` | Pipeline | all | all | Available for all jobs executed in CI/CD. `true` when available. | +| `GITLAB_FEATURES` | Pipeline | 10.6 | all | The comma-separated list of licensed features available for the GitLab instance and license. | +| `GITLAB_USER_EMAIL` | Pipeline | 8.12 | all | The email of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the email of the user who started the job. | +| `GITLAB_USER_ID` | Pipeline | 8.12 | all | The numeric ID of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the ID of the user who started the job. | +| `GITLAB_USER_LOGIN` | Pipeline | 10.0 | all | The username of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the username of the user who started the job. | +| `GITLAB_USER_NAME` | Pipeline | 10.0 | all | The display name of the user who started the pipeline, unless the job is a manual job. In manual jobs, the value is the name of the user who started the job. | +| `KUBECONFIG` | Pipeline | 14.2 | all | The path to the `kubeconfig` file with contexts for every shared agent connection. Only available when a [GitLab agent is authorized to access the project](../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent). | +| `TRIGGER_PAYLOAD` | Pipeline | 13.9 | all | The webhook payload. Only available when a pipeline is [triggered with a webhook](../triggers/index.md#access-webhook-payload). | ## Predefined variables for merge request pipelines @@ -157,7 +161,11 @@ These variables are available when: |---------------------------------------------|--------|--------|-------------| | `CI_MERGE_REQUEST_APPROVED` | 14.1 | all | Approval status of the merge request. `true` when [merge request approvals](../../user/project/merge_requests/approvals/index.md) is available and the merge request has been approved. | | `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of usernames of assignees for the merge request. | +| `CI_MERGE_REQUEST_DIFF_BASE_SHA` | 13.7 | all | The base SHA of the merge request diff. | +| `CI_MERGE_REQUEST_DIFF_ID` | 13.7 | all | The version of the merge request diff. | +| `CI_MERGE_REQUEST_EVENT_TYPE` | 12.3 | all | The event type of the merge request. Can be `detached`, `merged_result` or `merge_train`. | | `CI_MERGE_REQUEST_ID` | 11.6 | all | The instance-level ID of the merge request. This is a unique ID across all projects on the GitLab instance. | +| `CI_MERGE_REQUEST_DESCRIPTION` | 16.7 | all | The description of the merge request. | | `CI_MERGE_REQUEST_IID` | 11.6 | all | The project-level IID (internal ID) of the merge request. This ID is unique for the current project, and is the number used in the merge request URL, page title, and other visible locations. | | `CI_MERGE_REQUEST_LABELS` | 11.9 | all | Comma-separated label names of the merge request. | | `CI_MERGE_REQUEST_MILESTONE` | 11.9 | all | The milestone title of the merge request. | @@ -165,20 +173,17 @@ These variables are available when: | `CI_MERGE_REQUEST_PROJECT_PATH` | 11.6 | all | The path of the project of the merge request. For example `namespace/awesome-project`. | | `CI_MERGE_REQUEST_PROJECT_URL` | 11.6 | all | The URL of the project of the merge request. For example, `http://192.168.10.15:3000/namespace/awesome-project`. | | `CI_MERGE_REQUEST_REF_PATH` | 11.6 | all | The ref path of the merge request. For example, `refs/merge-requests/1/head`. | -| `CI_MERGE_REQUEST_SQUASH_ON_MERGE` | 16.4 | all | `true` when the [squash on merge](../../user/project/merge_requests/squash_and_merge.md) option is set. | | `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` | 11.6 | all | The source branch name of the merge request. | | `CI_MERGE_REQUEST_SOURCE_BRANCH_PROTECTED` | 16.4 | all | `true` when the source branch of the merge request is [protected](../../user/project/protected_branches.md). | | `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the source branch of the merge request. The variable is empty in merge request pipelines. The SHA is present only in [merged results pipelines](../pipelines/merged_results_pipelines.md). | | `CI_MERGE_REQUEST_SOURCE_PROJECT_ID` | 11.6 | all | The ID of the source project of the merge request. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` | 11.6 | all | The path of the source project of the merge request. | | `CI_MERGE_REQUEST_SOURCE_PROJECT_URL` | 11.6 | all | The URL of the source project of the merge request. | +| `CI_MERGE_REQUEST_SQUASH_ON_MERGE` | 16.4 | all | `true` when the [squash on merge](../../user/project/merge_requests/squash_and_merge.md) option is set. | | `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | 11.6 | all | The target branch name of the merge request. | | `CI_MERGE_REQUEST_TARGET_BRANCH_PROTECTED` | 15.2 | all | `true` when the target branch of the merge request is [protected](../../user/project/protected_branches.md). | | `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the target branch of the merge request. The variable is empty in merge request pipelines. The SHA is present only in [merged results pipelines](../pipelines/merged_results_pipelines.md). | | `CI_MERGE_REQUEST_TITLE` | 11.9 | all | The title of the merge request. | -| `CI_MERGE_REQUEST_EVENT_TYPE` | 12.3 | all | The event type of the merge request. Can be `detached`, `merged_result` or `merge_train`. | -| `CI_MERGE_REQUEST_DIFF_ID` | 13.7 | all | The version of the merge request diff. | -| `CI_MERGE_REQUEST_DIFF_BASE_SHA` | 13.7 | all | The base SHA of the merge request diff. | ## Predefined variables for external pull request pipelines @@ -208,3 +213,8 @@ defines deployment variables that you can use with the integration. The [documentation for each integration](../../user/project/integrations/index.md) explains if the integration has any deployment variables available. + +## Troubleshooting + +You can [output the values of all variables available for a job](index.md#list-all-variables) +with a `script` command. diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index d25f9801f5b..bddb0947fac 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Where variables can be used **(FREE ALL)** @@ -149,15 +148,15 @@ Pipeline-level persisted variables: Job-level persisted variables: +- `CI_DEPLOY_PASSWORD` +- `CI_DEPLOY_USER` - `CI_JOB_ID` -- `CI_JOB_URL` -- `CI_JOB_TOKEN` - `CI_JOB_STARTED_AT` -- `CI_REGISTRY_USER` +- `CI_JOB_TOKEN` +- `CI_JOB_URL` - `CI_REGISTRY_PASSWORD` +- `CI_REGISTRY_USER` - `CI_REPOSITORY_URL` -- `CI_DEPLOY_USER` -- `CI_DEPLOY_PASSWORD` Persisted variables are: diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index e931a8b3b4e..5867a5b3506 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD artifacts reports types **(FREE ALL)** @@ -17,7 +17,8 @@ Use [`artifacts:reports`](index.md#artifactsreports) to: Artifacts created for `artifacts: reports` are always uploaded, regardless of the job results (success or failure). You can use [`artifacts:expire_in`](index.md#artifactsexpire_in) to set an expiration -date for the artifacts. +time for the artifacts, which overrides the instance's [default setting](../../administration/settings/continuous_integration.md#maximum-artifacts-size). +GitLab.com might have a [different default artifacts expiry value](../../user/gitlab_com/index.md#gitlab-cicd). Some `artifacts:reports` types can be generated by multiple jobs in the same pipeline, and used by merge request or pipeline features from each job. @@ -30,8 +31,6 @@ not supported. Track progress on adding support in [this issue](https://gitlab.c ## `artifacts:reports:accessibility` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 12.8. - The `accessibility` report uses [pa11y](https://pa11y.org/) to report on the accessibility impact of changes introduced in merge requests. @@ -91,9 +90,6 @@ The following is an example of what a job annotations report might look like: ## `artifacts:reports:api_fuzzing` **(ULTIMATE ALL)** -> - Introduced in GitLab 13.4. -> - Requires GitLab Runner 13.4 or later. - The `api_fuzzing` report collects [API Fuzzing bugs](../../user/application_security/api_fuzzing/index.md) as artifacts. @@ -143,8 +139,7 @@ GitLab can display the results of coverage report in the merge request ## `artifacts:reports:codequality` -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. -> - Support for multiple reports in diff annotations and full pipeline report [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9014) in 15.7. +> Support for multiple reports in diff annotations and full pipeline report [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9014) in 15.7. The `codequality` report collects [code quality issues](../testing/code_quality.md). The collected code quality report uploads to GitLab as an artifact. @@ -155,6 +150,8 @@ GitLab can display the results of one or more reports in: - The merge request [diff annotations](../testing/code_quality.md#merge-request-changes-view). - The [full report](../testing/metrics_reports.md). +The [`artifacts:expire_in`](../yaml/index.md#artifactsexpire_in) value is set to `1 week`. + ## `artifacts:reports:container_scanning` **(ULTIMATE ALL)** The `container_scanning` report collects [Container Scanning vulnerabilities](../../user/application_security/container_scanning/index.md). @@ -169,9 +166,6 @@ GitLab can display the results of one or more reports in: ## `artifacts:reports:coverage_fuzzing` **(ULTIMATE ALL)** -> - Introduced in GitLab 13.4. -> - Requires GitLab Runner 13.4 or later. - The `coverage_fuzzing` report collects [coverage fuzzing bugs](../../user/application_security/coverage_fuzzing/index.md). The collected coverage fuzzing report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: @@ -233,8 +227,6 @@ GitLab can display the results of one or more reports in: ## `artifacts:reports:dotenv` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9. - The `dotenv` report collects a set of environment variables as artifacts. The collected variables are registered as runtime-created variables of the job, @@ -294,24 +286,8 @@ concatenate them into a single file. Use either: - A combination of both (`junit: [rspec.xml, test-results/TEST-*.xml]`). - Directories are not supported(`junit: test-results`, `junit: test-results/**`). -<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> - -## `artifacts:reports:license_scanning` **(ULTIMATE ALL)** - -> Introduced in GitLab 12.8. - -The license scanning report was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) -in GitLab 15.9 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421363) in GitLab 16.3. -You should instead migrate to use [License approval policies](../../user/compliance/license_approval_policies.md) and -the [new method of license scanning](../../user/compliance/license_scanning_of_cyclonedx_files/index.md). - -<!--- end_remove --> - ## `artifacts:reports:load_performance` **(PREMIUM ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in GitLab 13.2. -> - Requires GitLab Runner 11.5 and above. - The `load_performance` report collects [Load Performance Testing metrics](../testing/load_performance_testing.md). The report is uploaded to GitLab as an artifact. @@ -330,14 +306,18 @@ GitLab can display the results of one or more reports in the merge request ## `artifacts:reports:requirements` **(ULTIMATE ALL)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. - The `requirements` report collects `requirements.json` files. The collected Requirements report uploads to GitLab as an artifact and existing [requirements](../../user/project/requirements/index.md) are marked as Satisfied. GitLab can display the results of one or more reports in the [project requirements](../../user/project/requirements/index.md#view-a-requirement). +## `artifacts:reports:repository_xray` **(ULTIMATE ALL)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/432235) in GitLab 16.7. + +The `repository_xray` report collects information about your repository for use by AI in code suggestions. + ## `artifacts:reports:sast` > [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. @@ -352,10 +332,6 @@ GitLab can display the results of one or more reports in: ## `artifacts:reports:secret_detection` -> - Introduced in GitLab 13.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) to GitLab Free in 13.3. -> - Requires GitLab Runner 11.5 and above. - The `secret-detection` report collects [detected secrets](../../user/application_security/secret_detection/index.md). The collected Secret Detection report is uploaded to GitLab. @@ -367,9 +343,6 @@ GitLab can display the results of one or more reports in: ## `artifacts:reports:terraform` -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0. -> - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. - The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/iac/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform plan report uploads to GitLab as an artifact. diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index f0e5a475838..8da4195f5aa 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use CI/CD configuration from other files **(FREE ALL)** diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 9b781ca6d13..df2330e04f6 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD YAML syntax reference **(FREE ALL)** @@ -55,13 +54,11 @@ A GitLab CI/CD pipeline configuration includes: | [`dast_configuration`](#dast_configuration) | Use configuration from DAST profiles on a job level. | | [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. | | [`environment`](#environment) | Name of an environment to which the job deploys. | - | [`except`](#only--except) | Control when jobs are not created. | | [`extends`](#extends) | Configuration entries that this job inherits from. | | [`image`](#image) | Use Docker images. | | [`inherit`](#inherit) | Select which global defaults all jobs inherit. | | [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. | | [`needs`](#needs) | Execute jobs earlier than the stage ordering. | - | [`only`](#only--except) | Control when jobs are created. | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | | [`parallel`](#parallel) | How many instances of a job should be run in parallel. | | [`release`](#release) | Instructs the runner to generate a [release](../../user/project/releases/index.md) object. | @@ -193,6 +190,27 @@ The time limit to resolve all files is 30 seconds. - [Use variables with `include`](includes.md#use-variables-with-include). - [Use `rules` with `include`](includes.md#use-rules-with-include). +#### `include:component` + +Use `include:component` to add a [CI/CD component](../components/index.md) to the +pipeline configuration. + +**Keyword type**: Global keyword. + +**Possible inputs**: The full address of the CI/CD component, formatted as +`<fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version>`. + +**Example of `include:component`**: + +```yaml +include: + - component: gitlab.example.com/my-org/security-components/secret-detection@1.0 +``` + +**Related topics**: + +- [Use a CI/CD component](../components/index.md#use-a-component). + #### `include:local` Use `include:local` to include a file that is in the same repository and branch as the configuration file containing the `include` keyword. @@ -454,6 +472,9 @@ start. Jobs in the current stage are not stopped and continue to run. Use [`workflow`](workflow.md) to control pipeline behavior. +You can use some [predefined CI/CD variables](../variables/predefined_variables.md) in +`workflow` configuration, but not variables that are only defined when jobs start. + **Related topics**: - [`workflow: rules` examples](workflow.md#workflow-rules-examples) @@ -499,6 +520,7 @@ workflow: - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/' variables: PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline' + - when: always # Other pipelines can run, but use the default name ``` **Additional details**: @@ -727,8 +749,11 @@ In this example: **Additional details**: -- If an input uses both `default` and [`options`](#specinputsoptions), the default value - must be one of the listed options. If not, the pipeline fails with a validation error. +- The pipeline fails with a validation error when the input: + - Uses both `default` and [`options`](#specinputsoptions), but the default value + is not one of the listed options. + - Uses both `default` and `regex`, but the default value does not match the regular expression. + - Value does not match the [`type`](#specinputstype). ##### `spec:inputs:description` @@ -788,8 +813,42 @@ In this example: **Additional details**: -- If an input uses both [`default`](#specinputsdefault) and `options`, the default value - must be one of the listed options. If not, the pipeline fails with a validation error. +- The pipeline fails with a validation error when: + - The input uses both `options` and [`default`](#specinputsdefault), but the default value + is not one of the listed options. + - Any of the input options do not match the [`type`](#specinputstype), which can + be either `string` or `number`, but not `boolean` when using `options`. + +##### `spec:inputs:regex` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/410836) in GitLab 16.5. + +Use `spec:inputs:regex` to specify a regular expression that the input must match. + +**Keyword type**: Header keyword. `specs` must be declared at the top of the configuration file, +in a header section. + +**Possible inputs**: Must be a regular expression that starts and ends with the `/` character. + +**Example of `spec:inputs:regex`**: + +```yaml +spec: + inputs: + version: + regex: /^v\d\.\d+(\.\d+)$/ +--- + +# The pipeline configuration would follow... +``` + +In this example, inputs of `v1.0` or `v1.2.3` match the regular expression and pass validation. +An input of `v1.A.B` does not match the regular expression and fails validation. + +**Additional details**: + +- `inputs:regex` can only be used with a [`type`](#specinputstype) of `string`, + not `number` or `boolean`. ##### `spec:inputs:type` @@ -1213,6 +1272,7 @@ job: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223273) in GitLab 13.8 [with a flag](../../user/feature_flags.md) named `non_public_artifacts`, disabled by default. > - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/322454) in GitLab 15.10. Artifacts created with `artifacts:public` before 15.10 are not guaranteed to remain private after this update. +> - [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/294503) in GitLab 16.7. Rolled out and removed a feature flag named `non_public_artifacts` WARNING: On self-managed GitLab, by default this feature is not available. To make it available, @@ -2041,7 +2101,7 @@ stop_review_app: #### `environment:auto_stop_in` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8. +> CI/CD variable support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365140) in GitLab 15.4. The `auto_stop_in` keyword specifies the lifetime of the environment. When an environment expires, GitLab automatically stops it. @@ -2056,6 +2116,8 @@ these are all equivalent: - `one week` - `never` +CI/CD variables [are supported](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). + **Example of `environment:auto_stop_in`**: ```yaml @@ -2404,6 +2466,37 @@ image: - [Override the entrypoint of an image](../docker/using_docker_images.md#override-the-entrypoint-of-an-image). +#### `image:docker` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27919) in GitLab 16.7. Requires GitLab Runner 16.7 or later. + +Use `image:docker` to pass options to the Docker executor of a GitLab Runner. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). + +**Possible inputs**: + +A hash of options for the Docker executor, which can include: + +- `platform`: Selects the architecture of the image to pull. When not specified, + the default is the same platform as the host runner. + +**Example of `image:docker`**: + +```yaml +arm-sql-job: + script: echo "Run sql tests" + image: + name: super/sql:experimental + docker: + platform: arm64/v8 +``` + +**Additional details**: + +- `image:docker:platform` maps to the [`docker pull --platform` option](https://docs.docker.com/engine/reference/commandline/pull/#options). + #### `image:pull_policy` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default. @@ -2444,8 +2537,8 @@ job2: **Related topics**: - [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). -- [How runner pull policies work](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work). -- [Using multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#using-multiple-pull-policies). +- [Configure how runners pull images](https://docs.gitlab.com/runner/executors/docker.html#configure-how-runners-pull-images). +- [Set multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#set-multiple-pull-policies). ### `inherit` @@ -2529,13 +2622,22 @@ job2: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes. +Use `interruptible` to configure the [auto-cancel redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) +feature to cancel a job before it completes if a new pipeline on the same ref starts for a newer commit. If the feature +is disabled, the keyword has no effect. -This keyword has no effect if [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) -is disabled. When enabled, a running job with `interruptible: true` is cancelled when -starting a pipeline for a new change on the same branch. +**Running** jobs are only cancelled when the jobs are configured with `interruptible: true` and: -You can't cancel subsequent jobs after a job with `interruptible: false` starts. +- No jobs configured with `interruptible: false` have started at any time. + After a job with `interruptible: false` starts, the entire pipeline is no longer + considered interruptible. + - If the pipeline triggered a downstream pipeline, but no job with `interruptible: false` + in the downstream pipeline has started yet, the downstream pipeline is also cancelled. +- The new pipeline is for a commit with new changes. The **Auto-cancel redundant pipelines** + feature has no effect if you select **Run pipeline** in the UI to run a pipeline for the same commit. + +A job that has not started yet is always considered `interruptible: true`, regardless of the job's configuration. +The `interruptible` configuration is only considered after the job starts. **Keyword type**: Job keyword. You can use it only as part of a job or in the [`default` section](#default). @@ -2579,11 +2681,10 @@ In this example, a new pipeline causes a running pipeline to be: - Only set `interruptible: true` if the job can be safely canceled after it has started, like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments. -- To completely cancel a running pipeline, all jobs must have `interruptible: true`, - or `interruptible: false` jobs must not have started. -- Running jobs are only cancelled if the newer pipeline has new changes. - For example, a running job is not be cancelled if you run a new pipeline for the same - commit by selecting **Run pipeline** in the UI. +- You can add an optional manual job with `interruptible: false` in the first stage of + a pipeline to allow users to manually prevent a pipeline from being automatically + cancelled. After a user starts the job, the pipeline cannot be canceled by the + **Auto-cancel redundant pipelines** feature. ### `needs` @@ -3051,7 +3152,7 @@ pages: environment: production ``` -This example moves all files from a `my-html-content/` directory to the `public/` directory. +This example renames the `my-html-content/` directory to `public/`. This directory is exported as an artifact and published with GitLab Pages. #### `pages:publish` @@ -3084,6 +3185,41 @@ This example uses [Eleventy](https://www.11ty.dev) to generate a static website output the generated HTML files into a the `dist/` directory. This directory is exported as an artifact and published with GitLab Pages. +#### `pages:pages.path_prefix` **(PREMIUM ALL EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129534) in GitLab 16.7 as an [Experiment](../../policy/experiment-beta-support.md) [with a flag](../../user/feature_flags.md) named `pages_multiple_versions_setting`, disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +an administrator can [enable the feature flag](../../administration/feature_flags.md) named +`pages_multiple_versions_setting`. On GitLab.com, this feature is not available. This feature is not ready for production use. + +Use `pages.path_prefix` to configure a path prefix for [multiple deployments](../../user/project/pages/index.md#create-multiple-deployments) of GitLab Pages. + +**Keyword type**: Job keyword. You can use it only as part of a `pages` job. + +**Possible inputs**: + +- A string with valid [URL characters](https://www.ietf.org/rfc/rfc1738.txt). +- [CI/CD variables](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). +- A combination of both. + +**Example of `pages.path_prefix`**: + +```yaml +pages: + stage: deploy + script: + - echo "Pages accessible through ${CI_PAGES_URL}/${CI_COMMIT_BRANCH}" + pages: + path_prefix: "$CI_COMMIT_BRANCH" + artifacts: + paths: + - public +``` + +In this example, a different pages deployment is created for each branch. + ### `parallel` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336576) in GitLab 15.9, the maximum value for `parallel` is increased from 50 to 200. @@ -3222,7 +3358,7 @@ The release job must have access to the [`release-cli`](https://gitlab.com/gitla which must be in the `$PATH`. If you use the [Docker executor](https://docs.gitlab.com/runner/executors/docker.html), -you can use this image from the GitLab Container Registry: `registry.gitlab.com/gitlab-org/release-cli:latest` +you can use this image from the GitLab container registry: `registry.gitlab.com/gitlab-org/release-cli:latest` If you use the [Shell executor](https://docs.gitlab.com/runner/executors/shell.html) or similar, [install `release-cli`](../../user/project/releases/release_cli.md) on the server where the runner is registered. @@ -3556,7 +3692,7 @@ Use `retry:when` with `retry:max` to retry jobs for only specific failure cases. - `archived_failure`: Retry if the job is archived and can't be run. - `unmet_prerequisites`: Retry if the job failed to complete prerequisite tasks. - `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner. -- `data_integrity_failure`: Retry if there is a structural integrity problem detected. +- `data_integrity_failure`: Retry if there is an unknown job problem. **Example of `retry:when`** (single failure type): @@ -3706,8 +3842,6 @@ An array including any number of: - A directory and all its subdirectories, for example `path/to/directory/**/*`. - Wildcard [glob](https://en.wikipedia.org/wiki/Glob_(programming)) paths for all files with the same extension or multiple extensions, for example `*.md` or `path/to/directory/*.{rb,py,sh}`. - See the [Ruby `fnmatch` documentation](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) - for the supported syntax list. - Wildcard paths to files in the root directory, or all directories, wrapped in double quotes. For example `"*.json"` or `"**/*.json"`. @@ -3735,6 +3869,9 @@ docker build: **Additional details**: - `rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychanges--exceptchanges). +- Glob patterns are interpreted with Ruby's [`File.fnmatch`](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) + with the [flags](https://docs.ruby-lang.org/en/master/File/Constants.html#module-File::Constants-label-Filename+Globbing+Constants+-28File-3A-3AFNM_-2A-29) + `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. - You can use `when: never` to implement a rule similar to [`except:changes`](#onlychanges--exceptchanges). - `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). @@ -3838,8 +3975,9 @@ job: **Additional details**: -- Glob patterns are interpreted with Ruby [`File.fnmatch`](https://docs.ruby-lang.org/en/2.7.0/File.html#method-c-fnmatch) - with the flags `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. +- Glob patterns are interpreted with Ruby's [`File.fnmatch`](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) + with the [flags](https://docs.ruby-lang.org/en/master/File/Constants.html#module-File::Constants-label-Filename+Globbing+Constants+-28File-3A-3AFNM_-2A-29) + `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. - For performance reasons, GitLab performs a maximum of 10,000 checks against `exists` patterns or file paths. After the 10,000th check, rules with patterned globs always match. In other words, the `exists` rule always assumes a match in @@ -3995,7 +4133,7 @@ job2: **Additional details**: -- When you use [these special characters in `script`](script.md#use-special-characters-with-script), you must use single quotes (`'`) or double quotes (`"`) . +- When you use [these special characters in `script`](script.md#use-special-characters-with-script), you must use single quotes (`'`) or double quotes (`"`). **Related topics**: @@ -4210,7 +4348,39 @@ In this example, GitLab launches two containers for the job: - [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). - [Use Docker to build Docker images](../docker/using_docker_build.md). -#### `service:pull_policy` +#### `services:docker` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27919) in GitLab 16.7. Requires GitLab Runner 16.7 or later. + +Use `services:docker` to pass options to the Docker executor of a GitLab Runner. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default` section](#default). + +**Possible inputs**: + +A hash of options for the Docker executor, which can include: + +- `platform`: Selects the architecture of the image to pull. When not specified, + the default is the same platform as the host runner. + +**Example of `services:docker`**: + +```yaml +arm-sql-job: + script: echo "Run sql tests in service container" + image: ruby:2.6 + services: + - name: super/sql:experimental + docker: + platform: arm64/v8 +``` + +**Additional details**: + +- `services:docker:platform` maps to the [`docker pull --platform` option](https://docs.docker.com/engine/reference/commandline/pull/#options). + +#### `services:pull_policy` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21619) in GitLab 15.1 [with a flag](../../administration/feature_flags.md) named `ci_docker_image_pull_policy`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363186) in GitLab 15.2. @@ -4226,7 +4396,7 @@ The pull policy that the runner uses to fetch the Docker image. - A single pull policy, or multiple pull policies in an array. Can be `always`, `if-not-present`, or `never`. -**Examples of `service:pull_policy`**: +**Examples of `services:pull_policy`**: ```yaml job1: @@ -4250,8 +4420,8 @@ job2: **Related topics**: - [Run your CI/CD jobs in Docker containers](../docker/using_docker_images.md). -- [How runner pull policies work](https://docs.gitlab.com/runner/executors/docker.html#how-pull-policies-work). -- [Using multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#using-multiple-pull-policies). +- [Configure how runners pull images](https://docs.gitlab.com/runner/executors/docker.html#configure-how-runners-pull-images). +- [Set multiple pull policies](https://docs.gitlab.com/runner/executors/docker.html#set-multiple-pull-policies). ### `stage` @@ -4420,7 +4590,7 @@ In this example, only runners with *both* the `ruby` and `postgres` tags can run **Related topics**: -- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run). +- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#control-jobs-that-a-runner-can-run). - [Select different runner tags for each parallel matrix job](../jobs/job_control.md#select-different-runner-tags-for-each-parallel-matrix-job). ### `timeout` @@ -4431,7 +4601,7 @@ Use `timeout` to configure a timeout for a specific job. If the job runs for lon than the timeout, the job fails. The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run), -but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). +but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-the-maximum-job-timeout). **Keyword type**: Job keyword. You can use it only as part of a job or in the [`default` section](#default). @@ -4670,6 +4840,13 @@ child3: yaml_variables: false ``` +**Additional details**: + +- CI/CD variables forwarded to downstream pipelines with `trigger:forward` have the + [highest precedence](../variables/index.md#cicd-variable-precedence). If a variable + with the same name is defined in the downstream pipeline, that variable is overwritten + by the forwarded variable. + ### `variables` Use `variables` to define [CI/CD variables](../variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) for jobs. @@ -5121,12 +5298,11 @@ Use `changes` in pipelines with the following refs: **Possible inputs**: An array including any number of: - Paths to files. -- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory - and all its subdirectories, for example `path/to/directory/**/*`. -- Wildcard [glob](https://en.wikipedia.org/wiki/Glob_(programming)) paths for all - files with the same extension or multiple extensions, for example `*.md` or `path/to/directory/*.{rb,py,sh}`. - See the [Ruby `fnmatch` documentation](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) - for the supported syntax list. +- Wildcard paths for: + - Single directories, for example `path/to/directory/*`. + - A directory and all its subdirectories, for example `path/to/directory/**/*`. +- Wildcard [glob](https://en.wikipedia.org/wiki/Glob_(programming)) paths for all files + with the same extension or multiple extensions, for example `*.md` or `path/to/directory/*.{rb,py,sh}`. - Wildcard paths to files in the root directory, or all directories, wrapped in double quotes. For example `"*.json"` or `"**/*.json"`. @@ -5149,6 +5325,9 @@ docker build: **Additional details**: - `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). +- Glob patterns are interpreted with Ruby's [`File.fnmatch`](https://docs.ruby-lang.org/en/master/File.html#method-c-fnmatch) + with the [flags](https://docs.ruby-lang.org/en/master/File/Constants.html#module-File::Constants-label-Filename+Globbing+Constants+-28File-3A-3AFNM_-2A-29) + `File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB`. - If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`, `changes` can't determine if a given file is new or old and always returns `true`. - If you use `only: changes` with other refs, jobs ignore the changes and always run. diff --git a/doc/ci/yaml/inputs.md b/doc/ci/yaml/inputs.md index 089d6bc5b62..0869be6da9f 100644 --- a/doc/ci/yaml/inputs.md +++ b/doc/ci/yaml/inputs.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Define inputs for configuration added with `include` **(FREE ALL)** @@ -9,19 +9,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/391331) in GitLab 15.11 as a Beta feature. > - Made generally available in GitLab 16.6. -## Define input parameters with `spec:inputs` +Use inputs to increase the flexibility of CI/CD configuration files that are designed +to be reused. + +Inputs can use CI/CD variables, but have the same [variable limitations as the `include` keyword](includes.md#use-variables-with-include). -> - `description` keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415637) in GitLab 16.5. -> - `options` keyword [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393401) in GitLab 16.6. +## Define input parameters with `spec:inputs` Use `spec:inputs` to define input parameters for CI/CD configuration intended to be added to a pipeline with `include`. Use [`include:inputs`](#set-input-values-when-using-include) -to define the values to use when the pipeline runs. +to pass input values when building the configuration for a pipeline. The specs must be declared at the top of the configuration file, in a header section. Separate the header from the rest of the configuration with `---`. -Use the interpolation format `$[[ input.input-id ]]` to reference the values outside of the header section. +Use the interpolation format `$[[ inputs.input-id ]]` outside the header section to replace the values. The inputs are evaluated and interpolated when the configuration is fetched during pipeline creation, but before the configuration is merged with the contents of the `.gitlab-ci.yml` file. @@ -42,9 +44,9 @@ scan-website: When using `spec:inputs`: - Inputs are mandatory by default. -- Inputs must be strings by default. -- A string containing an interpolation block must not exceed 1 MB. -- The string inside an interpolation block must not exceed 1 KB. +- Validation errors are returned if: + - A string containing an interpolation block exceeds 1 MB. + - The string inside an interpolation block exceeds 1 KB. Additionally, use: @@ -55,8 +57,53 @@ Additionally, use: understand the input details or expected values. - [`spec:inputs:options`](index.md#specinputsoptions) to specify a list of allowed values for an input. +- [`spec:inputs:regex`](index.md#specinputsoptions) to specify a regular expression + that the input must match. - [`spec:inputs:type`](index.md#specinputstype) to force a specific input type, which - can be `string` (the default type), `number`, or `boolean`. + can be `string` (default when not specified), `number`, or `boolean`. + +### Define inputs with multiple parameters + +You can define multiple inputs per CI/CD configuration file, and each input can have +multiple configuration parameters. + +For example, in a file named `scan-website-job.yml`: + +```yaml +spec: + inputs: + job-prefix: # Mandatory string input + description: "Define a prefix for the job name" + job-stage: # Optional string input with a default value when not provided + default: test + environment: # Mandatory input that must match one of the options + options: ['test', 'staging', 'production'] + concurrency: + type: number # Optional numeric input with a default value when not provided + default: 1 + version: # Mandatory string input that must match the regular expression + type: string + regex: /^v\d\.\d+(\.\d+)$/ + export_results: # Optional boolean input with a default value when not provided + type: boolean + default: true +--- + +"$[[ job-prefix ]]-scan-website": + stage: $[[ inputs.job-stage ]] + script: + - echo "scanning website -e $[[ inputs.environment ]] -c $[[ inputs.concurrency ]] -v $[[ inputs.version ]]" + - if [ $[[ inputs.export_results ]] ]; then echo "export results"; fi +``` + +In this example: + +- `job-prefix` is a mandatory string input and must be defined. +- `job-stage` is optional. If not defined, the value is `test`. +- `environment` is a mandatory string input that must match one of the defined options. +- `concurrency` is an optional numeric input. When not specified, it defaults to `1`. +- `version` is a mandatory string input that must match the specified regular expression. +- `export_results` is an optional boolean input. When not specified, it defaults to `true`. ## Set input values when using `include` @@ -65,29 +112,29 @@ Additionally, use: Use [`include:inputs`](index.md#includeinputs) to set the values for the parameters when the included configuration is added to the pipeline. -For example, to include a `custom_website_scan.yml` that has the same specs -as the [example above](#define-input-parameters-with-specinputs): +For example, to include the `scan-website-job.yml` in the [example above](#define-inputs-with-multiple-parameters): ```yaml include: - - local: 'custom_website_scan.yml' + - local: 'scan-website-job.yml' inputs: - job-stage: post-deploy - environment: production - -stages: - - build - - test - - deploy - - post-deploy - -# The pipeline configuration would follow... + job-prefix: 'some-service-' + environment: 'staging' + concurrency: 2 + version: 'v1.3.2' + export_results: false ``` -In this example, the included configuration is added with: +In this example, the inputs for the included configuration are: -- `job-stage` set to `post-deploy`, so the included job runs in the custom `post-deploy` stage. -- `environment` set to `production`, so the included job runs for the production environment. +| Input | Value | Details | +|------------------|-----------------|---------| +| `job-prefix` | `some-service-` | Must be explicitly defined. | +| `job-stage` | `test` | Not defined in `include:inputs`, so the value comes from `spec:inputs:default` in the included configuration. | +| `environment` | `staging` | Must be explicitly defined, and must match one of the values in `spec:inputs:options` in the included configuration. | +| `concurrency` | `2` | Must be a numeric value to match the `spec:inputs:type` set to `number` in the included configuration. Overrides the default value. | +| `version` | `v1.3.2` | Must be explicitly defined, and must match the regular expression in the `spec:inputs:regex` in the included configuration. | +| `export_results` | `false` | Must be either `true` or `false` to match the `spec:inputs:type` set to `boolean` in the included configuration. Overrides the default value. | ### Use `include:inputs` with multiple files @@ -96,7 +143,7 @@ For example: ```yaml include: - - component: gitlab.com/org/my-component@1.0 + - component: gitlab.com/the-namespace/the-project/the-component@1.0 inputs: stage: my-stage - local: path/to/file.yml diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 016b0ae9482..756f14ea5a5 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Format scripts and job logs **(FREE ALL)** diff --git a/doc/ci/yaml/signing_examples.md b/doc/ci/yaml/signing_examples.md index b808edebe7a..e56109085a3 100644 --- a/doc/ci/yaml/signing_examples.md +++ b/doc/ci/yaml/signing_examples.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Sigstore for keyless signing and verification **(FREE SAAS)** @@ -142,7 +142,7 @@ You can use Sigstore and npm, together with GitLab CI/CD, to digitally sign buil CLI provenance generation allows users to trust and verify that the package they are downloading and using is from you and the build system that built it. -For more information on how to publish npm packages, see [GitLab npm Package Registry](../../user/packages/npm_registry/index.md). +For more information on how to publish npm packages, see [GitLab npm package registry](../../user/packages/npm_registry/index.md). ### Sigstore diff --git a/doc/ci/yaml/workflow.md b/doc/ci/yaml/workflow.md index af275a15f9c..a22e4e322b6 100644 --- a/doc/ci/yaml/workflow.md +++ b/doc/ci/yaml/workflow.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD `workflow` keyword **(FREE ALL)** diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md index 84be9c85676..67383ad8e9e 100644 --- a/doc/ci/yaml/yaml_optimization.md +++ b/doc/ci/yaml/yaml_optimization.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Optimize GitLab CI/CD configuration files **(FREE ALL)** diff --git a/doc/cloud_seed/index.md b/doc/cloud_seed/index.md index 70166b2d09f..8180669b1af 100644 --- a/doc/cloud_seed/index.md +++ b/doc/cloud_seed/index.md @@ -120,7 +120,7 @@ The following databases and versions are supported: - 2019: Standard, Enterprise, Express, and Web - 2017: Standard, Enterprise, Express, and Web -Google Cloud pricing applies. Please refer to the [Cloud SQL pricing page](https://cloud.google.com/sql/pricing). +Google Cloud pricing applies. Refer to the [Cloud SQL pricing page](https://cloud.google.com/sql/pricing). 1. [Create a database instance](#create-a-database-instance) 1. [Database setup through a background worker](#database-setup-through-a-background-worker) diff --git a/doc/development/activitypub/actors/group.md b/doc/development/activitypub/actors/group.md index 1ebc9310e05..eec4ead7d78 100644 --- a/doc/development/activitypub/actors/group.md +++ b/doc/development/activitypub/actors/group.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" remove_date: '2024-01-22' redirect_to: 'index.md' --- diff --git a/doc/development/activitypub/actors/index.md b/doc/development/activitypub/actors/index.md index 0a56cc7b093..6d82e79b9a0 100644 --- a/doc/development/activitypub/actors/index.md +++ b/doc/development/activitypub/actors/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Implement an ActivityPub actor **(EXPERIMENT)** diff --git a/doc/development/activitypub/actors/project.md b/doc/development/activitypub/actors/project.md index 37c753b36e6..ed6280ad7f0 100644 --- a/doc/development/activitypub/actors/project.md +++ b/doc/development/activitypub/actors/project.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" remove_date: '2024-01-22' redirect_to: 'index.md' --- diff --git a/doc/development/activitypub/actors/releases.md b/doc/development/activitypub/actors/releases.md index 009b98b6adf..ae3aabaa34a 100644 --- a/doc/development/activitypub/actors/releases.md +++ b/doc/development/activitypub/actors/releases.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Activities for following releases actor **(EXPERIMENT)** diff --git a/doc/development/activitypub/actors/topic.md b/doc/development/activitypub/actors/topic.md index 2cac837791f..fe2e0bf5eff 100644 --- a/doc/development/activitypub/actors/topic.md +++ b/doc/development/activitypub/actors/topic.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" remove_date: '2024-01-22' redirect_to: 'index.md' --- diff --git a/doc/development/activitypub/actors/user.md b/doc/development/activitypub/actors/user.md index fa4e948f27a..7ddab8d2700 100644 --- a/doc/development/activitypub/actors/user.md +++ b/doc/development/activitypub/actors/user.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" remove_date: '2024-01-22' redirect_to: 'index.md' --- diff --git a/doc/development/activitypub/index.md b/doc/development/activitypub/index.md index ae00290f901..66bd9cc27f5 100644 --- a/doc/development/activitypub/index.md +++ b/doc/development/activitypub/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # ActivityPub **(EXPERIMENT)** diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index 3ce303d429a..7996a9b1195 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Adding a new Service Component to GitLab diff --git a/doc/development/advanced_search.md b/doc/development/advanced_search.md index 805459cb4ee..a552b22226d 100644 --- a/doc/development/advanced_search.md +++ b/doc/development/advanced_search.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Global Search -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Advanced search development guidelines @@ -32,7 +32,7 @@ See the [Elasticsearch GDK setup instructions](https://gitlab.com/gitlab-org/git - `gitlab:elastic:test:index_size`: Tells you how much space the current index is using, as well as how many documents are in the index. - `gitlab:elastic:test:index_size_change`: Outputs index size, reindexes, and outputs index size again. Useful when testing improvements to indexing size. -Additionally, if you need large repositories or multiple forks for testing, please consider [following these instructions](rake_tasks.md#extra-project-seed-options) +Additionally, if you need large repositories or multiple forks for testing, consider [following these instructions](rake_tasks.md#extra-project-seed-options) ## How does it work? @@ -40,7 +40,7 @@ The Elasticsearch integration depends on an external indexer. We ship an [indexe After initial indexing is complete, create, update, and delete operations for all models except projects (see [#207494](https://gitlab.com/gitlab-org/gitlab/-/issues/207494)) are tracked in a Redis [`ZSET`](https://redis.io/docs/manual/data-types/#sorted-sets). A regular `sidekiq-cron` `ElasticIndexBulkCronWorker` processes this queue, updating many Elasticsearch documents at a time with the [Bulk Request API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html). -Search queries are generated by the concerns found in [`ee/app/models/concerns/elastic`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/app/models/concerns/elastic). These concerns are also in charge of access control, and have been a historic source of security bugs so please pay close attention to them! +Search queries are generated by the concerns found in [`ee/app/models/concerns/elastic`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/app/models/concerns/elastic). These concerns are also in charge of access control, and have been a historic source of security bugs so pay close attention to them! ### Custom routing @@ -62,13 +62,13 @@ The following analyzers and tokenizers are defined in [`ee/lib/elastic/latest/co Used when indexing blobs' paths. Uses the `path_tokenizer` and the `lowercase` and `asciifolding` filters. -Please see the `path_tokenizer` explanation below for an example. +See the `path_tokenizer` explanation below for an example. #### `sha_analyzer` Used in blobs and commits. Uses the `sha_tokenizer` and the `lowercase` and `asciifolding` filters. -Please see the `sha_tokenizer` explanation later below for an example. +See the `sha_tokenizer` explanation later below for an example. #### `code_analyzer` @@ -76,7 +76,7 @@ Used when indexing a blob's filename and content. Uses the `whitespace` tokenize The `whitespace` tokenizer was selected to have more control over how tokens are split. For example the string `Foo::bar(4)` needs to generate tokens like `Foo` and `bar(4)` to be properly searched. -Please see the `code` filter for an explanation on how tokens are split. +See the `code` filter for an explanation on how tokens are split. NOTE: The [Elasticsearch `code_analyzer` doesn't account for all code cases](../integration/advanced_search/elasticsearch_troubleshooting.md#elasticsearch-code_analyzer-doesnt-account-for-all-code-cases). diff --git a/doc/development/ai_architecture.md b/doc/development/ai_architecture.md index 54ad52f0c39..0717872a12b 100644 --- a/doc/development/ai_architecture.md +++ b/doc/development/ai_architecture.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # AI Architecture @@ -19,7 +19,7 @@ The following diagram from the [architecture blueprint](../architecture/blueprin ## SaaS-based AI abstraction layer -GitLab currently operates a cloud-hosted AI architecture. We will allow access to it for licensed self managed instances using the AI-gateway. Please see [the blueprint](../architecture/blueprints/ai_gateway) for details +GitLab currently operates a cloud-hosted AI architecture. We will allow access to it for licensed self managed instances using the AI-gateway. See [the blueprint](../architecture/blueprints/ai_gateway) for details. There are two primary reasons for this: the best AI models are cloud-based as they often depend on specialized hardware designed for this purpose, and operating self-managed infrastructure capable of AI at-scale and with appropriate performance is a significant undertaking. We are actively [tracking self-managed customers interested in AI](https://gitlab.com/gitlab-org/gitlab/-/issues/409183). diff --git a/doc/development/ai_features/duo_chat.md b/doc/development/ai_features/duo_chat.md index ad044f4a923..d7f88997fca 100644 --- a/doc/development/ai_features/duo_chat.md +++ b/doc/development/ai_features/duo_chat.md @@ -1,7 +1,7 @@ --- stage: AI-powered group: Duo Chat -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab Duo Chat @@ -14,7 +14,7 @@ Use [this snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/2554994) for 1. [Enable Anthropic API features](index.md#configure-anthropic-access). 1. [Ensure the embedding database is configured](index.md#set-up-the-embedding-database). 1. Ensure that your current branch is up-to-date with `master`. -1. To access the GitLab Duo Chat interface, in the lower-left corner of any page, select **Help** and **Ask GitLab Duo Chat**. +1. Enable the feature in Rails console: `Feature.enable(:tanuki_bot_breadcrumbs_entry_point)` ## Working with GitLab Duo Chat @@ -85,7 +85,7 @@ gdk start tail -f log/llm.log ``` -## Testing GitLab Duo Chat against real LLMs +## Testing GitLab Duo Chat against real LLMs locally Because success of answers to user questions in GitLab Duo Chat heavily depends on toolchain and prompts of each tool, it's common that even a minor change in a @@ -101,7 +101,7 @@ export ANTHROPIC_API_KEY='<key>' # can use dev value of Gitlab::CurrentSettings export VERTEX_AI_CREDENTIALS='<vertex-ai-credentials>' # can set as dev value of Gitlab::CurrentSettings.vertex_ai_credentials export VERTEX_AI_PROJECT='<vertex-project-name>' # can use dev value of Gitlab::CurrentSettings.vertex_ai_project -REAL_AI_REQUEST=1 bundle exec rspec ee/spec/lib/gitlab/llm/chain/agents/zero_shot/executor_real_requests_spec.rb +REAL_AI_REQUEST=1 bundle exec rspec ee/spec/lib/gitlab/llm/completions/chat_real_requests_spec.rb ``` When you need to update the test questions that require documentation embeddings, @@ -109,21 +109,96 @@ make sure a new fixture is generated and committed together with the change. ## Running the rspecs tagged with `real_ai_request` -The rspecs tagged with the metadata `real_ai_request` can be run in GitLab project's CI by triggering -`rspec-ee unit gitlab-duo-chat`. -The former runs with Vertex APIs enabled. The CI jobs are optional and allowed to fail to account for -the non-deterministic nature of LLM responses. +The following CI jobs for GitLab project run the rspecs tagged with `real_ai_request`: + +- `rspec-ee unit gitlab-duo-chat-zeroshot`: + the job runs `ee/spec/lib/gitlab/llm/completions/chat_real_requests_spec.rb`. + The job is optionally triggered and allowed to fail. + +- `rspec-ee unit gitlab-duo-chat-qa`: + The job runs the QA evaluation tests in + `ee/spec/lib/gitlab/llm/chain/agents/zero_shot/qa_evaluation_spec.rb`. + The job is optionally triggered and allowed to fail. + Read about [GitLab Duo Chat QA Evaluation Test](#gitlab-duo-chat-qa-evaluation-test). + +- `rspec-ee unit gitlab-duo-chat-qa-fast`: + The job runs a single QA evaluation test from `ee/spec/lib/gitlab/llm/chain/agents/zero_shot/qa_evaluation_spec.rb`. + The job is always run and not allowed to fail. Although there's a chance that the QA test still might fail, + it is cheap and fast to run and intended to prevent a regression in the QA test helpers. + +- `rspec-ee unit gitlab-duo pg14`: + This job runs tests to ensure that the GitLab Duo features are functional without running into system errors. + The job is always run and not allowed to fail. + This job does NOT conduct evaluations. The quality of the feature is tested in the other jobs such as QA jobs. ### Management of credentials and API keys for CI jobs All API keys required to run the rspecs should be [masked](../../ci/variables/index.md#mask-a-cicd-variable) The exception is GCP credentials as they contain characters that prevent them from being masked. -Because `rspec-ee unit gitlab-duo-chat` needs to run on MR branches, GCP credentials cannot be added as a protected variable +Because the CI jobs need to run on MR branches, GCP credentials cannot be added as a protected variable and must be added as a regular CI variable. For security, the GCP credentials and the associated project added to GitLab project's CI must not be able to access any production infrastructure and sandboxed. +### GitLab Duo Chat QA Evaluation Test + +Evaluation of a natural language generation (NLG) system such as +GitLab Duo Chat is a rapidly evolving area with many unanswered questions and ambiguities. + +A practical working assumption is LLMs can generate a reasonable answer when given a clear question and a context. +With the assumption, we are exploring using LLMs as evaluators +to determine the correctness of a sample of questions +to track the overall accuracy of GitLab Duo Chat's responses and detect regressions in the feature. + +For the discussions related to the topic, +see [the merge request](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/431) +and [the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/427251). + +The current QA evaluation test consists of the following components. + +#### Epic and issue fixtures + +The fixtures are the replicas of the _public_ issues and epics from projects and groups _owned by_ GitLab. +The internal notes were excluded when they were sampled. The fixtures have been commited into the canonical `gitlab` repository. +See [the snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/3613745) used to create the fixtures. + +#### RSpec and helpers + +1. [The RSpec file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/lib/gitlab/llm/chain/agents/zero_shot/qa_evaluation_spec.rb) + and the included helpers invoke the Chat service, an internal interface with the question. + +1. After collecting the Chat service's answer, + the answer is injected into a prompt, also known as an "evaluation prompt", that instructs + a LLM to grade the correctness of the answer based on the question and a context. + The context is simply a JSON serialization of the issue or epic being asked about in each question. + +1. The evaluation prompt is sent to two LLMs, Claude and Vertex. + +1. The evaluation responses of the LLMs are saved as JSON files. + +1. For each question, RSpec will regex-match for `CORRECT` or `INCORRECT`. + +#### Collection and tracking of QA evaluations via CI/CD automation + +The `gitlab` project's CI configurations have been setup to +run the RSpec, +collect the evaluation response as artifacts +and execute [a reporter script](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/duo_chat/reporter.rb) +that automates collection and tracking of evaluations. + +When `rspec-ee unit gitlab-duo-chat-qa` job runs in a pipeline for a merge request, +the reporter script uses the evaluations saved as CI artifacts +to generate a Markdown report and posts it as a note in the merge request. + +When `rspec-ee unit gitlab-duo-chat-qa` is run in a pipeline for a commit on `master` branch, +the reporter script instead +posts the generated report as an issue, +saves the evaluations artfacts as a snippet, +and updates the tracking issue in +[`gitlab-org/ai-powered/ai-framework/qa-evaluation#1`](https://gitlab.com/gitlab-org/ai-powered/ai-framework/qa-evaluation/-/issues/1) +in the project [`gitlab-org/ai-powered/ai-framework/qa-evaluation`](https://gitlab.com/gitlab-org/ai-powered/ai-framework/qa-evaluation). + ## GraphQL Subscription The GraphQL Subscription for Chat behaves slightly different because it's user-centric. A user could have Chat open on multiple browser tabs, or also on their IDE. @@ -134,3 +209,14 @@ We therefore need to broadcast messages to multiple clients to keep them in sync Note that we still broadcast chat messages and currently used tools using the `userId` and `resourceId` as identifier. However, this is deprecated and should no longer be used. We want to remove `resourceId` on the subscription as part of [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/420296). + +## Testing GitLab Duo Chat in production-like environments + +GitLab Duo Chat is enabled in the [Staging](https://staging.gitlab.com) and +[Staging Ref](https://staging-ref.gitlab.com/) GitLab environments. + +Because GitLab Duo Chat is currently only available to members of groups in the +Ultimate tier, Staging Ref may be an easier place to test changes as a GitLab +team member because +[you can make yourself an instance Admin in Staging Ref](https://about.gitlab.com/handbook/engineering/infrastructure/environments/staging-ref/#admin-access) +and, as an Admin, easily create licensed groups for testing. diff --git a/doc/development/ai_features/glossary.md b/doc/development/ai_features/glossary.md new file mode 100644 index 00000000000..be856639b83 --- /dev/null +++ b/doc/development/ai_features/glossary.md @@ -0,0 +1,81 @@ +--- +stage: AI-powered +group: AI Framework +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab Duo Glossary + +This is a list of terms that may have a general meaning but also may have a +specific meaning at GitLab. If you encounter a piece of technical jargon related +to AI that you think could benefit from being in this list, add it! + +- **AI Gateway**: standalone service used to give access to AI features to + non-SaaS GitLab users. This logic will be moved to Cloud Connector when that + service is ready. Eventually, the AI Gateway will be used to host endpoints that + proxy requests to AI providers, removing the need for the GitLab Rails monolith + to integrate and communicate directly with third-party LLMs. + [Blueprint](../../architecture/blueprints/ai_gateway/index.md). +- **Chat Evaluation**: automated mechanism for determining the helpfulness and + accuracy of GitLab Duo Chat to various user questions. The MVC is an RSpec test + run via GitLab CI that asks a set of questions to Chat and then has a + two different third-party LLMs determine if the generated answer is accurate or not. + [MVC](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134610). + [Design doc for next iteration](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136127). +- **Cloud Connector**: Today, Cloud Connector is not a system. It is an umbrella + term for all the projects we engage in that make existing SaaS-only features + available to self-managed and GitLab Dedicated customers. Today, the only + feature available through Cloud Connector is Code Suggestions. + Cloud Connector also refer to a planned GitLab-hosted edge service which would + act as a way for non-SaaS GitLab instances to access SaaS offerings. + [Cloud Connector MVC](../cloud_connector/code_suggestions_for_sm.md). + [Blueprint for future Cloud Connector service](../../architecture/blueprints/cloud_connector/index.md). +- **Consensus Filtering**: method for LLM evaluation where you instruct an LLM + to evaluate the output of another LLM based on the question and context that + resulted in the output. This is the method of evaluation being used for the Chat + Evaluation MVC. + [Issue from Model Validation team](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/prompt-library/-/issues/91#metric-2-consensus-filtering-with-llm-based-evaluation). +- **Context**: relevant information that surrounds a data point, an event, or a + piece of information, which helps to clarify its meaning and implications. + For GitLab Duo Chat, context is the attributes of the Issue or Epic being + referenced in a user question. +- **Golden Questions**: a small subset of the types of questions we think a user + should be able to ask GitLab Duo Chat. Used to generate data for Chat evaluation. + [Questions for Chat Beta](https://gitlab.com/groups/gitlab-org/-/epics/10550#what-the-user-can-ask). +- **Ground Truth**: data that is determined to be the true + output for a given input, representing the reality that the AI model aims to + learn and predict. Ground truth data is usually human-annotated. +- **Model Validation**: group within the AI-powered Stage working on the Prompt + Library and researching AI/ML models to support other use-cases for AI at GitLab. + [Team handbook section](https://about.gitlab.com/handbook/product/categories/features/#ai-poweredai-model-validation-group). +- **Prompt library**: The ["Prompt Library"](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/prompt-library) is a Python library that provides a CLI for testing different prompting techniques with LLMs. It enables data-driven improvements to LLM applications by facilitating hypothesis testing. Key features include the ability to manage and run dataflow pipelines using Apache Beam, and the execution of multiple evaluation experiments in a single pipeline run. + on prompts with various third-party AI Services. + [Code](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/prompt-library). +- **Prompt Registry**: stored, versioned prompts used to interact with third-party + AI Services. [Blueprint](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135872). +- **Prompt**: instructions sent to an LLM to perform certain tasks. [Prompt guidelines](prompts.md). +- **RAG Pipeline**: (Retrieval-Augmented Generation) is a mechanism used to take + an input (such as a user question) into a system, retrieve any relevant data + for that input, augment the input with additional context, and then + synthesize the information to generate a coherent, contextualy-relevant answer. + This design pattern is helpful in open-domain question answering with LLMs, + which is why we use this design pattern for answering questions to GitLab Duo Chat. +- **Similarity Score**: method to determine the likeness between answers produced by an LLM and the reference ground truth answers. + [Issue from Model Validation team](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/prompt-library/-/issues/91#metric-1-similarity-score-as-comparisons-for-llms). +- **Tool**: logic that performs a specific LLM-related task; each tool has a + description and its own prompt. [How to add a new tool](duo_chat.md#adding-a-new-tool). +- **Word-Level Metrics**: method for LLM evaluation that compares aspects of + text at the granularity of individual words. + [Issue from Model Validation team](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/prompt-library/-/issues/98#metric-3-word-level-metrics). +- **Zero-shot agent**: in the general world of AI, a learning model or system + that can perform tasks without having seen any examples of that task during + training. At GitLab, we use this term to refer specifically to a piece of our + code that serves as a sort of LLM-powered air traffic controller for GitLab Duo Chat. + The GitLab zero-shot agent has a system prompt that explains how an LLM should + interpret user input from GitLab Duo Chat as well as a list of tool descriptions. + Using this information, the agent determines which tool to use to answer a + user's question. The agent may decide that no tools are required and answer the + question directly. If a tool is used, the answer from the tool is fed back to + the zero-shot agent to evaluate if the answer is sufficient or if an additional + tool must be used to answer the question. + [Code](https://gitlab.com/gitlab-org/gitlab/-/blob/6b747cbd7c6a71145a8bfb8201db3c857b5aed6a/ee/lib/gitlab/llm/chain/agents/zero_shot/executor.rb). [Zero-shot agent in action](https://gitlab.com/gitlab-org/gitlab/-/issues/427979). diff --git a/doc/development/ai_features/index.md b/doc/development/ai_features/index.md index df1627f2dc3..e99a49f3bb9 100644 --- a/doc/development/ai_features/index.md +++ b/doc/development/ai_features/index.md @@ -1,7 +1,7 @@ --- stage: AI-powered group: AI Framework -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # AI features based on 3rd-party integrations @@ -37,7 +37,7 @@ Apply the following two feature flags to any AI feature work: - A general flag (`ai_global_switch`) that applies to all AI features. - A flag specific to that feature. The feature flag name [must be different](../feature_flags/index.md#feature-flags-for-licensed-features) than the licensed feature name. -See the [feature flag tracker](https://gitlab.com/gitlab-org/gitlab/-/issues/405161) for the list of all feature flags and how to use them. +See the [feature flag tracker epic](https://gitlab.com/groups/gitlab-org/-/epics/10524) for the list of all feature flags and how to use them. ## Implement a new AI action @@ -50,8 +50,14 @@ All AI features are experimental. ## Test AI features locally -NOTE: -Use [this snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/2554994) for help automating the following section. +**One-line setup** + +```shell +# Replace the <test-group-name> by the group name you want to enable GitLab Duo features. If the group doesn't exist, it creates a new one. +RAILS_ENV=development bundle exec rake gitlab:duo:setup['<test-group-name>'] +``` + +**Manual way** 1. Enable the required general feature flags: @@ -61,20 +67,18 @@ Use [this snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/2554994) for 1. Ensure you have followed [the process to obtain an EE license](https://about.gitlab.com/handbook/developer-onboarding/#working-on-gitlab-ee-developer-licenses) for your local instance 1. Simulate the GDK to [simulate SaaS](../ee_features.md#simulate-a-saas-instance) and ensure the group you want to test has an Ultimate license -1. Enable `Experimental features`: +1. Enable `Experiment & Beta features` 1. Go to the group with the Ultimate license 1. **Group Settings** > **General** -> **Permissions and group features** - 1. Enable **Experiment features** + 1. Enable **Experiment & Beta features** 1. Enable the specific feature flag for the feature you want to test +1. You can use Rake task `rake gitlab:duo:enable_feature_flags` to enable all feature flags that are assigned to group AI Framework 1. Set the required access token. To receive an access token: 1. For Vertex, follow the [instructions below](#configure-gcp-vertex-access). - 1. For all other providers, like Anthropic, create an access request where `@m_gill`, `@wayne`, and `@timzallmann` are the tech stack owners. + 1. For Anthropic, create an access request ### Set up the embedding database -NOTE: -Use [this snippet](https://gitlab.com/gitlab-org/gitlab/-/snippets/2554994) for help automating the following section. - For features that use the embedding database, additional setup is needed. 1. Enable [`pgvector`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/pgvector.md#enable-pgvector-in-the-gdk) in GDK @@ -87,19 +91,13 @@ For features that use the embedding database, additional setup is needed. 1. Run `gdk reconfigure` 1. Run database migrations to create the embedding database -### Setup for GitLab documentation chat (legacy chat) - -To populate the embedding database for GitLab chat: - -1. Open a rails console -1. Run [this script](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/10588#note_1373586079) to populate the embedding database - ### Configure GCP Vertex access -In order to obtain a GCP service key for local development, please follow the steps below: +In order to obtain a GCP service key for local development, follow the steps below: - Create a sandbox GCP project by visiting [this page](https://about.gitlab.com/handbook/infrastructure-standards/#individual-environment) and following the instructions, or by requesting access to our existing group GCP project by using [this template](https://gitlab.com/gitlab-com/it/infra/issue-tracker/-/issues/new?issuable_template=gcp_group_account_iam_update_request). - If you are using an individual GCP project, you may also need to enable the Vertex AI API: + 1. Visit [welcome page](https://console.cloud.google.com/welcome), choose your project (e.g. jdoe-5d23dpe). 1. Go to **APIs & Services > Enabled APIs & services**. 1. Select **+ Enable APIs and Services**. 1. Search for `Vertex AI API`. @@ -141,7 +139,7 @@ we can add a few selected embeddings to the table from a pre-generated fixture. For instance, to test that the question "How can I reset my password" is correctly retrieving the relevant embeddings and answered, we can extract the top N closet embeddings to the question into a fixture and only restore a small number of embeddings quickly. -To faciliate an extraction process, a Rake task been written. +To facilitate an extraction process, a Rake task has been written. You can add or remove the questions needed to be tested in the Rake task and run the task to generate a new fixture. ```shell @@ -277,65 +275,6 @@ I --> J[GraphqlTriggers.ai_completion_response] J --> K[::GitlabSchema.subscriptions.trigger] ``` -## CircuitBreaker - -The CircuitBreaker concern is a reusable module that you can include in any class that needs to run code with circuit breaker protection. The concern provides a `run_with_circuit` method that wraps a code block with circuit breaker functionality, which helps prevent cascading failures and improves system resilience. For more information about the circuit breaker pattern, see: - -- [What is Circuit breaker](https://martinfowler.com/bliki/CircuitBreaker.html). -- [The Hystrix documentation on CircuitBreaker](https://github.com/Netflix/Hystrix/wiki/How-it-Works#circuit-breaker). - -### Use CircuitBreaker - -To use the CircuitBreaker concern, you need to include it in a class. For example: - -```ruby -class MyService - include Gitlab::Llm::Concerns::CircuitBreaker - - def call_external_service - run_with_circuit do - # Code that interacts with external service goes here - - raise InternalServerError - end - end -end -``` - -The `call_external_service` method is an example method that interacts with an external service. -By wrapping the code that interacts with the external service with `run_with_circuit`, the method is executed within the circuit breaker. -The circuit breaker is created and configured by the `circuit` method, which is called automatically when the `CircuitBreaker` module is included. -The method should raise `InternalServerError` error which will be counted towards the error threshold if raised during the execution of the code block. - -The circuit breaker tracks the number of errors and the rate of requests, -and opens the circuit if it reaches the configured error threshold or volume threshold. -If the circuit is open, subsequent requests fail fast without executing the code block, and the circuit breaker periodically allows a small number of requests through to test the service's availability before closing the circuit again. - -### Configuration - -The circuit breaker is configured with two constants which control the number of errors and requests at which the circuit will open: - -- `ERROR_THRESHOLD` -- `VOLUME_THRESHOLD` - -You can adjust these values as needed for the specific service and usage pattern. -The `InternalServerError` is the exception class counted towards the error threshold if raised during the execution of the code block. -This is the exception class that triggers the circuit breaker when raised by the code that interacts with the external service. - -NOTE: -The `CircuitBreaker` module depends on the `Circuitbox` gem to provide the circuit breaker implementation. By default, the service name is inferred from the class name where the concern module is included. Override the `service_name` method if the name needs to be different. - -### Testing - -To test code that uses the `CircuitBreaker` concern, you can use `RSpec` shared examples and pass the `service` and `subject` variables: - -```ruby -it_behaves_like 'has circuit breaker' do - let(:service) { dummy_class.new } - let(:subject) { service.dummy_method } -end -``` - ## How to implement a new action ### Register a new method @@ -523,7 +462,7 @@ module Gitlab end def to_prompt - <<-PROMPT + <<~PROMPT You are an assistant that writes code for the following context: context: #{user_input} diff --git a/doc/development/ai_features/prompts.md b/doc/development/ai_features/prompts.md index f4738055f6b..b3a2462331b 100644 --- a/doc/development/ai_features/prompts.md +++ b/doc/development/ai_features/prompts.md @@ -1,7 +1,7 @@ --- stage: AI-powered group: AI Framework -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Working with AI prompts diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 318f9bed6d3..cfe82fe9b81 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -1,13 +1,27 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL API style guide This document outlines the style guide for the GitLab [GraphQL API](../api/graphql/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. + +To help us meet this vision, the frontend should use GraphQL in preference to +the REST API for new features. +The GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning). + +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. + ## How GitLab implements GraphQL <!-- vale gitlab.Spelling = NO --> @@ -44,7 +58,7 @@ For example, the one for [GitLab.com](https://gitlab.com/-/graphql-explorer). The GraphQL framework has some specific gotchas to be aware of, and domain expertise is required to ensure they are satisfied. -If you are asked to review a merge request that modifies any GraphQL files or adds an endpoint, please have a look at +If you are asked to review a merge request that modifies any GraphQL files or adds an endpoint, have a look at [our GraphQL review guide](graphql_guide/reviewing.md). ## Reading GraphQL logs @@ -78,7 +92,7 @@ a connection. ### Max complexity -Complexity is explained [on our client-facing API page](../api/graphql/index.md#max-query-complexity). +Complexity is explained [on our client-facing API page](../api/graphql/index.md#maximum-query-complexity). Fields default to adding `1` to a query's complexity score, but developers can [specify a custom complexity](#field-complexity) when defining a field. @@ -174,8 +188,8 @@ See the [deprecating schema items](#deprecating-schema-items) section for how to ### Breaking change exemptions -Schema items [marked as alpha](#mark-schema-items-as-alpha) are exempt from the deprecation process, -and can be removed or changed at any time without notice. +See the +[GraphQL API breaking change exemptions documentation](../api/graphql/index.md#breaking-change-exemptions). ## Global IDs @@ -190,6 +204,7 @@ See also: - [Exposing Global IDs](#exposing-global-ids). - [Mutation arguments](#object-identifier-arguments). - [Deprecating Global IDs](#deprecate-global-ids). +- [Customer-facing Global ID documentation](../api/graphql/index.md#global-ids). We have a custom scalar type (`Types::GlobalIDType`) which should be used as the type of input and output arguments when the value is a `GlobalID`. The benefits @@ -205,6 +220,35 @@ it is perfectly possible to parameterize this type with a concern or a supertype, if you want to accept a wider range of objects (such as `GlobalIDType[Issuable]` vs `GlobalIDType[Issue]`). +## Optimizations + +By default, GraphQL tends to introduce N+1 problems unless you actively try to minimize them. + +For stability and scalability, you must ensure that our queries do not suffer from N+1 +performance issues. + +The following are a list of tools to help you to optimize your GraphQL code: + +- [Look ahead](#look-ahead) allows you to preload data based on which fields are selected in the query. +- [Batch loading](graphql_guide/batchloader.md) allows you batch database queries together to be executed in one statement. +- [`BatchModelLoader`](graphql_guide/batchloader.md#the-batchmodelloader) is the recommended way to lookup + records by ID to leverage batch loading. +- [`before_connection_authorization`](#before_connection_authorization) allows you to address N+1 problems + specific to [type authorization](#authorization) permission checks. +- [Limit maximum field call count](#limit-maximum-field-call-count) allows you to restrict how many times + a field can return data where optimizations cannot be improved. + +## How to see N+1 problems in development + +N+1 problems can be discovered during development of a feature by: + +- Tailing `development.log` while you execute GraphQL queries that return collections of data. + [Bullet](../development/profiling.md#bullet) may help. +- Observing the [performance bar](../administration/monitoring/performance/performance_bar.md) if + executing queries in the GitLab UI. +- Adding a [request spec](#testing-tips-and-tricks) that asserts there are no (or limited) N+1 + problems with the feature. + ## Types We use a code-first schema, and we declare what type everything is in Ruby. @@ -447,7 +491,7 @@ field :tags, ### Field complexity The GitLab GraphQL API uses a _complexity_ score to limit performing overly complex queries. -Complexity is described in [our client documentation](../api/graphql/index.md#max-query-complexity) on the topic. +Complexity is described in [our client documentation](../api/graphql/index.md#maximum-query-complexity) on the topic. Complexity limits are defined in [`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb). @@ -806,9 +850,10 @@ The documentation mentions that the old Global ID style is now deprecated. You can mark GraphQL schema items (fields, arguments, enum values, and mutations) as [Alpha](../policy/experiment-beta-support.md#experiment). -An item marked as Alpha is [exempt from the deprecation process](#breaking-change-exemptions) and can be removed -at any time without notice. Mark an item as Alpha when it is -subject to change and not ready for public use. +An item marked as Alpha is +[exempt from the deprecation process](../api/graphql/index.md#breaking-change-exemptions) and can be +removed at any time without notice. Mark an item as Alpha when it is subject to +change and not ready for public use. NOTE: Only mark new items as Alpha. Never mark existing items @@ -833,8 +878,8 @@ mount_mutation Mutations::Ci::JobArtifact::BulkDestroy, alpha: { milestone: '15. Alpha GraphQL items is a custom GitLab feature that leverages GraphQL deprecations. An Alpha item appears as deprecated in the GraphQL schema. Like all deprecated schema items, you can test an -Alpha field in [GraphiQL](../api/graphql/index.md#graphiql). However, be aware that the GraphiQL -autocomplete editor doesn't suggest deprecated fields. +Alpha field in the [interactive GraphQL explorer](../api/graphql/index.md#interactive-graphql-explorer) (GraphiQL). +However, be aware that the GraphiQL autocomplete editor doesn't suggest deprecated fields. The item shows as Alpha in our generated GraphQL documentation and its GraphQL schema description. @@ -1091,7 +1136,7 @@ To find objects to display in a field, we can add resolvers to `app/graphql/resolvers`. Arguments can be defined in the resolver in the same way as in a mutation. -See the [Mutation arguments](#object-identifier-arguments) section. +See the [Arguments](#arguments) section. To limit the amount of queries performed, we can use [BatchLoader](graphql_guide/batchloader.md). @@ -1260,32 +1305,9 @@ field :jobs, resolver: JobsResolver, description: 'All jobs.' field :job, resolver: JobsResolver.single, description: 'A single job.' ``` -### Correct use of `Resolver#ready?` - -Resolvers have two public API methods as part of the framework: `#ready?(**args)` and `#resolve(**args)`. -We can use `#ready?` to perform set-up, validation or early-return without invoking `#resolve`. - -Good reasons to use `#ready?` include: +### Optimizing Resolvers -- validating mutually exclusive arguments (see [validating arguments](#validating-arguments)) -- Returning `Relation.none` if we know before-hand that no results are possible -- Performing setup such as initializing instance variables (although consider lazily initialized methods for this) - -Implementations of [`Resolver#ready?(**args)`](https://graphql-ruby.org/api-doc/1.10.9/GraphQL/Schema/Resolver#ready%3F-instance_method) should -return `(Boolean, early_return_data)` as follows: - -```ruby -def ready?(**args) - [false, 'have this instead'] -end -``` - -For this reason, whenever you call a resolver (mainly in tests - as framework -abstractions Resolvers should not be considered re-usable, finders are to be -preferred), remember to call the `ready?` method and check the boolean flag -before calling `resolve`! An example can be seen in our [`GraphqlHelpers`](https://gitlab.com/gitlab-org/gitlab/-/blob/2d395f32d2efbb713f7bc861f96147a2a67e92f2/spec/support/helpers/graphql_helpers.rb#L20-27). - -### Look-Ahead +#### Look-Ahead The full query is known in advance during execution, which means we can make use of [lookahead](https://graphql-ruby.org/queries/lookahead.html) to optimize our @@ -1368,6 +1390,54 @@ end For an example of real world use, see [`ResolvesMergeRequests`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/concerns/resolves_merge_requests.rb). +#### `before_connection_authorization` + +A `before_connection_authorization` hook can help resolvers eliminate N+1 problems that originate from +[type authorization](graphql_guide/authorization.md#type-authorization) permission checks. + +The `before_connection_authorization` method receives the resolved nodes and the current user. In +the block, use `ActiveRecord::Associations::Preloader` or a `Preloaders::` class to preload data +for the type authorization check. + +Example: + +```ruby +class LabelsResolver < BaseResolver + before_connection_authorization do |labels, current_user| + Preloaders::LabelsPreloader.new(labels, current_user).preload_all + end +end +``` + +#### BatchLoading + +See [GraphQL BatchLoader](graphql_guide/batchloader.md). + +### Correct use of `Resolver#ready?` + +Resolvers have two public API methods as part of the framework: `#ready?(**args)` and `#resolve(**args)`. +We can use `#ready?` to perform set-up, validation, or early-return without invoking `#resolve`. + +Good reasons to use `#ready?` include: + +- Validating mutually exclusive arguments. +- Returning `Relation.none` if we know before-hand that no results are possible. +- Performing setup such as initializing instance variables (although consider lazily initialized methods for this). + +Implementations of [`Resolver#ready?(**args)`](https://graphql-ruby.org/api-doc/1.10.9/GraphQL/Schema/Resolver#ready%3F-instance_method) should +return `(Boolean, early_return_data)` as follows: + +```ruby +def ready?(**args) + [false, 'have this instead'] +end +``` + +For this reason, whenever you call a resolver (mainly in tests because framework +abstractions Resolvers should not be considered re-usable, finders are to be +preferred), remember to call the `ready?` method and check the boolean flag +before calling `resolve`! An example can be seen in our [`GraphqlHelpers`](https://gitlab.com/gitlab-org/gitlab/-/blob/2d395f32d2efbb713f7bc861f96147a2a67e92f2/spec/support/helpers/graphql_helpers.rb#L20-27). + ### Negated arguments Negated filters can filter some resources (for example, find all issues that @@ -1555,85 +1625,6 @@ Examples: If you need advice for mutation naming, canvass the Slack `#graphql` channel for feedback. -### Arguments - -Arguments for a mutation are defined using `argument`. - -Example: - -```ruby -argument :my_arg, GraphQL::Types::String, - required: true, - description: "A description of the argument." -``` - -#### Nullability - -Arguments can be marked as `required: true` which means the value must be present and not `null`. -If a required argument's value can be `null`, use the `required: :nullable` declaration. - -Example: - -```ruby -argument :due_date, - Types::TimeType, - required: :nullable, - description: 'The desired due date for the issue. Due date is removed if null.' -``` - -In the above example, the `due_date` argument must be given, but unlike the GraphQL spec, the value can be `null`. -This allows 'unsetting' the due date in a single mutation rather than creating a new mutation for removing the due date. - -```ruby -{ due_date: null } # => OK -{ due_date: "2025-01-10" } # => OK -{ } # => invalid (not given) -``` - -#### Keywords - -Each GraphQL `argument` defined is passed to the `#resolve` method -of a mutation as keyword arguments. - -Example: - -```ruby -def resolve(my_arg:) - # Perform mutation ... -end -``` - -#### Input Types - -`graphql-ruby` wraps up arguments into an -[input type](https://graphql.org/learn/schema/#input-types). - -For example, the -[`mergeRequestSetDraft` mutation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/set_draft.rb) -defines these arguments (some -[through inheritance](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/base.rb)): - -```ruby -argument :project_path, GraphQL::Types::ID, - required: true, - description: "The project the merge request to mutate is in." - -argument :iid, GraphQL::Types::String, - required: true, - description: "The IID of the merge request to mutate." - -argument :draft, - GraphQL::Types::Boolean, - required: false, - description: <<~DESC - Whether or not to set the merge request as a draft. - DESC -``` - -These arguments automatically generate an input type called -`MergeRequestSetDraftInput` with the 3 arguments we specified and the -`clientMutationId`. - ### Object identifier arguments In keeping with the GitLab use of [Global IDs](#global-ids), mutation @@ -1947,36 +1938,110 @@ code so that we have a single source of truth and we do not trigger a subscripti For more information, see [GraphQL pagination](graphql_guide/pagination.md). -## Validating arguments +## Arguments -For validations of single arguments, use the -[`prepare` option](https://github.com/rmosolgo/graphql-ruby/blob/master/guides/fields/arguments.md) -as usual. +[Arguments](https://graphql-ruby.org/fields/arguments.html) for a resolver or mutation are defined using `argument`. -Sometimes a mutation or resolver may accept a number of optional -arguments, but we still want to validate that at least one of the optional -arguments is provided. In this situation, consider using the `#ready?` -method in your mutation or resolver to provide the validation. The -`#ready?` method is called before any work is done in the -`#resolve` method. +Example: + +```ruby +argument :my_arg, GraphQL::Types::String, + required: true, + description: "A description of the argument." +``` + +### Nullability + +Arguments can be marked as `required: true` which means the value must be present and not `null`. +If a required argument's value can be `null`, use the `required: :nullable` declaration. Example: ```ruby -def ready?(**args) - if args.values_at(:body, :position).compact.blank? - raise Gitlab::Graphql::Errors::ArgumentError, - 'body or position arguments are required' - end +argument :due_date, + Types::TimeType, + required: :nullable, + description: 'The desired due date for the issue. Due date is removed if null.' +``` - # Always remember to call `#super` - super +In the above example, the `due_date` argument must be given, but unlike the GraphQL spec, the value can be `null`. +This allows 'unsetting' the due date in a single mutation rather than creating a new mutation for removing the due date. + +```ruby +{ due_date: null } # => OK +{ due_date: "2025-01-10" } # => OK +{ } # => invalid (not given) +``` + +#### Nullability and required: false + +If an argument is marked `required: false` the client is permitted to send `null` as a value. +Often this is undesirable. + +If an argument is optional but `null` is not an allowed value, use validation to ensure that passing `null` returns an error: + +```ruby +argument :name, GraphQL::Types::String, + required: false, + validates: { allow_null: false } +``` + +Alternatively, if you wish to allow `null` when it is not an allowed value, you can replace it with a default value: + +```ruby +argument :name, GraphQL::Types::String, + required: false, + default_value: "No Name Provided", + replace_null_with_default: true +``` + +See [Validation](https://graphql-ruby.org/fields/validation.html), +[Nullability](https://graphql-ruby.org/fields/arguments.html#nullability) and +[Default Values](https://graphql-ruby.org/fields/arguments.html#default-values) for more details. + +### Keywords + +Each GraphQL `argument` defined is passed to the `#resolve` method +of a mutation as keyword arguments. + +Example: + +```ruby +def resolve(my_arg:) + # Perform mutation ... end ``` -In the future this may be able to be done using `OneOf Input Objects` if -[this RFC](https://github.com/graphql/graphql-spec/pull/825) -is merged. +### Input Types + +`graphql-ruby` wraps up arguments into an +[input type](https://graphql.org/learn/schema/#input-types). + +For example, the +[`mergeRequestSetDraft` mutation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/set_draft.rb) +defines these arguments (some +[through inheritance](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/base.rb)): + +```ruby +argument :project_path, GraphQL::Types::ID, + required: true, + description: "The project the merge request to mutate is in." + +argument :iid, GraphQL::Types::String, + required: true, + description: "The IID of the merge request to mutate." + +argument :draft, + GraphQL::Types::Boolean, + required: false, + description: <<~DESC + Whether or not to set the merge request as a draft. + DESC +``` + +These arguments automatically generate an input type called +`MergeRequestSetDraftInput` with the 3 arguments we specified and the +`clientMutationId`. ## GitLab custom scalars @@ -2063,7 +2128,7 @@ additional items: Integration tests can also verify the following items, because they invoke the full stack: -- An argument or scalar's [`prepare`](#validating-arguments) applies correctly. +- An argument or scalar's validations apply correctly. - Logic in a resolver or mutation's [`#ready?` method](#correct-use-of-resolverready) applies correctly. - An [argument's `default_value`](https://graphql-ruby.org/fields/arguments.html) applies correctly. - Objects resolve successfully, and there are no N+1 issues. @@ -2214,101 +2279,6 @@ end `spec/requests/api/graphql/ci/pipeline_spec.rb` regardless of the query being used to fetch the pipeline data. -- There can be possible cyclic dependencies in our GraphQL types. - See [Adding field with resolver on a Type causes "Can't determine the return type " error on a different Type](https://github.com/rmosolgo/graphql-ruby/issues/3974#issuecomment-1084444214) - and [Fix unresolved name due to cyclic definition](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84202/diffs#diff-content-32d14251082fd45412e1fdbf5820e62d157e70d2). - - In particular, this can happen with `connection_type`. Typically we might use the following in a resolver: - - ```ruby - type Types::IssueType.connection_type, null: true - ``` - - However this might cause a cyclic definition, which can result in errors like: - - ```ruby - NameError: uninitialized constant Resolvers::GroupIssuesResolver - - or - - GraphQL::Pagination::Connections::ImplementationMissingError - ``` - - though you might see something different. - - To fix this, we must create a new file that encapsulates the connection type, - and then reference it using double quotes. This gives a delayed resolution, - and the proper connection type. For example: - - [app/graphql/resolvers/base_issues_resolver.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/base_issues_resolver.rb) - originally contained the line - - ```ruby - type Types::IssueType.connection_type, null: true - ``` - - Running the specs locally for this file caused the - `NameError: uninitialized constant Resolvers::GroupIssuesResolver` error. - - The fix was to create a new file, [app/graphql/types/issue_connection.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/types/issue_connection.rb) with the - line: - - ```ruby - Types::IssueConnection = Types::IssueType.connection_type - ``` - - and in [app/graphql/resolvers/base_issues_resolver.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/base_issues_resolver.rb) - we use the line - - ```ruby - type "Types::IssueConnection", null: true - ``` - - Only use this style if you are having spec failures. We should not typically - use this pattern. This issue should disappear after we've upgraded to `2.x`. - -- There can be instances where a spec fails because the class is not loaded correctly. - It relates to the - [circular dependencies problem](https://github.com/rmosolgo/graphql-ruby/issues/1929) and - [Adding field with resolver on a Type causes "Can't determine the return type " error on a different Type](https://github.com/rmosolgo/graphql-ruby/issues/3974). - - Unfortunately, the errors generated don't really indicate what the problem is. For example, - remove the quotes from the `Rspec.describe` in - [ee/spec/graphql/resolvers/compliance_management/merge_requests/compliance_violation_resolver_spec.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/graphql/resolvers/compliance_management/merge_requests/compliance_violation_resolver_spec.rb). - Then run `rspec ee/spec/graphql/resolvers/compliance_management/merge_requests/compliance_violation_resolver_spec.rb`. - - This generates errors with the expectations. For example: - - ```ruby - 1) Resolvers::ComplianceManagement::MergeRequests::ComplianceViolationResolver#resolve user is authorized filtering the results when given an array of project IDs finds the filtered compliance violations - Failure/Error: expect(subject).to contain_exactly(compliance_violation) - - expected collection contained: [#<MergeRequests::ComplianceViolation id: 4, violating_user_id: 26, merge_request_id: 4, reason: "approved_by_committer", severity_level: "low">] - actual collection contained: [#<MergeRequests::ComplianceViolation id: 4, violating_user_id: 26, merge_request_id: 4, reason: "app...er_id: 27, merge_request_id: 5, reason: "approved_by_merge_request_author", severity_level: "high">] - the extra elements were: [#<MergeRequests::ComplianceViolation id: 5, violating_user_id: 27, merge_request_id: 5, reason: "approved_by_merge_request_author", severity_level: "high">] - # ./ee/spec/graphql/resolvers/compliance_management/merge_requests/compliance_violation_resolver_spec.rb:55:in `block (6 levels) in <top (required)>' - ``` - - However, this is not a case of the wrong result being generated, it's because of the loading order - of the `ComplianceViolationResolver` class. - - The only way we've found to fix this is by quoting the class name in the spec. For example, changing - - ```ruby - RSpec.describe Resolvers::ComplianceManagement::MergeRequests::ComplianceViolationResolver do - ``` - - into: - - ```ruby - RSpec.describe 'Resolvers::ComplianceManagement::MergeRequests::ComplianceViolationResolver' do - ``` - - See [this merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87295#note_946174036) for some discussion. - - Only use this style if you are having spec failures. We should not typically use this pattern. - This issue may disappear after we've upgraded to `2.x`. - - When testing resolvers using `GraphqlHelpers#resolve`, arguments for the resolver can be handled two ways. 1. 95% of the resolver specs use arguments that are Ruby objects, as opposed to when using the GraphQL API diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 45568c700c7..714115d474a 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # API style guide @@ -10,7 +10,7 @@ This style guide recommends best practices for API development. ## Instance variables -Please do not use instance variables, there is no need for them (we don't need +Don't use instance variables, there is no need for them (we don't need to access them as we do in Rails views), local variables are fine. ## Entities @@ -321,7 +321,7 @@ it's own file in the [`validators`](https://gitlab.com/gitlab-org/gitlab/-/blob/ ## Internal API -The [internal API](internal_api/index.md) is documented for internal use. Please keep it up to date so we know what endpoints +The [internal API](internal_api/index.md) is documented for internal use. Keep it up to date so we know what endpoints different components are making use of. ## Avoiding N+1 problems diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index 40d157a4411..d84614e0751 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Application limits development diff --git a/doc/development/application_secrets.md b/doc/development/application_secrets.md index 33bba2b3285..3217f0500f8 100644 --- a/doc/development/application_secrets.md +++ b/doc/development/application_secrets.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Application secrets @@ -46,4 +46,4 @@ GitLab.com environments prior to changing this file. ## Further iteration We may either deprecate or remove this automatic secret generation `01_secret_token.rb` in the future. -Please see [issue 222690](https://gitlab.com/gitlab-org/gitlab/-/issues/222690) for more information. +See [issue 222690](https://gitlab.com/gitlab-org/gitlab/-/issues/222690) for more information. diff --git a/doc/development/application_settings.md b/doc/development/application_settings.md new file mode 100644 index 00000000000..835fd782633 --- /dev/null +++ b/doc/development/application_settings.md @@ -0,0 +1,58 @@ +--- +stage: none +group: unassigned +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. +--- + +# Application settings development + +This document provides a development guide for contributors to add application +settings to GitLab. + +Application settings are stored in the `application_settings` table. Each setting has its own column and there should only be one row. + +## Add a new application setting + +First of all, you have to decide if it is necessary to add an application setting. +Consider our [configuration principles](https://about.gitlab.com/handbook/product/product-principles/#configuration-principles) when adding a new setting. + +To add a new setting, you have to: + +- Add a new column to the `application_settings` table. +- Add the new setting to the [list of visible attributes](https://gitlab.com/gitlab-org/gitlab/-/blob/6f33ad46ffeac454c6c9ce92d6ba328a72f062fd/app/helpers/application_settings_helper.rb#L215). +- Add the new setting to it to [`ApplicationSettingImplementation#defaults`](https://gitlab.com/gitlab-org/gitlab/-/blob/6f33ad46ffeac454c6c9ce92d6ba328a72f062fd/app/models/application_setting_implementation.rb#L36), if the setting has a default value. +- Add a [test for the default value](https://gitlab.com/gitlab-org/gitlab/-/blob/6f33ad46ffeac454c6c9ce92d6ba328a72f062fd/spec/models/application_setting_spec.rb#L20), if the setting has a default value. +- Add a validation for the new field to the [`ApplicationSetting` model](https://gitlab.com/gitlab-org/gitlab/-/blob/6f33ad46ffeac454c6c9ce92d6ba328a72f062fd/app/models/application_setting.rb). +- Add a [model test](https://gitlab.com/gitlab-org/gitlab/-/blob/6f33ad46ffeac454c6c9ce92d6ba328a72f062fd/spec/models/application_setting_spec.rb) for the validation and default value +- Find the [right view file](https://gitlab.com/gitlab-org/gitlab/-/tree/26ad8f4086c03283814bda50ff6e7043902cdbff/app/views/admin/application_settings) or create a new one and add a form field to the new setting. +- Update the [API documentation](https://gitlab.com/gitlab-org/gitlab/-/blob/6f33ad46ffeac454c6c9ce92d6ba328a72f062fd/doc/api/settings.md). Application settings will automatically be available on the REST API. + +### Database migration example + +```ruby +class AddNewSetting < Gitlab::Database::Migration[2.1] + disable_ddl_transaction! + + def up + with_lock_retries do + add_column :application_settings, :new_setting, :text, if_not_exists: true + end + + add_text_limit :application_settings, :new_setting, 255 + end + + def down + with_lock_retries do + remove_column :application_settings, :new_setting, if_exists: true + end + end +end +``` + +### Model validation example + +```ruby +validates :new_setting, + length: { maximum: 255, message: N_('is too long (maximum is %{count} characters)') }, + allow_blank: true +``` diff --git a/doc/development/application_slis/index.md b/doc/development/application_slis/index.md index 30bd6011a67..c5cdc6edc5a 100644 --- a/doc/development/application_slis/index.md +++ b/doc/development/application_slis/index.md @@ -1,7 +1,7 @@ --- stage: Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab Application Service Level Indicators (SLIs) @@ -179,7 +179,7 @@ In [this project](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/614) we are extending this so alerts for SLIs with a `feature_category` label in the source metrics can also be routed. -For any question, please don't hesitate to create an issue in +For any question, don't hesitate to create an issue in [the Scalability issue tracker](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues) or come find us in [#g_scalability](https://gitlab.slack.com/archives/CMMF8TKR9) on Slack. diff --git a/doc/development/application_slis/rails_request.md b/doc/development/application_slis/rails_request.md index e5a02c20472..2d18e2a8a15 100644 --- a/doc/development/application_slis/rails_request.md +++ b/doc/development/application_slis/rails_request.md @@ -1,7 +1,7 @@ --- stage: Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Rails request SLIs (service level indicators) @@ -126,7 +126,7 @@ a case-by-case basis. Take the following into account: view. We cannot scale up the fleet fast enough to accommodate for the incoming slow requests alongside the regular traffic. -When lowering the urgency for an existing endpoint, please involve a +When lowering the urgency for an existing endpoint, involve a [Scalability team member](https://about.gitlab.com/handbook/engineering/infrastructure/team/scalability/#team-members) in the review. We can use request rates and durations available in the logs to come up with a recommendation. You can pick a threshold @@ -172,7 +172,7 @@ information in the logs to check: the target duration we want to set. As decreasing a threshold too much could result in alerts for the -Apdex degradation, please also involve a Scalability team member in +Apdex degradation, also involve a Scalability team member in the merge request. ## How to adjust the urgency @@ -184,10 +184,10 @@ are available: | Urgency | Duration in seconds | Notes | |------------|---------------------|-----------------------------------------------| -| `:high` | 0.25s | | -| `:medium` | 0.5s | | -| `:default` | 1s | The default when nothing is specified. | -| `:low` | 5s | | +| `:high` | [0.25s](https://gitlab.com/gitlab-org/gitlab/-/blob/2f7a38fe48934b78f04233c4d2c81cde88a06da7/lib/gitlab/endpoint_attributes/config.rb#L8) | | +| `:medium` | [0.5s](https://gitlab.com/gitlab-org/gitlab/-/blob/2f7a38fe48934b78f04233c4d2c81cde88a06da7/lib/gitlab/endpoint_attributes/config.rb#L9) | | +| `:default` | [1s](https://gitlab.com/gitlab-org/gitlab/-/blob/2f7a38fe48934b78f04233c4d2c81cde88a06da7/lib/gitlab/endpoint_attributes/config.rb#L10) | The default when nothing is specified. | +| `:low` | [5s](https://gitlab.com/gitlab-org/gitlab/-/blob/2f7a38fe48934b78f04233c4d2c81cde88a06da7/lib/gitlab/endpoint_attributes/config.rb#L11) | | ### Rails controller diff --git a/doc/development/application_slis/sidekiq_execution.md b/doc/development/application_slis/sidekiq_execution.md index dfe7f3864d5..cc787978066 100644 --- a/doc/development/application_slis/sidekiq_execution.md +++ b/doc/development/application_slis/sidekiq_execution.md @@ -1,7 +1,7 @@ --- stage: Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sidekiq execution SLIs (service level indicators) diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 094853f5c42..2f6f93fc15b 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab architecture overview @@ -12,6 +12,7 @@ There are two software distributions of GitLab: - The open source [Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/) (CE). - The open core [Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/) (EE). + **Note:** The EE repository has been archived. GitLab now operates [under a single codebase](https://about.gitlab.com/blog/2019/08/23/a-single-codebase-for-gitlab-community-and-enterprise-edition/). GitLab is available under [different subscriptions](https://about.gitlab.com/pricing/). @@ -763,7 +764,7 @@ See our [Redis guidelines](redis.md) for more information about how GitLab uses - [Source](../administration/packages/container_registry.md#enable-the-container-registry) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/registry.md) - Layer: Core Service (Processor) -- GitLab.com: [GitLab Container Registry](../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) +- GitLab.com: [GitLab container registry](../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) The registry is what users use to store their own Docker images. The bundled registry uses NGINX as a load balancer and GitLab as an authentication manager. diff --git a/doc/development/audit_event_guide/index.md b/doc/development/audit_event_guide/index.md index aeab188fa76..28af4c3e0bb 100644 --- a/doc/development/audit_event_guide/index.md +++ b/doc/development/audit_event_guide/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Audit event development guidelines @@ -23,7 +23,7 @@ While any events could trigger an Audit Event, not all events should. In general - Are tracking information for product feature adoption. - Are covered in the direction page's discussion on [what is not planned](https://about.gitlab.com/direction/govern/compliance/audit-events/#what-is-not-planned-right-now). -If you have any questions, please reach out to `@gitlab-org/govern/compliance` to see if an Audit Event, or some other approach, may be best for your event. +If you have any questions, reach out to `@gitlab-org/govern/compliance` to see if an Audit Event, or some other approach, may be best for your event. ## Audit Event Schemas @@ -199,7 +199,7 @@ In addition to recording to the database, we also write these events to > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367847) in GitLab 15.4. -All new audit events must have a type definition stored in `config/audit_events/types/` that contains a single source of truth for every auditable event in GitLab. +All new audit events must have a type definition stored in `config/audit_events/types/` or `ee/config/audit_events/types/` that contains a single source of truth for every auditable event in GitLab. ### Add a new audit event type @@ -244,7 +244,7 @@ to check if the documentation is up-to-date. ## Event streaming All events where the entity is a `Group` or `Project` are recorded in the audit log, and also streamed to one or more -[event streaming destinations](../../administration/audit_event_streaming.md). When the entity is a: +[event streaming destinations](../../administration/audit_event_streaming/index.md). When the entity is a: - `Group`, events are streamed to the group's root ancestor's event streaming destinations. - `Project`, events are streamed to the project's root ancestor's event streaming destinations. diff --git a/doc/development/auto_devops.md b/doc/development/auto_devops.md index ccbad7f7314..d5a011e7e55 100644 --- a/doc/development/auto_devops.md +++ b/doc/development/auto_devops.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Auto DevOps development guidelines diff --git a/doc/development/avoiding_required_stops.md b/doc/development/avoiding_required_stops.md index d523a16a882..74db216a1f0 100644 --- a/doc/development/avoiding_required_stops.md +++ b/doc/development/avoiding_required_stops.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Avoiding required stops @@ -32,7 +32,7 @@ Wherever possible, a required stop should be avoided. If it can't be avoided, the required stop should be aligned to a _scheduled_ required stop. In cases where we are considering retroactively declaring an unplanned required stop, -please contact the [Distribution team product manager](https://about.gitlab.com/handbook/product/categories/#distributionbuild-group) to advise on next steps. If there +contact the [Distribution team product manager](https://about.gitlab.com/handbook/product/categories/#distributionbuild-group) to advise on next steps. If there is uncertainty about whether we should declare a required stop, the Distribution product manager may escalate to GitLab product leadership (VP or Chief Product Officer) to make a final determination. This may happen, for example, if a change might require a stop for diff --git a/doc/development/backend/create_source_code_be/gitaly_touch_points.md b/doc/development/backend/create_source_code_be/gitaly_touch_points.md index 98607c7f6c7..73e5708ca16 100644 --- a/doc/development/backend/create_source_code_be/gitaly_touch_points.md +++ b/doc/development/backend/create_source_code_be/gitaly_touch_points.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Source Code - Gitaly Touch Points diff --git a/doc/development/backend/create_source_code_be/index.md b/doc/development/backend/create_source_code_be/index.md index d894a14b006..3ae3c989966 100644 --- a/doc/development/backend/create_source_code_be/index.md +++ b/doc/development/backend/create_source_code_be/index.md @@ -1,25 +1,79 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- -# Create: Source Code backend +# Source Code Management -The Create: Source Code backend (BE) team focuses on the GitLab suite of Source Code Management -(SCM) tools. It is responsible for all backend aspects of the product categories +The Source Code Management team is responsible for all backend aspects of the product categories that fall under the [Source Code group](https://about.gitlab.com/handbook/product/categories/#source-code-group) of the [Create stage](https://about.gitlab.com/handbook/product/categories/#create-stage) of the [DevOps lifecycle](https://about.gitlab.com/handbook/product/categories/#devops-stages). -We interface with the Gitaly and Code Review teams, and work closely with the -[Create: Source Code frontend team](https://about.gitlab.com/handbook/engineering/development/dev/create/create-source-code-fe/). The features -we work with are listed on the +The Source Code Management team interfaces with the Gitaly and Code Review teams and works across three codebases: Workhorse, GitLab Shell and GitLab Rails. + +## Source Code Features Reference + +Features owned by the Source Code Management group are listed on the [Features by Group Page](https://about.gitlab.com/handbook/product/categories/features/#createsource-code-group). -The team works across three codebases: Workhorse, GitLab Shell and GitLab Rails. +### Code Owners + +Source Code Management shares ownership of Code Owners with the Code Review group. + +- [Feature homepage](../../../user/project/codeowners/index.md) +- [Developer Reference](../../code_owners/index.md) + +### Approval Rules + +- [Approval Rules](../../merge_request_concepts/approval_rules.md) + +### Push Rules + +- [Push Rules development guidelines](../../push_rules/index.md) + +### Protected Branches + +Details about Protected Branches models can be found in the [Code Owners](../../code_owners/index.md#related-models) technical reference page. + +### Repositories + +- [Project Repository Storage Moves](../../repository_storage_moves/index.md) + +### Project Templates + +- [Custom group-level project templates development guidelines](../../project_templates/index.md) + +### Git LFS + +- [Git LFS Development guidelines](../../lfs.md) + +## Technical Stack -## Workhorse +## GitLab Rails + +### Gitaly touch points + +[Gitaly](../../../administration/gitaly/index.md) provides high-level RPC access to Git repositories. +It is present in every GitLab installation and coordinates Git repository storage and retrieval. +Gitaly implements a client-server architecture with Gitaly as the server and Gitaly clients, also +known as _Gitaly consumers_, including: + +- GitLab Rails +- GitLab Shell +- GitLab Workhorse + +Gitaly Rails provides API endpoints that are counterparts of Gitaly RPCs. For more information, read [Gitaly touch points](gitaly_touch_points.md). + +### Annotated Rails Source Code + +The `:source_code_management` annotation indicates which code belongs to the Source Code Management +group in the Rails codebase. The annotated objects are presented on +[this page](https://gitlab-com.gitlab.io/gl-infra/platform/stage-groups-index/source-code.html) along +with the [Error Budgets dashboards](https://dashboards.gitlab.net/d/stage-groups-source_code/stage-groups3a-source-code3a-group-dashboard?orgId=1). + +## GitLab Workhorse [GitLab Workhorse](../../workhorse/index.md) is a smart reverse proxy for GitLab. It handles "large" HTTP requests such as file downloads, file uploads, `git push`, `git pull` and `git` archive downloads. @@ -34,18 +88,3 @@ For more information, refer to the [GitLab Shell documentation](../../gitlab_she To learn about the reasoning behind our creation of `gitlab-sshd`, read the blog post [Why we implemented our own SSHD solution](https://about.gitlab.com/blog/2022/08/17/why-we-have-implemented-our-own-sshd-solution-on-gitlab-sass/). - -## GitLab Rails - -### Gitaly touch points - -Gitaly is a Go RPC service which handles all the `git` calls made by GitLab. -GitLab is not exposed directly, and all traffic comes through Create: Source Code. -For more information, read [Gitaly touch points](gitaly_touch_points.md). - -### Source Code REST API Endpoints - -Create: Source Code has over 100 REST endpoints, being a mixture of Grape API endpoints and Rails controller endpoints. -For a detailed list, refer to [Source Code REST Endpoints](rest_endpoints.md). - -An alternative list of the [Source Code endpoints and other owned objects](https://gitlab-com.gitlab.io/gl-infra/platform/stage-groups-index/source-code.html) is available. diff --git a/doc/development/backend/create_source_code_be/rest_endpoints.md b/doc/development/backend/create_source_code_be/rest_endpoints.md index 2130d76d014..ccbb11288d5 100644 --- a/doc/development/backend/create_source_code_be/rest_endpoints.md +++ b/doc/development/backend/create_source_code_be/rest_endpoints.md @@ -1,112 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'index.md' +remove_date: '2024-03-13' --- -# Source Code REST endpoints +This document was moved to [another location](index.md). -The Create :: Source Code team maintains these endpoints: - -| Endpoint | Threshold | Source | -| -----------------------------------------------------------------------------------|---------------------------------------|--------------------------------------------------------------------------------------| -| `DELETE /api/:version/projects/:id/protected_branches/:name` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/protected_branches.rb) | -| `GET /api/:version/internal/authorized_keys` | `:high` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/internal/base.rb) | | | -| `GET /api/:version/internal/lfs` | `:high` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/internal/lfs.rb)| -| `GET /api/:version/projects/:id/approval_rules` | `:low` | | -| `GET /api/:version/projects/:id/approval_settings` | default | | -| `GET /api/:version/projects/:id/approvals` | default | | -| `GET /api/:version/projects/:id/forks` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/projects.rb) | -| `GET /api/:version/projects/:id/groups` | default | [source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/projects.rb) | -| `GET /api/:version/projects/:id/languages` | `:medium` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/projects.rb) | -| `GET /api/:version/projects/:id/merge_request_approval_setting` | `:medium` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/api/merge_request_approval_settings.rb) | -| `GET /api/:version/projects/:id/merge_requests/:merge_request_iid/approval_rules` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/api/merge_request_approval_rules.rb) | -| `GET /api/:version/projects/:id/merge_requests/:merge_request_iid/approval_settings` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/api/project_approval_settings.rb) | -| `GET /api/:version/projects/:id/merge_requests/:merge_request_iid/approval_state` | `:low` | [source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/merge_request_approvals.rb) | -| `GET /api/:version/projects/:id/merge_requests/:merge_request_iid/approvals` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/merge_request_approvals.rb) | -| `GET /api/:version/projects/:id/protected_branches` | default |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/protected_branches.rb) | -| `GET /api/:version/projects/:id/protected_branches/:name` | default |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/protected_branches.rb) | -| `GET /api/:version/projects/:id/protected_tags` | default | | -| `GET /api/:version/projects/:id/protected_tags/:name` | default | | -| `GET /api/:version/projects/:id/push_rule` | default | | -| `GET /api/:version/projects/:id/remote_mirrors` | default | | -| `GET /api/:version/projects/:id/repository/archive` | default | | -| `GET /api/:version/projects/:id/repository/blobs/:sha` | default | | -| `GET /api/:version/projects/:id/repository/blobs/:sha/raw` | default | | -| `GET /api/:version/projects/:id/repository/branches` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/branches.rb) | -| `GET /api/:version/projects/:id/repository/branches/:branch` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/branches.rb) | -| `GET /api/:version/projects/:id/repository/commits` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/commits.rb)| -| `GET /api/:version/projects/:id/repository/commits/:sha` | default | [source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/commits.rb) | -| `GET /api/:version/projects/:id/repository/commits/:sha/comments` | default | [source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/commits.rb) | -| `GET /api/:version/projects/:id/repository/commits/:sha/diff` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/commits.rb) | -| `GET /api/:version/projects/:id/repository/commits/:sha/merge_requests` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/commits.rb)| -| `GET /api/:version/projects/:id/repository/commits/:sha/refs` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/commits.rb) | -| `GET /api/:version/projects/:id/repository/compare` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/repositories.rb) | -| `GET /api/:version/projects/:id/repository/contributors` | default | | -| `GET /api/:version/projects/:id/repository/files/:file_path` | default | | -| `GET /api/:version/projects/:id/repository/files/:file_path/raw` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/files.rb) | -| `GET /api/:version/projects/:id/repository/tags` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/tags.rb) | -| `GET /api/:version/projects/:id/repository/tree` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/repositories.rb) | -| `GET /api/:version/projects/:id/statistics` | default | | -| `GraphqlController#execute` | default | | -| `HEAD /api/:version/projects/:id/repository/files/:file_path` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/files.rb) | -| `HEAD /api/:version/projects/:id/repository/files/:file_path/raw` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/files.rb) | -| `POST /api/:version/internal/allowed` | default | [source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/internal/base.rb) | -| `POST /api/:version/internal/lfs_authenticate` | `:high` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/internal/base.rb) | -| `POST /api/:version/internal/post_receive` | default | [source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/internal/base.rb) | -| `POST /api/:version/internal/pre_receive` | `:high` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/internal/base.rb) | -| `POST /api/:version/projects/:id/approvals` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/api/project_approvals.rb) | -| `POST /api/:version/projects/:id/merge_requests/:merge_request_iid/approvals` | `:low` | [source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/merge_request_approvals.rb) | -| `POST /api/:version/projects/:id/merge_requests/:merge_request_iid/approve` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/merge_request_approvals.rb) | -| `POST /api/:version/projects/:id/merge_requests/:merge_request_iid/unapprove` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/merge_request_approvals.rb)| -| `POST /api/:version/projects/:id/protected_branches` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/protected_branches.rb)| -| `POST /api/:version/projects/:id/repository/commits` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/commits.rb)| -| `POST /api/:version/projects/:id/repository/files/:file_path` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/files.rb) | -| `PUT /api/:version/projects/:id/push_rule` | default | | -| `PUT /api/:version/projects/:id/repository/files/:file_path` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/files.rb) | -| `Projects::BlameController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/blame_controller.rb) | -| `Projects::BlobController#create` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/blob_controller.rb) | -| `Projects::BlobController#diff` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/blob_controller.rb) | -| `Projects::BlobController#edit` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/blob_controller.rb) | -| `Projects::BlobController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/blob_controller.rb) | -| `Projects::BlobController#update` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/blob_controller.rb) | -| `Projects::BranchesController#create` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/branches_controller.rb) | -| `Projects::BranchesController#destroy` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/branches_controller.rb) | -| `Projects::BranchesController#diverging_commit_counts` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/branches_controller.rb) | -| `Projects::BranchesController#index` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/branches_controller.rb) | -| `Projects::BranchesController#new` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/branches_controller.rb) | -| `Projects::CommitController#branches` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/commit_controller.rb) | -| `Projects::CommitController#merge_requests` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/commit_controller.rb) | -| `Projects::CommitController#pipelines` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/commit_controller.rb) | -| `Projects::CommitController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/commit_controller.rb) | -| `Projects::CommitsController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/commits_controller.rb)| -| `Projects::CommitsController#signatures` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/commits_controller.rb) | -| `Projects::CompareController#create` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/commits_controller.rb) | -| `Projects::CompareController#index` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/compare_controller.rb) | -| `Projects::CompareController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/compare_controller.rb) | -| `Projects::CompareController#signatures` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/compare_controller.rb) | -| `Projects::FindFileController#list` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/find_file_controller.rb) | -| `Projects::FindFileController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/find_file_controller.rb) | -| `Projects::ForksController#index` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/forks_controller.rb) | -| `Projects::GraphsController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/graphs_controller.rb) | -| `Projects::NetworkController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/network_controller.rb) | -| `Projects::PathLocksController#index` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/controllers/projects/path_locks_controller.rb) | -| `Projects::RawController#show` | default | | -| `Projects::RefsController#logs_tree` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/refs_controller.rb) | -| `Projects::RefsController#switch` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/refs_controller.rb) | -| `Projects::RepositoriesController#archive` | default | | -| `Projects::Settings::RepositoryController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/settings/repository_controller.rb) | -| `Projects::TagsController#index` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/tags_controller.rb) | -| `Projects::TagsController#new` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/tags_controller.rb) | -| `Projects::TagsController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/tags_controller.rb) | -| `Projects::TemplatesController#names` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/templates_controller.rb) | -| `Projects::TreeController#show` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/tree_controller.rb) | -| `ProjectsController#refs` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects_controller.rb) | -| `Repositories::GitHttpController#git_receive_pack` | default | | -| `Repositories::GitHttpController#git_upload_pack` | default | | -| `Repositories::GitHttpController#info_refs` | default | | -| `Repositories::LfsApiController#batch` | `:medium` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/repositories/lfs_api_controller.rb) | -| `Repositories::LfsLocksApiController#verify` | default | | -| `Repositories::LfsStorageController#download` | `:medium` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/repositories/lfs_storage_controller.rb) | -| `Repositories::LfsStorageController#upload_authorize` | `:medium` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/repositories/lfs_storage_controller.rb) | -| `Repositories::LfsStorageController#upload_finalize` | `:low` |[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/repositories/lfs_storage_controller.rb) | +<!-- This redirect file can be deleted after <2024-03-13>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/backend/ruby_style_guide.md b/doc/development/backend/ruby_style_guide.md index 384d8122ccf..73c4d8719a0 100644 --- a/doc/development/backend/ruby_style_guide.md +++ b/doc/development/backend/ruby_style_guide.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Ruby style guide diff --git a/doc/development/bitbucket_cloud_importer.md b/doc/development/bitbucket_cloud_importer.md index 8a59743a243..98620ca39eb 100644 --- a/doc/development/bitbucket_cloud_importer.md +++ b/doc/development/bitbucket_cloud_importer.md @@ -1,16 +1,11 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Bitbucket Cloud importer developer documentation -The Bitbucket Cloud importer can be configured with the `bitbucket_parallel_importer` feature flag. When the feature flag is: - -- Enabled, the importer uses Sidekiq to schedule work asynchronously. -- Disabled, the importer does all the work in a single thread. - ## Prerequisites You must be authenticated with Bitbucket: diff --git a/doc/development/bitbucket_server_importer.md b/doc/development/bitbucket_server_importer.md new file mode 100644 index 00000000000..3a1f5a4febd --- /dev/null +++ b/doc/development/bitbucket_server_importer.md @@ -0,0 +1,84 @@ +--- +stage: none +group: unassigned +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. +--- + +# Bitbucket Server importer developer documentation + +## Prerequisites + +To test imports, you need a Bitbucket Server instance running locally. For information on running a local instance, see +[these instructions](https://gitlab.com/gitlab-org/manage/import-and-integrate/team/-/blob/main/integrations/bitbucket_server.md). + +## Code structure + +The importer's codebase is broken up into the following directories: + +- `lib/gitlab/bitbucket_server_import`: this directory contains most of the code such as + the classes used for importing resources. +- `app/workers/gitlab/bitbucket_server_import`: this directory contains the Sidekiq + workers. + +## How imports advance + +When a Bitbucket Server project is imported, work is divided into separate stages, with +each stage consisting of a set of Sidekiq jobs that are executed. + +Between every stage, a job called `Gitlab::BitbucketServerImport::AdvanceStageWorker` +is scheduled that periodically checks if all work of the current stage is completed. If +all the work is complete, the job advances the import process to the next stage. + +## Stages + +### 1. Stage::ImportRepositoryWorker + +This worker imports the repository and schedules the next stage when +done. + +### 2. Stage::ImportPullRequestsWorker + +This worker imports all pull requests. For every pull request, a job for the +`Gitlab::BitbucketImport::ImportPullRequestWorker` worker is scheduled. + +Bitbucket Server keeps tracks of references for open pull requests in +`refs/heads/pull-requests`, but closed and merged requests get moved +into hidden internal refs under `stash-refs/pull-requests`. + +As a result, they are not fetched by default. To prevent merge requests from not having +commits and therefore having empty diffs, we fetch affected source and target +commits from the server before importing the pull request. +We save the fetched commits as refs so that Git doesn't remove them, which can happen +if they are unused. +Source commits are saved as `#{commit}:refs/merge-requests/#{pull_request.iid}/head` +and target commits are saved as `#{commit}:refs/keep-around/#{commit}`. + +When creating a pull request, we need to match Bitbucket users with GitLab users for +the author and reviewers. Whenever a matching user is found, the GitLab user ID is cached +for 24 hours so that it doesn't have to be searched for again. + +### 3. Stage::ImportNotesWorker + +This worker imports notes (comments) for all merge requests. + +For every merge request, a job for the `Gitlab::BitbucketServerImport::ImportPullRequestNotesWorker` +worker is scheduled which imports all standalone comments, inline comments, merge events, and +approved events for the merge request. + +### 4. Stage::ImportLfsObjectsWorker + +Imports LFS objects from the source project by scheduling a +`Gitlab::BitbucketServerImport::ImportLfsObjectsWorker` job for every LFS object. + +### 5. Stage::FinishImportWorker + +This worker completes the import process by performing some housekeeping +such as marking the import as completed. + +## Pull request mentions + +Pull request descriptions and notes can contain @mentions to users. If a user with the +same email does not exist on GitLab, this can lead to incorrect users being tagged. + +To get around this, we build a cache containing all users who have access to the Bitbucket +project and then convert mentions in pull request descriptions and notes. diff --git a/doc/development/build_test_package.md b/doc/development/build_test_package.md index bc8cebed3fc..336baab51c6 100644 --- a/doc/development/build_test_package.md +++ b/doc/development/build_test_package.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Building a package for testing diff --git a/doc/development/bulk_import.md b/doc/development/bulk_import.md index 502bee97c9c..6c0bed8e204 100644 --- a/doc/development/bulk_import.md +++ b/doc/development/bulk_import.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Group migration by direct transfer diff --git a/doc/development/cached_queries.md b/doc/development/cached_queries.md index 4696f05873c..f2f4593bfc1 100644 --- a/doc/development/cached_queries.md +++ b/doc/development/cached_queries.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Cached queries guidelines diff --git a/doc/development/caching.md b/doc/development/caching.md index c3385c8499d..9a02c795bbe 100644 --- a/doc/development/caching.md +++ b/doc/development/caching.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Caching guidelines diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md index 74695f03451..11387d6cfb6 100644 --- a/doc/development/cascading_settings.md +++ b/doc/development/cascading_settings.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Cascading Settings diff --git a/doc/development/cells/index.md b/doc/development/cells/index.md index 1ab88e0d8c6..cd222e7b209 100644 --- a/doc/development/cells/index.md +++ b/doc/development/cells/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab Cells Development Guidelines diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 486808f25e7..f2ba1aa13a9 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Changelog entries diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md index 196ec14bffa..0a11e76e8d9 100644 --- a/doc/development/chaos_endpoints.md +++ b/doc/development/chaos_endpoints.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Generating chaos in a test GitLab instance diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md index 002470f7325..e283c1a0987 100644 --- a/doc/development/chatops_on_gitlabcom.md +++ b/doc/development/chatops_on_gitlabcom.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # ChatOps on GitLab.com diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md index e358b24c60f..ccd952f586c 100644 --- a/doc/development/cicd/cicd_reference_documentation_guide.md +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Documenting the `.gitlab-ci.yml` keywords diff --git a/doc/development/cicd/cicd_tables.md b/doc/development/cicd/cicd_tables.md index 8cfb0faca00..465597ca455 100644 --- a/doc/development/cicd/cicd_tables.md +++ b/doc/development/cicd/cicd_tables.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Add new tables to the CI database diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 41ae4fe14b4..18781f9315a 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -1,15 +1,14 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, concepts, howto +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # CI/CD development guidelines Development guides that are specific to CI/CD are listed here: -- If you are creating new CI/CD templates, please read [the development guide for GitLab CI/CD templates](templates.md). +- If you are creating new CI/CD templates, read [the development guide for GitLab CI/CD templates](templates.md). - If you are adding a new keyword or changing the CI schema, check the [CI schema guide](schema.md) See the [CI/CD YAML reference documentation guide](cicd_reference_documentation_guide.md) diff --git a/doc/development/cicd/pipeline_wizard.md b/doc/development/cicd/pipeline_wizard.md index f322ec2e2bf..0c0c0f3cc45 100644 --- a/doc/development/cicd/pipeline_wizard.md +++ b/doc/development/cicd/pipeline_wizard.md @@ -1,7 +1,7 @@ --- stage: none group: Incubation Engineering -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Pipeline Wizard @@ -133,8 +133,7 @@ is planned to add the ability to create a MR from here. should be committed to - `default-branch` (required): The branch that will be pre-selected during the commit step. This can be changed by the user. -- `default-filename` (optional, default: `.gitlab-ci.yml`): The Filename - to be used for the file. This can be overridden in the template file. +- `default-filename` (optional, default: `.gitlab-ci.yml`): The file name to be used for the file. This can be overridden in the template file. ### Events diff --git a/doc/development/cicd/schema.md b/doc/development/cicd/schema.md index 26e63fb53d8..e9a0b93b5f3 100644 --- a/doc/development/cicd/schema.md +++ b/doc/development/cicd/schema.md @@ -1,8 +1,7 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, howto +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Contribute to the CI/CD Schema diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index f977a70ac05..a2b490b9106 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -1,12 +1,22 @@ --- stage: Verify group: Pipeline Authoring -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, concepts, howto +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Development guide for GitLab CI/CD templates +NOTE: +With the introduction of the [CI/CD Catalog](../../ci/components/index.md#cicd-catalog), +GitLab is no longer accepting contributions of new CI/CD templates to the codebase. Instead, +we encourage team members to create [CI/CD components](../../ci/components/index.md) +for the catalog. This transition enhances the modularity and maintainability of our +shared CI/CD resources, and avoids the complexities of contributing new CI/CD templates. +If you need to update an existing template, you must also update the matching CI/CD component. +If no component exists that matches the CI/CD template yet, consider creating the matching component. +This ensures that template and component functionality remain in sync, aligning with +our new development practices. + This document explains how to develop [GitLab CI/CD templates](../../ci/examples/index.md#cicd-templates). ## Requirements for CI/CD templates @@ -285,7 +295,7 @@ the user's `.gitlab-ci.yml` immediately causes a lint error because there are no such jobs named `performance` in the included template anymore. Therefore, users have to fix their `.gitlab-ci.yml` that could annoy their workflow. -Please read [versioning](#versioning) section for introducing breaking change safely. +Read [versioning](#versioning) section for introducing breaking change safely. ## Versioning @@ -378,7 +388,7 @@ Each CI/CD template must be tested to make sure that it's safe to be published. ### Manual QA It's always good practice to test the template in a minimal demo project. -To do so, please follow the following steps: +To do so, follow the following steps: 1. Create a public sample project on <https://gitlab.com>. 1. Add a `.gitlab-ci.yml` to the project with the proposed template. @@ -482,6 +492,6 @@ If you're unsure if it's secure or not, you must ask security experts for cross- After your CI/CD template MR is created and labeled with `ci::templates`, DangerBot suggests one reviewer and one maintainer that can review your code. When your merge -request is ready for review, please [mention](../../user/discussions/index.md#mentions) +request is ready for review, [mention](../../user/discussions/index.md#mentions) the reviewer and ask them to review your CI/CD template changes. See details in the merge request that added [a DangerBot task for CI/CD template MRs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44688). diff --git a/doc/development/cloud_connector/code_suggestions_for_sm.md b/doc/development/cloud_connector/code_suggestions_for_sm.md index bd8a39bc0d6..6393eca815c 100644 --- a/doc/development/cloud_connector/code_suggestions_for_sm.md +++ b/doc/development/cloud_connector/code_suggestions_for_sm.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Cloud Connector MVC: Code Suggestions for Self-Managed/GitLab Dedicated diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md index 306f371f306..51643f3e7ed 100644 --- a/doc/development/code_comments.md +++ b/doc/development/code_comments.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Code comments Whenever you add comment to the code that is expected to be addressed at any time -in future, please create a technical debt issue for it. Then put a link to it +in future, create a technical debt issue for it. Then put a link to it to the code comment you've created. This allows other developers to quickly check if a comment is still relevant and what needs to be done to address it. diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index 2034f57d995..945916d8fcd 100644 --- a/doc/development/code_intelligence/index.md +++ b/doc/development/code_intelligence/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Code intelligence development guidelines diff --git a/doc/development/code_owners/index.md b/doc/development/code_owners/index.md index d962a36b497..45c632d5adc 100644 --- a/doc/development/code_owners/index.md +++ b/doc/development/code_owners/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Code Owners development guidelines diff --git a/doc/development/code_review.md b/doc/development/code_review.md index c2f2a7643ae..84d2537d058 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Code Review Guidelines @@ -179,7 +179,7 @@ by a reviewer before passing it to a maintainer as described in the | `~UX` user-facing changes <sup>3</sup> | [Product Designer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_reviewers_UX). Refer to the [design and user interface guidelines](contributing/design.md) for details. | | Adding a new JavaScript library <sup>1</sup> | - [Frontend foundations member](https://about.gitlab.com/direction/manage/foundations/) if the library significantly increases the [bundle size](https://gitlab.com/gitlab-org/frontend/playground/webpack-memory-metrics/-/blob/master/doc/report.md).<br/>- A [legal department member](https://about.gitlab.com/handbook/legal/) if the license used by the new library hasn't been approved for use in GitLab.<br/><br/>More information about license compatibility can be found in our [GitLab Licensing and Compatibility documentation](licensing.md). | | A new dependency or a file system change | - [Distribution team member](https://about.gitlab.com/company/team/). See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/systems/distribution/#how-to-work-with-distribution) for more details.<br/>- For RubyGems, request an [AppSec review](gemfile.md#request-an-appsec-review). | -| `~documentation` or `~UI text` changes | [Technical writer](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) based on assignments in the appropriate [DevOps stage group](https://about.gitlab.com/handbook/product/categories/#devops-stages). | +| `~documentation` or `~UI text` changes | [Technical writer](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments) based on assignments in the appropriate [DevOps stage group](https://about.gitlab.com/handbook/product/categories/#devops-stages). | | Changes to development guidelines | Follow the [review process](development_processes.md#development-guidelines-review) and get the approvals accordingly. | | End-to-end **and** non-end-to-end changes <sup>4</sup> | [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors). | | Only End-to-end changes <sup>4</sup> **or** if the MR author is a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors) | [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa). | @@ -187,7 +187,8 @@ by a reviewer before passing it to a maintainer as described in the | Analytics Instrumentation (telemetry or analytics) changes | [Analytics Instrumentation engineer](https://gitlab.com/gitlab-org/analytics-section/analytics-instrumentation/engineers). | | An addition of, or changes to a [Feature spec](testing_guide/testing_levels.md#frontend-feature-tests) | [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa) or [Quality reviewer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_reviewers_qa). | | A new service to GitLab (Puma, Sidekiq, Gitaly are examples) | [Product manager](https://about.gitlab.com/company/team/). See the [process for adding a service component to GitLab](adding_service_component.md) for details. | -| Changes related to authentication or authorization | [Manage:Authentication and Authorization team member](https://about.gitlab.com/company/team/). Check the [code review section on the group page](https://about.gitlab.com/handbook/engineering/development/dev/manage/authentication-and-authorization/#additional-considerations) for more details. Patterns for files known to require review from the team are listed in the in the `Authentication and Authorization` section of the [`CODEOWNERS`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS) file, and the team will be listed in the approvers section of all merge requests that modify these files. | +| Changes related to authentication | [Manage:Authentication](https://about.gitlab.com/company/team/). Check the [code review section on the group page](https://about.gitlab.com/handbook/engineering/development/dev/manage/authentication/#additional-considerations) for more details. Patterns for files known to require review from the team are listed in the in the `Authentication` section of the [`CODEOWNERS`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS) file, and the team will be listed in the approvers section of all merge requests that modify these files. | +| Changes related to custom roles or policies | [Manage:Authorization Engineer](https://gitlab.com/gitlab-org/govern/authorization/approvers). | 1. Specs other than JavaScript specs are considered `~backend` code. Haml markup is considered `~frontend` code. However, Ruby code in Haml templates is considered `~backend` code. When in doubt, request both a frontend and backend review. 1. We encourage you to seek guidance from a database maintainer if your merge @@ -199,8 +200,39 @@ by a reviewer before passing it to a maintainer as described in the Designers do not require a Product Designer to approve feature changes, unless the changes are community contributions. 1. End-to-end changes include all files in the `qa` directory. +#### CODEOWNERS approval + +Some merge requests require mandatory approval by specific groups. +See `.gitlab/CODEOWNERS` for definitions. + +Mandatory sections in `.gitlab/CODEOWNERS` should only be limited to cases where +it is necessary due to: + +- compliance +- availability +- security + +When adding a mandatory section, you should track the impact on the new mandatory section +on merge request rates. +See the [Verify issue](https://gitlab.com/gitlab-org/gitlab/-/issues/411559) for a good example. + +All other cases should not use mandatory sections as we favor +[responsibility over ridigity](https://handbook.gitlab.com/handbook/values/#freedom-and-responsibility-over-rigidity). + +Additionally, the current structure of the monolith means that merge requests +are likely to touch seemingly unrelated parts. +Multiple mandatory approvals means that such merge requests require the author +to seek approvals, which is not efficient. + +Efforts to improve this are in: + +- <https://gitlab.com/groups/gitlab-org/-/epics/11624> +- <https://gitlab.com/gitlab-org/gitlab/-/issues/377326> + #### Acceptance checklist +<!-- When editing, remember to announce the change to Engineering Division --> + This checklist encourages the authors, reviewers, and maintainers of merge requests (MRs) to confirm changes were analyzed for high-impact risks to quality, performance, reliability, security, observability, and maintainability. Using checklists improves quality in software engineering. This checklist is a straightforward tool to support and bolster the skills of contributors to the GitLab codebase. @@ -250,7 +282,7 @@ See the [test engineering process](https://about.gitlab.com/handbook/engineering 1. You have reviewed the documentation regarding [internal application security reviews](https://about.gitlab.com/handbook/security/#internal-application-security-reviews) for **when** and **how** to request a security review and requested a security review if this is warranted for this change. 1. If there are security scan results that are blocking the MR (due to the [scan result policies](https://gitlab.com/gitlab-com/gl-security/security-policies)): - For true positive findings, they should be corrected before the merge request is merged. This will remove the AppSec approval required by the scan result policy. - - For false positive findings, something that should be discussed for risk acceptance, or anything questionable, please ping `@gitlab-com/gl-security/appsec`. + - For false positive findings, something that should be discussed for risk acceptance, or anything questionable, ping `@gitlab-com/gl-security/appsec`. ##### Deployment @@ -465,7 +497,7 @@ Here is a summary of the changes, also reflected in this section above. ### Having your merge request reviewed -Please keep in mind that code review is a process that can take multiple +Keep in mind that code review is a process that can take multiple iterations, and reviewers may spot things later that they may not have seen the first time. @@ -619,9 +651,8 @@ WARNING: [very specific cases](https://about.gitlab.com/handbook/engineering/workflow/#criteria-for-merging-during-broken-master). For other cases, follow these [handbook instructions](https://about.gitlab.com/handbook/engineering/workflow/#merging-during-broken-master). - If the latest pipeline was created before the merge request was approved, start a new pipeline to ensure that full RSpec suite has been run. You may skip this step only if the merge request does not contain any backend change. - - If the **latest [merged results pipeline](../ci/pipelines/merged_results_pipelines.md)** was **created less than 6 hours ago**, and **finished less than 2 hours ago**, you - may merge without starting a new pipeline as the merge request is close - enough to `main`. + - If the **latest [merged results pipeline](../ci/pipelines/merged_results_pipelines.md)** was **created less than 4 hours ago**, you + may merge without starting a new pipeline as the merge request is close enough to the target branch. - When you set the MR to auto-merge, you should take over subsequent revisions for anything that would be spotted after that. - For merge requests that have had [Squash and merge](../user/project/merge_requests/squash_and_merge.md) set, diff --git a/doc/development/code_suggestions/index.md b/doc/development/code_suggestions/index.md index 743d06c2b4c..bdf3bcdd520 100644 --- a/doc/development/code_suggestions/index.md +++ b/doc/development/code_suggestions/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Code Suggestions development guidelines @@ -42,7 +42,7 @@ This should enable everyone to see locally any change in an IDE being sent to th When testing interactions with the Model Gateway, you might want to integrate your local GDK with the deployed staging Model Gateway. To do this: -1. You need a [cloud staging license](../../user/project/repository/code_suggestions/self_managed.md#update-gitlab) that has the Code Suggestions add-on, because add-ons are enabled on staging. Drop a note in the `#s_fulfillment` internal Slack channel to request an add-on to your license. See this [handbook page](https://about.gitlab.com/handbook/developer-onboarding/#working-on-gitlab-ee-developer-licenses) for how to request a license for local development. +1. You need a [cloud staging license](../../user/project/repository/code_suggestions/self_managed.md#upgrade-gitlab) that has the Code Suggestions add-on, because add-ons are enabled on staging. Drop a note in the `#s_fulfillment` internal Slack channel to request an add-on to your license. See this [handbook page](https://about.gitlab.com/handbook/developer-onboarding/#working-on-gitlab-ee-developer-licenses) for how to request a license for local development. 1. Set environment variables to point customers-dot to staging, and the Model Gateway to staging: ```shell diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index c4ec0f66b62..0e922550856 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Design and user interface changes @@ -48,7 +47,7 @@ Check these aspects both when _designing_ and _reviewing_ UI changes. - Use clear and consistent [terminology](https://design.gitlab.com/content/terminology/). - Check grammar and spelling. - Consider help content and follow its [guidelines](https://design.gitlab.com/usability/contextual-help). -- Request review from the [appropriate Technical Writer](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments), +- Request review from the [appropriate Technical Writer](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments), indicating any specific files or lines they should review, and how to preview or understand the location/context of the text from the user's perspective. diff --git a/doc/development/contributing/first_contribution.md b/doc/development/contributing/first_contribution.md index 834f34328bc..c6d097574e8 100644 --- a/doc/development/contributing/first_contribution.md +++ b/doc/development/contributing/first_contribution.md @@ -1,20 +1,24 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Tutorial: Make a GitLab contribution Anyone can contribute to the development of GitLab. -Maybe you want to add functionality that you feel is missing. Or maybe -you noticed some UI text that you want to improve. +Maybe you want to add functionality that you feel is missing. +Or maybe you noticed some UI text that you want to improve. This tutorial will walk you through the process of updating UI text and related files by using the GitLab Development Kit and the GitLab community fork. -You can follow this example exactly to familiarize yourself with the process, -or you can choose other UI text to update. +You can follow this example to familiarize yourself with the process. + +NOTE: +We recommend joining our [Discord server](https://discord.gg/gitlab), where GitLab team +members and the wider community are ready and waiting to answer your questions +and ensure [everyone can contribute](https://handbook.gitlab.com/handbook/company/mission/). ## Steps @@ -40,9 +44,11 @@ On your local machine: On GitLab.com: - Create an account. Ensure you can successfully sign in. -- Go to the [`gitlab-community/community-members` group](https://gitlab.com/gitlab-community/community-members) - and select **Request access**. This action will give you access to the GitLab - community fork, where you'll author your changes. +- Click [here](https://gitlab.com/groups/gitlab-community/community-members/-/group_members/request_access) + to request access to the [community forks](https://gitlab.com/gitlab-community). + - The access request will be manually verified and should take no more than a few hours. + - You can get started without access, and only need it prior to pushing your changes to GitLab.com. + - NOTE: If you see an error, you are either: not signed in, or already have access. ## Step 1: Configure the GitLab Development Kit @@ -55,13 +61,40 @@ You can run it on your local machine, or use GitPod to run a remote version.  -If you've never used the GDK before, and you think you might contribute -more than once, you should install it. +We recommend using Gitpod for your first contribution, it will run the GDK regardless +of your local hardware and software (e.g. operating system). + If you already have a working GDK, you should [update it to use the community fork](#an-existing-gdk-installation). +### Using Gitpod + +If you want to contribute without the overhead of setting up a local development environment, +you can use [Gitpod](../../integration/gitpod.md). +Gitpod runs a virtual instance of the GDK. + +Set aside about 15 minutes to launch the GDK in Gitpod. + +1. Launch the GDK in [Gitpod](https://gitpod.io/#https://gitlab.com/gitlab-community/gitlab/-/tree/master/). +1. Create an account if this is your first time using Gitpod. + After registering, you may need to relaunch [GitLab in Gitpod](https://gitpod.io/#https://gitlab.com/gitlab-community/gitlab/-/tree/master/). +1. Select **Continue with GitLab**. +1. If this is your first time using Gitpod with GitLab, select **Authorize** when prompted to + **Authorize Gitpod.io to use your account?**. +1. Leave the default repository URL: `gitlab.com/gitlab-community/gitlab/-/tree/master/`. +1. Select your preferred **Editor**. +1. Leave the default **Class**: `Standard`. +1. Wait for Gitpod to launch. + +You can begin exploring the codebase and making your changes once your editor of choice has launched. + +You will need to wait a little longer for GitLab to be available to preview your changes. + ### A new GDK installation +NOTE: +Skip this step if you're using Gitpod. + Set aside about two hours to install the GDK. If all goes smoothly, it should take about an hour to install. @@ -156,12 +189,6 @@ To confirm it was successful: If you get errors, run `gdk doctor` to troubleshoot. For more advanced troubleshooting, see [the troubleshooting docs](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/main/doc/troubleshooting). -### Gitpod - -If you want to contribute without the overhead of setting up a local development environment, -you can use [Gitpod](../../integration/gitpod.md) instead. -Gitpod runs a virtual instance of the GDK. - ## Step 2: Change the code [View an interactive demo of this step](https://gitlab.navattic.com/uu5a0dc5). @@ -177,6 +204,9 @@ I want to change this text: Other settings on the page start with the word `Customize` and skip the `This setting allows you to` part. I'll update this phrase to match the others. +NOTE: +As this text has already been [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116472) when developing this tutorial, you can instead search for `Customize the appearance of the syntax` to find the files that were changed. + 1. Search the `gitlab-development-kit/gitlab` directory for the string `This setting allows you to customize`. The results show one `.haml` file, two `.md` files, one `.pot` file, and diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index abec161bd6e..2c8b5b2af20 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Contribute to GitLab development @@ -143,7 +142,7 @@ Lastly, keep the following in mind when submitting merge requests: ## Contributing to Premium/Ultimate features with an Enterprise Edition license If you would like to work on GitLab features that are within a paid tier, also known as the code that lives in the [EE folder](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee), it requires a GitLab Enterprise Edition license. -Please request an Enterprise Edition Developers License according to the [documented process](https://about.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows.html#contributing-to-the-gitlab-enterprise-edition-ee). +Request an Enterprise Edition Developers License according to the [documented process](https://about.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows#contributing-to-the-gitlab-enterprise-edition-ee). ## Get help diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 0b1c7303fc0..b59a77c1f52 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Issues workflow @@ -27,7 +26,7 @@ Do **not** create publicly viewable issues for suspected security vulnerabilitie ### Feature proposals -To create a feature proposal, open an issue in the issue tracker using the +To create a feature proposal, open an issue in the issue tracker using the [**Feature Proposal - detailed** issue template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal%20-%20detailed). In order to help track feature proposals, we use the @@ -35,7 +34,7 @@ In order to help track feature proposals, we use the Users that are not members of the project cannot add labels via the UI. Instead, use [reactive label commands](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#reactive-label-and-unlabel-commands). -Please keep feature proposals as small and simple as possible, complex ones +Keep feature proposals as small and simple as possible, complex ones might be edited to make them small and simple. For changes to the user interface (UI), follow our [design and UI guidelines](design.md), @@ -78,7 +77,7 @@ You are very welcome to help the GitLab team triage issues. The most important thing is making sure valid issues receive feedback from the development team. Therefore the priority is mentioning developers that can help -on those issues. Please select someone with relevant experience from the +on those issues. Select someone with relevant experience from the [GitLab team](https://about.gitlab.com/company/team/). If there is nobody mentioned with that expertise, look in the commit history for the affected files to find someone. @@ -121,7 +120,7 @@ with a reference to an issue describing the regression, and then to update that note with a reference to the merge request that fixes it as it becomes available. If you're a contributor who doesn't have the required permissions to update -other users' notes, please post a new note with a reference to both the issue +other users' notes, post a new note with a reference to both the issue and the merge request. The release manager will diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index e739799557e..8ede40e741e 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Merge requests workflow @@ -15,7 +14,7 @@ label, but you are free to contribute to any issue you want. ## Working from issues -If you find an issue, please submit a merge request with a fix or improvement, +If you find an issue, submit a merge request with a fix or improvement, if you can, and include tests. If you want to add a new feature that is not labeled, it is best to first create @@ -71,13 +70,13 @@ For a walkthrough of the contribution process, see [Tutorial: Make a GitLab cont - If you would like quick feedback on your merge request feel free to mention someone from the [core team](https://about.gitlab.com/community/core-team/) or one of the [merge request coaches](https://about.gitlab.com/company/team/). When having your code reviewed - and when reviewing merge requests, please keep the [code review guidelines](../code_review.md) + and when reviewing merge requests, keep the [code review guidelines](../code_review.md) in mind. And if your code also makes changes to the database, or does expensive queries, check the [database review guidelines](../database_review.md). ### Keep it simple -*Live by smaller iterations.* Please keep the amount of changes in a single MR **as small as possible**. +*Live by smaller iterations.* Keep the amount of changes in a single MR **as small as possible**. If you want to contribute a large feature, think very carefully about what the [minimum viable change](https://about.gitlab.com/handbook/product/#the-minimally-viable-change) is. Can you split the functionality into two smaller MRs? Can you submit only the @@ -157,7 +156,7 @@ Example commit message template that can be used on your machine that embodies t ## Contribution acceptance criteria -To make sure that your merge request can be approved, please ensure that it meets +To make sure that your merge request can be approved, ensure that it meets the contribution acceptance criteria below: 1. The change is as small as possible. @@ -196,7 +195,7 @@ the contribution acceptance criteria below: ## Definition of done -If you contribute to GitLab, please know that changes involve more than just +If you contribute to GitLab, know that changes involve more than just code. We use the following [definition of done](https://www.agilealliance.org/glossary/definition-of-done/). To reach the definition of done, the merge request must create no regressions and meet all these criteria: @@ -264,7 +263,7 @@ requirements. 1. For tests that use Capybara, read [how to write reliable, asynchronous integration tests](https://thoughtbot.com/blog/write-reliable-asynchronous-integration-tests-with-capybara). 1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-at-the-system-level-aka-end-to-end-tests) - added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) + added if required. Contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) with any questions. 1. The change is tested in a review app where possible and if appropriate. 1. Code affected by a feature flag is covered by [automated tests with the feature flag enabled and disabled](../feature_flags/index.md#feature-flags-in-tests), or both @@ -276,7 +275,7 @@ requirements. 1. Use available components from the GitLab Design System, [Pajamas](https://design.gitlab.com/). 1. The MR must include *Before* and *After* screenshots if UI changes are made. -1. If the MR changes CSS classes, please include the list of affected pages, which +1. If the MR changes CSS classes, include the list of affected pages, which can be found by running `grep css-class ./app -R`. ### Description of changes @@ -295,7 +294,7 @@ requirements. ### Approval -1. The [MR acceptance checklist](../code_review.md#acceptance-checklist) has been checked as confirmed in the MR. +1. The MR was evaluated against the [MR acceptance checklist](../code_review.md#acceptance-checklist). 1. Create an issue in the [infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues) to inform the Infrastructure department when your contribution is changing default settings or introduces a new setting, if relevant. 1. An agreed-upon [rollout plan](https://about.gitlab.com/handbook/engineering/development/processes/rollout-plans/). 1. Reviewed by relevant reviewers, and all concerns are addressed for Availability, Regressions, and Security. Documentation reviews should take place as soon as possible, but they should not block a merge request. @@ -324,7 +323,7 @@ Contributions do not require approval from the [Product team](https://about.gitl ## Dependencies -If you add a dependency in GitLab (such as an operating system package) please +If you add a dependency in GitLab (such as an operating system package), consider updating the following, and note the applicability of each in your merge request: diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 80ac0b872d6..e560920cca1 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Development style guides diff --git a/doc/development/contributing/verify/index.md b/doc/development/contributing/verify/index.md index 8d1bd3c76f0..dbc48121dff 100644 --- a/doc/development/contributing/verify/index.md +++ b/doc/development/contributing/verify/index.md @@ -1,5 +1,4 @@ --- -type: reference, dev stage: Verify group: Pipeline Execution --- @@ -243,7 +242,7 @@ scenario relating to a software being built by one of our [early customers](http > could generate a new particle that would then cause the universe to implode. That would be quite an undesirable outcome of a small bug in GitLab CI/CD status -processing. Please take extra care when you are working on CI/CD statuses, +processing. Take extra care when you are working on CI/CD statuses, we don't want to implode our Universe! This is an extreme and unlikely scenario, but presenting data that is not accurate diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index 476d370e7ee..c25c4751ee8 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Danger bot @@ -34,6 +34,8 @@ from the start of the merge request. - It's not obvious Danger updates the old comment, thus you need to pay attention to it if it is updated or not. +- When Danger tokens are rotated, it creates confusion/clutter (as old comments + can't be updated). ## Run Danger locally @@ -179,15 +181,19 @@ at GitLab so far: ## Limitations -Danger is run but its output is not added to a merge request comment if working -on a fork. This happens because the secret variable from the canonical project -is not shared to forks. +If working on a personal fork, Danger is run but it's output is not added to a +merge request comment and labels are not applied. +This happens because the secret variable from the canonical project is not shared +to forks. -### Configuring Danger for forks +The best and recommended approach is to work from the [community forks](https://gitlab.com/gitlab-community/meta), +where Danger is already configured. + +### Configuring Danger for personal forks Contributors can configure Danger for their forks with the following steps: -1. Create a [personal API token](https://gitlab.com/-/profile/personal_access_tokens?name=GitLab+Dangerbot&scopes=api) +1. Create a [personal API token](https://gitlab.com/-/user_settings/personal_access_tokens?name=GitLab+Dangerbot&scopes=api) that has the `api` scope set (don't forget to copy it to the clipboard). 1. In your fork, add a [project CI/CD variable](../ci/variables/index.md#for-a-project) called `DANGER_GITLAB_API_TOKEN` with the token copied in the previous step. diff --git a/doc/development/data_science/index.md b/doc/development/data_science/index.md index 832d3999645..632acb8602f 100644 --- a/doc/development/data_science/index.md +++ b/doc/development/data_science/index.md @@ -1,7 +1,9 @@ --- stage: Data Science group: ModelOps -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- +# Data Science + - [Model Registry](model_registry/index.md) diff --git a/doc/development/data_science/model_registry/index.md b/doc/development/data_science/model_registry/index.md index 6ebf6430727..c8f37ca06eb 100644 --- a/doc/development/data_science/model_registry/index.md +++ b/doc/development/data_science/model_registry/index.md @@ -1,7 +1,7 @@ --- stage: Data Science group: ModelOps -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Model Registry diff --git a/doc/development/database/add_foreign_key_to_existing_column.md b/doc/development/database/add_foreign_key_to_existing_column.md index 823fb49a9ab..4a0e3a47633 100644 --- a/doc/development/database/add_foreign_key_to_existing_column.md +++ b/doc/development/database/add_foreign_key_to_existing_column.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Add a foreign key constraint to an existing column diff --git a/doc/development/database/adding_database_indexes.md b/doc/development/database/adding_database_indexes.md index d41800d2df7..05425fdbb21 100644 --- a/doc/development/database/adding_database_indexes.md +++ b/doc/development/database/adding_database_indexes.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Adding Database Indexes diff --git a/doc/development/database/avoiding_downtime_in_migrations.md b/doc/development/database/avoiding_downtime_in_migrations.md index 3b4b45935b9..bf75b7c2ab2 100644 --- a/doc/development/database/avoiding_downtime_in_migrations.md +++ b/doc/development/database/avoiding_downtime_in_migrations.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Avoiding downtime in migrations diff --git a/doc/development/database/background_migrations.md b/doc/development/database/background_migrations.md deleted file mode 100644 index be121cc0bfe..00000000000 --- a/doc/development/database/background_migrations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/database/batched_background_migrations.md b/doc/development/database/batched_background_migrations.md index a6d827df820..ec1a71eb4f4 100644 --- a/doc/development/database/batched_background_migrations.md +++ b/doc/development/database/batched_background_migrations.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: Data Stores group: Database -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Batched background migrations @@ -258,6 +257,41 @@ Make sure the newly-created data is either migrated, or saved in both the old and new version upon creation. Removals in turn can be handled by defining foreign keys with cascading deletes. +### Finalize a batched background migration + +Finalizing a batched background migration is done by calling +`ensure_batched_background_migration_is_finished`. + +It is important to finalize all batched background migrations when it is safe +to do so. Leaving around old batched background migration is a form of +technical debt that needs to be maintained in tests and in application +behavior. It is important to note that you cannot depend on any batched +background migration being completed until after it is finalized. + +We recommend that batched background migrations are finalized after all of the +following conditions are met: + +- The batched background migration is completed on GitLab.com +- The batched background migration was added in or before the last [required stop](required_stops.md) + +The `ensure_batched_background_migration_is_finished` call must exactly match +the migration that was used to enqueue it. Pay careful attention to: + +- The job arguments: Needs to exactly match or it will not find the queued migration +- The `gitlab_schema`: Needs to exactly match or it will not find the queued + migration. Even if the `gitlab_schema` of the table has changed from + `gitlab_main` to `gitlab_main_cell` in the meantime you must finalize it + with `gitlab_main` if that's what was used when queueing the batched + background migration. + +When finalizing a batched background migration you also need to update the +`finalized_by` in the corresponding `db/docs/batched_background_migrations` +file. The value should be the timestamp/version of the migration you added to +finalize it. + +See the below [Examples](#examples) for specific details on what the actual +migration code should be. + ### Use job arguments `BatchedMigrationJob` provides the `job_arguments` helper method for job classes to define the job arguments they need. @@ -654,6 +688,65 @@ index 4ae3622479f0800c0553959e132143ec9051898e..d556ec7f55adae9d46a56665ce02de78 Create a Draft merge request with your changes and trigger the manual `db:gitlabcom-database-testing` job. +### Establish dependencies + +In some instances, migrations depended on the completion of previously enqueued BBMs. If the BBMs are +still running, the dependent migration fails. For example: introducing an unique index on a large table can depend on +the previously enqueued BBM to handle any duplicate records. + +The following process has been configured to make dependencies more evident while writing a migration. + +- Version of the migration that queued the BBM is stored in _batched_background_migrations_ table and in BBM dictionary file. +- `DEPENDENT_BATCHED_BACKGROUND_MIGRATIONS` constant is added (commented by default) in each migration file. + To establish the dependency, add `queued_migration_version` of the dependent BBMs. If not, remove + the commented line. +- `Migration::UnfinishedDependencies` cop complains if the dependent BBMs are not yet finished. It determines + whether they got finished by looking up the `finalized_by` key in the + [BBM dictionary](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/batched_background_migration/templates/batched_background_migration_dictionary.template). + +Example: + +```ruby +# db/post_migrate/20231113120650_queue_backfill_routes_namespace_id.rb +class QueueBackfillRoutesNamespaceId < Gitlab::Database::Migration[2.1] + MIGRATION = 'BackfillRouteNamespaceId' + + restrict_gitlab_migration gitlab_schema: :gitlab_main + ... + ... + + def up + queue_batched_background_migration( + MIGRATION, + ... + ) + end +end +``` + +```ruby +# This depends on the finalization of QueueBackfillRoutesNamespaceId BBM +class AddNotNullToRoutesNamespaceId < Gitlab::Database::Migration[2.1] + DEPENDENT_BATCHED_BACKGROUND_MIGRATIONS = ["20231113120650"] + + def up + add_not_null_constraint :routes, :namespace_id + end + + def down + remove_not_null_constraint :routes, :namespace_id + end +end +``` + +#### Notes + +- `BackgroundMigration::DictionaryFile` cop ensures the presence of `finalize_after` and `introduced_by_url` keys in the + BBM dictionary. + - `finalize_after`: Captures the (approximate) date after which the BBM is expected to be finalized. + - `introduced_by_url`: After the `finalize_after` date, an issue is created using the labels and author from `introduced_by_url`. + - As of writing (2023-08-11), issue [#424886](https://gitlab.com/gitlab-org/gitlab/-/issues/424886) is still open. + ## Managing NOTE: @@ -1003,6 +1096,19 @@ background migration. end ``` + ```yaml + # db/docs/batched_background_migrations/backfill_route_namespace_id.yml + --- + migration_job_name: BackfillRouteNamespaceId + description: Copies source_id values from routes to namespace_id + feature_category: source_code_management + introduced_by_url: "https://mr_url" + milestone: 16.6 + queued_migration_version: 20231113120650 + finalize_after: "2023-11-15" + finalized_by: # version of the migration that ensured this bbm + ``` + NOTE: When queuing a batched background migration, you need to restrict the schema to the database where you make the actual changes. @@ -1015,8 +1121,8 @@ background migration. - Continues using the data as before. - Ensures that both existing and new data are migrated. -1. Add a new post-deployment migration - that checks that the batched background migration is completed. For example: +1. Add a new post-deployment migration that checks that the batched background migration is complete. Also update + `finalized_by` attribute in BBM dictionary with the version of this migration. ```ruby class FinalizeBackfillRouteNamespaceId < Gitlab::Database::Migration[2.1] @@ -1041,6 +1147,19 @@ background migration. end ``` + ```yaml + # db/docs/batched_background_migrations/backfill_route_namespace_id.yml + --- + migration_job_name: BackfillRouteNamespaceId + description: Copies source_id values from routes to namespace_id + feature_category: source_code_management + introduced_by_url: "https://mr_url" + milestone: 16.6 + queued_migration_version: 20231113120650 + finalize_after: "2023-11-15" + finalized_by: 20231115120912 + ``` + NOTE: If the batched background migration is not finished, the system will execute the batched background migration inline. If you don't want diff --git a/doc/development/database/ci_mirrored_tables.md b/doc/development/database/ci_mirrored_tables.md index 1e37739bdc4..31c16926c51 100644 --- a/doc/development/database/ci_mirrored_tables.md +++ b/doc/development/database/ci_mirrored_tables.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # CI mirrored tables diff --git a/doc/development/database/clickhouse/clickhouse_within_gitlab.md b/doc/development/database/clickhouse/clickhouse_within_gitlab.md index 2f7a3c4dfe0..a459f89b185 100644 --- a/doc/development/database/clickhouse/clickhouse_within_gitlab.md +++ b/doc/development/database/clickhouse/clickhouse_within_gitlab.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # ClickHouse within GitLab @@ -205,6 +205,26 @@ end NOTE: It's important to test and verify efficient batching of database records from PostgreSQL. Consider using the techniques described in the [Iterating tables in batches](../iterating_tables_in_batches.md). +## Implementing Sidekiq workers + +Sidekiq workers leveraging ClickHouse databases should include the `ClickHouseWorker` module. +This ensures that the worker is paused while database migrations are running, +and that migrations do not run while the worker is active. + +```ruby +# events_sync_worker.rb +# frozen_string_literal: true + +module ClickHouse + class EventsSyncWorker + include ApplicationWorker + include ClickHouseWorker + + ... + end +end +``` + ## Testing ClickHouse is enabled on CI/CD but to avoid significantly affecting the pipeline runtime we've decided to run the ClickHouse server for test cases tagged with `:click_house` only. diff --git a/doc/development/database/clickhouse/gitlab_activity_data.md b/doc/development/database/clickhouse/gitlab_activity_data.md index 7c30703a016..af327ba64a8 100644 --- a/doc/development/database/clickhouse/gitlab_activity_data.md +++ b/doc/development/database/clickhouse/gitlab_activity_data.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Store GitLab activity data in ClickHouse diff --git a/doc/development/database/clickhouse/index.md b/doc/development/database/clickhouse/index.md index 52e9aecce4a..f877ce4053f 100644 --- a/doc/development/database/clickhouse/index.md +++ b/doc/development/database/clickhouse/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Introduction to ClickHouse use and table design diff --git a/doc/development/database/clickhouse/merge_request_analytics.md b/doc/development/database/clickhouse/merge_request_analytics.md index 34da71d6c4c..db441ca9051 100644 --- a/doc/development/database/clickhouse/merge_request_analytics.md +++ b/doc/development/database/clickhouse/merge_request_analytics.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Merge request analytics with ClickHouse diff --git a/doc/development/database/clickhouse/optimization.md b/doc/development/database/clickhouse/optimization.md index 166bbf7d2b1..91431d150b4 100644 --- a/doc/development/database/clickhouse/optimization.md +++ b/doc/development/database/clickhouse/optimization.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Optimizing query execution diff --git a/doc/development/database/clickhouse/tiered_storage.md b/doc/development/database/clickhouse/tiered_storage.md index d9026f47e28..afa1747b6f8 100644 --- a/doc/development/database/clickhouse/tiered_storage.md +++ b/doc/development/database/clickhouse/tiered_storage.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Tiered Storages in ClickHouse diff --git a/doc/development/database/client_side_connection_pool.md b/doc/development/database/client_side_connection_pool.md index 3c9f8e76d89..04e2d1fc9f2 100644 --- a/doc/development/database/client_side_connection_pool.md +++ b/doc/development/database/client_side_connection_pool.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Client-side connection-pool diff --git a/doc/development/database/constraint_naming_convention.md b/doc/development/database/constraint_naming_convention.md index 4ac1cd2a71d..3b4f2e92b98 100644 --- a/doc/development/database/constraint_naming_convention.md +++ b/doc/development/database/constraint_naming_convention.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Constraints naming conventions diff --git a/doc/development/database/creating_enums.md b/doc/development/database/creating_enums.md index 908656dae84..bc83b1a022b 100644 --- a/doc/development/database/creating_enums.md +++ b/doc/development/database/creating_enums.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Creating enums diff --git a/doc/development/database/database_debugging.md b/doc/development/database/database_debugging.md index 9cc85610e98..271f14e91bc 100644 --- a/doc/development/database/database_debugging.md +++ b/doc/development/database/database_debugging.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Troubleshooting and debugging the database diff --git a/doc/development/database/database_dictionary.md b/doc/development/database/database_dictionary.md index 70691d8746c..bce1d5a43da 100644 --- a/doc/development/database/database_dictionary.md +++ b/doc/development/database/database_dictionary.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database Dictionary @@ -41,7 +41,7 @@ gitlab_schema: gitlab_main | `feature_categories` | Array(String) | yes | List of feature categories using this table. | | `description` | String | no | Text description of the information stored in the table, and its purpose. | | `introduced_by_url` | URL | no | URL to the merge request or commit which introduced this table. | -| `milestone` | String | no | The milestone that introduced this table. | +| `milestone` | String | yes | The milestone that introduced this table. | | `gitlab_schema` | String | yes | GitLab schema name. | ### Process diff --git a/doc/development/database/database_lab.md b/doc/development/database/database_lab.md index 7cdf034844d..3458dd9b570 100644 --- a/doc/development/database/database_lab.md +++ b/doc/development/database/database_lab.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database Lab and Postgres.ai diff --git a/doc/development/database/database_migration_pipeline.md b/doc/development/database/database_migration_pipeline.md index 280254d90b0..069665a83c5 100644 --- a/doc/development/database/database_migration_pipeline.md +++ b/doc/development/database/database_migration_pipeline.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database migration pipeline diff --git a/doc/development/database/database_query_comments.md b/doc/development/database/database_query_comments.md index 946947db502..c6ec29bcf2e 100644 --- a/doc/development/database/database_query_comments.md +++ b/doc/development/database/database_query_comments.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database query comments with Marginalia diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index c75503c503b..07785557813 100644 --- a/doc/development/database/database_reviewer_guidelines.md +++ b/doc/development/database/database_reviewer_guidelines.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database Reviewer Guidelines @@ -84,7 +84,7 @@ topics and use cases. The most frequently required during database reviewing are Database maintainership uses the same process as other projects for identifying maintainers. [Follow the general process documented here](https://about.gitlab.com/handbook/engineering/workflow/code-review/#how-to-become-a-project-maintainer). -For database specific requirements, please see [`Project maintainer process for gitlab-database`](https://about.gitlab.com/handbook/engineering/workflow/code-review/#project-maintainer-process-for-gitlab-database) +For database specific requirements, see [`Project maintainer process for gitlab-database`](https://about.gitlab.com/handbook/engineering/workflow/code-review/#project-maintainer-process-for-gitlab-database) ## What to do if you feel overwhelmed diff --git a/doc/development/database/db_dump.md b/doc/development/database/db_dump.md index b09c601537c..f22636ab042 100644 --- a/doc/development/database/db_dump.md +++ b/doc/development/database/db_dump.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Importing a database dump into a staging environment diff --git a/doc/development/database/dbcheck-migrations-job.md b/doc/development/database/dbcheck-migrations-job.md index 4ebfb40cd03..a2e50096e45 100644 --- a/doc/development/database/dbcheck-migrations-job.md +++ b/doc/development/database/dbcheck-migrations-job.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # db:check-migrations job diff --git a/doc/development/database/deleting_migrations.md b/doc/development/database/deleting_migrations.md index bd03e6c11ae..829477bc755 100644 --- a/doc/development/database/deleting_migrations.md +++ b/doc/development/database/deleting_migrations.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Delete existing migrations diff --git a/doc/development/database/efficient_in_operator_queries.md b/doc/development/database/efficient_in_operator_queries.md index 87976df5711..8e334e5bb5c 100644 --- a/doc/development/database/efficient_in_operator_queries.md +++ b/doc/development/database/efficient_in_operator_queries.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Efficient `IN` operator queries diff --git a/doc/development/database/filtering_by_label.md b/doc/development/database/filtering_by_label.md index a30322176ba..a7e7d7d5fd6 100644 --- a/doc/development/database/filtering_by_label.md +++ b/doc/development/database/filtering_by_label.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Filtering by label diff --git a/doc/development/database/foreign_keys.md b/doc/development/database/foreign_keys.md index 4a457622a49..a341b9d9b72 100644 --- a/doc/development/database/foreign_keys.md +++ b/doc/development/database/foreign_keys.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Foreign keys and associations diff --git a/doc/development/database/hash_indexes.md b/doc/development/database/hash_indexes.md index aba23dbea70..8198459bd39 100644 --- a/doc/development/database/hash_indexes.md +++ b/doc/development/database/hash_indexes.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Hash Indexes diff --git a/doc/development/database/index.md b/doc/development/database/index.md index 70681994229..c5969176d72 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database development guidelines diff --git a/doc/development/database/insert_into_tables_in_batches.md b/doc/development/database/insert_into_tables_in_batches.md index 547ca25b264..df843c5d596 100644 --- a/doc/development/database/insert_into_tables_in_batches.md +++ b/doc/development/database/insert_into_tables_in_batches.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: "Sometimes it is necessary to store large amounts of records at once, which can be inefficient when iterating collections and performing individual `save`s. With the arrival of `insert_all` in Rails 6, which operates at the row level (that is, using `Hash`es), GitLab has added a set diff --git a/doc/development/database/iterating_tables_in_batches.md b/doc/development/database/iterating_tables_in_batches.md index 44a8c72ea2c..802b7622592 100644 --- a/doc/development/database/iterating_tables_in_batches.md +++ b/doc/development/database/iterating_tables_in_batches.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Iterating tables in batches diff --git a/doc/development/database/keyset_pagination.md b/doc/development/database/keyset_pagination.md index ff8038ee24c..9bb44d2ed71 100644 --- a/doc/development/database/keyset_pagination.md +++ b/doc/development/database/keyset_pagination.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Keyset pagination @@ -87,6 +87,55 @@ Because keyset pagination does not support page numbers, we are restricted to go - Last page - First page +#### Usage in REST API with `paginate_with_strategies` + +For the REST API, the `paginate_with_strategies` helper can be used on a relation in order to use either keyset pagination or offset pagination. + +```ruby + desc 'Get the things related to a project' do + detail 'This feature was introduced in GitLab 16.1' + success code: 200, model: ::API::Entities::Thing + failure [ + { code: 401, message: 'Unauthorized' }, + { code: 403, message: 'Forbidden' }, + { code: 404, message: 'Not Found' } + ] + end + params do + use :pagination + requires :project_id, type: Integer, desc: 'The ID of the project' + optional :cursor, type: String, desc: 'Cursor for obtaining the next set of records' + optional :order_by, type: String, values: %w[id name], default: 'id', + desc: 'Attribute to sort by' + optional :sort, type: String, values: %w[asc desc], default: 'desc', desc: 'Order of sorting' + end + route_setting :authentication + get ':project_id/things' do + project = Project.find_by_id(params[:project_id]) + + not_found! if project.blank? + + things = project.things + + present paginate_with_strategies(things), with: ::API::Entities::Thing + end +``` + +In order for keyset pagination to be used, the following conditions must be met: + +1. `params[:keyset]` must return `'keyset'` +1. `params[:order_by]` and `params[:sort]` must both appear in the object returned by the + `supported_keyset_orderings` class method on the model. In the following example, `Thing` + supports keyset pagination when ordering by ID in either ascending or descending order. + + ```ruby + class Thing < ApplicationRecord + def self.supported_keyset_orderings + { id: [:asc, :desc] } + end + end + ``` + #### Usage in Rails with HAML views Consider the following controller action, where we list the projects ordered by name: diff --git a/doc/development/database/layout_and_access_patterns.md b/doc/development/database/layout_and_access_patterns.md index 06ac24c284c..498edc7155b 100644 --- a/doc/development/database/layout_and_access_patterns.md +++ b/doc/development/database/layout_and_access_patterns.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Best practices for data layout and access patterns diff --git a/doc/development/database/load_balancing.md b/doc/development/database/load_balancing.md index f6e145ac7f5..9ec6ef6fce7 100644 --- a/doc/development/database/load_balancing.md +++ b/doc/development/database/load_balancing.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database load balancing diff --git a/doc/development/database/loose_foreign_keys.md b/doc/development/database/loose_foreign_keys.md index 08d618a26ae..3003ee970ce 100644 --- a/doc/development/database/loose_foreign_keys.md +++ b/doc/development/database/loose_foreign_keys.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Loose foreign keys @@ -119,9 +119,9 @@ To match foreign key (FK), write one or many filters to match against FROM/TO/CO - scripts/decomposition/generate-loose-foreign-key dast_site_profiles_pipelines ``` -The command accepts a list of filters to match from, to, or column for the purpose of the foreign key generation. -For example, run this to swap all foreign keys for `ci_job_token_project_scope_links` for the -decomposed database: +The command accepts a list of regular expressions to match from, to, or column +for the purpose of the foreign key generation. For example, run this to swap +all foreign keys for `ci_job_token_project_scope_links` for the decomposed database: ```shell scripts/decomposition/generate-loose-foreign-key -c ci_job_token_project_scope_links @@ -133,6 +133,15 @@ To swap only the `source_project_id` of `ci_job_token_project_scope_links` for t scripts/decomposition/generate-loose-foreign-key -c ci_job_token_project_scope_links source_project_id ``` +To match the exact name of a table or columns, you can make use of the regular expressions +position anchors `^` and `$`. For example, this command matches only the +foreign keys on the `events` table only, but not on the table +`incident_management_timeline_events`. + +```shell +scripts/decomposition/generate-loose-foreign-key -n ^events$ +``` + To swap all the foreign keys (all having `_id` appended), but not create a new branch (only commit the changes) and not create RSpec tests, run: diff --git a/doc/development/database/maintenance_operations.md b/doc/development/database/maintenance_operations.md index bfe18068aab..2701c228b74 100644 --- a/doc/development/database/maintenance_operations.md +++ b/doc/development/database/maintenance_operations.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Maintenance operations diff --git a/doc/development/database/migrations_for_multiple_databases.md b/doc/development/database/migrations_for_multiple_databases.md index ae9348a2090..b7f3b37ada0 100644 --- a/doc/development/database/migrations_for_multiple_databases.md +++ b/doc/development/database/migrations_for_multiple_databases.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Migrations for Multiple databases diff --git a/doc/development/database/multiple_databases.md b/doc/development/database/multiple_databases.md index a045d8ad144..e453a7f27ea 100644 --- a/doc/development/database/multiple_databases.md +++ b/doc/development/database/multiple_databases.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Multiple Databases @@ -64,6 +64,136 @@ After a schema has been assigned, the merge request pipeline might fail due to o - [Cross-database transactions](#fixing-cross-database-transactions) - [Cross-database foreign keys](#foreign-keys-that-cross-databases) +### Defining a sharding key for all cell-local tables + +All tables with the following `gitlab_schema` are considered "cell-local": + +- `gitlab_main_cell` +- `gitlab_ci` + +All newly created cell-local tables are required to have a `sharding_key` +defined in the corresponding `db/docs/` file for that table. + +The purpose of the sharding key is documented in the +[Organization isolation blueprint](../../architecture/blueprints/organization/isolation.md), +but in short this column is used to provide a standard way of determining which +Organization owns a particular row in the database. The column will be used in +the future to enforce constraints on data not cross Organization boundaries. It +will also be used in the future to provide a uniform way to migrate data +between Cells. + +The actual name of the foreign key can be anything but it must reference a row +in `projects` or `groups`. The following are examples of valid sharding keys: + +- The table entries belong to a project only: + + ```yaml + sharding_key: + project_id: projects + ``` + +- The table entries belong to a project and the foreign key is `target_project_id`: + + ```yaml + sharding_key: + target_project_id: projects + ``` + +- The table entries belong to a namespace/group only: + + ```yaml + sharding_key: + namespace_id: namespaces + ``` + +- The table entries belong to a namespace/group only and the foreign key is `group_id`: + + ```yaml + sharding_key: + group_id: namespaces + ``` + +- The table entries belong to a namespace or a project: + + ```yaml + sharding_key: + project_id: projects + namespace_id: namespaces + ``` + +#### The sharding key must be immutable + +The choice of a `sharding_key` should always be immutable. Therefore, if your feature +requires a user experience which allows data to be moved between projects or +groups/namespaces, then you may need to redesign the move feature to create new rows. An +example of this can be seen in the +[move an issue feature](../../user/project/issues/managing_issues.md#move-an-issue). +This feature does not actually change the `project_id` column for an existing +`issues` row but instead creates a new `issues` row and creates a link in the +database from the original `issues` row. If there is a particularly challenging +existing feature that needs to allow moving data you will need to reach out to +the Tenant Scale team early on to discuss options for how to manage the +sharding key. + +#### Using the same sharding key for projects and namespaces + +Developers may also choose to use `namespace_id` only for tables that can +belong to a project where the feature used by the table is being developed +following the +[Consolidating Groups and Projects blueprint](../../architecture/blueprints/consolidating_groups_and_projects/index.md). +In that case the `namespace_id` would need to be the ID of the +`ProjectNamespace` and not the group that the namespace belongs to. + +#### Defining a `desired_sharding_key` for automatically backfilling a `sharding_key` + +We need to backfill a `sharding_key` to hundreds of tables that do not have one. +This process will involve creating a merge request like +<https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136800> to add the new +column, backfill the data from a related table in the database, and then create +subsequent merge requests to add indexes, foreign keys and not-null +constraints. + +In order to minimize the amount of repetitive effort for developers we've +introduced a concise declarative way to describe how to backfill the +`sharding_key` for this specific table. This content will later be used in +automation to create all the necessary merge requests. + +An example of the `desired_sharding_key` was added in +<https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139336> and it looks like: + +```yaml +--- # db/docs/security_findings.yml +table_name: security_findings +classes: +- Security::Finding + +... + +desired_sharding_key: + project_id: + references: projects + backfill_via: + parent: + foreign_key: scanner_id + table: vulnerability_scanners + sharding_key: project_id + belongs_to: scanner +``` + +To understand best how this YAML data will be used you can map it onto +the merge request we created manually in +<https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136800>. The idea +will be to automatically create this. The content of the YAML specifies +the parent table and its `sharding_key` to backfill from in the batched +background migration. It also specifies a `belongs_to` relation which +will be added to the model to automatically populate the `sharding_key` in +the `before_save`. + +There are likely edge cases where this `desired_sharding_key` structure is not +suitable for backfilling a `sharding_key`. In such cases the team owning the +table will need to create the necessary merge requests to add the +`sharding_key` manually. + ### The impact of `gitlab_schema` The usage of `gitlab_schema` has a significant impact on the application. diff --git a/doc/development/database/namespaces_storage_statistics.md b/doc/development/database/namespaces_storage_statistics.md index c653cfb145d..07754839a1f 100644 --- a/doc/development/database/namespaces_storage_statistics.md +++ b/doc/development/database/namespaces_storage_statistics.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database case study: Namespaces storage statistics diff --git a/doc/development/database/new_database_migration_version.md b/doc/development/database/new_database_migration_version.md index b97ecd83f37..f253f99c8a6 100644 --- a/doc/development/database/new_database_migration_version.md +++ b/doc/development/database/new_database_migration_version.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Introducing a new database migration version diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md index 05b1081fc4d..5615edfcc2a 100644 --- a/doc/development/database/not_null_constraints.md +++ b/doc/development/database/not_null_constraints.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # `NOT NULL` constraints @@ -204,11 +204,117 @@ If you have to clean up a nullable column for a [high-traffic table](../migratio it needs an additional [batched background migration cleaning up](batched_background_migrations.md#cleaning-up-a-batched-background-migration) in the release after adding the data migration. -In that rare case you need 3 releases end-to-end: - -1. Release `N.M` - Add the `NOT NULL` constraint and the background-migration to fix the existing records. -1. Release `N.M+1` - Cleanup the background migration. -1. Release `N.M+2` - Validate the `NOT NULL` constraint. +In this case the number of releases depends on the amount of time needed to migrate existing records. The cleanup is +scheduled after the background migration has completed, which could be several releases after the constraint was added. + +1. Release `N.M`: + - Add the `NOT NULL` constraint without validating it: + + ```ruby + # db/post_migrate/ + class AddMergeRequestDiffsProjectIdNotNullConstraint < Gitlab::Database::Migration[2.2] + disable_ddl_transaction! + milestone '16.7' + + def up + add_not_null_constraint :merge_request_diffs, :project_id, validate: false + end + + def down + remove_not_null_constraint :merge_request_diffs, :project_id + end + end + ``` + + - Add the background-migration to fix the existing records: + + ```ruby + # db/post_migrate/ + class QueueBackfillMergeRequestDiffsProjectId < Gitlab::Database::Migration[2.2] + milestone '16.7' + restrict_gitlab_migration gitlab_schema: :gitlab_main + + MIGRATION = 'BackfillMergeRequestDiffsProjectId' + DELAY_INTERVAL = 2.minutes + + def up + queue_batched_background_migration( + MIGRATION, + :merge_request_diffs, + :id, + job_interval: DELAY_INTERVAL + ) + end + + def down + delete_batched_background_migration(MIGRATION, :merge_request_diffs, :id, []) + end + end + ``` + +1. Release `N.M+X`, where `X` is the number of releases the migration was running: + - Cleanup the background migration: + + ```ruby + # db/post_migrate/ + class FinalizeMergeRequestDiffsProjectIdBackfill < Gitlab::Database::Migration[2.2] + disable_ddl_transaction! + milestone '16.10' + restrict_gitlab_migration gitlab_schema: :gitlab_main + + MIGRATION = 'BackfillMergeRequestDiffsProjectId' + + def up + ensure_batched_background_migration_is_finished( + job_class_name: MIGRATION, + table_name: :merge_request_diffs, + column_name: :id, + job_arguments: [], + finalize: true + ) + end + + def down + # no-op + end + end + ``` + + - **Optional.** For very large tables, schedule asynchronous validation of the `NOT NULL` constraint: + + ```ruby + # db/post_migrate/ + class PrepareMergeRequestDiffsProjectIdNotNullValidation < Gitlab::Database::Migration[2.2] + milestone '16.10' + + CONSTRAINT_NAME = 'check_11c5f029ad' + + def up + prepare_async_check_constraint_validation :merge_request_diffs, name: CONSTRAINT_NAME + end + + def down + unprepare_async_check_constraint_validation :merge_request_diffs, name: CONSTRAINT_NAME + end + end + ``` + +1. Validate the `NOT NULL` constraint (if the constraint was validated asynchronously, wait for this validation to finish): + + ```ruby + # db/post_migrate/ + class ValidateMergeRequestDiffsProjectIdNullConstraint < Gitlab::Database::Migration[2.2] + milestone '16.10' + + def up + validate_not_null_constraint :merge_request_diffs, :project_id + end + + def down + # no-op + end + end + ``` For these cases, consult the database team early in the update cycle. The `NOT NULL` constraint may not be required or other options could exist that do not affect really large diff --git a/doc/development/database/ordering_table_columns.md b/doc/development/database/ordering_table_columns.md index 286313fb3ce..a97e1f60a2d 100644 --- a/doc/development/database/ordering_table_columns.md +++ b/doc/development/database/ordering_table_columns.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Ordering Table Columns in PostgreSQL diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md index 8b07dcada05..77fecccb38e 100644 --- a/doc/development/database/pagination_guidelines.md +++ b/doc/development/database/pagination_guidelines.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Pagination guidelines diff --git a/doc/development/database/pagination_performance_guidelines.md b/doc/development/database/pagination_performance_guidelines.md index b06839979da..f3a08c0240f 100644 --- a/doc/development/database/pagination_performance_guidelines.md +++ b/doc/development/database/pagination_performance_guidelines.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Pagination performance guidelines diff --git a/doc/development/database/poc_tree_iterator.md b/doc/development/database/poc_tree_iterator.md index 453f77f0cde..118d2d605be 100644 --- a/doc/development/database/poc_tree_iterator.md +++ b/doc/development/database/poc_tree_iterator.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Batch iteration in a tree hierarchy (proof of concept) diff --git a/doc/development/database/polymorphic_associations.md b/doc/development/database/polymorphic_associations.md index bb7eb46b448..54ef1c27229 100644 --- a/doc/development/database/polymorphic_associations.md +++ b/doc/development/database/polymorphic_associations.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Polymorphic Associations diff --git a/doc/development/database/post_deployment_migrations.md b/doc/development/database/post_deployment_migrations.md index 8ee9a4ae099..772c34b76d1 100644 --- a/doc/development/database/post_deployment_migrations.md +++ b/doc/development/database/post_deployment_migrations.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Post Deployment Migrations diff --git a/doc/development/database/query_count_limits.md b/doc/development/database/query_count_limits.md index b5fd4395b36..4575669c7af 100644 --- a/doc/development/database/query_count_limits.md +++ b/doc/development/database/query_count_limits.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Query Count Limits diff --git a/doc/development/database/query_performance.md b/doc/development/database/query_performance.md index 1bf9ded3f15..a5fbc2dec17 100644 --- a/doc/development/database/query_performance.md +++ b/doc/development/database/query_performance.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Query performance guidelines diff --git a/doc/development/database/query_recorder.md b/doc/development/database/query_recorder.md index 39d54954268..81fc94ea055 100644 --- a/doc/development/database/query_recorder.md +++ b/doc/development/database/query_recorder.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # QueryRecorder @@ -17,8 +17,8 @@ As a rule, merge requests [should not increase query counts](../merge_request_co This style of test works by counting the number of SQL queries executed by ActiveRecord. First a control count is taken, then you add new records to the database and rerun the count. If the number of queries has significantly increased then an `N+1` queries problem exists. ```ruby -it "avoids N+1 database queries" do - control = ActiveRecord::QueryRecorder.new { visit_some_page } +it "avoids N+1 database queries", :use_sql_query_cache do + control = ActiveRecord::QueryRecorder.new(skip_cached: false) { visit_some_page } create_list(:issue, 5) expect { visit_some_page }.to issue_same_number_of_queries_as(control) end diff --git a/doc/development/database/rename_database_tables.md b/doc/development/database/rename_database_tables.md index 641bba1f131..ad641797496 100644 --- a/doc/development/database/rename_database_tables.md +++ b/doc/development/database/rename_database_tables.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Rename table without downtime diff --git a/doc/development/database/required_stops.md b/doc/development/database/required_stops.md index 361a0495545..d476a2e70eb 100644 --- a/doc/development/database/required_stops.md +++ b/doc/development/database/required_stops.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Adding required stops diff --git a/doc/development/database/serializing_data.md b/doc/development/database/serializing_data.md index b25c8d49b64..64b7e19f528 100644 --- a/doc/development/database/serializing_data.md +++ b/doc/development/database/serializing_data.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Serializing Data diff --git a/doc/development/database/setting_multiple_values.md b/doc/development/database/setting_multiple_values.md index 48be7ff9f10..169a699d5a8 100644 --- a/doc/development/database/setting_multiple_values.md +++ b/doc/development/database/setting_multiple_values.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Update multiple database objects diff --git a/doc/development/database/sha1_as_binary.md b/doc/development/database/sha1_as_binary.md index 5ad9d106086..bd955c61441 100644 --- a/doc/development/database/sha1_as_binary.md +++ b/doc/development/database/sha1_as_binary.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Storing SHA1 Hashes As Binary diff --git a/doc/development/database/single_table_inheritance.md b/doc/development/database/single_table_inheritance.md index 40b608bd110..ecc42a3b5d1 100644 --- a/doc/development/database/single_table_inheritance.md +++ b/doc/development/database/single_table_inheritance.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Single Table Inheritance @@ -53,8 +53,13 @@ class Animal < ActiveRecord::Base def self.inheritance_column = 'species' end -class Dog < Animal; end -class Cat < Animal; end +class Dog < Animal + self.allow_legacy_sti_class = true +end + +class Cat < Animal + self.allow_legacy_sti_class = true +end ``` If your table already has a `*_type`, new classes for the different types can be added as needed. diff --git a/doc/development/database/strings_and_the_text_data_type.md b/doc/development/database/strings_and_the_text_data_type.md index adb715e219d..70d59603e0c 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Strings and the Text data type diff --git a/doc/development/database/swapping_tables.md b/doc/development/database/swapping_tables.md index f659d1408d3..1c634c6a83e 100644 --- a/doc/development/database/swapping_tables.md +++ b/doc/development/database/swapping_tables.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Swapping Tables diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md index 8477dd180a6..4d3101b40fb 100644 --- a/doc/development/database/table_partitioning.md +++ b/doc/development/database/table_partitioning.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database table partitioning diff --git a/doc/development/database/transaction_guidelines.md b/doc/development/database/transaction_guidelines.md index 1648cf58937..741a40c660f 100644 --- a/doc/development/database/transaction_guidelines.md +++ b/doc/development/database/transaction_guidelines.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Transaction guidelines diff --git a/doc/development/database/understanding_explain_plans.md b/doc/development/database/understanding_explain_plans.md index 3e8978e1046..22c52c04745 100644 --- a/doc/development/database/understanding_explain_plans.md +++ b/doc/development/database/understanding_explain_plans.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Understanding EXPLAIN plans @@ -571,8 +571,8 @@ what if we slightly change the purpose of it? What if instead of retrieving all projects with `visibility_level` 0 or 20, we retrieve those that a user interacted with somehow? -Fortunately, GitLab has an answer for this, and it's a table called -`user_interacted_projects`. This table has the following schema: +Prior to GitLab 16.7, GitLab used a table named `user_interacted_projects` to track user interactions with projects. +This table had the following schema: ```sql Table "public.user_interacted_projects" diff --git a/doc/development/database/verifying_database_capabilities.md b/doc/development/database/verifying_database_capabilities.md index c1dd29082ba..f39ce0ae30c 100644 --- a/doc/development/database/verifying_database_capabilities.md +++ b/doc/development/database/verifying_database_capabilities.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Verifying Database Capabilities diff --git a/doc/development/database_review.md b/doc/development/database_review.md index ba0423a1a0d..ec4c4f9f2c5 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Database Review Guidelines @@ -182,6 +182,7 @@ Include in the MR description: - To produce a query plan with enough data, you can use the IDs of: - The `gitlab-org` namespace (`namespace_id = 9970`), for queries involving a group. - The `gitlab-org/gitlab-foss` (`project_id = 13083`) or the `gitlab-org/gitlab` (`project_id = 278964`) projects, for queries involving a project. + - For queries involving membership of projects, `project_namespace_id` of these projects may be required to create a query plan. These are `15846663` (for `gitlab-org/gitlab`) and `15846626` (for `gitlab-org/gitlab-foss`) - The `gitlab-qa` user (`user_id = 1614863`), for queries involving a user. - Optionally, you can also use your own `user_id`, or the `user_id` of a user with a long history within the project or group being used to generate the query plan. - That means that no query plan should return 0 records or less records than the provided limit (if a limit is included). If a query is used in batching, a proper example batch with adequate included results should be identified and provided. diff --git a/doc/development/dependencies.md b/doc/development/dependencies.md index 3b935ceba22..0acd9472075 100644 --- a/doc/development/dependencies.md +++ b/doc/development/dependencies.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Dependencies diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index d586f25ffbf..7d1551cfc6c 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Deprecating GitLab features diff --git a/doc/development/developing_with_solargraph.md b/doc/development/developing_with_solargraph.md index 7b9912a865e..61e4d3b124a 100644 --- a/doc/development/developing_with_solargraph.md +++ b/doc/development/developing_with_solargraph.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Using Solargraph diff --git a/doc/development/development_seed_files.md b/doc/development/development_seed_files.md index 2bf3688fd48..fbbc1cc7efb 100644 --- a/doc/development/development_seed_files.md +++ b/doc/development/development_seed_files.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Development seed files @@ -18,6 +18,7 @@ data for features. |-------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | DevOps Adoption | `FILTER=devops_adoption bundle exec rake db:seed_fu` | [31_devops_adoption.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/db/fixtures/development/31_devops_adoption.rb) | | Value Streams Dashboard | `FILTER=cycle_analytics SEED_VSA=1 bundle exec rake db:seed_fu` | [17_cycle_analytics.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/db/fixtures/development/17_cycle_analytics.rb) | +| Value Streams Dashboard overview counts | `FILTER=vsd_overview_counts SEED_VSD_COUNTS=1 bundle exec rake db:seed_fu` | [93_vsd_overview_counts.rb](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/db/fixtures/development/93_vsd_overview_counts.rb) | | Value Stream Analytics | `FILTER=customizable_cycle_analytics SEED_CUSTOMIZABLE_CYCLE_ANALYTICS=1 bundle exec rake db:seed_fu` | [30_customizable_cycle_analytics](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/db/fixtures/development/30_customizable_cycle_analytics.rb) | | CI/CD analytics | `FILTER=ci_cd_analytics SEED_CI_CD_ANALYTICS=1 bundle exec rake db:seed_fu` | [38_ci_cd_analytics](https://gitlab.com/gitlab-org/gitlab/-/blob/master/db/fixtures/development/38_ci_cd_analytics.rb?ref_type=heads) | | Contributions Analytics<br><br>Productivity Analytics<br><br>Code review Analytics<br><br>Merge Request Analytics | `FILTER=productivity_analytics SEED_PRODUCTIVITY_ANALYTICS=1 bundle exec rake db:seed_fu` | [90_productivity_analytics](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/db/fixtures/development/90_productivity_analytics.rb) | diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 56c114ba8de..86732c3a8ac 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Distributed tracing development guidelines diff --git a/doc/development/distribution/index.md b/doc/development/distribution/index.md index 168e3854eca..2c164b6745d 100644 --- a/doc/development/distribution/index.md +++ b/doc/development/distribution/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: "GitLab's development guidelines for Distribution" --- diff --git a/doc/development/documentation/contribute.md b/doc/development/documentation/contribute.md deleted file mode 100644 index 2b166266ddb..00000000000 --- a/doc/development/documentation/contribute.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-10-27' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-10-27>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/documentation/drawers.md b/doc/development/documentation/drawers.md index 7ede1a0b652..1dfe50a8c00 100644 --- a/doc/development/documentation/drawers.md +++ b/doc/development/documentation/drawers.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Create content for drawers diff --git a/doc/development/documentation/experiment_beta.md b/doc/development/documentation/experiment_beta.md index fab78082cb5..85f6dc38621 100644 --- a/doc/development/documentation/experiment_beta.md +++ b/doc/development/documentation/experiment_beta.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects stage: none group: unassigned --- diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index a08052bf0e4..617691e8628 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned description: "GitLab development - how to document features deployed behind feature flags" diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index 3c96dd06b25..264ba19226f 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: "Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation." --- diff --git a/doc/development/documentation/help.md b/doc/development/documentation/help.md index a921429bf49..59ffe93f904 100644 --- a/doc/development/documentation/help.md +++ b/doc/development/documentation/help.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # GitLab /help diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index c06a396b378..698bc59a951 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Contribute to the GitLab documentation @@ -76,7 +76,7 @@ Ask for help from the Technical Writing team if you: To identify someone who can help you: 1. Locate the Technical Writer for the relevant - [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). + [DevOps stage group](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments). 1. Either: - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request. - If non-urgent help is required, ping the Technical Writer in the issue or merge request. diff --git a/doc/development/documentation/metadata.md b/doc/development/documentation/metadata.md new file mode 100644 index 00000000000..4e80ea154b3 --- /dev/null +++ b/doc/development/documentation/metadata.md @@ -0,0 +1,92 @@ +--- +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +stage: none +group: unassigned +--- + +# Metadata + +Each documentation Markdown page contains YAML front matter. +All values in the metadata are treated as strings and are used for the +docs website only. + +## Stage and group metadata + +Each page should have metadata related to the stage and group it +belongs to, as well as an information block. For example: + +```yaml +--- +stage: Example Stage +group: Example Group +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- +``` + +To populate the metadata, include this information: + +- `stage`: The [Stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) + that the majority of the page's content belongs to. +- `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups) + that the majority of the page's content belongs to. +- `info`: How to find the Technical Writer associated with the page's stage and + group. + +## Additional metadata + +The following metadata is optional and is not actively maintained. + +- `description`: A short description of what the page is about. See the Google [Best practices for creating quality meta descriptions](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions) for writing tips. This content can be used in search result snippets and is shown in social media previews. +- `feedback`: Set to `false` to not include the "Help & Feedback" footer. +- `noindex`: Set to `false` to prevent the page from being indexed by search engines. +- `redirect_to`: Used to control redirects. For more information, see [Redirects in GitLab documentation](redirects.md). +- `searchbar`: Set to `false` to not include the search bar in the page header. +- `toc`: Set to `false` to not include the "On this page" navigation. + +## Batch updates for TW metadata + +The [`CODEOWNERS`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS) +file contains a list of files and the associated technical writers. + +When a merge request contains documentation, the information in the `CODEOWNERS` file determines: + +- The list of users in the **Approvers** section. +- The technical writer that the GitLab Bot pings for community contributions. + +You can use a Rake task to update the `CODEOWNERS` file. + +### Update the `CODEOWNERS` file + +When groups or [TW assignments](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments) +change, you must update the `CODEOWNERS` file: + +1. Update the [stage and group metadata](#stage-and-group-metadata) for any affected doc pages, if necessary. If there are many changes, you can do this step in a separate MR. +1. Update the [`codeowners.rake`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) file with the changes. +1. Go to the root of the `gitlab` repository. +1. Run the Rake task with this command: `bundle exec rake tw:codeowners` +1. Review the changes in the `CODEOWNERS` file. +1. Add and commit all your changes and push your branch up to `origin`. +1. Create a merge request and assign it to a technical writing manager for review. + +When you update the `codeowners.rake` file: + +- To specify multiple writers for a single group, use a space between writer names. Files are assigned to both writers. + + ```ruby + CodeOwnerRule.new('Group Name', '@writer1 @writer2'), + ``` + + - To assign different writers within a group to docs in different directories, use the `path` parameter to specify a directory: + + ```ruby + CodeOwnerRule.new('Group Name', ->(path) { path.start_with?('/doc/user') ? '@writer1' : '@writer2' }), + ``` + + In this example, `writer1` is a code owner for files related to this group that are in `/doc/user`. + For everything else, `writer2` is made code owner. For an example, see [MR 127903](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127903). + +- For a group that does not have an assigned writer, include the group name in the file and comment out the line: + + ```ruby + # CodeOwnerRule.new('Group Name', ''), + ``` diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index f080625ea9c..056ef9d3d62 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. description: Learn how to contribute to GitLab Documentation. --- diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index a53330a7e63..66bb662e1c7 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned description: 'Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs.' @@ -24,7 +24,7 @@ In the Markdown doc for a resource (AKA endpoint): - Every method must have the REST API request. For example: ```plaintext - GET /projects/:id/repository/branches + GET /api/v4/projects/:id/repository/branches ``` - Every method must have a detailed [description of the attributes](#method-description). @@ -57,7 +57,7 @@ One or two sentence description of what endpoint does. Description of the method. ```plaintext -METHOD /endpoint +METHOD /api/v4/endpoint ``` Supported attributes: diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md index 483145d1f44..2402a15e61b 100644 --- a/doc/development/documentation/review_apps.md +++ b/doc/development/documentation/review_apps.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. description: Learn how documentation review apps work. --- @@ -44,7 +44,7 @@ the GitLab team to run the job. If you want to know the in-depth details, here's what's really happening: 1. You manually run the `review-docs-deploy` job in a merge request. -1. The job runs the [`scripts/trigger-build.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build.rb) +1. The job downloads and runs the [`scripts/trigger-build.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build.rb) script with the `docs deploy` flag, which triggers the "Triggered from `gitlab-org/gitlab` 'review-docs-deploy' job" pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `main`). 1. The preview URL is shown both at the job output and in the merge request @@ -64,6 +64,69 @@ The following GitLab features are used among others: - [Artifacts](../../ci/yaml/index.md#artifacts) - [Merge request pipelines](../../ci/pipelines/merge_request_pipelines.md) +## How to add a new documentation review app + +In case a documentation review app is missing from one of the documentation +projects, you can use the following CI/CD template to add a manually triggered review app: + +```yaml +# Set up documentation review apps +# https://docs.gitlab.com/ee/development/documentation/review_apps.html +.review-docs: + image: ruby:3.1-alpine + needs: [] + before_script: + - gem install gitlab --no-doc + # We need to download the script rather than clone the repo since the + # review-docs-cleanup job will not be able to run when the branch gets + # deleted (when merging the MR). + - apk add --update openssl + - wget https://gitlab.com/gitlab-org/gitlab/-/raw/master/scripts/trigger-build.rb + - chmod 755 trigger-build.rb + variables: + GIT_STRATEGY: none + DOCS_REVIEW_APPS_DOMAIN: docs.gitlab-review.app + # By default, deploy the Review App using the `main` branch of the `gitlab-org/gitlab-docs` project + DOCS_BRANCH: main + when: manual + allow_failure: true + +# Trigger a docs build in gitlab-docs +# Useful to preview the docs changes live +# https://docs.gitlab.com/ee/development/documentation/index.html#previewing-the-changes-live +review-docs-deploy: + extends: + - .review-docs + environment: + name: review-docs/mr-${CI_MERGE_REQUEST_IID} + # DOCS_REVIEW_APPS_DOMAIN and DOCS_GITLAB_REPO_SUFFIX are CI variables + # Discussion: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/14236/diffs#note_40140693 + auto_stop_in: 2 weeks + url: https://${DOCS_BRANCH}-${DOCS_GITLAB_REPO_SUFFIX}-${CI_MERGE_REQUEST_IID}.${DOCS_REVIEW_APPS_DOMAIN}/${DOCS_GITLAB_REPO_SUFFIX} + on_stop: review-docs-cleanup + script: + - ./trigger-build.rb docs deploy + +# Cleanup remote environment of gitlab-docs +review-docs-cleanup: + extends: + - .review-docs + environment: + name: review-docs/mr-${CI_MERGE_REQUEST_IID} + action: stop + script: + - ./trigger-build.rb docs cleanup +``` + +You may need to add some rules when those jobs run, it depends on the project. +You can find the current implementations: + +- [GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml) +- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/ee8699658c8a7d4c635ad503ef0b825ac592dc4b/gitlab-ci-config/gitlab-com.yml#L367-391) +- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/.gitlab/ci/docs.gitlab-ci.yml) +- [GitLab Charts](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/aae7ee8d23a60d6025eec7d1a864ce244f21cd85/.gitlab-ci.yml#L629-679) +- [GitLab Operator](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/5fa29607cf9286b510148a8f5fef7595dca34186/.gitlab-ci.yml#L180-228) + ## Troubleshooting review apps ### `NoSuchKey The specified key does not exist` diff --git a/doc/development/documentation/site_architecture/automation.md b/doc/development/documentation/site_architecture/automation.md index 5b2b02ad97e..75e69e848e8 100644 --- a/doc/development/documentation/site_architecture/automation.md +++ b/doc/development/documentation/site_architecture/automation.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Automated pages @@ -57,7 +57,7 @@ If you want to automate a page on the docs site: 1. Review [issue 823](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/823) and consider adding feedback there. 1. If that issue does not describe what you need, contact - [the DRI for the docs site backend](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects). + [the DRI for the docs site backend](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects). Because automation adds extra complexity and a support burden, we review it on a case-by-case basis. diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 767fdf907d6..7f232ad0c0d 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Documentation deployments diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md index d4a3c856e0a..739c432ee27 100644 --- a/doc/development/documentation/site_architecture/folder_structure.md +++ b/doc/development/documentation/site_architecture/folder_structure.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Folder structure for documentation diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 3e0534220a8..0dfe538cfbd 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. description: "Learn how GitLab docs' global navigation works and how to add new items." --- diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 822c7992222..d2de745a8b7 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Documentation site architecture @@ -61,7 +61,7 @@ Then you can use one of these approaches: [to the global navigation](global_nav.md#add-a-navigation-entry), but keep the rest of the documentation in the external repository. The landing page is indexed and searchable on <https://docs.gitlab.com>, but the rest of the documentation is not. - For example, the [GitLab Workflow extension for VS Code](../../../user/project/repository/vscode.md). + For example, the [GitLab Workflow extension for VS Code](../../../editor_extensions/visual_studio_code/index.md). We do not encourage the use of [pages with lists of links](../topic_types/index.md#pages-and-topics-to-avoid), so only use this option if the recommended options are not feasible. @@ -77,3 +77,19 @@ code review. For docs changes in merge requests, whenever a change to files unde is made, Danger Bot leaves a comment with further instructions about the documentation process. This is configured in the `Dangerfile` in the GitLab repository under [/danger/documentation/](https://gitlab.com/gitlab-org/gitlab/-/tree/master/danger/documentation). + +## Request a documentation survey banner + +To reach to a wider audience, you can request +[a survey banner](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/maintenance.md#survey-banner). + +Only one banner can exist at any given time. Priority is given based on who +asked for the banner first. + +To request a survey banner: + +1. [Open an issue](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/new?issue[title]=Survey%20banner%20request&issuable_template=Survey%20banner%20request) + in the `gitlab-docs` project and use the "Survey banner request" template. +1. Fill in the details in the issue description. +1. Create the issue and someone from the Technical Writing team will handle your request. +1. When you no longer need the banner, ping the person assigned to the issue and ask them to remove it. diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 6158d60a0ba..26660d2eba1 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' @@ -147,105 +147,61 @@ Use backticks for: - Commands, parameters, and filenames. - Values. For example: "In the **Name** text box, type `test`." -## Metadata - -Each documentation Markdown page contains YAML front matter. -All values in the metadata are treated as strings and are used for the -docs website only. - -### Stage and group metadata - -Each page should have metadata related to the stage and group it -belongs to, as well as an information block. For example: - -```yaml ---- -stage: Example Stage -group: Example Group -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments ---- -``` - -To populate the metadata, include this information: - -- `stage`: The [Stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) - that the majority of the page's content belongs to. -- `group`: The [Group](https://about.gitlab.com/company/team/structure/#product-groups) - that the majority of the page's content belongs to. -- `info`: How to find the Technical Writer associated with the page's stage and - group. +## Language -### Additional metadata +GitLab documentation should be clear and easy to understand. -The following metadata is optional and is not actively maintained. +- Avoid unnecessary words. +- Be clear, concise, and stick to the goal of the topic. +- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) -- `description`: A short description of what the page is about. See the Google [Best practices for creating quality meta descriptions](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions) for writing tips. This content can be used in search result snippets and is shown in social media previews. -- `feedback`: Set to `false` to not include the "Help & Feedback" footer. -- `noindex`: Set to `false` to prevent the page from being indexed by search engines. -- `redirect_to`: Used to control redirects. For more information, see [Redirects in GitLab documentation](../redirects.md). -- `searchbar`: Set to `false` to not include the search bar in the page header. -- `toc`: Set to `false` to not include the "On this page" navigation. +### Active voice -### Deprecated metadata +In most cases, text is easier to understand and to translate if you use active voice instead of passive. -The `type` metadata parameter is deprecated but still exists in documentation -pages. You can remove the `type` metadata parameter and its values. +For example, use: -### Batch updates for TW metadata +- The developer writes code for the application. -The [`CODEOWNERS`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS) -file contains a list of files and the associated technical writers. +Instead of: -When a merge request contains documentation, the information in the `CODEOWNERS` file determines: +- Application code is written by the developer. -- The list of users in the **Approvers** section. -- The technical writer that the GitLab Bot pings for community contributions. +Sometimes, using `GitLab` as the subject can be awkward. For example, `GitLab exports the report`. +In this case, you can use passive voice instead. For example, `The report is exported`. -You can use a Rake task to update the `CODEOWNERS` file. +### Customer perspective -#### Update the `CODEOWNERS` file +Focus on the functionality and benefits that GitLab brings to customer, +rather than what GitLab has created. -When groups or [TW assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) -change, you must update the `CODEOWNERS` file: +For example, use: -1. Update the [stage and group metadata](#stage-and-group-metadata) for any affected doc pages, if necessary. If there are many changes, you can do this step in a separate MR. -1. Update the [`codeowners.rake`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/tw/codeowners.rake) file with the changes. -1. Go to the root of the `gitlab` repository. -1. Run the Rake task with this command: `bundle exec rake tw:codeowners` -1. Review the changes in the `CODEOWNERS` file. -1. Add and commit all your changes and push your branch up to `origin`. -1. Create a merge request and assign it to a technical writing manager for review. +- Use merge requests to compare code in the source and target branches. -When you update the `codeowners.rake` file: +Instead of: -- To specify multiple writers for a single group, use a space between writer names. Files are assigned to both writers. +- GitLab allows you to compare code. +- GitLab created the ability to let you compare code. +- Merge requests let you compare code. - ```ruby - CodeOwnerRule.new('Group Name', '@writer1 @writer2'), - ``` +Words that indicate you are not writing from a customer perspective are +[allow and enable](word_list.md#allow-enable). Try instead to use +[you](word_list.md#you-your-yours) and to speak directly to the user. - - To assign different writers within a group to docs in different directories, use the `path` parameter to specify a directory: +### Building trust - ```ruby - CodeOwnerRule.new('Group Name', ->(path) { path.start_with?('/doc/user') ? '@writer1' : '@writer2' }), - ``` +Product documentation should be focused on providing clear, concise information, +without the addition of sales or marketing text. - In this example, `writer1` is a code owner for files related to this group that are in `/doc/user`. - For everything else, `writer2` is made code owner. For an example, see [MR 127903](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127903). +- Do not use words like [easily](word_list.md#easily) or [simply](word_list.md#simply-simple). +- Do not use marketing phrases like "This feature will save you time and money." -- For a group that does not have an assigned writer, include the group name in the file and comment out the line: +Instead, focus on facts and achievable goals. Be specific. For example: - ```ruby - # CodeOwnerRule.new('Group Name', ''), - ``` - -## Language - -GitLab documentation should be clear and easy to understand. - -- Avoid unnecessary words. -- Be clear, concise, and stick to the goal of the topic. -- Write in US English with US grammar. (Tested in [`British.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml).) +- The build time can decrease when you use this feature. +- You can use this feature to save time when you create a project. The API creates the file and you + do not need to manually intervene. ### Capitalization @@ -262,8 +218,6 @@ Use sentence case for topic titles. For example: When referring to specific user interface text, like a button label or menu item, use the same capitalization that's displayed in the user interface. -Standards for this content are listed in the [Pajamas Design System Content section](https://design.gitlab.com/content/punctuation/) -and typically match what's mentioned in this Documentation Style Guide. If you think the user interface text contains style mistakes, create an issue or an MR to propose a change to the user interface text. @@ -350,10 +304,10 @@ Some contractions, however, should be avoided: | Do not use a contraction | Example | Use instead | |-------------------------------|--------------------------------------------------|------------------------------------------------------------------| -| With a proper noun and a verb | The **Container Registry's** a powerful feature. | The **Container Registry** is a powerful feature. | +| With a proper noun and a verb | **Terraform's** a helpful tool. | **Terraform** is a helpful tool. | | To emphasize a negative | **Don't** install X with Y. | **Do not** install X with Y. | | In reference documentation | **Don't** set a limit. | **Do not** set a limit. | -| In error messages | Requests to localhost **aren't** allowed. | Requests to localhost **are not** allowed. | +| In error messages | Requests to localhost **aren't** allowed. | Requests to localhost **are not** allowed. | <!-- vale gitlab.Possessive = YES --> @@ -559,9 +513,13 @@ about styling cURL commands. ## Lists +Use lists to present information in a format that is easier to scan. + +- Make all items in the list parallel. + For example, do not start some bullets with nouns and others with verbs. - Do not use a period if the phrase is not a full sentence. - Use a period after every sentence. Do not use semicolons or commas. -- Majority rules. All items should have the same punctuation. +- Give all items the same punctuation. - Start list items with a capital letter. - Separate the introductory phrase from explanatory text with a colon (`:`). For example: @@ -754,8 +712,20 @@ Instead, follow the [API topic template](../restful_api_styleguide.md#api-topic- ### Footnotes -To indicate a footnote, use the HTML tag `<sup>` with a number. -Put the tag at the end of the sentence or term. For example: +Use footnotes below tables when it's not suitable to include the content in the table +itself. For example, use footnotes when you need to: + +- Provide the same reference information on several table cells. +- Include content that would disrupt the table's layout. + +#### Footnote format + +For each footnote, use the HTML superscript tag `<sup>`. +Put the tag at the end of the sentence or term. + +When you add a footnote, do not re-sort the existing tags in the table. + +For example: ```markdown | App name | Description | @@ -1010,7 +980,9 @@ Guidance for each individual UI element is in [the word list](word_list.md). ### How to write navigation task steps -To be consistent, use these templates when you write navigation steps in a task topic. +To be consistent, use these examples to write navigation steps in a task topic. +Although alternative steps might exist, including items pinned by default, +use these steps instead. To open project settings: @@ -1051,10 +1023,12 @@ To create a group: To open the Admin Area: ```markdown -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD**. ``` +You do not need to repeat `On the left sidebar` in your second step. + To open the **Your work** menu item: ```markdown diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 1888d72f991..9d0d59e27c5 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- @@ -50,7 +50,7 @@ Don't use backticks. Spell out **two-factor authentication** in sentence case for the first use and in topic titles, and **2FA** thereafter. If the first word in a sentence, do not capitalize `factor` or `authentication`. For example: -- Two-factor authentication (2FA) helps secure your account. Set up 2FA when you first log in. +- Two-factor authentication (2FA) helps secure your account. Set up 2FA when you first sign in. ## above @@ -77,28 +77,15 @@ When you create a user, you choose an access level: **Regular**, **Auditor**, or Capitalize these words when you refer to the UI. Otherwise use lowercase. -## active voice - -Use active voice instead of passive. - -Use: - -- The contributor writes the documentation. - -Instead of: - -- The documentation is written by contributors. - -NOTE: -If you can add the phrase "by zombies" to the phrase, -the construction is passive. For example, `The button is selected by zombies` -is passive. `Zombies select the button` is active. - ## Admin Area Use title case for **Admin Area**. This area of the UI says **Admin Area** at the top of the page and on the menu. +## Admin Mode + +Use title case for **Admin Mode**. The UI uses title case. + ## administrator Use **administrator access** instead of **admin** when talking about a user's access level. @@ -235,8 +222,8 @@ Try to avoid **below** when referring to an example or table in a documentation Use uppercase for **Beta**. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** -You might also want to link to [this section](../../../policy/experiment-beta-support.md#beta) -in the handbook when writing about Beta features. +You might also want to link to [this topic](../../../policy/experiment-beta-support.md#beta) +when writing about Beta features. ## blacklist @@ -307,9 +294,18 @@ Use **check out** as a verb. For the Git command, use `checkout`. - Use `git checkout` to check out a branch locally. - Check out the files you want to edit. +## CI, CD + +When talking about GitLab features, use **CI/CD**. Do not use **CI** or **CD** alone. + ## CI/CD -CI/CD is always uppercase. No need to spell it out on first use. +**CI/CD** is always uppercase. No need to spell it out on first use. + +You can omit **CI/CD** when the context is clear, especially after the first use. For example: + +- Test your code in a **CI/CD pipeline**. Configure the **pipeline** to run for merge requests. +- Store the value in a **CI/CD variable**. Set the **variable** to masked. ## CI/CD minutes @@ -384,6 +380,18 @@ Use **compute minutes** instead of these (or similar) terms: For more information, see [epic 2150](https://gitlab.com/groups/gitlab-com/-/epics/2150). +## configuration + +When you update a collection of settings, call it a **configuration**. + +## configure + +Use **configure** after a feature or product has been [set up](#setup-set-up). +For example: + +1. Set up your installation. +1. Configure your installation. + ## confirmation dialog Use **confirmation dialog** to describe the dialog that asks you to confirm an action. For example: @@ -394,7 +402,7 @@ Do not use **confirmation box** or **confirmation dialog box**. See also [**dial ## container registry -When documenting the GitLab container registry features and functionality, use lower case. +When documenting the GitLab container registry features and functionality, use lowercase. Use: @@ -505,6 +513,13 @@ To be more upbeat and precise, do not use **downgrade**. Focus instead on the ac - For changing to earlier GitLab versions, use [**roll back**](#roll-back). - For changing to lower GitLab tiers, use **change the subscription tier**. +## download + +Use **download** to describe saving data to a user's device. For details, see +[the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/download). + +Do not confuse download with [export](#export). + ## dropdown list Use **dropdown list** to refer to the UI element. Do not use **dropdown** without **list** after it. @@ -611,14 +626,41 @@ Use **expand** instead of **open** when you are talking about expanding or colla Use uppercase for **Experiment**. For example: **The XYZ feature is an Experiment.** or **This Experiment is ready to test.** -You might also want to link to [this section](../../../policy/experiment-beta-support.md#experiment) -in the handbook when writing about Experiment features. +You might also want to link to [this topic](../../../policy/experiment-beta-support.md#experiment) +when writing about Experiment features. + +## export + +Use **export** to indicate translating raw data, +which is not represented by a file in GitLab, into a standard file format. + +You can differentiate **export** from **download** because: + +- Often, you can use export options to change the output. +- Exported data is not necessarily downloaded to a user's device. + +For example: + +- Export the contents of your report to CSV format. + +Do not confuse with [download](#download). ## FAQ We want users to find information quickly, and they rarely search for the term **FAQ**. Information in FAQs belongs with other similar information, under an easily searchable topic title. +## feature + +You should rarely need to use the word **feature**. Instead, explain what GitLab does. +For example, use: + +- Use merge requests to incorporate changes into the target branch. + +Instead of: + +- Use the merge request feature to incorporate changes into the target branch. + ## field Use **text box** instead of **field** or **box**. @@ -641,6 +683,12 @@ of the fields at once. For example: Learn more about [documenting multiple fields at once](index.md#documenting-multiple-fields-at-once). +## file name + +Use two words for **file name**. When using file name as a variable, use `<file_name>`. + +([Vale](../testing.md#vale) rule: [`SubstitutionWarning.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionWarning.yml)) + ## filter When you are viewing a list of items, like issues or merge requests, you filter the list by @@ -655,14 +703,19 @@ Do not use **foo** in product documentation. You can use it in our API and contr ## fork A **fork** is a project that was created from a **upstream project** by using the -[forking process](../../../topics/git/terminology.md#fork). +forking process. The **upstream project** (also known as the **source project**) and the **fork** have a **fork relationship** and are **linked**. -If the [**fork relationship** is removed](../../../user/project/repository/forking_workflow.md#unlink-a-fork), the +If the **fork relationship** is removed, the **fork** is **unlinked** from the **upstream project**. +## full screen + +Use two words for **full screen**. +([Vale](../testing.md#vale) rule: [`SubstitutionWarning.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionWarning.yml)) + ## future tense When possible, use present tense instead of future tense. For example, use **after you execute this command, GitLab displays the result** instead of **after you execute this command, GitLab will display the result**. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) @@ -698,7 +751,8 @@ Do not use **Dedicated** by itself. Always use **GitLab Dedicated**. Do not use **Duo** by itself. Always use **GitLab Duo**. -On first use on a page, use **GitLab Duo `<featurename>`**. For example: +On first use on a page, use **GitLab Duo `<featurename>`**. As of Dec, 2023, +the following are the names of GitLab Duo features: - GitLab Duo Chat - GitLab Duo Code Suggestions @@ -709,6 +763,7 @@ On first use on a page, use **GitLab Duo `<featurename>`**. For example: - GitLab Duo Code review summary - GitLab Duo Code explanation - GitLab Duo Vulnerability summary +- GitLab Duo Vulnerability resolution - GitLab Duo Test generation - GitLab Duo Git suggestions - GitLab Duo Root cause analysis @@ -966,7 +1021,15 @@ Do not use **limitations**. Use **known issues** instead. ## log in, log on -Do not use **log in** or **log on**. Use [sign in](#sign-in-sign-in) instead. If the user interface has **Log in**, you can use it. +Do not use: + +- **log in**. +- **log on**. +- **login** + +Use [sign in](#sign-in-sign-in) instead. + +However, if the user interface has **Log in**, you should match the UI. ## logged-in user, logged in user @@ -985,6 +1048,14 @@ Instead of: - In GitLab 14.1 and lower. - In GitLab 14.1 and older. +## machine learning + +Use lowercase for **machine learning**. + +When machine learning is used as an adjective, like **a machine learning model**, +do not hyphenate. While a hyphen might be more grammatically correct, we risk +becoming inconsistent if we try to be more precise. + ## Maintainer When writing about the Maintainer role: @@ -1252,9 +1323,14 @@ Do not use bold. Do not use **Owner permissions**. A user who is assigned the Owner role has a set of associated permissions. An Owner is the highest role a user can have. -## Package Registry +## package registry -Use title case for the GitLab Package Registry. +When documenting the GitLab package registry features and functionality, use lowercase. + +Use: + +- The GitLab package registry supports A, B, and C. +- You can publish a package to your project's package registry. ## page @@ -1289,10 +1365,16 @@ see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a- Use **Premium**, in uppercase, for the subscription tier. When you refer to **Premium** in the context of other subscription tiers, follow [the subscription tier](#subscription-tier) guidance. +## preferences + +Use **preferences** to describe user-specific, system-level settings like theme and layout. + ## prerequisites Use **prerequisites** when documenting the tasks that must be completed or the conditions that must be met before a user can complete a task. Do not use **requirements**. +**Prerequisites** must always be plural, even if the list includes only one item. + For more information, see [the task topic type](../topic_types/task.md). For tutorial page types, use [**before you begin**](#before-you-begin) instead. @@ -1367,6 +1449,17 @@ Do not use **Reporter permissions**. A user who is assigned the Reporter role ha Use title case for **Repository Mirroring**. +## resolution, resolve + +Use **resolution** when the troubleshooting solution fixes the issue permanently. +A resolution usually involves file and code changes to correct the problem. +For example: + +- To resolve this issue, update the `.gitlab-ci.yml` file. +- One resolution is to update the `.gitlab-ci.yml` file. + +See also [workaround](#workaround). + ## requirements When documenting the tasks that must be completed or the conditions that must be met before a user can complete the steps: @@ -1376,6 +1469,10 @@ When documenting the tasks that must be completed or the conditions that must be Do not use **requirements**. +## reset + +Use **reset** to describe the action associated with resetting an item to a new state. + ## respectively Avoid **respectively** and be more precise instead. @@ -1389,6 +1486,10 @@ Instead of: - Select **Create user** or **Save changes** if you created a new user or edited an existing one respectively. +## restore + +See the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/r/restore) for guidance on **restore**. + ## review app Use lowercase for **review app**. @@ -1508,18 +1609,37 @@ Use **setup** as a noun, and **set up** as a verb. For example: - Your remote office setup is amazing. - To set up your remote office correctly, consider the ergonomics of your work area. +Do not confuse **set up** with [**configure**](#configure). +**Set up** implies that it's the first time you've done something. For example: + +1. Set up your installation. +1. Configure your installation. + +## settings + +A **setting** changes the default behavior of the product. A **setting** consists of a key/value pair, +typically represented by a label with one or more options. + ## sign in, sign-in -Use **sign in** or **sign in to** as a verb to describe the action of signing in. +To describe the action of signing in, use: -Do not use **sign on** or **sign into**, or **log on**, **log in**, or **log into**. +- **sign in**. +- **sign in to** as a verb. For example: Use your password to sign in to GitLab. -If the user interface has different words, use those. +You can also use: + +- **sign-in** as a noun or adjective. For example: **sign-in page** or + **sign-in restrictions**. +- **single sign-on**. + +Do not use: -You can use **sign-in** as a noun or adjective. For example, **sign-in page** or -**sign-in restrictions**. +- **sign on**. +- **sign into**. +- [**log on**, **log in**, or **log into**](#log-in-log-on). -You can use **single sign-on**. +If the user interface has different words, you can use those. ## sign up @@ -1709,6 +1829,10 @@ See also [**enter**](#enter). Use **Ultimate**, in uppercase, for the subscription tier. When you refer to **Ultimate** in the context of other subscription tiers, follow [the subscription tier](#subscription-tier) guidance. +## undo + +See the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/undo) for guidance on **undo**. + ## units of measurement Use a space between the number and the unit of measurement. For example, **128 GB**. @@ -1762,6 +1886,19 @@ Do not use **useful**. If the user doesn't find the process to be useful, we los You create a **user account**. The user account has an [access level](#access-level). When you add a **user account** to a group or project, the user account becomes a **member**. +## using + +Avoid **using** in most cases. It hides the subject and makes the phrase more difficult to translate. +Use **by using**, **that use**, or re-write the sentence. + +For example: + +- Instead of: The files using storage... +- Use: The files that use storage... + +- Instead of: Change directories using the command line. +- Use: Change directories by using the command line. Or even better: To change directories, use the command line. + ## utilize Do not use **utilize**. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. @@ -1777,6 +1914,13 @@ Thereafter, use **Value stream forecasting** by itself. Do not use Latin abbreviations. Use **with**, **through**, or **by using** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml)) +## Vulnerability resolution + +Use sentence case for **Vulnerability resolution**. + +On first mention on a page, use **GitLab Duo Vulnerability resolution**. +Thereafter, use **Vulnerability resolution** by itself. + ## Vulnerability summary Use sentence case for **Vulnerability summary**. @@ -1798,6 +1942,16 @@ Instead of: ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) +## workaround + +Use **workaround** when the troubleshooting solution is a temporary fix. +A workaround is usually an immediate fix and might have ongoing issues. +For example: + +- The workaround is to temporarily pin your template to the deprecated version. + +See also [resolution](#resolution-resolve). + ## while Use **while** to refer only to something occurring in time. For example, diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 414c2bede7b..62df2395fbb 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. description: Learn how to contribute to GitLab Documentation. --- @@ -629,8 +629,7 @@ You can disable a specific Vale linting rule or all Vale linting rules for any p document: - To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a - `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename - of a test in the + `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the file name of a test in the [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) directory. - To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index 50220b9bebe..fe9a6f8af71 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Concept topic type @@ -19,6 +19,8 @@ Don't tell them **how** to do this thing. Tell them **what it is**. If you start describing another concept, start a new concept and link to it. +## Format + Concepts should be in this format: ```markdown diff --git a/doc/development/documentation/topic_types/get_started.md b/doc/development/documentation/topic_types/get_started.md new file mode 100644 index 00000000000..b43f9a1b71c --- /dev/null +++ b/doc/development/documentation/topic_types/get_started.md @@ -0,0 +1,92 @@ +--- +stage: none +group: Style Guide +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +--- + +# Get started page type + +A **Get started** page is meant to introduce high-level concepts for a broad feature area. +While a specific feature might be defined in the feature documentation, +a **Get started** page is meant to give an introduction to a set of concepts. +When you group the concepts together, you help the user see how they fit together. + +A **Get started** page should familiarize the reader with terms and then quickly +point them to actions they can take to get started. Hopefully the actions are +task-based, but the next step can also be to learn more. + +## When to use a Get started page + +A **Get started** page should be used only for a larger concept, +like CI/CD or security. In general, we describe features in concept topics. +However, if you find you want to explain how multiple concepts fit together, +then a **Get started** page might be what you need. + +To determine if a **Get started** page makes sense, make a list +of the common terms you expect to include. If you have more than four or five, +then this page type might make sense. + +A **Get started** page is different from a tutorial. It's conceptual, while +a tutorial helps the user achieve a task. A **Get started** page should point +to tutorials, however, because tutorials are a great way for a user to get started. + +## Format + +Get started pages should be in this format: + +```markdown +# Get started with abc + +Abc is a thing you use to do xyz. You might use it when you need to blah, +and it can be helpful for etc. + +## Common terms + +If you're new to abc, start by reviewing some of the most commonly used terms. + +### First term + +This thing is this. Describe what it is, not how to do it. + +**Get started:** + +- [Create your first abc](LINK). +- [Learn more about abc](LINK). + +### Second term + +This thing is this. Describe what it is, not how to do it. + +**Get started:** + +- [Create your first abc](LINK). +- [Learn more about abc](LINK). + +## Videos + +- [Video 1](LINK). +- [Video 2](LINK). + +## Related topics + +- [Link 1](LINK). +- [Link 2](LINK). +``` + +- Follow [the video guidance](../styleguide/index.md#link-to-video) + for the links in the Video topic. +- Do not use links inline with content (as part of sentences). + Use them where links are specified only. +- The terms described on this page can exist elsewhere in the docs. + However, the term descriptions on this page should be relatively brief. + +## Get started page titles + +For the title, use `Get started with topic_name`. + +For the left nav, use `Getting started`. + +## Example + +For an example of the Get started page type, +see [Get started with GitLab CI/CD](../../../ci/index.md). diff --git a/doc/development/documentation/topic_types/glossary.md b/doc/development/documentation/topic_types/glossary.md index f6137953cb0..ee72ad76855 100644 --- a/doc/development/documentation/topic_types/glossary.md +++ b/doc/development/documentation/topic_types/glossary.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Glossary topic type diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index 10e7e3d2014..b4f28ad46d3 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Documentation topic types (CTRT) @@ -24,6 +24,7 @@ The acronym refers to the first letter of each topic type. In addition to the four primary topic types, you can use the following: - Page type: [Tutorials](tutorial.md) +- Page type: [Get started](get_started.md) - Topic type: [Related topics](#related-topics) - Page or topic type: [Glossaries](glossary.md) @@ -36,7 +37,6 @@ You should avoid: - Topics that have one or two sentences only. In these cases: - Incorporate the information in another topic. - If the sentence links to another page, use a [Related topics](#related-topics) link instead. -- Get started topics. To document a procedure for a single feature, use a [task](task.md). For a set of steps, use a [tutorial](tutorial.md). ## Topic title guidelines diff --git a/doc/development/documentation/topic_types/reference.md b/doc/development/documentation/topic_types/reference.md index ef2ca2f791d..f9db71aa9f8 100644 --- a/doc/development/documentation/topic_types/reference.md +++ b/doc/development/documentation/topic_types/reference.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Reference topic type @@ -9,6 +9,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w Reference information should be in an easily-scannable format, like a table or list. It's similar to a dictionary or encyclopedia entry. +## Format + +Reference topics should be in this format: + ```markdown # Title (a noun, like "Pipeline settings" or "Administrator options") diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index a6e4c01505d..2130a28c56c 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -1,13 +1,15 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Task topic type A task gives instructions for how to complete a procedure. +## Format + Tasks should be in this format: ```markdown @@ -153,6 +155,8 @@ As a best practice, if the task requires the user to have a role other than Gues put the minimum role in the prerequisites. See [the Word list](../styleguide/word_list.md) for how to write the phrase for each role. +`Prerequisites` must always be plural, even if the list includes only one item. + ## Related topics - [How to write task steps](../styleguide/index.md#navigation) diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md index a2fe6f8ca2d..aee5bd1377c 100644 --- a/doc/development/documentation/topic_types/troubleshooting.md +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -1,15 +1,17 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Troubleshooting topic type Troubleshooting topics should be the final topics on a page. -If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page `Troubleshooting <feature>` -and in the left nav, use the word `Troubleshooting` only. +If a page has five or more troubleshooting topics, put those topics on a separate page. + +- Name the page `Troubleshooting <feature>`. +- In the left nav, use the word `Troubleshooting` only. ## What type of troubleshooting information to include @@ -25,7 +27,7 @@ If you think you have an exception to this rule, contact the Technical Writing t GitLab Support maintains their own [troubleshooting content](../../../administration/troubleshooting/index.md). -## Troubleshooting topic types +## Format Troubleshooting can be one of three types: introductory, task, or reference. @@ -47,7 +49,7 @@ For example, "Run debug tools" or "Verify syntax." ### Troubleshooting reference -This topic includes the error message. For example: +This topic includes the error message. To be consistent, use **workaround** for temporary solutions and **resolution** and **resolve** for permanent solutions. For example: ```markdown ### The error message or a description of it @@ -59,9 +61,11 @@ This issue occurs when... The workaround is... ``` -If multiple causes or workarounds exist, consider putting them into a table format. +If multiple causes or solutions exist, consider putting them into a table format. If you use the exact error message, surround it in backticks so it's styled as code. +For more guidance on solution types, see [workaround](../../documentation/styleguide/word_list.md#workaround) and [resolution, resolve](../../documentation/styleguide/word_list.md#resolution-resolve). + ## Troubleshooting topic titles For the title of a **Troubleshooting reference** topic: diff --git a/doc/development/documentation/topic_types/tutorial.md b/doc/development/documentation/topic_types/tutorial.md index 50976149cf8..c5eeceac4cb 100644 --- a/doc/development/documentation/topic_types/tutorial.md +++ b/doc/development/documentation/topic_types/tutorial.md @@ -1,7 +1,7 @@ --- stage: none group: Documentation Guidelines -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial page type diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index bd83ed7eff2..22fda69094b 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -1,5 +1,5 @@ --- -info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' @@ -69,6 +69,16 @@ If a feature is moved to another subscription tier, use `moved`: > - [Moved](<link-to-issue>) from GitLab Premium to GitLab Free in 12.0. ``` +#### Changing the feature status + +If the feature status changes, use `changed`: + +```markdown +> - [Introduced](<link-to-issue>) as an [Experiment](../../policy/experiment-beta-support.md) in GitLab 15.7. +> - [Changed](<link-to-issue>) to Beta in GitLab 16.0. +> - [Changed](<link-to-issue>) to Generally Available in GitLab 16.3. +``` + #### Features introduced behind feature flags When features are introduced behind feature flags, you must add details about the feature flag to the documentation. @@ -155,7 +165,7 @@ To remove a page: --- stage: Data Stores group: Global Search - info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments + info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments remove_date: '2022-08-02' redirect_to: '../newpath/to/file/index.md' --- diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 5c99f5c48df..965559bd217 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: For assistance with this Style Guide page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Documentation workflow @@ -95,7 +95,7 @@ For these reasons, do not add AI-generated content to the documentation. ## Related topics - [Reviews and levels of edit](https://about.gitlab.com/handbook/product/ux/technical-writing/#reviews) -- [Technical writing assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) +- [Technical writing assignments](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments) - The [Style Guide](styleguide/index.md) - The [Word list](styleguide/word_list.md) - The [Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index d05249f3d3f..08045675295 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Guidelines for implementing Enterprise Edition features @@ -133,16 +133,14 @@ version of the product: 1. Enable **Allow use of licensed EE features** to make licensed EE features available to projects only if the project namespace's plan includes the feature. - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Account and limit**. 1. Select the **Allow use of licensed EE features** checkbox. 1. Select **Save changes**. 1. Ensure the group you want to test the EE feature for is actually using an EE plan: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Groups**. 1. Identify the group you want to modify, and select **Edit**. 1. Scroll to **Permissions and group features**. For **Plan**, select `Ultimate`. diff --git a/doc/development/emails.md b/doc/development/emails.md index bf32b71f2b7..c69eade7cb6 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Working with email in development diff --git a/doc/development/event_store.md b/doc/development/event_store.md index 918da8fb738..0ffcf8704ff 100644 --- a/doc/development/event_store.md +++ b/doc/development/event_store.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab EventStore @@ -184,7 +184,7 @@ Changes to the schema require multiple rollouts. While the new version is being - Existing subscribers can consume events using the old version. - Events get persisted in the Sidekiq queue as job arguments, so we could have 2 versions of the schema during deployments. -As changing the schema ultimately impacts the Sidekiq arguments, please refer to our +As changing the schema ultimately impacts the Sidekiq arguments, refer to our [Sidekiq style guide](sidekiq/compatibility_across_updates.md#changing-the-arguments-for-a-worker) with regards to multiple rollouts. #### Add properties @@ -277,6 +277,10 @@ declaring the subscription in `ee/lib/ee/gitlab/event_store.rb`. Subscriptions are stored in memory when the Rails app is loaded and they are immediately frozen. It's not possible to modify subscriptions at runtime. +NOTE: +Before creating a subscription, make sure that the worker is already deployed to GitLab.com as the +newly introduced workers are [not compatible with canary deployments](sidekiq/compatibility_across_updates.md#adding-new-workers). + ### Conditional dispatch of events A subscription can specify a condition when to accept an event: @@ -315,6 +319,26 @@ on the subscriber Sidekiq worker, instead of `perform_async`. This technique is useful when publishing many events and leverage the Sidekiq deduplication. +### Publishing group of events + +In some scenarios we publish multiple events of same type in a single business transaction. +This puts additional load to Sidekiq by invoking a job for each event. In such cases, we can +publish a group of events by calling `Gitlab::EventStore.publish_group`. This method accepts an +array of events of similar type. By default the subscriber worker receives a group of max 10 events, +but this can be configured by defining `group_size` parameter while creating the subscription. +The number of published events are dispatched to the subscriber in batches based on the +configured `group_size`. If the number of groups exceeds 100, we schedule each group with a delay +of 10 seconds, to reduce the load on Sidekiq. + +```ruby +store.subscribe ::Security::RefreshProjectPoliciesWorker, + to: ::ProjectAuthorizations::AuthorizationsChangedEvent, + delay: 1.minute, + group_size: 25 +``` + +The `handle_event` method in the subscriber worker is called for each of the events in the group. + ## Testing ### Testing the publisher diff --git a/doc/development/experiment_guide/experiment_code_reviews.md b/doc/development/experiment_guide/experiment_code_reviews.md index 7242acfbdcf..53016f0f7c6 100644 --- a/doc/development/experiment_guide/experiment_code_reviews.md +++ b/doc/development/experiment_guide/experiment_code_reviews.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Experiment code reviews diff --git a/doc/development/experiment_guide/experiment_rollout.md b/doc/development/experiment_guide/experiment_rollout.md index b2e1b1168d3..d9e8b747a50 100644 --- a/doc/development/experiment_guide/experiment_rollout.md +++ b/doc/development/experiment_guide/experiment_rollout.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Experiment rollouts and feature flags diff --git a/doc/development/experiment_guide/implementing_experiments.md b/doc/development/experiment_guide/implementing_experiments.md index 15b8f8fc192..d38bca41fc3 100644 --- a/doc/development/experiment_guide/implementing_experiments.md +++ b/doc/development/experiment_guide/implementing_experiments.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Implementing an A/B/n experiment diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 5e68921510e..714d5700de4 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Experiment Guide diff --git a/doc/development/experiment_guide/testing_experiments.md b/doc/development/experiment_guide/testing_experiments.md index 2e88029a27f..6e4fa9f528e 100644 --- a/doc/development/experiment_guide/testing_experiments.md +++ b/doc/development/experiment_guide/testing_experiments.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Testing experiments diff --git a/doc/development/export_csv.md b/doc/development/export_csv.md index ce0a6e026ff..23f08802893 100644 --- a/doc/development/export_csv.md +++ b/doc/development/export_csv.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review.ment-guidelines-review.ment-guidelines-review.ment-guidelines-review. --- # Export to CSV diff --git a/doc/development/fe_guide/accessibility/automated_testing.md b/doc/development/fe_guide/accessibility/automated_testing.md index 2c0d598dc58..b7f50452802 100644 --- a/doc/development/fe_guide/accessibility/automated_testing.md +++ b/doc/development/fe_guide/accessibility/automated_testing.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Automated accessibility testing diff --git a/doc/development/fe_guide/accessibility/best_practices.md b/doc/development/fe_guide/accessibility/best_practices.md index 37c28f99116..d9186278643 100644 --- a/doc/development/fe_guide/accessibility/best_practices.md +++ b/doc/development/fe_guide/accessibility/best_practices.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Accessibility best practices diff --git a/doc/development/fe_guide/accessibility/index.md b/doc/development/fe_guide/accessibility/index.md index 5274fa644e1..fef97aadaa5 100644 --- a/doc/development/fe_guide/accessibility/index.md +++ b/doc/development/fe_guide/accessibility/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Accessibility diff --git a/doc/development/fe_guide/architecture.md b/doc/development/fe_guide/architecture.md index 810d9af2de7..971c527ef68 100644 --- a/doc/development/fe_guide/architecture.md +++ b/doc/development/fe_guide/architecture.md @@ -1,16 +1,65 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Architecture -When building new features, consider reaching out to relevant stakeholders as early as possible in the process. +At GitLab, there are no dedicated "software architects". Everyone is encouraged to make their own decisions and document them appropriately. To know how or where to document these decisions, read on. -Architectural decisions should be accessible to everyone. Document -them in the relevant Merge Request discussions or by updating our documentation -when appropriate by adding an entry to this section. +## Documenting decisions + +When building new features, consider the scope and scale of what you are about to build. Depending on the answer, there are several tools or processes that could support your endeavor. We aim to keep the process of building features as efficient as possible. As a general rule, use the simplest process possible unless you need the additional support and structure of more time consuming solutions. + +### Merge requests + +When a change impacts is limited within a group or has a single contributor, the smallest possible documentation of architecture decisions is a commit and by extension a merge request (MR). MRs or commits can still be referenced even after they are merged, so it is vital to leave a good description, comments and commit messages to explain certain decisions in case it needs to be referenced later. Even a MR that is intended to be reviewed within a group should contain all relevant decision-making explicitly. + +### Architectural Issue + +When a unit of work starts to get big enough that it might impact an entire group's direction, it may be a good idea to create an architecture issue to discuss the technical direction. This process is informal and has no official requirements. Create an issue within the GitLab project where you can propose a plan for the work to be done and invite collaborators to refine the proposal with you. + +This structure allows the group to think through a proposed change, gather feedback and iterate. It also allows them to use the issue as a source of truth rather than a comments thread on the feature issue or the MRs themselves. Consider adding some kind of visual support (like a schema) to facilitate the discussion. For example, you can reference this [architectural issue of the CI/CD Catalog](https://gitlab.com/gitlab-org/gitlab/-/issues/393225). + +### Design Documents + +When the work ahead may affect more than a single group, stage or potentially an entirement department (for example, all of the Frontend team) then it is likely that there is need for a [Design Document](https://about.gitlab.com/handbook/engineering/architecture/workflow/). + +This is well documented in the handbook, but to touch on it shortly, it is **the best way** to propose large changes and gather the required feedback and support to move forward. These documents are version controlled, keep evolving with time and are a great way to share a complex understanding across the entire organization. They also require a coach, which is a great way to involve someone with a lot of experience with larger changes. This process is shared across all engineering departments and is owned by the CTO. + +To see all Design Documents, you can check the [Architecture at GitLab page](../../architecture/index.md) + +### Frontend RFCs (deprecated) + +In the past, we had a [Frontend RFC project](https://gitlab.com/gitlab-org/frontend/rfcs) which goal was to propose larger changes and get opinions from the entire department. This project is no longer used for a couple of reasons: + +1. Issues created in this project had a very low participation rate (less than 20%) +1. Controversial issues would stall with no clear way to resolve them +1. Issues that were completed often did not need a RFC in the first place (small issues) +1. Changes were often proposed "naively" without clear time and resource allocation + +In most instances where we would have created a RFC, a Design Document can be used instead as it will have it's own RFC attached to it. This makes the conversation centered around the technical design and RFCs are just a way to further the completion of the design. + +### Entry in the Frontend documentation + +Adding an architecture section to the docs is a way to tell frontend engineers how to use or build upon an existing architecture. Use it to help "onboard" engineers to a part of the application that may not be self-evident. Try to avoid documenting your group's architecture here if it has no impact on other teams. + +### Which to choose? + +As a general rule, the wider the scope of your change, the more likely it is that you and your team would benefit from a Design Document. Also consider whether your change is a true two-way door decision: changes that can easily be reverted require less thinking ahead than those that cannot. + +Work that can be achieved within a single milestone probably only needs Merge requests. Work that may take several milestone to complete, but where you are the only DRI is probably also easier done through MRs. + +When multiple DRIs are involved, ask yourself if the work ahead is clear for all of you. If the work you do is complex and affects each others, consider gathering technical feedback from your team before you start working on an Architectural issue. Write a clear proposal, involve all stakeholders early and keep yourselves accountable to the decisions made on the issue. + +Very small changes may have a very broad impact. For example, a change to any ESLint rule will impact all of engineering, but might not require a Design Document. Consider sending your proposal through Slack to gauge interest ("Should we enable X rule?") and then simply create a MR. Finally, share widely to the appropriate channels to gather feedback. + +For recommending certain code patterns in our documentation, you can write the MR that apply your proposed change, share it broadly with the department and if no strong objections are raised, merge your change. This is more efficient than RFCs because of the bias for action, while also gathering all the feedback necessary for everyone to feel included. + +If you'd like to propose a major change to the technological stack (Vue to React, JavaScript to TypeScript, etc.), start by reaching out on Slack to gauge interest. Always ask yourself whether or not the problems that you see can be fixed from our current tech stack, as we should always try to fix our problems with the tools we already have. Other departments, such as Backend and QA, do not have a clear process to propose technological changes either. That is because these changes would require huge investements from the company and probably cannot be decided without involving high-ranking executives from engineering. + +Instead, consider starting a Design Document that explains the problem and try to solve it with our current tools. Invite contribution from the department and research this thoroughly as there can only be two outcomes. Either the problem **can** be solved with our current tools or it cannot. If it can, this is a huge with for our teams since we've fixed and issue without the need to completly change our stack, and if it cannot, then the Design Document can be the start of the larger conversation around the technological change. ## Widget Architecture diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index 876855b807c..57d8bb39321 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Axios diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md index fdeabc99ea4..7a76b39edbc 100644 --- a/doc/development/fe_guide/content_editor.md +++ b/doc/development/fe_guide/content_editor.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Rich text editor development guidelines diff --git a/doc/development/fe_guide/customizable_dashboards.md b/doc/development/fe_guide/customizable_dashboards.md index be0794b95d0..93b5b20b047 100644 --- a/doc/development/fe_guide/customizable_dashboards.md +++ b/doc/development/fe_guide/customizable_dashboards.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Customizable dashboards @@ -206,7 +206,8 @@ export default { ## Dashboard designer -> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. +> - Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/411407) in GitLab 16.6. Feature flag `combined_analytics_dashboards_editor` removed. The dashboard designer provides a graphical interface for users to modify the panels and add new ones on user-defined dashboards. Is is not available on diff --git a/doc/development/fe_guide/dark_mode.md b/doc/development/fe_guide/dark_mode.md index 185bd60dd9a..3af65edf317 100644 --- a/doc/development/fe_guide/dark_mode.md +++ b/doc/development/fe_guide/dark_mode.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- This page is about developing dark mode for GitLab. For more information on how to enable dark mode, see [Change the syntax highlighting theme](../../user/profile/preferences.md#change-the-syntax-highlighting-theme). diff --git a/doc/development/fe_guide/dependencies.md b/doc/development/fe_guide/dependencies.md index b9bacada499..0ba38c04d7b 100644 --- a/doc/development/fe_guide/dependencies.md +++ b/doc/development/fe_guide/dependencies.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Frontend dependencies diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index 44238ff5dc5..b8be003776f 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Design Patterns diff --git a/doc/development/fe_guide/design_tokens.md b/doc/development/fe_guide/design_tokens.md index b47c2661e19..1556602e298 100644 --- a/doc/development/fe_guide/design_tokens.md +++ b/doc/development/fe_guide/design_tokens.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Design tokens diff --git a/doc/development/fe_guide/emojis.md b/doc/development/fe_guide/emojis.md index c93e1bb34c5..f1e4c55f985 100644 --- a/doc/development/fe_guide/emojis.md +++ b/doc/development/fe_guide/emojis.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Emojis diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index ab75cc27b6a..b8e98b47cac 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Frontend FAQ diff --git a/doc/development/fe_guide/frontend_goals.md b/doc/development/fe_guide/frontend_goals.md index 4f39e82c72e..d2ae9ceff28 100644 --- a/doc/development/fe_guide/frontend_goals.md +++ b/doc/development/fe_guide/frontend_goals.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Frontend Goals diff --git a/doc/development/fe_guide/getting_started.md b/doc/development/fe_guide/getting_started.md index 14e704d567e..5687d912de3 100644 --- a/doc/development/fe_guide/getting_started.md +++ b/doc/development/fe_guide/getting_started.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Getting started diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 5807c9c5621..22b977519be 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL @@ -105,7 +104,7 @@ Default client accepts two parameters: `resolvers` and `config`. ### Multiple client queries for the same object -If you are making multiple queries to the same Apollo client object you might encounter the following error: `Cache data may be lost when replacing the someProperty field of a Query object. To address this problem, either ensure all objects of SomeEntityhave an id or a custom merge function`. We are already checking `id` presence for every GraphQL type that has an `id`, so this shouldn't be the case (unless you see this warning when running unit tests; in this case please ensure your mocked responses contain an `id` whenever it's requested). +If you are making multiple queries to the same Apollo client object you might encounter the following error: `Cache data may be lost when replacing the someProperty field of a Query object. To address this problem, either ensure all objects of SomeEntityhave an id or a custom merge function`. We are already checking `id` presence for every GraphQL type that has an `id`, so this shouldn't be the case (unless you see this warning when running unit tests; in this case ensure your mocked responses contain an `id` whenever it's requested). When `SomeEntity` type doesn't have an `id` property in the GraphQL schema, to fix this warning we need to define a custom merge function. @@ -974,6 +973,31 @@ const data = store.readQuery({ Read more about the `@connection` directive in [Apollo's documentation](https://www.apollographql.com/docs/react/caching/advanced-topics/#the-connection-directive). +### Batching similar queries + +By default, the Apollo client sends one HTTP request from the browser per query. You can choose to +batch several queries in a single outgoing request and lower the number of requests by defining a +[batchKey](https://www.apollographql.com/docs/react/api/link/apollo-link-batch-http/#batchkey). + +This can be helpful when a query is called multiple times from the same component but you +want to update the UI once. In this example we use the component name as the key: + +```javascript +export default { + name: 'MyComponent' + apollo: { + user: { + query: QUERY_IMPORT, + context: { + batchKey: 'MyComponent', + }, + } + }, +}; +``` + +The batch key can be the name of the component. + #### Polling and Performance While the Apollo client has support for simple polling, for performance reasons, our [ETag-based caching](../polling.md) is preferred to hitting the database each time. diff --git a/doc/development/fe_guide/guides.md b/doc/development/fe_guide/guides.md index dc2fffcf10a..ce53d3df0fc 100644 --- a/doc/development/fe_guide/guides.md +++ b/doc/development/fe_guide/guides.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Guides diff --git a/doc/development/fe_guide/haml.md b/doc/development/fe_guide/haml.md index 1dc8cf63de9..88f4a785a70 100644 --- a/doc/development/fe_guide/haml.md +++ b/doc/development/fe_guide/haml.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # HAML diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index df296f13f48..d1882644c02 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Icons and SVG Illustrations diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 6bea22bd6bf..40ff704edfa 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Frontend Development Guidelines @@ -11,7 +11,7 @@ across the GitLab frontend team. ## Overview -GitLab is built on top of [Ruby on Rails](https://rubyonrails.org). It uses [Haml](https://haml.info/) and a JavaScript-based frontend with [Vue.js](https://vuejs.org). If you are not sure when to use Vue on top of Haml-page, please read [this explanation](vue.md#when-to-add-vue-application). +GitLab is built on top of [Ruby on Rails](https://rubyonrails.org). It uses [Haml](https://haml.info/) and a JavaScript-based frontend with [Vue.js](https://vuejs.org). If you are not sure when to use Vue on top of Haml-page, read [this explanation](vue.md#when-to-add-vue-application). <!-- vale gitlab.Spelling = NO --> @@ -19,19 +19,19 @@ Be wary of [the limitations that come with using Hamlit](https://github.com/k0ku <!-- vale gitlab.Spelling = YES --> -When it comes to CSS, we use a utils-based CSS approach. GitLab has its own CSS utils which are packaged inside the `gitlab-ui` project and can be seen [in the repository](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/main/src/scss/utility-mixins) or on [UNPKG](https://unpkg.com/browse/@gitlab/ui@latest/src/scss/utility-mixins/). Please favor using these before adding or using any SCSS classes. +When it comes to CSS, we use a utils-based CSS approach. GitLab has its own CSS utils which are packaged inside the `gitlab-ui` project and can be seen [in the repository](https://gitlab.com/gitlab-org/gitlab-ui/-/tree/main/src/scss/utility-mixins) or on [UNPKG](https://unpkg.com/browse/@gitlab/ui@latest/src/scss/utility-mixins/). Favor using these before adding or using any SCSS classes. We also use [SCSS](https://sass-lang.com) and plain JavaScript with modern ECMAScript standards supported through [Babel](https://babeljs.io/) and ES module support through [webpack](https://webpack.js.org/). -When making API calls, we use [GraphQL](graphql.md) as [the first choice](../../api/graphql/index.md#vision). There are still instances where GitLab REST API is used such as when creating new simple HAML pages or in legacy part of the codebase, but we should always default to GraphQL when possible. +When making API calls, we use [GraphQL](graphql.md) as [the first choice](../api_graphql_styleguide.md#vision). There are still instances where GitLab REST API is used such as when creating new simple HAML pages or in legacy part of the codebase, but we should always default to GraphQL when possible. We use [Apollo](https://www.apollographql.com/) as our global state manager and [GraphQL client](graphql.md). [VueX](vuex.md) is still in use across the codebase, but it is no longer the recommended global state manager. You should **not** [use VueX and Apollo together](graphql.md#using-with-vuex), and should [avoid adding new VueX stores](migrating_from_vuex.md) whenever possible. -For copy strings and translations, we have frontend utilities available. Please see the JavaScript section of [Preparing a page for translation](../i18n/externalization.md#javascript-files) for more information. +For copy strings and translations, we have frontend utilities available. See the JavaScript section of [Preparing a page for translation](../i18n/externalization.md#javascript-files) for more information. Working with our frontend assets requires Node (v12.22.1 or greater) and Yarn (v1.10.0 or greater). You can find information on how to install these on our diff --git a/doc/development/fe_guide/keyboard_shortcuts.md b/doc/development/fe_guide/keyboard_shortcuts.md index aeeee72e6be..35ca240a2ad 100644 --- a/doc/development/fe_guide/keyboard_shortcuts.md +++ b/doc/development/fe_guide/keyboard_shortcuts.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Implementing keyboard shortcuts diff --git a/doc/development/fe_guide/logging.md b/doc/development/fe_guide/logging.md index 750bf95e8b2..debe9cad27d 100644 --- a/doc/development/fe_guide/logging.md +++ b/doc/development/fe_guide/logging.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Client-side logging for frontend development diff --git a/doc/development/fe_guide/merge_request_widget_extensions.md b/doc/development/fe_guide/merge_request_widget_extensions.md index 99206d99590..5319048dfa5 100644 --- a/doc/development/fe_guide/merge_request_widget_extensions.md +++ b/doc/development/fe_guide/merge_request_widget_extensions.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Merge request widget extensions diff --git a/doc/development/fe_guide/migrating_from_vuex.md b/doc/development/fe_guide/migrating_from_vuex.md index 8dca744e192..45a1ea0b7ee 100644 --- a/doc/development/fe_guide/migrating_from_vuex.md +++ b/doc/development/fe_guide/migrating_from_vuex.md @@ -1,14 +1,14 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Migrating from Vuex ## Why? -We have defined [GraphQL as our primary API](../../api/graphql/index.md#vision) for all user-facing features, +We have defined the [GraphQL API](../../api/graphql/index.md) as [the primary API](../api_graphql_styleguide.md#vision) for all user-facing features, so we can safely assume that whenever GraphQL is present, so will the Apollo Client. We [do not want to use Vuex with Apollo](graphql.md#using-with-vuex), so the VueX stores count will naturally decline over time as we move from the REST API to GraphQL. diff --git a/doc/development/fe_guide/onboarding_course/index.md b/doc/development/fe_guide/onboarding_course/index.md index 0b0ffc69f1b..d8d4cdad8a6 100644 --- a/doc/development/fe_guide/onboarding_course/index.md +++ b/doc/development/fe_guide/onboarding_course/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Frontend onboarding course @@ -46,7 +46,7 @@ A fortnightly 1-on-1 mentoring sessions are also available to each participant. There are 10 places available on the course. The date will be set after the course material has been prepared. -Please complete the [Frontend Onboarding Course Application Form](https://forms.gle/39Rs4w4ZxQuByhE4A) to apply. +Complete the [Frontend Onboarding Course Application Form](https://forms.gle/39Rs4w4ZxQuByhE4A) to apply. You may also participate in the course informally at your own pace, without the benefit of the synchronous office hours or mentoring session. GitLab team members are happy to support you regardless. diff --git a/doc/development/fe_guide/onboarding_course/lesson_1.md b/doc/development/fe_guide/onboarding_course/lesson_1.md index e82d350f854..ec26da8c4eb 100644 --- a/doc/development/fe_guide/onboarding_course/lesson_1.md +++ b/doc/development/fe_guide/onboarding_course/lesson_1.md @@ -1,7 +1,7 @@ --- stage: manage group: foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Lesson 1 diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 5e8581663b6..aedb391ed25 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Performance diff --git a/doc/development/fe_guide/registry_architecture.md b/doc/development/fe_guide/registry_architecture.md index cf267e80619..bc46c2643de 100644 --- a/doc/development/fe_guide/registry_architecture.md +++ b/doc/development/fe_guide/registry_architecture.md @@ -1,7 +1,7 @@ --- stage: Package group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Registry architecture @@ -12,8 +12,8 @@ already exists to unify the user and developer experiences. Existing registries: -- Package Registry -- Container Registry +- Package registry +- Container registry - Terraform Module Registry - Dependency Proxy @@ -82,7 +82,7 @@ main pieces of the desired UI and UX of a registry page. The most important comp When adding a new registry: - Leverage the shared components that already exist. It's good to look at how the components are - structured and used in the more mature registries (for example, the Package Registry). + structured and used in the more mature registries (for example, the package registry). - If it's in line with the backend requirements, we suggest using GraphQL for the API. This helps in dealing with the innate performance issue of registries. - If possible, we recommend using [Vue Router](https://v3.router.vuejs.org/) diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md index 4e06c22b383..e4b748f7e7c 100644 --- a/doc/development/fe_guide/security.md +++ b/doc/development/fe_guide/security.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Security diff --git a/doc/development/fe_guide/sentry.md b/doc/development/fe_guide/sentry.md index 95a170b7976..fa85d51afb0 100644 --- a/doc/development/fe_guide/sentry.md +++ b/doc/development/fe_guide/sentry.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sentry monitoring in the frontend development of GitLab diff --git a/doc/development/fe_guide/source_editor.md b/doc/development/fe_guide/source_editor.md index 943ac2969f3..e65ede53a13 100644 --- a/doc/development/fe_guide/source_editor.md +++ b/doc/development/fe_guide/source_editor.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Source Editor diff --git a/doc/development/fe_guide/storybook.md b/doc/development/fe_guide/storybook.md index cbda9d5efa2..05d4397933f 100644 --- a/doc/development/fe_guide/storybook.md +++ b/doc/development/fe_guide/storybook.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Storybook diff --git a/doc/development/fe_guide/style/html.md b/doc/development/fe_guide/style/html.md index 9d8809f19c7..c9168a68614 100644 --- a/doc/development/fe_guide/style/html.md +++ b/doc/development/fe_guide/style/html.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # HTML style guide diff --git a/doc/development/fe_guide/style/index.md b/doc/development/fe_guide/style/index.md index 552b769d6f6..31b5db82153 100644 --- a/doc/development/fe_guide/style/index.md +++ b/doc/development/fe_guide/style/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Frontend style guides diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index cccaefe8a19..01caf65be5f 100644 --- a/doc/development/fe_guide/style/javascript.md +++ b/doc/development/fe_guide/style/javascript.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # JavaScript style guide diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index 400b178d9a4..a78fcf67665 100644 --- a/doc/development/fe_guide/style/scss.md +++ b/doc/development/fe_guide/style/scss.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # SCSS style guide diff --git a/doc/development/fe_guide/style/typescript.md b/doc/development/fe_guide/style/typescript.md index 529459097b4..567b80489fb 100644 --- a/doc/development/fe_guide/style/typescript.md +++ b/doc/development/fe_guide/style/typescript.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # TypeScript diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index a3ab1c1af30..83d725d453b 100644 --- a/doc/development/fe_guide/style/vue.md +++ b/doc/development/fe_guide/style/vue.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Vue.js style guide diff --git a/doc/development/fe_guide/tech_stack.md b/doc/development/fe_guide/tech_stack.md index 9c0d50ea7bd..87a5e42f75e 100644 --- a/doc/development/fe_guide/tech_stack.md +++ b/doc/development/fe_guide/tech_stack.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Tech Stack diff --git a/doc/development/fe_guide/tips_and_tricks.md b/doc/development/fe_guide/tips_and_tricks.md index dcacdb8387b..ae19ecd3fe5 100644 --- a/doc/development/fe_guide/tips_and_tricks.md +++ b/doc/development/fe_guide/tips_and_tricks.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Tips and tricks diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index c1084ab4453..536cf5c4a2a 100644 --- a/doc/development/fe_guide/tooling.md +++ b/doc/development/fe_guide/tooling.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Tooling diff --git a/doc/development/fe_guide/troubleshooting.md b/doc/development/fe_guide/troubleshooting.md index 3e4c5007b64..743eaf7e494 100644 --- a/doc/development/fe_guide/troubleshooting.md +++ b/doc/development/fe_guide/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Troubleshooting frontend development issues diff --git a/doc/development/fe_guide/type_hinting.md b/doc/development/fe_guide/type_hinting.md index 026bf855e27..0252b5343d4 100644 --- a/doc/development/fe_guide/type_hinting.md +++ b/doc/development/fe_guide/type_hinting.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Type hinting overview diff --git a/doc/development/fe_guide/view_component.md b/doc/development/fe_guide/view_component.md index cfd78597501..a616a3d7c48 100644 --- a/doc/development/fe_guide/view_component.md +++ b/doc/development/fe_guide/view_component.md @@ -1,7 +1,7 @@ --- stage: Manage group: Foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # ViewComponent diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index cfc3ac466d5..69967a5a2be 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Vue @@ -39,9 +39,9 @@ In the past, we added interactivity to the page piece-by-piece, adding multiple - multiple applications lead to unpredictable user experience, increased page complexity, harder debugging process; - the way apps communicate with each other affects Web Vitals numbers. -Because of these reasons, we want to be cautious about adding new Vue applications to the pages where another Vue application is already present (this does not include old or new navigation). Before adding a new app, please make sure that it is absolutely impossible to extend an existing application to achieve a desired functionality. When in doubt, please feel free to ask for the architectural advise on `#frontend` or `#frontend-maintainers` Slack channel. +Because of these reasons, we want to be cautious about adding new Vue applications to the pages where another Vue application is already present (this does not include old or new navigation). Before adding a new app, make sure that it is absolutely impossible to extend an existing application to achieve a desired functionality. When in doubt, feel free to ask for the architectural advise on `#frontend` or `#frontend-maintainers` Slack channel. -If you still need to add a new application, please make sure it shares local state with existing applications (preferably via Apollo Client, or Vuex if we use REST API) +If you still need to add a new application, make sure it shares local state with existing applications (preferably via Apollo Client, or Vuex if we use REST API) ## Vue architecture @@ -860,7 +860,7 @@ component under test, with the `computed` property, for example). Remember to us We should test for events emitted in response to an action in our component. This testing verifies the correct events are being fired with the correct arguments. -For any DOM events we should use [`trigger`](https://v1.test-utils.vuejs.org/api/wrapper/#trigger) +For any native DOM events we should use [`trigger`](https://v1.test-utils.vuejs.org/api/wrapper/#trigger) to fire out event. ```javascript @@ -892,6 +892,20 @@ it('should fire the itemClicked event', () => { We should verify an event has been fired by asserting against the result of the [`emitted()`](https://v1.test-utils.vuejs.org/api/wrapper/#emitted) method. +It is a good practice to prefer to use `vm.$emit` over `trigger` when emitting events from child components. + +Using `trigger` on the component means we treat it as a white box: we assume that the root element of child component has a native `click` event. Also, some tests fail in Vue3 mode when using `trigger` on child components. + + ```javascript + const findButton = () => wrapper.findComponent(GlButton); + + // bad + findButton().trigger('click'); + + // good + findButton().vm.$emit('click'); + ``` + ## Vue.js Expert Role You should only apply to be a Vue.js expert when your own merge requests and your reviews show: diff --git a/doc/development/fe_guide/vue3_migration.md b/doc/development/fe_guide/vue3_migration.md index b9e819a95bd..6eb1d4c2413 100644 --- a/doc/development/fe_guide/vue3_migration.md +++ b/doc/development/fe_guide/vue3_migration.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Migration to Vue 3 diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 06d7070b855..aff3588a503 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -1,12 +1,12 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Vuex -[Vuex](https://vuex.vuejs.org) should no longer be considered a preferred path to store management and is currently in its legacy phase. This means it is acceptable to add upon existing `Vuex` stores, but we strongly recommend reducing store sizes over time and eventually [migrating away from VueX entirely](migrating_from_vuex.md). Before adding any new `Vuex` store to an application, first ensure that the `Vue` application you plan to add it into **does not use** `Apollo`. `Vuex` and `Apollo` should not be combined unless absolutely necessary. Please consider reading through [our GraphQL documentation](../fe_guide/graphql.md) for more guidelines on how you can build `Apollo` based applications. +[Vuex](https://vuex.vuejs.org) should no longer be considered a preferred path to store management and is currently in its legacy phase. This means it is acceptable to add upon existing `Vuex` stores, but we strongly recommend reducing store sizes over time and eventually [migrating away from VueX entirely](migrating_from_vuex.md). Before adding any new `Vuex` store to an application, first ensure that the `Vue` application you plan to add it into **does not use** `Apollo`. `Vuex` and `Apollo` should not be combined unless absolutely necessary. Consider reading through [our GraphQL documentation](../fe_guide/graphql.md) for more guidelines on how you can build `Apollo` based applications. The information included in this page is explained in more detail in the official [Vuex documentation](https://vuex.vuejs.org). diff --git a/doc/development/fe_guide/widgets.md b/doc/development/fe_guide/widgets.md index 6cd8e6c091c..de4ac7620c2 100644 --- a/doc/development/fe_guide/widgets.md +++ b/doc/development/fe_guide/widgets.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Widgets diff --git a/doc/development/feature_categorization/index.md b/doc/development/feature_categorization/index.md index 2f4a7380bff..dfd327270f2 100644 --- a/doc/development/feature_categorization/index.md +++ b/doc/development/feature_categorization/index.md @@ -1,7 +1,7 @@ --- stage: Enablement group: Infrastructure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Feature Categorization diff --git a/doc/development/feature_development.md b/doc/development/feature_development.md index 4dbde42b0ff..a5a6439b420 100644 --- a/doc/development/feature_development.md +++ b/doc/development/feature_development.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Feature development @@ -96,6 +96,7 @@ Consult these topics for information on contributing to specific GitLab features - [Value Stream Analytics development guide](value_stream_analytics.md) - [Application limits](application_limits.md) - [AI features](ai_features/index.md) +- [Application settings](application_settings.md) ### Import and Export diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index 6e0f0e8dbcf..5006b21965e 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Use ChatOps to enable and disable feature flags @@ -43,7 +42,7 @@ The GitLab feature library (using [Feature flags process](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/) guide) supports rolling out changes to a percentage of time to users. This in turn can be controlled using [GitLab ChatOps](../../ci/chatops/index.md). -For an up to date list of feature flag commands please see +For an up to date list of feature flag commands see [the source code](https://gitlab.com/gitlab-com/chatops/blob/master/lib/chatops/commands/feature.rb). Note that all the examples in that file must be preceded by `/chatops run`. @@ -105,7 +104,7 @@ Guidelines: - Consider notifying `#support_gitlab-com` beforehand. So in case if the feature has any side effects on user experience, they can mitigate and disable the feature flag to reduce some impact. - If the feature meets the requirements for creating a [Change Management](https://about.gitlab.com/handbook/engineering/infrastructure/change-management/#feature-flags-and-the-change-management-process) issue, create a Change Management issue per [criticality guidelines](https://about.gitlab.com/handbook/engineering/infrastructure/change-management/#change-request-workflows). - For simple, low-risk, easily reverted features, proceed and [enable the feature in `#production`](#process). -- For support requests to toggle feature flags for specific groups or projects, please follow the process outlined in the [support workflows](https://about.gitlab.com/handbook/support/workflows/saas_feature_flags.html). +- For support requests to toggle feature flags for specific groups or projects, follow the process outlined in the [support workflows](https://about.gitlab.com/handbook/support/workflows/saas_feature_flags.html). #### Guideline for which percentages to choose during the rollout @@ -204,7 +203,7 @@ Before enabling a feature flag, verify that you are not violating any [Productio The following `/chatops` commands should be performed in the Slack `#production` channel. -When you begin to enable the feature, please link to the relevant +When you begin to enable the feature, link to the relevant feature flag rollout issue within a Slack thread of the first `/chatops` command you make so people can understand the change if they need to. @@ -510,5 +509,5 @@ record still exists in the database that the flag was deployed too. The record can be deleted once the MR is deployed to all the environments: ```shell -/chatops run feature delete <feature-flag-name> --dev --ops --pre --staging --staging-ref --production +/chatops run feature delete <feature-flag-name> --dev --pre --staging --staging-ref --production ``` diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index c1a5963e97f..17dd8432f7b 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Feature flags in the development of GitLab @@ -20,7 +19,7 @@ All newly-introduced feature flags should be [used with an actor](controls.md#pe This document is the subject of continued work as part of an epic to [improve internal usage of feature flags](https://gitlab.com/groups/gitlab-org/-/epics/3551). Raise any suggestions as new issues and attach them to the epic. -For an [overview of the feature flag lifecycle](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flag-lifecycle), or if you need help deciding [if you should use a feature flag](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) or not, please see the [feature flag lifecycle](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/) handbook page. +For an [overview of the feature flag lifecycle](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flag-lifecycle), or if you need help deciding [if you should use a feature flag](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) or not, see the [feature flag lifecycle](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/) handbook page. ## When to use feature flags @@ -605,7 +604,7 @@ with the untested code path should be manually tested before deployment to produ When using the testing environment, all feature flags are enabled by default. Flags can be disabled by default in the [`spec/spec_helper.rb` file](https://gitlab.com/gitlab-org/gitlab/-/blob/b61fba42eea2cf5bb1ca64e80c067a07ed5d1921/spec/spec_helper.rb#L274). -Please add a comment inline to explain why the flag needs to be disabled. You can also attach the issue URL for reference if possible. +Add a comment inline to explain why the flag needs to be disabled. You can also attach the issue URL for reference if possible. WARNING: This does not apply to end-to-end (QA) tests, which [do not enable feature flags by default](#end-to-end-qa-tests). There is a different [process for using feature flags in end-to-end tests](../testing_guide/end_to_end/feature_flags.md). diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md index f8de93a2243..1217c2bf596 100644 --- a/doc/development/features_inside_dot_gitlab.md +++ b/doc/development/features_inside_dot_gitlab.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Features inside the `.gitlab/` directory We have implemented standard features that depend on configuration files in the `.gitlab/` directory. You can find `.gitlab/` in various GitLab repositories. -When implementing new features, please refer to these existing features to avoid conflicts: +When implementing new features, refer to these existing features to avoid conflicts: - [Issue Templates](../user/project/description_templates.md#create-an-issue-template): `.gitlab/issue_templates/`. - [Merge request Templates](../user/project/description_templates.md#create-a-merge-request-template): `.gitlab/merge_request_templates/`. diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index 39833a441ee..550b56af520 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -1,14 +1,14 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # File Storage in GitLab We use the [CarrierWave](https://github.com/carrierwaveuploader/carrierwave) gem to handle file upload, store and retrieval. -File uploads should be accelerated by workhorse, for details please refer to [uploads development documentation](uploads/index.md). +File uploads should be accelerated by workhorse, for details refer to [uploads development documentation](uploads/index.md). There are many places where file uploading is used, according to contexts: diff --git a/doc/development/fips_compliance.md b/doc/development/fips_compliance.md index 60677abf292..3563f7fc2d5 100644 --- a/doc/development/fips_compliance.md +++ b/doc/development/fips_compliance.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # FIPS compliance @@ -40,7 +40,7 @@ when FIPS mode is enabled. | Ubuntu 20.04 Libgcrypt Cryptographic Module | [3902](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3902) | EC2 instances | `gpg`, `sshd` | | Amazon Linux 2 Kernel Crypto API Cryptographic Module | [3709](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3709) | EKS nodes | Linux kernel | | Amazon Linux 2 OpenSSL Cryptographic Module | [3553](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3553) | EKS nodes | NGINX | -| RedHat Enterprise Linux 8 OpenSSL Cryptographic Module | [4271](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4271) | EKS nodes | UBI containers: Workhorse, Pages, Container Registry, Rails (Puma/Sidekiq), Security Analyzers | +| RedHat Enterprise Linux 8 OpenSSL Cryptographic Module | [4271](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4271) | EKS nodes | UBI containers: Workhorse, Pages, container registry, Rails (Puma/Sidekiq), Security Analyzers | | RedHat Enterprise Linux 8 Libgcrypt Cryptographic Module | [3784](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3784) | EKS nodes | UBI containers: GitLab Shell, `gpg` | ### Supported Operating Systems diff --git a/doc/development/gemfile.md b/doc/development/gemfile.md index ed38f6481e7..4801a8c2557 100644 --- a/doc/development/gemfile.md +++ b/doc/development/gemfile.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Gemfile development guidelines diff --git a/doc/development/gems.md b/doc/development/gems.md index 54d6e6dc30d..476ed8f916b 100644 --- a/doc/development/gems.md +++ b/doc/development/gems.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Gems development guidelines diff --git a/doc/development/geo.md b/doc/development/geo.md index ceaa2dbb056..d8b000c090a 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Geo (development) @@ -628,7 +628,7 @@ As another example, [Dependency Proxy](../administration/packages/dependency_pro If a new feature introduces a new kind of data which is not a Git repository, or a blob, or a combination of the two, then contact the Geo team to discuss how to handle it. -As an example, Container Registry data does not easily fit into the above categories. It is backed by a registry service which owns the data, and GitLab interacts with the registry service's API. So a one off approach is required for Geo support of Container Registry. Still, we are able to reuse much of the glue code of [the Geo self-service framework](geo/framework.md#repository-replicator-strategy). +As an example, container registry data does not easily fit into the above categories. It is backed by a registry service which owns the data, and GitLab interacts with the registry service's API. So a one off approach is required for Geo support of container registry. Still, we are able to reuse much of the glue code of [the Geo self-service framework](geo/framework.md#repository-replicator-strategy). ## History of communication channel diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index 60529db5ce6..4ec3309dc56 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Geo self-service framework diff --git a/doc/development/geo/proxying.md b/doc/development/geo/proxying.md index 45c60bc370e..49777771b2e 100644 --- a/doc/development/geo/proxying.md +++ b/doc/development/geo/proxying.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Geo proxying diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md index 65d2338cd65..f3e35f9cdf8 100644 --- a/doc/development/git_object_deduplication.md +++ b/doc/development/git_object_deduplication.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # How Git object deduplication works in GitLab diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index ed7fb6325d6..a391daf8962 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Gitaly development guidelines @@ -73,12 +73,12 @@ when Gitaly is called more than 30 times in a single Rails request or Sidekiq ex As a temporary measure, export `GITALY_DISABLE_REQUEST_LIMITS=1` to suppress the error. This disables the n+1 detection in your development environment. -Please raise an issue in the GitLab CE or EE repositories to report the issue. Include the labels ~Gitaly -~performance ~"technical debt". Please ensure that the issue contains the full stack trace and error message of the +Raise an issue in the GitLab CE or EE repositories to report the issue. Include the labels ~Gitaly +~performance ~"technical debt". Ensure that the issue contains the full stack trace and error message of the `TooManyInvocationsError`. Also include any known failing tests if possible. Isolate the source of the n+1 problem. This is usually a loop that results in Gitaly being called for each -element in an array. If you are unable to isolate the problem, please contact a member +element in an array. If you are unable to isolate the problem, contact a member of the [Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members) for assistance. After the source has been found, wrap it in an `allow_n_plus_1_calls` block, as follows: diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 9ce95cf7da1..56a4ea898df 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitHub importer developer documentation @@ -209,7 +209,8 @@ When you schedule a job, `AdvanceStageWorker` is given a project ID, a list of Redis keys, and the name of the next stage. The Redis keys (produced by `Gitlab::JobWaiter`) are used to check if the running stage has been completed or not. If the stage has not yet been -completed `AdvanceStageWorker` reschedules itself. After a stage finishes +completed `AdvanceStageWorker` reschedules itself. After a stage finishes, +or if more jobs have been finished after the last invocation. `AdvanceStageworker` refreshes the import JID (more on this below) and schedule the worker of the next stage. @@ -221,18 +222,19 @@ also reduces pressure on the system as a whole. ## Refreshing import job IDs GitLab includes a worker called `Gitlab::Import::StuckProjectImportJobsWorker` -that periodically runs and marks project imports as failed if they have been -running for more than 24 hours. For GitHub projects, this poses a bit of a -problem: importing large projects could take several hours depending on how +that periodically runs and marks project imports as failed if they have not been +refreshed for more than 24 hours. For GitHub projects, this poses a bit of a +problem: importing large projects could take several days depending on how often we hit the GitHub rate limit (more on this below), but we don't want `Gitlab::Import::StuckProjectImportJobsWorker` to mark our import as failed because of this. To prevent this from happening we periodically refresh the expiration time of -the import process. This works by storing the JID of the import job in the +the import. This works by storing the JID of the import job in the database, then refreshing this JID TTL at various stages throughout the import -process. This is done by calling `ProjectImportState#refresh_jid_expiration`. By -refreshing this TTL we can ensure our import does not get marked as failed so -long we're still performing work. +process. This is done either by calling `ProjectImportState#refresh_jid_expiration`, +or by using the RefreshImportJidWorker and passing in the current worker's jid. +By refreshing this TTL we can ensure our import does not get marked as failed so +long as we're still performing work. ## GitHub rate limit @@ -297,6 +299,54 @@ The code for this resides in: - `lib/gitlab/github_import/user_finder.rb` - `lib/gitlab/github_import/caching.rb` +## Increasing Sidekiq interrupts + +When a Sidekiq process shut downs, it waits for a period of time for running +jobs to finish before it then interrupts them. An interrupt terminates +the job and requeues it again. Our +[vendored `sidekiq-reliable-fetcher` gem](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/gems/sidekiq-reliable-fetch/README.md) +puts a limit of `3` interrupts before a job is no longer requeued and is +permanently terminated. Jobs that have been interrupted log a +`json.interrupted_count` in Kibana. + +This limit offers protection from jobs that can never be completed in +the time between Sidekiq restarts. + +For large imports, our GitHub [stage](#stages) workers (namespaced in +`Stage::`) take many hours to finish. By default, the import is at risk +of failing because of `sidekiq-reliable-fetcher` permanently stopping these +workers before they can complete. + +Stage workers that pick up from where they left off when restarted can +increase the interrupt limit of `sidekiq-reliable-fetcher` to `20` by +calling `.resumes_work_when_interrupted!`: + +```ruby +module Gitlab + module GithubImport + module Stage + class MyWorker + resumes_work_when_interrupted! + + # ... + end + end + end +end +``` + +Stage workers that do not fully resume their work when restarted should +not call this method. For example, a worker that skips already imported +objects, but starts its loop from the beginning each time. + +Examples of stage workers that do resume work fully are ones that +execute services that: + +- [Continue paging](https://gitlab.com/gitlab-org/gitlab/-/blob/487521cc/lib/gitlab/github_import/parallel_scheduling.rb#L114-117) + an endpoint from where it left off. +- [Continue their loop](https://gitlab.com/gitlab-org/gitlab/-/blob/487521cc26c1e2bdba4fc67c14478d2b2a5f2bfa/lib/gitlab/github_import/importer/attachments/issues_importer.rb#L27) + from where it left off. + ## Mapping labels and milestones To reduce pressure on the database we do not query it when setting labels and diff --git a/doc/development/gitlab_flavored_markdown/index.md b/doc/development/gitlab_flavored_markdown/index.md index cde83bff32e..fe743787fb8 100644 --- a/doc/development/gitlab_flavored_markdown/index.md +++ b/doc/development/gitlab_flavored_markdown/index.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- <!-- vale gitlab.GitLabFlavoredMarkdown = NO --> diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md index a0eb04d7cad..f8097d48739 100644 --- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md +++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- <!-- vale gitlab.GitLabFlavoredMarkdown = NO --> diff --git a/doc/development/gitlab_shell/features.md b/doc/development/gitlab_shell/features.md index f7931c4b94d..c34e430e520 100644 --- a/doc/development/gitlab_shell/features.md +++ b/doc/development/gitlab_shell/features.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab Shell feature list diff --git a/doc/development/gitpod_internals.md b/doc/development/gitpod_internals.md index a4b340916dd..33e18dc2133 100644 --- a/doc/development/gitpod_internals.md +++ b/doc/development/gitpod_internals.md @@ -1,7 +1,7 @@ --- stage: none group: Engineering Productivity -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Gitpod internal configuration @@ -19,7 +19,7 @@ The current settings are: A webhook that starts with `https://gitpod.io/` is created to enable prebuilds (see [Enabling Prebuilds](https://www.gitpod.io/docs/configure/authentication/gitlab#enabling-prebuilds) for more details). The webhook is maintained by an [Engineering Productivity team](https://about.gitlab.com/handbook/engineering/quality/engineering-productivity/). -You can find this webhook in [Webhook Settings in `gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab/-/hooks). If you cannot access this setting, please chat to the [Engineering Productivity team](https://about.gitlab.com/handbook/engineering/quality/engineering-productivity/). +You can find this webhook in [Webhook Settings in `gitlab-org/gitlab`](https://gitlab.com/gitlab-org/gitlab/-/hooks). If you cannot access this setting, chat to the [Engineering Productivity team](https://about.gitlab.com/handbook/engineering/quality/engineering-productivity/). ### Troubleshooting a failed webhook diff --git a/doc/development/go_guide/dependencies.md b/doc/development/go_guide/dependencies.md index f2b1ae9e7b8..aaf38d98625 100644 --- a/doc/development/go_guide/dependencies.md +++ b/doc/development/go_guide/dependencies.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Dependency Management in Go diff --git a/doc/development/go_guide/go_upgrade.md b/doc/development/go_guide/go_upgrade.md index 6bfa4ced229..5386221ea7e 100644 --- a/doc/development/go_guide/go_upgrade.md +++ b/doc/development/go_guide/go_upgrade.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Managing Go versions @@ -153,7 +153,7 @@ if you need help finding the correct person or labels: | Gitaly | [Issue Tracker](https://gitlab.com/gitlab-org/gitaly/-/issues) | | GitLab CLI (`glab`). | [Issue Tracker](https://gitlab.com/gitlab-org/cli/-/issues) | GitLab Compose Kit | [Issuer Tracker](https://gitlab.com/gitlab-org/gitlab-compose-kit/-/issues) | -| GitLab Container Registry | [Issue Tracker](https://gitlab.com/gitlab-org/container-registry) | +| GitLab container registry | [Issue Tracker](https://gitlab.com/gitlab-org/container-registry) | | GitLab Elasticsearch Indexer | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer/-/issues) | | GitLab agent server for Kubernetes (KAS) | [Issue Tracker](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues) | | GitLab Pages | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab-pages/-/issues) | diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index c6d7b231b72..a9f4b22c778 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Go standards and style guidelines @@ -26,7 +26,7 @@ can still have specifics. They are described in their respective The Go upgrade documentation [provides an overview](go_upgrade.md#overview) of how GitLab manages and ships Go binary support. -If a GitLab component requires a newer version of Go, please +If a GitLab component requires a newer version of Go, follow the [upgrade process](go_upgrade.md#updating-go-version) to ensure no customer, team, or component is adversely impacted. Sometimes, individual projects must also [manage builds with multiple versions of Go](go_upgrade.md#supporting-multiple-go-versions). diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 59362dc33c0..0f872bfff01 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Gotchas @@ -76,7 +76,7 @@ When run, this spec doesn't do what we might expect: This is because FactoryBot sequences are not reset for each example. -Please remember that sequence-generated values exist only to avoid having to +Remember that sequence-generated values exist only to avoid having to explicitly set attributes that have a uniqueness constraint when using a factory. ### Solution diff --git a/doc/development/graphql_guide/authorization.md b/doc/development/graphql_guide/authorization.md index 7b69ce36071..d40115bdb03 100644 --- a/doc/development/graphql_guide/authorization.md +++ b/doc/development/graphql_guide/authorization.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL Authorization diff --git a/doc/development/graphql_guide/batchloader.md b/doc/development/graphql_guide/batchloader.md index 5f06f1faf1e..a4295cb3214 100644 --- a/doc/development/graphql_guide/batchloader.md +++ b/doc/development/graphql_guide/batchloader.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL BatchLoader diff --git a/doc/development/graphql_guide/graphql_pro.md b/doc/development/graphql_guide/graphql_pro.md index 7c5770a4410..f6af4c88a47 100644 --- a/doc/development/graphql_guide/graphql_pro.md +++ b/doc/development/graphql_guide/graphql_pro.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL Pro diff --git a/doc/development/graphql_guide/index.md b/doc/development/graphql_guide/index.md index ef30d489832..5de90f8e858 100644 --- a/doc/development/graphql_guide/index.md +++ b/doc/development/graphql_guide/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL development guidelines diff --git a/doc/development/graphql_guide/monitoring.md b/doc/development/graphql_guide/monitoring.md index f92963dbdee..6e5c8e730eb 100644 --- a/doc/development/graphql_guide/monitoring.md +++ b/doc/development/graphql_guide/monitoring.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Reading GraphQL logs diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md index a858d9be681..117a9c691df 100644 --- a/doc/development/graphql_guide/pagination.md +++ b/doc/development/graphql_guide/pagination.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL pagination diff --git a/doc/development/graphql_guide/reviewing.md b/doc/development/graphql_guide/reviewing.md index 9c32179a89d..9216ea2884d 100644 --- a/doc/development/graphql_guide/reviewing.md +++ b/doc/development/graphql_guide/reviewing.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL API merge request checklist @@ -54,7 +54,7 @@ GraphQL is a framework with many moving parts. It's important that the framework - Do not manually invoke framework bits. For example, do not instantiate resolvers during execution and instead let the framework do that. - You can subclass resolvers, as in `MyResolver.single` (see [deriving resolvers](../api_graphql_styleguide.md#deriving-resolvers)). - Use the `ready?` method for more complex argument logic (see [correct use of resolver#ready](../api_graphql_styleguide.md#correct-use-of-resolverready)). -- Use the `prepare` method for more complex argument validation (see [validating arguments](../api_graphql_styleguide.md#validating-arguments)). +- Use the `prepare` method for more complex argument validation (see [Preprocessing](https://graphql-ruby.org/fields/arguments.html#preprocessing)). For details, see [resolver guide](../api_graphql_styleguide.md#writing-resolvers). @@ -68,7 +68,8 @@ For details, see [authorization guide](authorization.md). Ensure: -- You avoid N+1s with [BatchLoader](batchloader.md) or [Lookahead](../api_graphql_styleguide.md#look-ahead) when appropriate. +- You have [checked for N+1s](../api_graphql_styleguide.md#how-to-see-n1-problems-in-development) and + used [optimizations](../api_graphql_styleguide.md#optimizations) to remove N+1s whenever possible. - You use [laziness](../api_graphql_styleguide.md#laziness) appropriately. ### Use appropriate types diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 1ce35b254f1..47936dc6f70 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Internationalization for GitLab @@ -27,23 +27,27 @@ After you have the GitLab project ready, you can start working on the translatio The following tools are used: +- Custom written tools to aid day-to-day development work with translations: + + - `tooling/bin/gettext_extractor locale/gitlab.pot`: scan all source files for [new content to translate](#updating-the-po-files-with-the-new-content) + - `rake gettext:compile`: reads the contents of the PO files and generates JS files which + contain all the available translations for the Frontend. + - `rake gettext:lint`: [validate PO files](#validating-po-files) + - [`gettext_i18n_rails`](https://github.com/grosser/gettext_i18n_rails): - this gem allows us to translate content from models, views, and controllers. It also gives us - access to the following Rake tasks: + this gem allows us to translate content from models, views, and controllers. + It uses [`fast_gettext`](https://github.com/grosser/fast_gettext) under the hood. + It also provides access to the following Rake tasks, which are rarely needed in day-to-day: + + - `rake gettext:add_language[language]`: [adding a new language](#adding-a-new-language) - `rake gettext:find`: parses almost all the files from the Rails application looking for content marked for translation. It then updates the PO files with this content. - `rake gettext:pack`: processes the PO files and generates the binary MO files that the application uses. -- [`gettext_i18n_rails_js`](https://github.com/webhippie/gettext_i18n_rails_js): - this gem makes the translations available in JavaScript. It provides the following Rake task: - - - `rake gettext:compile`: reads the contents of the PO files and generates JS files which - contain all the available translations. - -- PO editor: there are multiple applications that can help us work with PO files. A good option is - [Poedit](https://poedit.net/download), +- PO editor: there are multiple applications that can help us work with PO files. + A good option is [Poedit](https://poedit.net/download), which is available for macOS, GNU/Linux, and Windows. ## Preparing a page for translation @@ -258,6 +262,11 @@ expect(wrapper.text()).toBe('There was an error: Please refresh and hope for the For more details you can see how we [keep translations dynamic](#keep-translations-dynamic). +## Making changes to translated strings + +If you change the source strings in GitLab, you must [update the `pot` file](#updating-the-po-files-with-the-new-content) before pushing your changes. +If the `pot` file is out of date, pre-push checks and a pipeline job for `gettext` fail. + ## Working with special content ### Interpolation @@ -839,7 +848,7 @@ When in doubt, try to follow the best practices described in this [Mozilla Devel ### Always pass string literals to the translation helpers -The `bin/rake gettext:regenerate` script parses the codebase and extracts all the strings from the +The `tooling/bin/gettext_extractor locale/gitlab.pot` script parses the codebase and extracts all the strings from the [translation helpers](#preparing-a-page-for-translation) ready to be translated. The script cannot resolve the strings if they are passed as variables or function calls. Therefore, @@ -865,7 +874,7 @@ Now that the new content is marked for translation, run this command to update t `locale/gitlab.pot` files: ```shell -bin/rake gettext:regenerate +tooling/bin/gettext_extractor locale/gitlab.pot ``` This command updates the `locale/gitlab.pot` file with the newly externalized strings and removes diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index b7e385a774a..9e39d5554ab 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Translate GitLab to your language @@ -29,6 +29,10 @@ strings. See [Externalization for GitLab](externalization.md). +### Editing externalized strings + +If you edit externalized strings in GitLab, you must [update the `pot` file](externalization.md#updating-the-po-files-with-the-new-content) before pushing your changes. + ## Translate strings The translation process is managed at [https://crowdin.com/project/gitlab-ee](https://crowdin.com/project/gitlab-ee) diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md index 4f36cbe125a..d33b8e701e9 100644 --- a/doc/development/i18n/merging_translations.md +++ b/doc/development/i18n/merging_translations.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Merging translations from Crowdin diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index f24ebacab18..35e423b28e9 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Proofread Translations @@ -33,7 +33,7 @@ are very appreciative of the work done by translators and proofreaders! - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) - Victor Wu - [GitLab](https://gitlab.com/_victorwu_), [Crowdin](https://crowdin.com/profile/victorwu) - Xiaogang Wen - [GitLab](https://gitlab.com/xiaogang_cn), [Crowdin](https://crowdin.com/profile/xiaogang_gitlab) - - Qi Zhao - [GitLab](https://gitlab.com/zhaoqi01), [Crowdin](https://crowdin.com/profile/zhaoqi01) + - Zhiyuan Lu - [GitLab](https://gitlab.com/luzhiyuan.deer), [Crowdin](https://crowdin.com/profile/luzhiyuan.deer) - Chinese Traditional 繁體中文 - Weizhe Ding - [GitLab](https://gitlab.com/d.weizhe), [Crowdin](https://crowdin.com/profile/d.weizhe) - Yi-Jyun Pan - [GitLab](https://gitlab.com/pan93412), [Crowdin](https://crowdin.com/profile/pan93412) diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md index cf6ee16f157..7149d431c30 100644 --- a/doc/development/i18n/translation.md +++ b/doc/development/i18n/translation.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Translating GitLab @@ -96,7 +96,7 @@ For example, in German, the word _user_ can be translated into _Benutzer_ (male) ### Updating the glossary -To propose additions to the glossary, please +To propose additions to the glossary, [open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=✓&state=all&label_name[]=Category%3AInternationalization). ## French translation guidelines diff --git a/doc/development/identity_verification.md b/doc/development/identity_verification.md index 7d1bf8586be..8058ce8b282 100644 --- a/doc/development/identity_verification.md +++ b/doc/development/identity_verification.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Identity verification development diff --git a/doc/development/image_scaling.md b/doc/development/image_scaling.md index 48b780b50bf..05792bfd5a3 100644 --- a/doc/development/image_scaling.md +++ b/doc/development/image_scaling.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Image scaling guide diff --git a/doc/development/img/snowplow_flow.png b/doc/development/img/snowplow_flow.png Binary files differdeleted file mode 100644 index aae597edc13..00000000000 --- a/doc/development/img/snowplow_flow.png +++ /dev/null diff --git a/doc/development/import_export.md b/doc/development/import_export.md index 11bddf190fa..909c31c1b62 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Import/Export development documentation @@ -10,6 +10,8 @@ General development guidelines and tips for the [Import/Export feature](../user/ <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> This document is originally based on the [Import/Export 201 presentation available on YouTube](https://www.youtube.com/watch?v=V3i1OfExotE). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For more context you can watch this [Deep dive on Import / Export Development on YouTube](https://www.youtube.com/watch?v=IYD39JMGK78). + ## Security The Import/Export feature is constantly updated (adding new things to export). However, @@ -286,13 +288,13 @@ Fixtures used in Import/Export specs live in `spec/fixtures/lib/gitlab/import_ex There are two versions of each of these fixtures: - A human readable single JSON file with all objects, called either `project.json` or `group.json`. -- A folder named `tree`, containing a tree of files in `ndjson` format. **Please do not edit files under this folder manually unless strictly necessary.** +- A folder named `tree`, containing a tree of files in `ndjson` format. **Do not edit files under this folder manually unless strictly necessary.** The tools to generate the NDJSON tree from the human-readable JSON files live in the [`gitlab-org/memory-team/team-tools`](https://gitlab.com/gitlab-org/memory-team/team-tools/-/blob/master/import-export/) project. ### Project -**Please use `legacy-project-json-to-ndjson.sh` to generate the NDJSON tree.** +**Use `legacy-project-json-to-ndjson.sh` to generate the NDJSON tree.** The NDJSON tree looks like: @@ -326,7 +328,7 @@ tree ### Group -**Please use `legacy-group-json-to-ndjson.rb` to generate the NDJSON tree.** +**Use `legacy-group-json-to-ndjson.rb` to generate the NDJSON tree.** The NDJSON tree looks like this: @@ -353,4 +355,4 @@ tree ``` WARNING: -When updating these fixtures, please ensure you update both `json` files and `tree` folder, as the tests apply to both. +When updating these fixtures, ensure you update both `json` files and `tree` folder, as the tests apply to both. diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 0be17ea5873..f592bfc5d35 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Test import project diff --git a/doc/development/index.md b/doc/development/index.md index abc19645ecb..b3a3729ed10 100644 --- a/doc/development/index.md +++ b/doc/development/index.md @@ -1,8 +1,7 @@ --- -type: index, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: "Development Guidelines: learn how to contribute to GitLab." --- diff --git a/doc/development/integrations/index.md b/doc/development/integrations/index.md index 382dba58ae3..23a22d2c121 100644 --- a/doc/development/integrations/index.md +++ b/doc/development/integrations/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: "GitLab's development guidelines for Integrations" --- @@ -63,13 +63,37 @@ You should always access the fields through their `getters` and not interact wit You **must not** write to the `properties` hash, you **must** use the generated setter method instead. Direct writes to this hash are not persisted. -You should also define validations for all your properties. To see how these fields are exposed in the frontend form for the integration, see [Customize the frontend form](#customize-the-frontend-form). Other approaches include using `Integration.prop_accessor` or `Integration.data_field`, which you might see in earlier versions of integrations. You should not use these approaches for new integrations. +### Define validations + +You should define Rails validations for all of your fields. + +Validations should only apply when the integration is enabled, by testing the `#activated?` method. + +Any field with the [`required:` property](#customize-the-frontend-form) should have a +corresponding validation for `presence`, as the `required:` field property is only for the frontend. + +For example: + +```ruby +module Integrations + class FooBar < Integration + with_options if: :activated? do + validates :key, presence: true, format: { with: KEY_REGEX } + validates :bar, inclusion: [true, false] + end + + field :key, required: true + field :bar, type: :checkbox + end +end +``` + ### Define trigger events Integrations are triggered by calling their `#execute` method in response to events in GitLab, @@ -194,7 +218,7 @@ This method should return an array of hashes for each field, where the keys can |:---------------|:--------|:---------|:-----------------------------|:-- | `type:` | symbol | true | `:text` | The type of the form field. Can be `:text`, `:textarea`, `:password`, `:checkbox`, or `:select`. | `name:` | string | true | | The property name for the form field. -| `required:` | boolean | false | `false` | Specify if the form field is required or optional. +| `required:` | boolean | false | `false` | Specify if the form field is required or optional. Note [backend validations](#define-validations) for presence are still needed. | `title:` | string | false | Capitalized value of `name:` | The label for the form field. | `placeholder:` | string | false | | A placeholder for the form field. | `help:` | string | false | | A help text that displays below the form field. @@ -353,6 +377,5 @@ You can refer to these issues for examples of adding new integrations: - [Datadog](https://gitlab.com/gitlab-org/gitlab/-/issues/270123): Metrics collector, similar to the Prometheus integration. - [EWM/RTC](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36662): External issue tracker. -- [Shimo](https://gitlab.com/gitlab-org/gitlab/-/issues/343386): External wiki, similar to the Confluence and External Wiki integrations. - [Webex Teams](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31543): Chat notifications. - [ZenTao](https://gitlab.com/gitlab-org/gitlab/-/issues/338178): External issue tracker with custom issue views, similar to the Jira integration. diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index f52098394dc..2a9903a0665 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # How to run Jenkins in development environment (on macOS) @@ -24,9 +24,8 @@ brew services start jenkins GitLab does not allow requests to localhost or the local network by default. When running Jenkins on your local machine, you need to enable local access. 1. Log into your GitLab instance as an administrator. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Outbound requests**, and select the following checkboxes: - **Allow requests to the local network from webhooks and integrations** diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index c7fbb73ca36..fd5ff66243a 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Set up a Jira development environment @@ -73,7 +73,7 @@ To avoid external dependencies like Gitpod and a Jira Cloud instance, use the [J ``` 1. Restart GDK. -1. Go to `http://127.0.0.1:3000/-/profile/personal_access_tokens`. +1. Go to `http://127.0.0.1:3000/-/user_settings/personal_access_tokens`. 1. Create a new token with the `api` scope and copy the token. 1. Go to `http://localhost:9292`. 1. Paste the token and select **Install GitLab.com Jira Cloud app**. diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 8c6e3145000..3fb89605bdd 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Security scanner integration @@ -239,7 +239,7 @@ Success also includes the case when vulnerabilities are found. When a CI job fails, security report results are not ingested by GitLab, even if the job [allows failure](../../ci/yaml/index.md#allow_failure). However, the report artifacts are still uploaded to GitLab and available -for [download in the pipeline security tab](../../user/application_security/vulnerability_report/pipeline.md#download-security-scan-outputs). +for [download in the pipeline security tab](../../user/application_security/vulnerability_report/pipeline.md#downloading-security-scan-results). ### Logging diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index ab94cad3bdc..53c333a6f13 100644 --- a/doc/development/integrations/secure_partner_integration.md +++ b/doc/development/integrations/secure_partner_integration.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Secure Partner Integration - Onboarding Process @@ -104,7 +104,7 @@ and complete an integration with the Secure stage. - If you specified `remediations` in your artifact, it is proposed through our [remediation](../../user/application_security/vulnerabilities/index.md#resolve-a-vulnerability) interface. 1. Demo the integration to GitLab: - - After you have tested and are ready to demo your integration please + - After you have tested and are ready to demo your integration, [reach out](https://about.gitlab.com/partners/technology-partners/integrate/) to us. If you skip this step you won't be able to do supported marketing. 1. Begin doing supported marketing of your GitLab integration. @@ -119,4 +119,4 @@ that may be helpful as part of this process. This covers various topics related tool. If you have any issues while working through your integration or the steps -above, please create an issue to discuss with us further. +above, create an issue to discuss with us further. diff --git a/doc/development/interacting_components.md b/doc/development/interacting_components.md index 7fb711795c1..b9da531f4f5 100644 --- a/doc/development/interacting_components.md +++ b/doc/development/interacting_components.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Developing against interacting components or features diff --git a/doc/development/internal_analytics/index.md b/doc/development/internal_analytics/index.md index b0e47233777..b5403f56600 100644 --- a/doc/development/internal_analytics/index.md +++ b/doc/development/internal_analytics/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Internal analytics @@ -97,6 +97,7 @@ FROM common_mart.mart_behavior_structured_event WHERE event_action = 'feature_used' AND event_category = 'InternalEventTracking' AND behavior_date > '2023-08-01' --restricted minimum date for performance +AND app_id='gitlab' -- use gitlab for production events and gitlab-staging for events from staging GROUP BY 1 ORDER BY 1 desc ``` diff --git a/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md b/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md index 807e27d546e..2c53185a5db 100644 --- a/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md +++ b/doc/development/internal_analytics/internal_event_instrumentation/event_definition_guide.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Event definition guide @@ -49,7 +49,7 @@ identifiers: - user - namespace product_section: dev -product_stage: analyze +product_stage: monitor product_group: group::product analytics milestone: "16.4" introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128029 diff --git a/doc/development/internal_analytics/internal_event_instrumentation/index.md b/doc/development/internal_analytics/internal_event_instrumentation/index.md index 35f9f31351e..a1683d4df85 100644 --- a/doc/development/internal_analytics/internal_event_instrumentation/index.md +++ b/doc/development/internal_analytics/internal_event_instrumentation/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Internal Event Tracking diff --git a/doc/development/internal_analytics/internal_event_instrumentation/introduction.md b/doc/development/internal_analytics/internal_event_instrumentation/introduction.md index e776691fdf0..1becf2da6ae 100644 --- a/doc/development/internal_analytics/internal_event_instrumentation/introduction.md +++ b/doc/development/internal_analytics/internal_event_instrumentation/introduction.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Internal event tracking diff --git a/doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md b/doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md index d9f45a2d93e..56e83184060 100644 --- a/doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md +++ b/doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Local setup and debugging @@ -54,9 +54,8 @@ On GitLab.com events are sent to a collector configured by GitLab. By default, s You can configure your self-managed GitLab instance to use a custom Snowplow collector. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Snowplow**. 1. Select **Enable Snowplow tracking** and enter your Snowplow configuration information. For example: diff --git a/doc/development/internal_analytics/internal_event_instrumentation/migration.md b/doc/development/internal_analytics/internal_event_instrumentation/migration.md index 2a3a3560292..2ef439e21e9 100644 --- a/doc/development/internal_analytics/internal_event_instrumentation/migration.md +++ b/doc/development/internal_analytics/internal_event_instrumentation/migration.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Migrating existing tracking to internal event tracking @@ -23,7 +23,7 @@ The event triggered by Internal Events has some special properties compared to p 1. The `label`, `property` and `value` attributes are not used within Internal Events and are always empty. 1. The `category` is automatically set to `InternalEventTracking` -Please make sure that you are okay with this change before you migrate and dashboards are changed accordingly. +Make sure that you are okay with this change before you migrate and dashboards are changed accordingly. ### Backend @@ -42,19 +42,14 @@ Gitlab::InternalEvents.track_event('ci_templates_unique', namespace: namespace, In addition, you have to create definitions for the metrics that you would like to track. -To generate metric definitions, you can use the generator like this: +To generate metric definitions, you can use the generator: ```shell -bin/rails g gitlab:analytics:internal_events \ - --time_frames=7d 28d\ - --group=project_management \ - --stage=plan \ - --section=dev \ - --event=ci_templates_unique \ - --unique=user.id \ - --mr=https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121544 +ruby scripts/internal_events/cli.rb ``` +The generator walks you through the required inputs step-by-step. + ### Frontend If you are using the `Tracking` mixin in the Vue component, you can replace it with the `InternalEvents` mixin. diff --git a/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md b/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md index 15ad4266d1b..6f48f83e7ca 100644 --- a/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md +++ b/doc/development/internal_analytics/internal_event_instrumentation/quick_start.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Quick start for Internal Event Tracking @@ -17,36 +17,17 @@ In order to instrument your code with Internal Events Tracking you need to do th ## Defining event and metrics -<div class="video-fallback"> - See the video about <a href="https://www.youtube.com/watch?v=QICKWznLyy0">adding events and metrics using the generator</a> -</div> -<figure class="video_container"> - <iframe src="https://www.youtube-nocookie.com/embed/QICKWznLyy0" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -To create an event and metric definitions you can use the `internal_events` generator. - -This example creates an event definition for an event called `project_created` and two metric definitions, which are aggregated every 7 and 28 days. +To create event and/or metric definitions, use the `internal_events` generator from the `gitlab` directory: ```shell -bundle exec rails generate gitlab:analytics:internal_events \ ---time_frames=7d 28d \ ---group=project_management \ ---stage=plan \ ---section=dev \ ---event=project_created \ ---unique=user.id \ ---mr=https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121544 +ruby scripts/internal_events/cli.rb ``` -Where: - -- `time_frames`: Valid options are `7d` and `28d` if you provide a `unique` value and `all` for metrics without `unique`. We are working to make `7d` and `28d` work for metrics with `all` time frame in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/411264). -- `unique`: Valid options are `user.id`, `project.id`, and `namespace.id`, as they are logged as part of the standard context. We [are actively working](https://gitlab.com/gitlab-org/gitlab/-/issues/411255) on a way to define uniqueness on arbitrary properties sent with the event, such as `merge_request.id`. +This CLI will help you create the correct defintion files based on your specific use-case, then provide code examples for instrumentation and testing. ## Trigger events -Triggering an event and thereby updating a metric is slightly different on backend and frontend. Please refer to the relevant section below. +Triggering an event and thereby updating a metric is slightly different on backend and frontend. Refer to the relevant section below. ### Backend tracking @@ -54,17 +35,27 @@ To trigger an event, call the `Gitlab::InternalEvents.track_event` method with t ```ruby Gitlab::InternalEvents.track_event( - "i_code_review_user_apply_suggestion", - user: user, - namespace: namespace, - project: project - ) + "i_code_review_user_apply_suggestion", + user: user, + namespace: namespace, + project: project +) ``` This method automatically increments all RedisHLL metrics relating to the event `i_code_review_user_apply_suggestion`, and sends a corresponding Snowplow event with all named arguments and standard context (SaaS only). +If you have defined a metric with a `unique` property such as `unique: project.id` it is required that you provide the `project` argument. + +It is encouraged to fill out as many of `user`, `namespace` and `project` as possible as it increases the data quality and make it easier to define metrics in the future. + +If a `project` but no `namespace` is provided, the `project.namespace` is used as the `namespace` for the event. + ### Frontend tracking +Any frontend tracking call automatically passes the values `user.id`, `namespace.id`, and `project.id` from the current context of the page. + +If you need to pass any further properties, such as `extra`, `context`, `label`, `property`, and `value`, you can use the [deprecated snowplow implementation](https://docs.gitlab.com/16.4/ee/development/internal_analytics/snowplow/implementation.html). In this case, let us know about your specific use-case in our [feedback issue for Internal Events](https://gitlab.com/gitlab-org/analytics-section/analytics-instrumentation/internal/-/issues/690). + #### Vue components In Vue components, tracking can be done with [Vue mixin](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/tracking/internal_events.js#L29). @@ -148,27 +139,3 @@ Sometimes we want to send internal events when the component is rendered or load = render Pajamas::ButtonComponent.new(button_options: { data: { event_tracking_load: 'true', event_tracking: 'i_devops' } }) do = _("New project") ``` - -### Props - -Apart from `eventName`, the `trackEvent` method also supports `extra` and `context` props. - -`extra`: Use this property to append supplementary information to GitLab standard context. -`context`: Use this property to attach an additional context, if needed. - -The following example shows how to use the `extra` and `context` props with the `trackEvent` method: - -```javascript -this.trackEvent('i_code_review_user_apply_suggestion', { - extra: { - projectId : 123, - }, - context: { - schema: 'iglu:com.gitlab/design_management_context/jsonschema/1-0-0', - data: { - 'design-version-number': '1.0.0', - 'design-is-current-version': '1.0.1', - }, - }, -}); -``` diff --git a/doc/development/internal_analytics/internal_events/index.md b/doc/development/internal_analytics/internal_events/index.md deleted file mode 100644 index d987317a2b0..00000000000 --- a/doc/development/internal_analytics/internal_events/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../internal_event_tracking/quick_start.md' -remove_date: '2023-10-27' ---- - -This document was moved to [another location](../internal_event_tracking/quick_start.md). - -<!-- This redirect file can be deleted after <2023-10-27>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/internal_analytics/metrics/index.md b/doc/development/internal_analytics/metrics/index.md index 45089ec8164..becd81eca51 100644 --- a/doc/development/internal_analytics/metrics/index.md +++ b/doc/development/internal_analytics/metrics/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Metrics diff --git a/doc/development/internal_analytics/metrics/metrics_dictionary.md b/doc/development/internal_analytics/metrics/metrics_dictionary.md index 6a3291eaba5..463d5be9100 100644 --- a/doc/development/internal_analytics/metrics/metrics_dictionary.md +++ b/doc/development/internal_analytics/metrics/metrics_dictionary.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Metrics Dictionary Guide @@ -29,28 +29,28 @@ Only metrics with a metric definition YAML and whose status is not `removed` are Each metric is defined in a separate YAML file consisting of a number of fields: -| Field | Required | Additional information | -|---------------------|----------|----------------------------------------------------------------| -| `key_path` | yes | JSON key path for the metric, location in Service Ping payload. | -| `description` | yes | | -| `product_section` | yes | The [section](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/sections.yml). | -| `product_stage` | yes | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the metric. | -| `product_group` | yes | The [group](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) that owns the metric. | -| `value_type` | yes | `string`; one of [`string`, `number`, `boolean`, `object`](https://json-schema.org/understanding-json-schema/reference/type.html). | -| `status` | yes | `string`; [status](#metric-statuses) of the metric, may be set to `active`, `removed`, `broken`. | -| `time_frame` | yes | `string`; may be set to a value like `7d`, `28d`, `all`, `none`. | -| `data_source` | yes | `string`; may be set to a value like `database`, `redis`, `redis_hll`, `prometheus`, `system`, `license`, `internal_events`. | -| `data_category` | yes | `string`; [categories](#data-category) of the metric, may be set to `operational`, `optional`, `subscription`, `standard`. The default value is `optional`.| -| `instrumentation_class` | yes | `string`; [the class that implements the metric](../service_ping/metrics_instrumentation.md). | -| `distribution` | yes | `array`; may be set to one of `ce, ee` or `ee`. The [distribution](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/product-and-solution-marketing/tiers/#definitions) where the tracked feature is available. | -| `performance_indicator_type` | no | `array`; may be set to one of [`gmau`, `smau`, `paid_gmau`, `umau` or `customer_health_score`](https://about.gitlab.com/handbook/business-technology/data-team/data-catalog/xmau-analysis/). | +| Field | Required | Additional information | +|---------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `key_path` | yes | JSON key path for the metric, location in Service Ping payload. | +| `description` | yes | | +| `product_section` | yes | The [section](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/sections.yml). | +| `product_stage` | yes | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the metric. | +| `product_group` | yes | The [group](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) that owns the metric. | +| `value_type` | yes | `string`; one of [`string`, `number`, `boolean`, `object`](https://json-schema.org/understanding-json-schema/reference/type.html). | +| `status` | yes | `string`; [status](#metric-statuses) of the metric, may be set to `active`, `removed`, `broken`. | +| `time_frame` | yes | `string`; may be set to a value like `7d`, `28d`, `all`, `none`. | +| `data_source` | yes | `string`; may be set to a value like `database`, `redis`, `redis_hll`, `prometheus`, `system`, `license`, `internal_events`. | +| `data_category` | yes | `string`; [categories](#data-category) of the metric, may be set to `operational`, `optional`, `subscription`, `standard`. The default value is `optional`. | +| `instrumentation_class` | no | `string`; used for metrics with `data_source` other than `internal_events`. See [the class that implements the metric](../service_ping/metrics_instrumentation.md). | +| `distribution` | yes | `array`; may be set to one of `ce, ee` or `ee`. The [distribution](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/product-and-solution-marketing/tiers/#definitions) where the tracked feature is available. | +| `performance_indicator_type` | no | `array`; may be set to one of [`gmau`, `smau`, `paid_gmau`, `umau` or `customer_health_score`](https://about.gitlab.com/handbook/business-technology/data-team/data-catalog/xmau-analysis/). | | `tier` | yes | `array`; may contain one or a combination of `free`, `premium` or `ultimate`. The [tier](https://about.gitlab.com/handbook/marketing/brand-and-product-marketing/product-and-solution-marketing/tiers/#definitions) where the tracked feature is available. This should be verbose and contain all tiers where a metric is available. | -| `milestone` | yes | The milestone when the metric is introduced and when it's available to self-managed instances with the official GitLab release. | -| `milestone_removed` | no | The milestone when the metric is removed. Required for removed metrics. | -| `introduced_by_url` | no | The URL to the merge request that introduced the metric to be available for self-managed instances. | -| `removed_by_url` | no | The URL to the merge request that removed the metric. Required for removed metrics. | -| `repair_issue_url` | no | The URL of the issue that was created to repair a metric with a `broken` status. | -| `options` | no | `object`: options information needed to calculate the metric value. | +| `milestone` | yes | The milestone when the metric is introduced and when it's available to self-managed instances with the official GitLab release. | +| `milestone_removed` | no | The milestone when the metric is removed. Required for removed metrics. | +| `introduced_by_url` | no | The URL to the merge request that introduced the metric to be available for self-managed instances. | +| `removed_by_url` | no | The URL to the merge request that removed the metric. Required for removed metrics. | +| `repair_issue_url` | no | The URL of the issue that was created to repair a metric with a `broken` status. | +| `options` | no | `object`: options information needed to calculate the metric value. | ### Metric `key_path` diff --git a/doc/development/internal_analytics/metrics/metrics_instrumentation.md b/doc/development/internal_analytics/metrics/metrics_instrumentation.md index df0b3ff9a6a..fa3d4069955 100644 --- a/doc/development/internal_analytics/metrics/metrics_instrumentation.md +++ b/doc/development/internal_analytics/metrics/metrics_instrumentation.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Metrics instrumentation guide diff --git a/doc/development/internal_analytics/metrics/metrics_lifecycle.md b/doc/development/internal_analytics/metrics/metrics_lifecycle.md index 2361b8d2ca6..681992b4379 100644 --- a/doc/development/internal_analytics/metrics/metrics_lifecycle.md +++ b/doc/development/internal_analytics/metrics/metrics_lifecycle.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Metric lifecycle @@ -24,7 +24,7 @@ As a result, if you need to change one of the following parts of a metric, you n - **calculation logic**: This means any changes that can produce a different value than the previous implementation - **YAML attributes**: The following attributes are directly used for analysis or calculation: `key_path`, `time_frame`, `value_type`, `data_source`. -If you change the `performance_indicator_type` attribute of a metric or think your case needs an exception from the outlined rules then please notify the Customer Success Ops team (`@csops-team`), Analytics Engineers (`@gitlab-data/analytics-engineers`), and Product Analysts (`@gitlab-data/product-analysts`) teams by `@` mentioning those groups in a comment on the merge request or issue. +If you change the `performance_indicator_type` attribute of a metric or think your case needs an exception from the outlined rules then notify the Customer Success Ops team (`@csops-team`), Analytics Engineers (`@gitlab-data/analytics-engineers`), and Product Analysts (`@gitlab-data/product-analysts`) teams by `@` mentioning those groups in a comment on the merge request or issue. You can change any other attributes without impact to the calculation or analysis. See [this video tutorial](https://youtu.be/bYf3c01KCls) for help updating metric attributes. @@ -91,7 +91,7 @@ To remove a metric: therefore continue to report the removed metric. The Analytics Instrumentation team requires a record of all removed metrics to identify and filter them. - For example please take a look at this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60149/diffs#b01f429a54843feb22265100c0e4fec1b7da1240_10_10). + For example, take a look at this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60149/diffs#b01f429a54843feb22265100c0e4fec1b7da1240_10_10). 1. After you verify the metric can be safely removed, remove the metric's instrumentation from @@ -99,7 +99,7 @@ To remove a metric: or [`ee/lib/ee/gitlab/usage_data.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/usage_data.rb). - For example please take a look at this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60149/diffs#6335dc533bd21df26db9de90a02dd66278c2390d_167_167). + For example, take a look at this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60149/diffs#6335dc533bd21df26db9de90a02dd66278c2390d_167_167). 1. Remove any other records related to the metric: - The feature flag YAML file at [`config/feature_flags/*/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/feature_flags). diff --git a/doc/development/internal_analytics/review_guidelines.md b/doc/development/internal_analytics/review_guidelines.md index bb7491fd20d..eb59b834cbc 100644 --- a/doc/development/internal_analytics/review_guidelines.md +++ b/doc/development/internal_analytics/review_guidelines.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Internal Analytics review guidelines diff --git a/doc/development/internal_analytics/service_ping/index.md b/doc/development/internal_analytics/service_ping/index.md index f010884272b..eb0e384b10d 100644 --- a/doc/development/internal_analytics/service_ping/index.md +++ b/doc/development/internal_analytics/service_ping/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Service Ping development guidelines @@ -361,7 +361,7 @@ Rake tasks exist to export Service Ping data in different formats. - The Rake tasks export the Redis counter class or the line of the Redis block for `redis_usage_data`. - The Rake tasks calculate the `alt_usage_data` metrics. -In the home directory of your local GitLab installation run the following Rake tasks for the YAML and JSON versions respectively: +In the home directory of your local GitLab installation run the following Rake tasks for either the YAML or the JSON versions: ```shell # for YAML export of SQL queries diff --git a/doc/development/internal_analytics/service_ping/metrics_dictionary.md b/doc/development/internal_analytics/service_ping/metrics_dictionary.md deleted file mode 100644 index 9adcaaf431d..00000000000 --- a/doc/development/internal_analytics/service_ping/metrics_dictionary.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../metrics/metrics_dictionary.md' -remove_date: '2023-09-25' ---- - -This document was moved to [another location](../metrics/metrics_dictionary.md). - -<!-- This redirect file can be deleted after <2023-12-25>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/internal_analytics/service_ping/metrics_lifecycle.md b/doc/development/internal_analytics/service_ping/metrics_lifecycle.md deleted file mode 100644 index 126bc3988ed..00000000000 --- a/doc/development/internal_analytics/service_ping/metrics_lifecycle.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../metrics/metrics_lifecycle.md' -remove_date: '2023-09-25' ---- - -This document was moved to [another location](../metrics/metrics_lifecycle.md). - -<!-- This redirect file can be deleted after <2023-12-25>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/internal_analytics/service_ping/performance_indicator_metrics.md b/doc/development/internal_analytics/service_ping/performance_indicator_metrics.md deleted file mode 100644 index 7388415f384..00000000000 --- a/doc/development/internal_analytics/service_ping/performance_indicator_metrics.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../metrics/metrics_dictionary.md#performance-indicator-metrics' -remove_date: '2023-09-25' ---- - -This document was moved to [another location](../metrics/metrics_lifecycle.md). - -<!-- This redirect file can be deleted after <2023-12-25>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/internal_analytics/service_ping/troubleshooting.md b/doc/development/internal_analytics/service_ping/troubleshooting.md index ba56ee1e223..1b74921fb2f 100644 --- a/doc/development/internal_analytics/service_ping/troubleshooting.md +++ b/doc/development/internal_analytics/service_ping/troubleshooting.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Troubleshooting Service Ping @@ -69,7 +69,7 @@ and run a local container instance: 1. In the downstream pipeline, wait for the `gitlab-docker` job to finish. 1. Open the job logs and locate the full container name including the version. It takes the following form: `registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>`. 1. On your local machine, make sure you are signed in to the GitLab Docker registry. You can find the instructions for this in - [Authenticate to the GitLab Container Registry](../../../user/packages/container_registry/authenticate_with_container_registry.md). + [Authenticate to the GitLab container registry](../../../user/packages/container_registry/authenticate_with_container_registry.md). 1. Once signed in, download the new image by using `docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>` 1. For more information about working with and running Omnibus GitLab containers in Docker, refer to [GitLab Docker images](../../../install/docker.md) documentation. @@ -142,8 +142,7 @@ checking the configuration file of your GitLab instance: - Using the Admin Area: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand **Usage statistics**. 1. Are you able to check or uncheck the checkbox to disable Service Ping? @@ -200,8 +199,7 @@ To work around this bug, you have two options: sudo gitlab-ctl reconfigure ``` - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Expand **Usage statistics**. 1. Clear the **Enable Service Ping** checkbox. diff --git a/doc/development/internal_api/index.md b/doc/development/internal_api/index.md index 9b5bafaad8f..84f5d09418f 100644 --- a/doc/development/internal_api/index.md +++ b/doc/development/internal_api/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Internal API @@ -467,8 +466,7 @@ Example response: ## GitLab agent endpoints > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41045) in GitLab 13.4. -> - This feature is not deployed on GitLab.com -> - It's not recommended for production use. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/432773) in GitLab 16.7. The following endpoints are used by the GitLab agent server (`kas`) for various purposes. @@ -556,6 +554,46 @@ curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Con --data '{"counters": {"gitops_sync":1}}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics" ``` +### GitLab agent events + +Called from GitLab agent server (`kas`) to track events. + +| Attribute | Type | Required | Description | +|:------------------------------------------------------------------------------|:--------------|:---------|:--------------------------------------------------------------------------| +| `events` | hash | no | Hash of events | +| `events["k8s_api_proxy_requests_unique_users_via_ci_access"]` | hash array | no | Array of events for `k8s_api_proxy_requests_unique_users_via_ci_access` | +| `events["k8s_api_proxy_requests_unique_users_via_ci_access"]["user_id"]` | integer | no | The user ID for the event | +| `events["k8s_api_proxy_requests_unique_users_via_ci_access"]["project_id"]` | integer | no | The project ID for the event | +| `events["k8s_api_proxy_requests_unique_users_via_user_access"]` | hash array | no | Array of events for `k8s_api_proxy_requests_unique_users_via_user_access` | +| `events["k8s_api_proxy_requests_unique_users_via_user_access"]["user_id"]` | integer | no | The user ID for the event | +| `events["k8s_api_proxy_requests_unique_users_via_user_access"]["project_id"]` | integer | no | The project ID for the event | +| `events["k8s_api_proxy_requests_unique_users_via_pat_access"]` | hash array | no | Array of events for `k8s_api_proxy_requests_unique_users_via_pat_access` | +| `events["k8s_api_proxy_requests_unique_users_via_pat_access"]["user_id"]` | integer | no | The user ID for the event | +| `events["k8s_api_proxy_requests_unique_users_via_pat_access"]["project_id"]` | integer | no | The project ID for the event | + +```plaintext +POST /internal/kubernetes/agent_events +``` + +Example Request: + +```shell +curl --request POST \ + --url "http://localhost:3000/api/v4/internal/kubernetes/agent_events" \ + --header "Gitlab-Kas-Api-Request: <JWT token>" \ + --header "Content-Type: application/json" \ + --data '{ + "events": { + "k8s_api_proxy_requests_unique_users_via_ci_access": [ + { + "user_id": 1, + "project_id": 1 + } + ] + } + }' +``` + ### Create Starboard vulnerability Called from the GitLab agent server (`kas`) to create a security vulnerability @@ -1236,10 +1274,12 @@ This group SCIM API is different to the [SCIM API](../../api/scim.md). The SCIM - Does not implement the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). - Gets, checks, updates, and deletes SCIM identities within groups. +NOTE: +This API does not require the `Gitlab-Shell-Api-Request` header. + ### Get a list of SCIM provisioned users -This endpoint is used as part of the SCIM syncing mechanism. It only returns -a single user based on a unique ID which should match the `extern_uid` of the user. +This endpoint is used as part of the SCIM syncing mechanism. It returns a list of users depending on the filter used. ```plaintext GET /api/scim/v2/groups/:group_path/Users @@ -1257,7 +1297,7 @@ Parameters: NOTE: Pagination follows the [SCIM spec](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.4) rather than GitLab pagination as used elsewhere. If records change between requests it is possible for a page to either be missing records that have moved to a different page or repeat records from a previous request. -Example request: +Example request filtering on a specific identifier: ```shell curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \ @@ -1414,7 +1454,7 @@ Parameters: | `group_path` | string | yes | Full path to the group. | | `Operations` | JSON string | yes | An [operations](#available-operations) expression. | -Example request: +Example request to update the user's `id`: ```shell curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ @@ -1424,6 +1464,16 @@ curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/te Returns an empty response with a `204` status code if successful. +Example request to set the user's `active` state: + +```shell +curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --data '{ "Operations": [{"op":"replace","path":"active","value":"true"}] }' \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +Returns an empty response with a `204` status code if successful. + ### Remove a single SCIM provisioned user Removes the user's SSO identity and group membership. @@ -1472,10 +1522,12 @@ This instance SCIM API is different to the [SCIM API](../../api/scim.md). The SC - Does not implement the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). - Gets, checks, updates, and deletes SCIM identities within groups. +NOTE: +This API does not require the `Gitlab-Shell-Api-Request` header. + ### Get a list of SCIM provisioned users -This endpoint is used as part of the SCIM syncing mechanism. It only returns -a single user based on a unique ID which should match the `extern_uid` of the user. +This endpoint is used as part of the SCIM syncing mechanism. It returns a list of users depending on the filter used. ```plaintext GET /api/scim/v2/application/Users @@ -1651,9 +1703,9 @@ curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/applicati Returns an empty response with a `204` status code if successful. -### Remove a single SCIM provisioned user +### Block a single SCIM provisioned user -The user is placed in an `ldap_blocked` status and signed out. This means +The user is placed in a `blocked` state and signed out. This means the user cannot sign in or push or pull code. ```plaintext diff --git a/doc/development/internal_api/internal_api_allowed.md b/doc/development/internal_api/internal_api_allowed.md index d5e4e8cf63d..8af6a85712f 100644 --- a/doc/development/internal_api/internal_api_allowed.md +++ b/doc/development/internal_api/internal_api_allowed.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Internal allowed API diff --git a/doc/development/internal_users.md b/doc/development/internal_users.md index 2b809137906..4af6245a64c 100644 --- a/doc/development/internal_users.md +++ b/doc/development/internal_users.md @@ -1,9 +1,8 @@ --- description: "Internal users documentation." -type: concepts, reference, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Internal users diff --git a/doc/development/issuable-like-models.md b/doc/development/issuable-like-models.md index 0b48883fe58..3e98dde6a2e 100644 --- a/doc/development/issuable-like-models.md +++ b/doc/development/issuable-like-models.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Issuable-like Rails models utilities diff --git a/doc/development/issue_types.md b/doc/development/issue_types.md index d0d513af781..8bacdc06c37 100644 --- a/doc/development/issue_types.md +++ b/doc/development/issue_types.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Issue Types (deprecated) diff --git a/doc/development/json.md b/doc/development/json.md index bdb7f73ab62..2292e102fa3 100644 --- a/doc/development/json.md +++ b/doc/development/json.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # JSON development guidelines diff --git a/doc/development/kubernetes.md b/doc/development/kubernetes.md index e537b4c4c76..43341483d86 100644 --- a/doc/development/kubernetes.md +++ b/doc/development/kubernetes.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Kubernetes integration development guidelines diff --git a/doc/development/labels/index.md b/doc/development/labels/index.md index c2caabda109..4288408baf6 100644 --- a/doc/development/labels/index.md +++ b/doc/development/labels/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Labels @@ -24,9 +24,9 @@ Most issues will have labels for at least one of the following: - Priority: `~"priority::1"`, `~"priority::2"`, `~"priority::3"`, `~"priority::4"` - Severity: `~"severity::1"`, `~"severity::2"`, `~"severity::3"`, `~"severity::4"` -Please add `~"breaking change"` label if the issue can be considered as a [breaking change](../deprecation_guidelines/index.md). +Add `~"breaking change"` label if the issue can be considered as a [breaking change](../deprecation_guidelines/index.md). -Please add `~security` label if the issue is related to application security. +Add `~security` label if the issue is related to application security. All labels, their meaning and priority are defined on the [labels page](https://gitlab.com/gitlab-org/gitlab/-/labels). @@ -252,7 +252,7 @@ We have the following priority labels: - `~"priority::3"` - `~"priority::4"` -Please refer to the issue triage [priority label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#priority) section in our handbook to see how it's used. +Refer to the issue triage [priority label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#priority) section in our handbook to see how it's used. ## Severity labels @@ -263,7 +263,7 @@ We have the following severity labels: - `~"severity::3"` - `~"severity::4"` -Please refer to the issue triage [severity label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#severity) section in our handbook to see how it's used. +Refer to the issue triage [severity label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#severity) section in our handbook to see how it's used. ## Label for community contributors @@ -301,7 +301,7 @@ with the [label `~"Community Challenge"`](https://gitlab.com/gitlab-org/gitlab/- If your MR for the `~"Community Challenge"` issue gets merged, you will also have a chance to win a custom GitLab merchandise. -If you've decided that you would like to work on an issue, please @-mention +If you've decided that you would like to work on an issue, @-mention the [appropriate product manager](https://about.gitlab.com/handbook/product/#who-to-talk-to-for-what) as soon as possible. The product manager will then pull in appropriate GitLab team members to further discuss scope, design, and technical considerations. This will diff --git a/doc/development/lfs.md b/doc/development/lfs.md index bb327bf5d04..289c258fafe 100644 --- a/doc/development/lfs.md +++ b/doc/development/lfs.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Git LFS development guidelines diff --git a/doc/development/licensing.md b/doc/development/licensing.md index de2df3c8ca1..c84f42270c3 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab Licensing and Compatibility @@ -44,7 +44,7 @@ To tell License Finder about a dependency's license if it isn't auto-detected: license_finder licenses add my_unknown_dependency MIT ``` -For all of the above, please include `--why "Reason"` and `--who "My Name"` so the `decisions.yml` file can keep track of when, why, and who approved of a dependency. +For all of the above, include `--why "Reason"` and `--who "My Name"` so the `decisions.yml` file can keep track of when, why, and who approved of a dependency. More detailed information on how the gem and its commands work is available in the [License Finder README](https://github.com/pivotal/LicenseFinder). @@ -77,4 +77,4 @@ Those projects are set to use a test license encryption key by default. ## Additional information -Please see the [Open Source](https://about.gitlab.com/handbook/engineering/open-source/#using-open-source-libraries) page for more information on licensing. +See the [Open Source](https://about.gitlab.com/handbook/engineering/open-source/#using-open-source-libraries) page for more information on licensing. diff --git a/doc/development/logging.md b/doc/development/logging.md index 908fa16d3f8..2af914d76ef 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Logging development guidelines @@ -361,7 +361,7 @@ class MyExampleWorker end ``` -Please see [this example](https://gitlab.com/gitlab-org/gitlab/-/blob/16ecc33341a3f6b6bebdf78d863c5bce76b040d3/app/workers/ci/pipeline_artifacts/expire_artifacts_worker.rb#L20-21) +See [this example](https://gitlab.com/gitlab-org/gitlab/-/blob/16ecc33341a3f6b6bebdf78d863c5bce76b040d3/app/workers/ci/pipeline_artifacts/expire_artifacts_worker.rb#L20-21) which logs a count of how many artifacts are destroyed per run of the `ExpireArtifactsWorker`. ## Exception Handling diff --git a/doc/development/maintenance_mode.md b/doc/development/maintenance_mode.md index 486519715ab..ad0893d8605 100644 --- a/doc/development/maintenance_mode.md +++ b/doc/development/maintenance_mode.md @@ -1,7 +1,7 @@ --- stage: Systems group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Internal workings of GitLab Maintenance Mode diff --git a/doc/development/mass_insert.md b/doc/development/mass_insert.md index 24f6127a3de..412639927a7 100644 --- a/doc/development/mass_insert.md +++ b/doc/development/mass_insert.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Mass inserting Rails models @@ -15,5 +15,5 @@ the following snippet in the rails console. ```ruby u = User.find(1) -Project.last(100).each { |p| p.set_timestamps_for_create && p.add_maintainer(u, current_user: u) } # Change 100 to whatever number of projects you need access to +Project.last(100).each { |p| p.send(:set_timestamps_for_create) && p.add_maintainer(u, current_user: u) } # Change 100 to whatever number of projects you need access to ``` diff --git a/doc/development/merge_request_concepts/approval_rules.md b/doc/development/merge_request_concepts/approval_rules.md index bba61a71543..44b53e2feb8 100644 --- a/doc/development/merge_request_concepts/approval_rules.md +++ b/doc/development/merge_request_concepts/approval_rules.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Approval rules development guidelines diff --git a/doc/development/merge_request_concepts/diffs/development.md b/doc/development/merge_request_concepts/diffs/development.md index 42f6c2dc16e..0aef8d03e51 100644 --- a/doc/development/merge_request_concepts/diffs/development.md +++ b/doc/development/merge_request_concepts/diffs/development.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Merge request diffs development guide diff --git a/doc/development/merge_request_concepts/diffs/frontend.md b/doc/development/merge_request_concepts/diffs/frontend.md index 0625c32377f..aeb1ba452a3 100644 --- a/doc/development/merge_request_concepts/diffs/frontend.md +++ b/doc/development/merge_request_concepts/diffs/frontend.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Merge request diffs frontend overview diff --git a/doc/development/merge_request_concepts/diffs/index.md b/doc/development/merge_request_concepts/diffs/index.md index c2dec5c4753..ad0e8603983 100644 --- a/doc/development/merge_request_concepts/diffs/index.md +++ b/doc/development/merge_request_concepts/diffs/index.md @@ -1,11 +1,14 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Working with diffs +This page contains developer documentation for diffs. For the user documentation, +see [Diffs in merge requests](../../../user/project/merge_requests/versions.md). + We rely on different sources to present diffs. These include: - Gitaly service @@ -18,7 +21,7 @@ We rely on different sources to present diffs. These include: In January 2019, Oswaldo Ferreira hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/-/issues/1`) on GitLab Diffs and Commenting on Diffs -functionality to share domain-specific knowledge with anyone who may work in this part of the +functionality to share domain-specific knowledge with anyone who works in this part of the codebase in the future: <!-- vale gitlab.Spelling = YES --> @@ -28,7 +31,7 @@ codebase in the future: - Slides on [Google Slides](https://docs.google.com/presentation/d/1bGutFH2AT3bxOPZuLMGl1ANWHqFnrxwQwjiwAZkF-TU/edit) - [PDF slides](https://gitlab.com/gitlab-org/create-stage/uploads/b5ad2f336e0afcfe0f99db0af0ccc71a/) -Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details may +Everything covered in this deep dive was accurate as of GitLab 11.7, and while specific details might have changed since then, it should still serve as a good introduction. ## Architecture overview diff --git a/doc/development/merge_request_concepts/index.md b/doc/development/merge_request_concepts/index.md index 8bec5e0c0b0..d04dff9f1be 100644 --- a/doc/development/merge_request_concepts/index.md +++ b/doc/development/merge_request_concepts/index.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: Create group: Code Review -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Merge request concepts @@ -28,7 +27,7 @@ The merge widget is the component of the merge request where the `merge` button  -This area of the merge request is where all of the options and commit messages are defined prior to merging. It also contains information about what is in the merge request, what issues may be closed, and other important information to the merging process. +This area of the merge request is where all of the options and commit messages are defined prior to merging. It also contains information about what is in the merge request, what issues are closed, and other information important to the merging process. ## Report widgets diff --git a/doc/development/merge_request_concepts/mergeability_framework.md b/doc/development/merge_request_concepts/mergeability_framework.md new file mode 100644 index 00000000000..a755615c885 --- /dev/null +++ b/doc/development/merge_request_concepts/mergeability_framework.md @@ -0,0 +1,85 @@ +--- +stage: Create +group: Code Review +info: Detailing the process to add a new mergeability check +--- + +# Mergeability framework + +The initial work started with the [better defined mergeability framework](https://gitlab.com/groups/gitlab-org/-/epics/5598) + +Originally, the mergeability knowledge was spread throughout the backend and frontend. +This work was to consolidate some of the mergeability criteria into the same location +in the backend. This allows the frontend to simply consume the API and display the error. + +## Add a new check + +The mergeability checks live under `app/services/merge_requests/mergeability/`. + +1. To create a new check, we can use this as a base: + + ```ruby + # frozen_string_literal: true + module MergeRequests + module Mergeability + class CheckCiStatusService < CheckBaseService + identifier :ci_must_pass + description 'Checks whether CI has passed' + + def execute + # If the merge check is behind a setting, we return inactive if the setting is false + return inactive unless merge_request.only_allow_merge_if_pipeline_succeeds? + + if merge_request.mergeable_ci_state? + success + else + failure + end + end + + def skip? + # Here we can check for the param or return false if its not skippable + # Skippablility of an MR is related to merge when checks pass functionality + params[:skip_ci_check].present? + end + + def cacheable? + false + end + end + end + end + ``` + +1. Add the new check in the `def mergeable_state_checks` method. +1. Add the new check to the GraphQL enum `app/graphql/types/merge_requests/detailed_merge_status_enum.rb`. +1. Update the GraphQL documentation with `bundle exec rake gitlab:graphql:compile_docs`. +1. Update the API documentation in `doc/api/merge_requests.md`. +1. Update the frontend to support the new message: `app/assets/javascripts/vue_merge_request_widget/components/checks/message.vue`. + +## Considerations + +1. **Should it be skippable?** If it is part of the merge when checks pass work, + then we should add the skippable check. Otherwise, you should return `false`. +1. **Performance**: These mergeability checks are run very frequently, and therefore + performance is a big consideration here. It is critical to check how the new + mergeability check performs. In general, we are expecting around 10-20 ms. +1. **Caching is an option too.** We can set the `def cacheable?` method to return `true`, + and in that case, we need to create another method `def cache_key` to set the + cache key for the particular check. Cache invalidation can often be tricky, + and we must consider all the edge cases in the cache key. If we keep the timing + around 10-20 ms, then caching is not needed. +1. **Time the checks.** We time each check through the `app/services/merge_requests/mergeability/logger.rb` + class, which can then be viewed in Kibana. + +## How the classes work together + +1. The main methods that call the mergeability framework are: `def mergeable?`, and `DetailedMergeStatusService`. +1. These methods call the `RunChecksService` class which handles the iterating + of the mergeability checks, caching and instrumentation. + +## Future work + +1. At the moment, the slow performance of the approval check is the main area of + concern. We have attempted to make this check cacheable, but there are a lot of + edge cases to consider in regard to when it is invalid. diff --git a/doc/development/merge_request_concepts/performance.md b/doc/development/merge_request_concepts/performance.md index 7e26bf982b2..7a1e33494d0 100644 --- a/doc/development/merge_request_concepts/performance.md +++ b/doc/development/merge_request_concepts/performance.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Merge Request Performance Guidelines @@ -286,7 +286,7 @@ be clearly mentioned in the merge request description. **Summary:** Iterating a single process to external services (for example, PostgreSQL, Redis, Object Storage) should be executed in a **batch-style** to reduce connection overheads. -For fetching rows from various tables in a batch-style, please see [Eager Loading](#eager-loading) section. +For fetching rows from various tables in a batch-style, see [Eager Loading](#eager-loading) section. ### Example: Delete multiple files from Object Storage @@ -323,7 +323,7 @@ Using [`ReactiveCaching`](../utilities.md#reactivecaching) is one of the best so transactions, otherwise it leads to severe contention problems as an open transaction basically blocks the release of a PostgreSQL backend connection. -For keeping transaction as minimal as possible, please consider using `AfterCommitQueue` +For keeping transaction as minimal as possible, consider using `AfterCommitQueue` module or `after_commit` AR hook. Here is [an example](https://gitlab.com/gitlab-org/gitlab/-/issues/36154#note_247228859) diff --git a/doc/development/merge_request_concepts/rate_limits.md b/doc/development/merge_request_concepts/rate_limits.md index 62c50e3d044..9544908b2a3 100644 --- a/doc/development/merge_request_concepts/rate_limits.md +++ b/doc/development/merge_request_concepts/rate_limits.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Application and rate limit guidelines diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index afb36519b8d..30f598ef736 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Migration Style Guide @@ -27,7 +27,7 @@ When writing your migrations, also consider that databases might have stale data or inconsistencies and guard for that. Try to make as few assumptions as possible about the state of the database. -Please don't depend on GitLab-specific code since it can change in future +Don't depend on GitLab-specific code since it can change in future versions. If needed copy-paste GitLab code into the migration to make it forward compatible. @@ -140,7 +140,7 @@ Changes to the schema should be committed to `db/structure.sql`. This file is automatically generated by Rails when you run `bundle exec rails db:migrate`, so you typically should not edit this file by hand. If your migration is adding a column to a -table, that column is added at the bottom. Please do not reorder +table, that column is added at the bottom. Do not reorder columns manually for existing tables as this causes confusion to other people using `db/structure.sql` generated by Rails. @@ -1019,9 +1019,13 @@ end ## Dropping a database table +NOTE: +After a table has been dropped, it should be added to the database dictionary, following the +steps in the [database dictionary guide](database/database_dictionary.md#dropping-tables). + Dropping a database table is uncommon, and the `drop_table` method provided by Rails is generally considered safe. Before dropping the table, -please consider the following: +consider the following: If your table has foreign keys on a [high-traffic table](#high-traffic-tables) (like `projects`), then the `DROP TABLE` statement is likely to stall concurrent traffic until it fails with **statement timeout** error. @@ -1105,9 +1109,6 @@ class DroppingTableMigrationClass < Gitlab::Database::Migration[2.1] end ``` -After a table has been dropped, it should be added to the database dictionary, following the -steps in the [database dictionary guide](database/database_dictionary.md#dropping-tables). - ## Dropping a sequence > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88387) in GitLab 15.1. @@ -1369,7 +1370,7 @@ See the [Testing Rails migrations](testing_guide/testing_migrations_guide.md) st ## Data migration -Please prefer Arel and plain SQL over usual ActiveRecord syntax. In case of +Prefer Arel and plain SQL over usual ActiveRecord syntax. In case of using plain SQL, you need to quote all input manually with `quote_string` helper. Example with Arel: diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md index 733823d7f6e..36e6639857b 100644 --- a/doc/development/module_with_instance_variables.md +++ b/doc/development/module_with_instance_variables.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Modules with instance variables could be considered harmful diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index 36b392a0037..40a30aa4926 100644 --- a/doc/development/multi_version_compatibility.md +++ b/doc/development/multi_version_compatibility.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Backwards compatibility across updates @@ -243,7 +243,7 @@ With all those details in mind, let's imagine we need to replace a query, and th 1. **contract**: from `Schema B` to `Schema C` (post-deployment migration). Nothing uses the old index anymore, we can safely remove it. This is only an example. More complex migrations, especially when background migrations are needed may -require more than one milestone. For details please refer to our [migration style guide](migration_style_guide.md). +require more than one milestone. For details refer to our [migration style guide](migration_style_guide.md). ## Examples of previous incidents diff --git a/doc/development/namespaces.md b/doc/development/namespaces.md index e25b0f57f08..8a094541c27 100644 --- a/doc/development/namespaces.md +++ b/doc/development/namespaces.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Namespaces diff --git a/doc/development/navigation_sidebar.md b/doc/development/navigation_sidebar.md index f7ab75b62f4..fb6385dd3ff 100644 --- a/doc/development/navigation_sidebar.md +++ b/doc/development/navigation_sidebar.md @@ -1,7 +1,7 @@ --- stage: Manage group: Foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Navigation sidebar diff --git a/doc/development/omnibus.md b/doc/development/omnibus.md index a0ba2751a06..1d9706c7245 100644 --- a/doc/development/omnibus.md +++ b/doc/development/omnibus.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # What you should know about Omnibus packages diff --git a/doc/development/organization/index.md b/doc/development/organization/index.md index 3a23e50caf9..3882000dc8b 100644 --- a/doc/development/organization/index.md +++ b/doc/development/organization/index.md @@ -1,8 +1,7 @@ --- -type: index, dev stage: Data Stores group: Tenant Scale -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "Development Guidelines: learn about organization when developing GitLab." --- diff --git a/doc/development/packages/cleanup_policies.md b/doc/development/packages/cleanup_policies.md index aa60cde450b..bbec6ce0623 100644 --- a/doc/development/packages/cleanup_policies.md +++ b/doc/development/packages/cleanup_policies.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Cleanup policies @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Cleanup policies are recurrent background processes that automatically remove objects according to some parameters set by users. -## Container Registry +## Container registry Cleanup policies for the container registry work on all the container repositories hosted in a single project. All tags that match the cleanup parameters are removed. diff --git a/doc/development/packages/debian_repository.md b/doc/development/packages/debian_repository.md index 2d8ba98f9ad..deb5eb05118 100644 --- a/doc/development/packages/debian_repository.md +++ b/doc/development/packages/debian_repository.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Debian Repository diff --git a/doc/development/packages/dependency_proxy.md b/doc/development/packages/dependency_proxy.md index e9568699c7e..ad6459e4916 100644 --- a/doc/development/packages/dependency_proxy.md +++ b/doc/development/packages/dependency_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Dependency Proxy diff --git a/doc/development/packages/harbor_registry_development.md b/doc/development/packages/harbor_registry_development.md index 609aba9251c..0ed1378ad65 100644 --- a/doc/development/packages/harbor_registry_development.md +++ b/doc/development/packages/harbor_registry_development.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Harbor Registry diff --git a/doc/development/packages/index.md b/doc/development/packages/index.md index 4f027825422..91351d3ef5a 100644 --- a/doc/development/packages/index.md +++ b/doc/development/packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Package and container registry development guidelines diff --git a/doc/development/packages/new_format_development.md b/doc/development/packages/new_format_development.md index 0af0b8ad480..018d9c0cde9 100644 --- a/doc/development/packages/new_format_development.md +++ b/doc/development/packages/new_format_development.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Developing support for a new package format @@ -229,7 +229,7 @@ in your local development environment. #### File size limits -Files uploaded to the GitLab Package Registry are [limited by format](../../administration/instance_limits.md#package-registry-limits). +Files uploaded to the GitLab package registry are [limited by format](../../administration/instance_limits.md#package-registry-limits). On GitLab.com, these are typically set to 5GB to help prevent timeout issues and abuse. When a new package type is added to the `Packages::Package` model, a size limit must be added diff --git a/doc/development/packages/settings.md b/doc/development/packages/settings.md index 0fc49c4eb5d..89f91f41f4c 100644 --- a/doc/development/packages/settings.md +++ b/doc/development/packages/settings.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Package Settings @@ -10,7 +10,7 @@ This page includes an exhaustive list of settings related to and maintained by t ## Instance Settings -### Package Registry +### Package registry Setting | Table | Description ------- | ----- | ----------- @@ -36,7 +36,7 @@ Setting | Table | Description `terraform_module_max_file_size` | `plan_limits` | Maximum file size for a Terraform package file. `helm_max_file_size` | `plan_limits` | Maximum file size for a Helm package file. -### Container Registry +### Container registry Setting | Table | Description ------- | ----- | ----------- @@ -51,7 +51,7 @@ Setting | Table | Description `container_registry_expiration_policies_caching` | `application_settings` | Enable or disable tag creation timestamp caching during execution of cleanup policies. `container_registry_import_max_tags_count` | `application_settings` | Defines what is a the maximum amount of tags that we accept to migrate. `container_registry_import_max_retries` | `application_settings` | The maximum amount of retries done on a migration that is aborted. -`container_registry_import_start_max_retries` | `application_settings` | The maximum amount of requests to start an import step that is sent to the Container Registry API. +`container_registry_import_start_max_retries` | `application_settings` | The maximum amount of requests to start an import step that is sent to the container registry API. `container_registry_import_max_step_duration` | `application_settings` | The maximum amount of seconds before an ongoing migration is considered as stale. `container_registry_import_target_plan` | `application_settings` | The target subscription plan on which we're intend to pick container repositories. `container_registry_import_created_before` | `application_settings` | Only image repositories created before this timestamp are eligible for the migration. @@ -69,6 +69,7 @@ Setting | Table | Description `generic_duplicate_exception_regex` | `namespace_package_settings` | Regex defining generic packages that are allowed to be duplicate when duplicates are not allowed. `nuget_duplicates_allowed` | `namespace_package_settings` | Allow or prevent duplicate NuGet packages. `nuget_duplicate_exception_regex` | `namespace_package_settings` | Regex defining NuGet packages that are allowed to be duplicate when duplicates are not allowed. +`nuget_symbol_server_enabled` | `namespace_package_settings` | Enable or disable the NuGet symbol server. Dependency Proxy Cleanup Policies - `ttl` | `dependency_proxy_image_ttl_group_policies` | Number of days to retain an unused Dependency Proxy file before it is removed. Dependency Proxy - `enabled` | `dependency_proxy_image_ttl_group_policies` | Enable or disable the Dependency Proxy cleanup policy. diff --git a/doc/development/packages/structure.md b/doc/development/packages/structure.md index 281ec2e6c39..371f33712f6 100644 --- a/doc/development/packages/structure.md +++ b/doc/development/packages/structure.md @@ -1,12 +1,12 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Package Structure -## Package Registry +## Package registry ```mermaid erDiagram @@ -58,7 +58,7 @@ erDiagram packages_debian_file_metadata |o--|| packages_package_files : "" ``` -## Container Registry +## Container registry ```mermaid erDiagram diff --git a/doc/development/pages/dnsmasq.md b/doc/development/pages/dnsmasq.md index a14e215ccd7..1506527c3f1 100644 --- a/doc/development/pages/dnsmasq.md +++ b/doc/development/pages/dnsmasq.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: "dnsmasq configuration guidelines for GitLab Pages" --- diff --git a/doc/development/pages/index.md b/doc/development/pages/index.md index 25c1ea7a864..f4710c951ed 100644 --- a/doc/development/pages/index.md +++ b/doc/development/pages/index.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: "GitLab's development guidelines for GitLab Pages" --- diff --git a/doc/development/performance.md b/doc/development/performance.md index 428d5637aa9..9bdb65aacba 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Performance Guidelines diff --git a/doc/development/permissions.md b/doc/development/permissions.md index 32d5ccfcdf1..9b0035f17ec 100644 --- a/doc/development/permissions.md +++ b/doc/development/permissions.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Permission development guidelines diff --git a/doc/development/permissions/authorizations.md b/doc/development/permissions/authorizations.md index 20b39f4093c..97eef8a648b 100644 --- a/doc/development/permissions/authorizations.md +++ b/doc/development/permissions/authorizations.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Authorization diff --git a/doc/development/permissions/custom_roles.md b/doc/development/permissions/custom_roles.md index 1630ea7b9ab..9d02c0c6f39 100644 --- a/doc/development/permissions/custom_roles.md +++ b/doc/development/permissions/custom_roles.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Custom Roles @@ -182,6 +182,7 @@ security dashboard. To add a new ability to a custom role: +- Generate YAML file by running `./ee/bin/custom-ability` generator - Add a new column to `member_roles` table, for example in [this change in merge request 114734](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114734/diffs#diff-content-5c53d6f1c29a272a87eecea3f62d017ab6635275). - Add the ability to the `MemberRole` model, `ALL_CUSTOMIZABLE_PERMISSIONS` hash, for example in [this change in merge request 121534](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121534/diffs#ce5ec769500a53ce2b603467d9984fc2b33ca71d_8_8). There are following possible keys in the `ALL_CUSTOMIZABLE_PERMISSIONS` hash: @@ -200,6 +201,33 @@ Examples of merge requests adding new abilities to custom roles: You should make sure a new custom roles ability is under a feature flag. +## Custom abilities definition + +All new custom abilities must have a type definition stored in `ee/config/custom_abilities` that contains a single source of truth for every ability that is part of custom roles feature. + +### Add a new custom ability definition + +To add a new custom ability: + +1. Create the YAML definition. You can either: + - Use the `ee/bin/custom-ability` CLI to create the YAML definition automatically. + - Perform manual steps to create a new file in `ee/config/custom_abilities/` with the filename matching the name of the ability name. +1. Add contents to the file that conform to the [schema](#schema) defined in `ee/config/custom_abilities/types/type_schema.json`. + +### Schema + +| Field | Required | Description | +| ----- | -------- |--------------| +| `name` | yes | Unique, lowercase and underscored name describing the custom ability. Must match the filename. | +| `description` | yes | Human-readable description of the custom ability. | +| `feature_category` | yes | Name of the feature category. For example, `vulnerability_management`. | +| `introduced_by_issue` | yes | Issue URL that proposed the addition of this custom ability. | +| `introduced_by_mr` | yes | MR URL that added this custom ability. | +| `milestone` | yes | Milestone in which this custom ability was added. | +| `group_ability` | yes | Indicate whether this ability is checked on group level. | +| `project_ability` | yes | Indicate whether this ability is checked on project level. | +| `skip_seat_consumption` | yes | Indicate wheter this ability should be skiped when counting licensed users. | + ### Privilege escalation consideration A base role typically has permissions that allow creation or management of artifacts corresponding to the base role when interacting with that artifact. For example, when a `Developer` creates an access token for a project, it is created with `Developer` access encoded into that credential. It is important to keep in mind that as new custom permissions are created, there might be a risk of elevated privileges when interacting with GitLab artifacts, and appropriate safeguards or base role checks should be added. diff --git a/doc/development/permissions/predefined_roles.md b/doc/development/permissions/predefined_roles.md index 0edbcb7b962..7cb00977e1f 100644 --- a/doc/development/permissions/predefined_roles.md +++ b/doc/development/permissions/predefined_roles.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Predefined system of user roles diff --git a/doc/development/pipelines/index.md b/doc/development/pipelines/index.md index 77f91300a57..c4dfda9466a 100644 --- a/doc/development/pipelines/index.md +++ b/doc/development/pipelines/index.md @@ -1,7 +1,7 @@ --- stage: none group: Engineering Productivity -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Pipelines for the GitLab project @@ -105,7 +105,7 @@ In addition, there are a few circumstances where we would always run the full RS #### Have you encountered a problem with backend predictive tests? -If so, please have a look at [the Engineering Productivity RUNBOOK on predictive tests](https://gitlab.com/gitlab-org/quality/engineering-productivity/team/-/blob/main/runbooks/predictive-tests.md) for instructions on how to act upon predictive tests issues. Additionally, if you identified any test selection gaps, please let `@gl-quality/eng-prod` know so that we can take the necessary steps to optimize test selections. +If so, have a look at [the Engineering Productivity RUNBOOK on predictive tests](https://gitlab.com/gitlab-org/quality/engineering-productivity/team/-/blob/main/runbooks/predictive-tests.md) for instructions on how to act upon predictive tests issues. Additionally, if you identified any test selection gaps, let `@gl-quality/eng-prod` know so that we can take the necessary steps to optimize test selections. ### Jest predictive jobs @@ -130,7 +130,7 @@ The `rules` definitions for full Jest tests are defined at `.frontend:rules:jest #### Have you encountered a problem with frontend predictive tests? -If so, please have a look at [the Engineering Productivity RUNBOOK on predictive tests](https://gitlab.com/gitlab-org/quality/engineering-productivity/team/-/blob/main/runbooks/predictive-tests.md) for instructions on how to act upon predictive tests issues. +If so, have a look at [the Engineering Productivity RUNBOOK on predictive tests](https://gitlab.com/gitlab-org/quality/engineering-productivity/team/-/blob/main/runbooks/predictive-tests.md) for instructions on how to act upon predictive tests issues. ### Fork pipelines @@ -302,7 +302,7 @@ The intent is to ensure that a change doesn't introduce a failure after `gitlab- #### What it is This pipeline is also called [JiHu validation pipeline](https://about.gitlab.com/handbook/ceo/chief-of-staff-team/jihu-support/jihu-validation-pipelines.html), -and it's currently allowed to fail. When that happens, please follow +and it's currently allowed to fail. When that happens, follow [What to do when the validation pipeline fails](https://about.gitlab.com/handbook/ceo/chief-of-staff-team/jihu-support/jihu-validation-pipelines.html#what-to-do-when-the-validation-pipeline-failed). #### How we run it diff --git a/doc/development/pipelines/internals.md b/doc/development/pipelines/internals.md index 0e2c1c991fd..1fdb2014c1f 100644 --- a/doc/development/pipelines/internals.md +++ b/doc/development/pipelines/internals.md @@ -1,7 +1,7 @@ --- stage: none group: Engineering Productivity -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # CI configuration internals diff --git a/doc/development/pipelines/performance.md b/doc/development/pipelines/performance.md index 7db498adc02..0cd4f4270fe 100644 --- a/doc/development/pipelines/performance.md +++ b/doc/development/pipelines/performance.md @@ -1,7 +1,7 @@ --- stage: none group: Engineering Productivity -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # CI configuration performance diff --git a/doc/development/policies.md b/doc/development/policies.md index d2a4fcef81f..7e4909c1eb9 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # `DeclarativePolicy` framework diff --git a/doc/development/polling.md b/doc/development/polling.md index ff239effb80..fa295d6d2df 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Polling with ETag caching diff --git a/doc/development/product_qualified_lead_guide/index.md b/doc/development/product_qualified_lead_guide/index.md index 9ebe607f66b..fae0225b52c 100644 --- a/doc/development/product_qualified_lead_guide/index.md +++ b/doc/development/product_qualified_lead_guide/index.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Product Qualified Lead (PQL) development guidelines diff --git a/doc/development/profiling.md b/doc/development/profiling.md index efee6ff3cd5..a7a5f993ca9 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Profiling diff --git a/doc/development/project_templates.md b/doc/development/project_templates.md index 11102f5825e..7200927858c 100644 --- a/doc/development/project_templates.md +++ b/doc/development/project_templates.md @@ -1,18 +1,18 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Contribute to built-in project templates ## Adding a new built-in project template -If you'd like to contribute a new built-in project template to be distributed with GitLab, please do the following: +If you'd like to contribute a new built-in project template to be distributed with GitLab, do the following: 1. Create a new public project with the project content you'd like to contribute in a namespace of your choosing. You can view a working example [here](https://gitlab.com/gitlab-org/project-templates/dotnetcore). - Projects should be as simple as possible and free of any unnecessary assets or dependencies. -1. When the project is ready for review, please create a new issue in [GitLab](https://gitlab.com/gitlab-org/gitlab/issues) with a link to your project. +1. When the project is ready for review, create a new issue in [GitLab](https://gitlab.com/gitlab-org/gitlab/issues) with a link to your project. - In your issue, `@` mention the relevant Backend Engineering Manager and Product Manager for the [Create:Source Code group](https://about.gitlab.com/handbook/product/categories/#source-code-group). To make the project template available when creating a new project, the vendoring process will have to be completed: @@ -40,7 +40,7 @@ To make the project template available when creating a new project, the vendorin 1. Run the `bundle_repo` script. Make sure to pass the correct arguments, or the script may damage the folder structure. 1. Add exported project (`$name.tar.gz`) to `gitlab/vendor/project_templates` and remove the resulting build folders `tar-base` and `project`. -1. Run `bin/rake gettext:regenerate` in the `gitlab` project and commit new `.pot` file. +1. Run `tooling/bin/gettext_extractor locale/gitlab.pot` in the `gitlab` project and commit new `.pot` file. 1. Add a changelog entry in the commit message (for example, `Changelog: added`). For more information, see [Changelog entries](changelog.md). 1. Add an icon to [`gitlab-svgs`](https://gitlab.com/gitlab-org/gitlab-svgs), as shown in @@ -59,7 +59,7 @@ To make the project template available when creating a new project, the vendorin Existing templates are available in the [project-templates](https://gitlab.com/gitlab-org/project-templates) group. -To contribute a change, please open a merge request in the relevant project +To contribute a change, open a merge request in the relevant project and mention `@gitlab-org/manage/import/backend` when you are ready for a review. Then, if your merge request gets accepted, either open an issue on @@ -79,7 +79,7 @@ Complete the following steps to test the project template in your own GitLab Dev ## For GitLab team members -Please ensure the merge request has been reviewed by the Security Counterpart before merging. +Ensure the merge request has been reviewed by the Security Counterpart before merging. To review a merge request which changes a vendored project template, run the `check-template-changes` script: diff --git a/doc/development/project_templates/index.md b/doc/development/project_templates/index.md index b6ecf3b3f00..4f93c58fa23 100644 --- a/doc/development/project_templates/index.md +++ b/doc/development/project_templates/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Custom group-level project templates development guidelines diff --git a/doc/development/projections.md b/doc/development/projections.md index caa54e7b912..a9a06d91d2c 100644 --- a/doc/development/projections.md +++ b/doc/development/projections.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Projections diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index f72805e0fe9..6a4a85f14ff 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Prometheus metrics development guidelines diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md index 8ad584a8edc..890e6b490ae 100644 --- a/doc/development/pry_debugging.md +++ b/doc/development/pry_debugging.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Pry debugging diff --git a/doc/development/push_rules/index.md b/doc/development/push_rules/index.md new file mode 100644 index 00000000000..343b199e613 --- /dev/null +++ b/doc/development/push_rules/index.md @@ -0,0 +1,93 @@ +--- +stage: Create +group: Source Code +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. +--- + +# Push Rules development guidelines + +This document was created to help contributors understand the code design of +[Push Rules](../../user/project/repository/push_rules.md). You should read this +document before making changes to the code for this feature. + +This document is intentionally limited to an overview of how the code is +designed, as code can change often. To understand how a specific part of the +feature works, view the code and the specs. The details here explain how the +major components of the Push Rules feature work. + +NOTE: +This document should be updated when parts of the codebase referenced in this +document are updated, removed, or new parts are added. + +## Business logic + +The business logic is contained in two main places. The `PushRule` model stores +the settings for a rule and then we have checks that use those settings to +change the push behavior. + +- `PushRule`: the main model used to store the configuration of each push rule. + - Defined in `ee/app/models/push_rule.rb`. +- `EE::Gitlab::Checks::DiffCheck`: Diff check prevents filenames matching the + push rule's `file_name_regex` and also files with names matching known secret + files, for example `id_rsa`. + - Defined in `ee/lib/ee/gitlab/checks/diff_check.rb`. +- `EE::Gitlab::Checks::PushRuleCheck`: Executes various push rule checks. + - Defined in `ee/lib/ee/gitlab/checks/push_rule_check.rb`. +- `EE::Gitlab::Checks::PushRules::BranchCheck`: Executes push rule checks + related to branch rules. + - Defined in `ee/lib/ee/gitlab/checks/push_rules/branch_check.rb`. +- `EE::Gitlab::Checks::PushRules::CommitCheck`: Executes push rule checks + related to commit rules. + - Defined in `ee/lib/ee/gitlab/checks/push_rules/commit_check.rb`. +- `EE::Gitlab::Checks::PushRules::FileSizeCheck`: Executes push rule checks + related to file size rules. + - Defined in `ee/lib/ee/gitlab/checks/push_rules/file_size_check.rb`. +- `EE::Gitlab::Checks::PushRules::SecretsCheck`: Executes push rule checks + related to secrets rules. + - Defined in `ee/lib/ee/gitlab/checks/push_rules/secrets_check.rb`. +- `EE::Gitlab::Checks::PushRules::TagCheck`: Executes push rule checks + related to tag rules. + - Defined in `ee/lib/ee/gitlab/checks/push_rules/tag_check.rb`. + +## Entrypoints + +The following controllers and APIs are all entrypoints into the push rules logic: + +- `Admin::PushRulesController`: This controller is used to manage the global push rule. +- `Group::PushRulesController`: This controller is used to manage the group-level push rule. +- `Project::PushRulesController`: This controller is used to manage the project-level push rule. +- `Api::Internal::Base`: This `/internal/allowed` endpoint is called when pushing to GitLab over SSH to + ensure the user is allowed to push. The `/internal/allowed` endpoint performs a + `Gitlab::Checks::DiffCheck`. In EE, this includes push rules checks. + - Defined in `lib/api/internal/base.rb`. +- `Repositories::GitHttpController`: When changes are pushed to GitLab over HTTP, the controller performs an access + check to ensure the user is allowed to push. The checks perform a + `Gitlab::Checks::DiffCheck`. In EE, this includes push rules checks. + - Defined in `app/controllers/repositories/git_http_controller.rb`. + +## Flow + +These flowcharts should help explain the flow from the controllers down to the +models for different features. + +### Git push over SSH + +```mermaid +graph TD + Repositories::GitHttpController --> Gitlab::GitAccess + Api::Internal::Base --> Gitlab::GitAccess + Gitlab::GitAccess --> Gitlab::Checks::ChangesAccess + Gitlab::Checks::ChangesAccess --> Gitlab::Checks::SingleChangeAccess + Gitlab::Checks::ChangesAccess --> EE::Gitlab::Checks::PushRuleCheck + Gitlab::Checks::SingleChangeAccess --> Gitlab::Checks::DiffCheck + EE::Gitlab::Checks::PushRuleCheck -->|Only if pushing to a tag| EE::Gitlab::Checks::PushRules::TagCheck + EE::Gitlab::Checks::PushRuleCheck -->|Only if pushing to a branch| EE::Gitlab::Checks::PushRules::BranchCheck + EE::Gitlab::Checks::PushRuleCheck --> EE::Gitlab::Checks::PushRules::FileSizeCheck + EE::Gitlab::Checks::PushRuleCheck --> EE::Gitlab::Checks::PushRules::SecretsCheck + EE::Gitlab::Checks::PushRuleCheck --> EE::Gitlab::Checks::PushRules::SecretsCheck +``` + +NOTE: +The `PushRuleCheck` only triggers checks in parallel if the +`parallel_push_checks` feature flag is enabled. Otherwise tag or branch check +runs first, then file size, then secrets. diff --git a/doc/development/python_guide/index.md b/doc/development/python_guide/index.md index e9b52b81c0e..d1d9fc03d8f 100644 --- a/doc/development/python_guide/index.md +++ b/doc/development/python_guide/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Python development guidelines diff --git a/doc/development/rails_endpoints/index.md b/doc/development/rails_endpoints/index.md index c5a166dd4be..adc17fde1d0 100644 --- a/doc/development/rails_endpoints/index.md +++ b/doc/development/rails_endpoints/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Rails Endpoints @@ -20,7 +19,7 @@ These Rails Endpoints: ## Proof of concept period: Feedback Request -We are currently evaluating a new approach for documenting Rails endpoints. Please [check out the Feedback Issue](https://gitlab.com/gitlab-org/gitlab/-/issues/411605) and feel free to share your thoughts, suggestions, or concerns. We appreciate your participation in helping us improve the documentation! +We are currently evaluating a new approach for documenting Rails endpoints. [Check out the Feedback Issue](https://gitlab.com/gitlab-org/gitlab/-/issues/411605) and feel free to share your thoughts, suggestions, or concerns. We appreciate your participation in helping us improve the documentation! ## SAST Scanners diff --git a/doc/development/rails_initializers.md b/doc/development/rails_initializers.md index 93a7b568974..e3faf1accb1 100644 --- a/doc/development/rails_initializers.md +++ b/doc/development/rails_initializers.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Rails initializers diff --git a/doc/development/rails_update.md b/doc/development/rails_update.md index 772206c2d73..d00a1681e76 100644 --- a/doc/development/rails_update.md +++ b/doc/development/rails_update.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Rails upgrade guidelines diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index d879668649d..25b0a42db3a 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Rake tasks for developers diff --git a/doc/development/reactive_caching.md b/doc/development/reactive_caching.md index d0652c85c6d..00110d21dc0 100644 --- a/doc/development/reactive_caching.md +++ b/doc/development/reactive_caching.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # `ReactiveCaching` diff --git a/doc/development/real_time.md b/doc/development/real_time.md index 1770760ac9b..9f735a9419d 100644 --- a/doc/development/real_time.md +++ b/doc/development/real_time.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Cloud Connector -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Build and deploy real-time view components diff --git a/doc/development/redis.md b/doc/development/redis.md index 63a778ec1c1..612d2bbcf2a 100644 --- a/doc/development/redis.md +++ b/doc/development/redis.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Redis development guidelines diff --git a/doc/development/redis/new_redis_instance.md b/doc/development/redis/new_redis_instance.md index f67f00967e5..ff5394cef8f 100644 --- a/doc/development/redis/new_redis_instance.md +++ b/doc/development/redis/new_redis_instance.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Add a new Redis instance diff --git a/doc/development/refactoring_guide/index.md b/doc/development/refactoring_guide/index.md index 5dd505ff5c6..ac9b9692a04 100644 --- a/doc/development/refactoring_guide/index.md +++ b/doc/development/refactoring_guide/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Refactoring guide diff --git a/doc/development/reference_processing.md b/doc/development/reference_processing.md index 5a026e0a2a0..044c1b01b30 100644 --- a/doc/development/reference_processing.md +++ b/doc/development/reference_processing.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: 'An introduction to reference parsers and reference filters, and a guide to their implementation.' --- diff --git a/doc/development/renaming_features.md b/doc/development/renaming_features.md index ee759efd7e2..94004177126 100644 --- a/doc/development/renaming_features.md +++ b/doc/development/renaming_features.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Renaming features diff --git a/doc/development/repository_mirroring.md b/doc/development/repository_mirroring.md index 6d95dec823b..d65df403fb9 100644 --- a/doc/development/repository_mirroring.md +++ b/doc/development/repository_mirroring.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Repository mirroring diff --git a/doc/development/repository_storage_moves/index.md b/doc/development/repository_storage_moves/index.md index 578bc1eabee..a6a2efebc50 100644 --- a/doc/development/repository_storage_moves/index.md +++ b/doc/development/repository_storage_moves/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Project Repository Storage Moves diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index 4a964f7d3c9..ba5998da844 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Guidelines for reusing abstractions diff --git a/doc/development/routing.md b/doc/development/routing.md index 8f475674c39..78c540683ce 100644 --- a/doc/development/routing.md +++ b/doc/development/routing.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Routing @@ -83,7 +83,8 @@ gitlab-org/serverless/runtimes/-/settings/repository Don't change a URL to an existing page, unless it's necessary. If you must make a change, make it unnoticeable for users, because we don't want them to receive `404 Not Found` -if we can avoid it. This table should help: +if we can avoid it. This table describes the minimum required in different +cases: | URL description | Example | What to do | |---|---|---| @@ -91,6 +92,11 @@ if we can avoid it. This table should help: | Likely to be saved or shared | `issue#show` | Add a redirect from an old URL to a new URL until the next major release. | | Limited use, unlikely to be shared | `admin#labels` | No extra steps required. | +In all cases, an old route should only be removed once traffic to it has +dropped sufficiently (e.g., according to logs or BigQuery). Otherwise, more +effort may be required to inform users about its deprecation before it can be +considered again for removal. + ## Migrating unscoped routes Currently, the majority of routes are placed under the `/-/` scope. However, diff --git a/doc/development/rubocop_development_guide.md b/doc/development/rubocop_development_guide.md index 807544b71d4..e56443d5653 100644 --- a/doc/development/rubocop_development_guide.md +++ b/doc/development/rubocop_development_guide.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # RuboCop rule development guidelines @@ -45,6 +44,9 @@ More context can go into code comments above this inline disable comment. To reduce verbose code comments link a resource (issue, epic, ...) to provide detailed context. +For temporary inline disables use `rubocop:todo` and link the follow-up issue +or epic. + For example: ```ruby @@ -53,6 +55,10 @@ module Types module Domain # rubocop:disable Graphql/AuthorizeTypes class SomeType < BaseObject + if condition # rubocop:disable Style/GuardClause + # more logic... + end + object.public_send(action) # rubocop:disable GitlabSecurity/PublicSend end # rubocop:enable Graphql/AuthorizeTypes @@ -64,6 +70,10 @@ module Types module Domain # rubocop:disable Graphql/AuthorizeTypes -- already authroized in parent entity class SomeType < BaseObject + if condition # rubocop:todo Style/GuardClause -- Cleanup via https://gitlab.com/gitlab-org/gitlab/-/issues/1234567890 + # more logic... + end + # At this point `action` is safe to be used in `public_send`. # See https://gitlab.com/gitlab-org/gitlab/-/issues/123457890. object.public_send(action) # rubocop:disable GitlabSecurity/PublicSend -- User input verified diff --git a/doc/development/ruby3_gotchas.md b/doc/development/ruby3_gotchas.md index 0d000bc68df..d32f71948d7 100644 --- a/doc/development/ruby3_gotchas.md +++ b/doc/development/ruby3_gotchas.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Ruby 3 gotchas @@ -150,7 +150,7 @@ We run automated detection for this warning in tests via `deprecation_toolkit`, but it relies on the fact that `Kernel#warn` emits a warning, so stubbing out this call will effectively remove the call to warn, which means `deprecation_toolkit` will never see the deprecation warnings. Stubbing out the implementation removes that warning, and we never pick it up, so the build is green. -Please refer to [issue 364099](https://gitlab.com/gitlab-org/gitlab/-/issues/364099) for more context. +Refer to [issue 364099](https://gitlab.com/gitlab-org/gitlab/-/issues/364099) for more context. ## Testing in `irb` and `rails console` diff --git a/doc/development/ruby_upgrade.md b/doc/development/ruby_upgrade.md index 61bc629e8c8..110bc6076b0 100644 --- a/doc/development/ruby_upgrade.md +++ b/doc/development/ruby_upgrade.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Ruby upgrade guidelines diff --git a/doc/development/runner_fleet_dashboard.md b/doc/development/runner_fleet_dashboard.md index 2a7c7d05453..70499e5a087 100644 --- a/doc/development/runner_fleet_dashboard.md +++ b/doc/development/runner_fleet_dashboard.md @@ -4,13 +4,13 @@ group: Runner info: >- To determine the technical writer assigned to the Stage/Group associated with this page, see - https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments + https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Runner Fleet Dashboard **(ULTIMATE BETA)** +# Runner Fleet Dashboard **(ULTIMATE EXPERIMENT)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424495) in GitLab 16.6 behind several [feature flags](#enable-feature-flags). -This feature is in [BETA](../policy/experiment-beta-support.md). +This feature is an [Experiment](../policy/experiment-beta-support.md). To join the list of users testing this feature, contact us in [epic 11180](https://gitlab.com/groups/gitlab-org/-/epics/11180). @@ -33,8 +33,7 @@ Prerequisites: To view the runner fleet dashboard: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Runners**. 1. Click **Fleet dashboard**. @@ -49,7 +48,7 @@ for some customers to try this feature. To test the Runner Fleet Dashboard as part of the early adopters program, you must: -- Run GitLab 16.6 or above. +- Run GitLab 16.7 or above. - Have an [Ultimate license](https://about.gitlab.com/pricing/). - Be able to run ClickHouse database. We recommend using [ClickHouse Cloud](https://clickhouse.cloud/). @@ -59,6 +58,7 @@ To setup ClickHouse as the GitLab data storage: 1. [Run ClickHouse Cluster and configure database](#run-and-configure-clickhouse). 1. [Configure GitLab connection to Clickhouse](#configure-the-gitlab-connection-to-clickhouse). +1. [Run ClickHouse migrations](#run-clickhouse-migrations). 1. [Enable the feature flags](#enable-feature-flags). ### Run and configure ClickHouse @@ -89,62 +89,6 @@ To create necessary user and database objects: GRANT gitlab_app TO gitlab; ``` -1. Connect to the `gitlab_clickhouse_main_production` database (or just switch it in the ClickHouse Cloud UI). - -1. To create the required database objects, execute: - - ```sql - CREATE TABLE ci_finished_builds - ( - id UInt64 DEFAULT 0, - project_id UInt64 DEFAULT 0, - pipeline_id UInt64 DEFAULT 0, - status LowCardinality(String) DEFAULT '', - created_at DateTime64(6, 'UTC') DEFAULT now(), - queued_at DateTime64(6, 'UTC') DEFAULT now(), - finished_at DateTime64(6, 'UTC') DEFAULT now(), - started_at DateTime64(6, 'UTC') DEFAULT now(), - runner_id UInt64 DEFAULT 0, - runner_manager_system_xid String DEFAULT '', - runner_run_untagged Boolean DEFAULT FALSE, - runner_type UInt8 DEFAULT 0, - runner_manager_version LowCardinality(String) DEFAULT '', - runner_manager_revision LowCardinality(String) DEFAULT '', - runner_manager_platform LowCardinality(String) DEFAULT '', - runner_manager_architecture LowCardinality(String) DEFAULT '', - duration Int64 MATERIALIZED age('ms', started_at, finished_at), - queueing_duration Int64 MATERIALIZED age('ms', queued_at, started_at) - ) - ENGINE = ReplacingMergeTree - ORDER BY (status, runner_type, project_id, finished_at, id) - PARTITION BY toYear(finished_at); - - CREATE TABLE ci_finished_builds_aggregated_queueing_delay_percentiles - ( - status LowCardinality(String) DEFAULT '', - runner_type UInt8 DEFAULT 0, - started_at_bucket DateTime64(6, 'UTC') DEFAULT now(), - - count_builds AggregateFunction(count), - queueing_duration_quantile AggregateFunction(quantile, Int64) - ) - ENGINE = AggregatingMergeTree() - ORDER BY (started_at_bucket, status, runner_type); - - CREATE MATERIALIZED VIEW ci_finished_builds_aggregated_queueing_delay_percentiles_mv - TO ci_finished_builds_aggregated_queueing_delay_percentiles - AS - SELECT - status, - runner_type, - toStartOfInterval(started_at, INTERVAL 5 minute) AS started_at_bucket, - - countState(*) as count_builds, - quantileState(queueing_duration) AS queueing_duration_quantile - FROM ci_finished_builds - GROUP BY status, runner_type, started_at_bucket; - ``` - ### Configure the GitLab connection to ClickHouse ::Tabs @@ -216,6 +160,14 @@ To verify that your connection is set up successfully: If successful, the command returns `[{"1"=>1}]` +### Run ClickHouse migrations + +To create the required database objects execute: + +```shell +sudo gitlab-rake gitlab:clickhouse:migrate +``` + ### Enable feature flags Features that use ClickHouse are currently under development and are disabled by feature flags. diff --git a/doc/development/scalability.md b/doc/development/scalability.md index 733e94cb5a7..ada7adc8bdd 100644 --- a/doc/development/scalability.md +++ b/doc/development/scalability.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab scalability diff --git a/doc/development/search/advanced_search_migration_styleguide.md b/doc/development/search/advanced_search_migration_styleguide.md index 10c4fa3dcc6..87083d1a36f 100644 --- a/doc/development/search/advanced_search_migration_styleguide.md +++ b/doc/development/search/advanced_search_migration_styleguide.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Global Search -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Advanced search migration style guide @@ -66,17 +66,15 @@ The following migration helpers are available in `ee/app/workers/concerns/elasti Backfills a specific field in an index. In most cases, the mapping for the field should already be added. -Requires the `index_name` and `field_name` methods to backfill a single field. +Requires the `field_name` method and `DOCUMENT_TYPE` constant to backfill a single field. ```ruby class MigrationName < Elastic::Migration include Elastic::MigrationBackfillHelper - private + DOCUMENT_TYPE = Issue - def index_name - Issue.__elasticsearch__.index_name - end + private def field_name :schema_version @@ -84,17 +82,15 @@ class MigrationName < Elastic::Migration end ``` -Requires the `index_name` and `field_names` methods to backfill multiple fields if any field is null. +Requires the `field_names` method and `DOCUMENT_TYPE` constant to backfill multiple fields if any field is null. ```ruby class MigrationName < Elastic::Migration include Elastic::MigrationBackfillHelper - private + DOCUMENT_TYPE = Issue - def index_name - Issue.__elasticsearch__.index_name - end + private def field_names %w[schema_version visibility_level] @@ -106,17 +102,15 @@ end Updates a mapping in an index by calling `put_mapping` with the mapping specified. -Requires the `index_name` and `new_mappings` methods. +Requires the `new_mappings` method and `DOCUMENT_TYPE` constant. ```ruby class MigrationName < Elastic::Migration include Elastic::MigrationUpdateMappingsHelper - private + DOCUMENT_TYPE = Issue - def index_name - Issue.__elasticsearch__.index_name - end + private def new_mappings { @@ -402,7 +396,7 @@ actually want to hold up GitLab.com deployments on advanced search migrations, as they may still have another week to go, and that's too long to block deployments. -### Process for removing migrations +### Process for marking migrations as obsolete For every migration that was created 2 minor versions before the major version being upgraded to, we do the following: @@ -415,8 +409,17 @@ being upgraded to, we do the following: ``` 1. Delete any spec files to support this migration. +1. Verify that there are no references of the migration in the `.rubocop_todo/` directory. 1. Remove any logic handling backwards compatibility for this migration. You can find this by looking for `Elastic::DataMigrationService.migration_has_finished?(:migration_name_in_lowercase)`. 1. Create a merge request with these changes. Noting that we should not accidentally merge this before the major release is started. + +### Process for removing migrations + +1. Select migrations that were marked as obsolete before the current major release +1. If the step above includes all obsolete migrations, keep one last migration as a safeguard for customers with unapplied migrations +1. Delete migration files and spec files for those migrations +1. Verify that there are no references of the migrations in the `.rubocop_todo/` directory. +1. Create a merge request and assign it to a team member from the global search team. diff --git a/doc/development/sec/analyzer_development_guide.md b/doc/development/sec/analyzer_development_guide.md index c76b7f5e55f..eb59d8fcaf5 100644 --- a/doc/development/sec/analyzer_development_guide.md +++ b/doc/development/sec/analyzer_development_guide.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sec section analyzer development @@ -226,7 +226,7 @@ After the above steps have been completed, the automatic release process execute ### Steps to perform after releasing an analyzer -1. After a new version of the analyzer Docker image has been tagged and deployed, please test it with the corresponding test project. +1. After a new version of the analyzer Docker image has been tagged and deployed, test it with the corresponding test project. 1. Announce the release on the relevant group Slack channel. Example message: > FYI I've just released `ANALYZER_NAME` `ANALYZER_VERSION`. `LINK_TO_RELEASE` diff --git a/doc/development/sec/gemnasium_analyzer_data.md b/doc/development/sec/gemnasium_analyzer_data.md index 2da787a277a..bc3a6aac78b 100644 --- a/doc/development/sec/gemnasium_analyzer_data.md +++ b/doc/development/sec/gemnasium_analyzer_data.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Gemnasium analyzer data diff --git a/doc/development/sec/generate_test_vulnerabilities.md b/doc/development/sec/generate_test_vulnerabilities.md index 75fb7edd68e..d862ee91c83 100644 --- a/doc/development/sec/generate_test_vulnerabilities.md +++ b/doc/development/sec/generate_test_vulnerabilities.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Generate test vulnerabilities @@ -11,7 +10,7 @@ You can generate test vulnerabilities for the [Vulnerability Report](../../user/ vulnerability management features without running a pipeline. 1. Log in to GitLab. -1. Go to `/-/profile/personal_access_tokens` and generate a personal access token with `api` permissions. +1. Go to `/-/user_settings/personal_access_tokens` and generate a personal access token with `api` permissions. 1. Go to your project page and find the project ID. You can find the project ID below the project title. 1. [Clone the GitLab repository](../../gitlab-basics/start-using-git.md#clone-a-repository) to your local machine. 1. Open a terminal and go to `gitlab/qa` directory. diff --git a/doc/development/sec/index.md b/doc/development/sec/index.md index b887d13c267..9e8486b26fa 100644 --- a/doc/development/sec/index.md +++ b/doc/development/sec/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, concepts, howto +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sec section development guidelines @@ -72,7 +71,7 @@ For details on how GitLab processes the reports generated by the scanners, see ## CI/CD template development While CI/CD templates are the responsibility of the Verify section, many are critical to the Sec Section's feature usage. -If you are working with CI/CD templates, please read the [development guide for GitLab CI/CD templates](../cicd/templates.md). +If you are working with CI/CD templates, read the [development guide for GitLab CI/CD templates](../cicd/templates.md). ## Importance of the primary identifier diff --git a/doc/development/sec/security_report_ingestion_overview.md b/doc/development/sec/security_report_ingestion_overview.md index 0408e47a1dd..de0c1861cfd 100644 --- a/doc/development/sec/security_report_ingestion_overview.md +++ b/doc/development/sec/security_report_ingestion_overview.md @@ -2,7 +2,6 @@ stage: Secure group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: concepts --- # Security report ingestion overview diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index 180d35e04fe..a575d1ff890 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Secure coding development guidelines @@ -15,17 +14,16 @@ goal of reducing the number of vulnerabilities released over time. **Contributing** If you would like to contribute to one of the existing documents, or add -guidelines for a new vulnerability type, please open an MR! Please try to +guidelines for a new vulnerability type, open an MR! Try to include links to examples of the vulnerability found, and link to any resources -used in defined mitigations. If you have questions or when ready for a review, -please ping `gitlab-com/gl-security/appsec`. +used in defined mitigations. If you have questions or when ready for a review, ping `gitlab-com/gl-security/appsec`. ## Permissions ### Description Application permissions are used to determine who can access what and what actions they can perform. -For more information about the permission model at GitLab, please see [the GitLab permissions guide](permissions.md) or the [EE docs on permissions](../../ee/user/permissions.md). +For more information about the permission model at GitLab, see [the GitLab permissions guide](permissions.md) or the [EE docs on permissions](../../ee/user/permissions.md). ### Impact @@ -341,7 +339,7 @@ The injected client-side code is executed on the victim's browser in the context - potentially <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [obtain the victim's session tokens](https://youtu.be/2VFavqfDS6w?t=739) - perform actions that lead to data loss/theft or account takeover -Much of the impact is contingent upon the function of the application and the capabilities of the victim's session. For further impact possibilities, please check out [the beef project](https://beefproject.com/). +Much of the impact is contingent upon the function of the application and the capabilities of the victim's session. For further impact possibilities, check out [the beef project](https://beefproject.com/). For a demonstration of the impact on GitLab with a realistic attack scenario, see [this video on the GitLab Unfiltered channel](https://www.youtube.com/watch?v=t4PzHNycoKo) (internal, it requires being logged in with the GitLab Unfiltered account). @@ -1308,6 +1306,24 @@ This sensitive data must be handled carefully to avoid leaks which could lead to In the event of credential leak through an MR, issue, or any other medium, [reach out to SIRT team](https://about.gitlab.com/handbook/security/security-operations/sirt/#-engaging-sirt). +### Token prefixes + +User error or software bugs can lead to tokens leaking. Consider prepending a static prefix to the beginning of secrets and adding that prefix to our secrets detection capabilities. For example, GitLab Personal Access Tokens have a prefix so that the plaintext is `glpat-1234567890abcdefghij`. + +The prefix pattern should be: + +1. `gl` for GitLab +1. lowercase letters abbreviating the token class name +1. a hyphen (`-`) + +Add the new prefix to: + +- [`gitlab/app/assets/javascripts/lib/utils/secret_detection.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/lib/utils/secret_detection.js) +- The [GitLab Secret Detection gem](https://gitlab.com/gitlab-org/gitlab/-/tree/master/gems/gitlab-secret_detection) +- GitLab [secrets SAST analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) +- [Tokinator](https://gitlab.com/gitlab-com/gl-security/appsec/tokinator/-/blob/main/CONTRIBUTING.md?ref_type=heads) (internal tool / team members only) +- [Token Overview](../security/token_overview.md#gitlab-tokens) documentation + ### Examples Encrypting a token with `attr_encrypted` so that the plaintext can be retrieved @@ -1339,6 +1355,19 @@ class WebHookLog < ApplicationRecord end ``` +Using the `TokenAuthenticatable` class helper to create a prefixed token. + +```ruby +class User + FEED_TOKEN_PREFIX = 'glft-' + + add_authentication_token_field :feed_token, format_with_prefix: :prefix_for_feed_token + + def prefix_for_feed_token + FEED_TOKEN_PREFIX + end +``` + ## Serialization Serialization of active record models can leak sensitive attributes if they are not protected. @@ -1464,11 +1493,43 @@ Logging helps track events for debugging. Logging also allows the application to - An audit trail for log edits must be available. - To avoid data loss, logs must be saved on different storage. -### Who to contact if you have questions +## URL Spoofing + +We want to protect our users from bad actors who might try to use GitLab +features to redirect other users to malicious sites. + +Many features in GitLab allow users to post links to external websites. It is +important that the destination of any user-specified link is made very clear +to the user. + +### `external_redirect_path` + +When presenting links provided by users, if the actual URL is hidden, use the `external_redirect_path` +helper method to redirect the user to a warning page first. For example: + +```ruby +# Bad :( +# This URL comes from User-Land and may not be safe... +# We need the user to *see* where they are going. +link_to foo_social_url(@user), title: "Foo Social" do + sprite_icon('question-o') +end + +# Good :) +# The external_redirect "leaving GitLab" page will show the URL to the user +# before they leave. +link_to external_redirect_path(url: foo_social_url(@user)), title: "Foo" do + sprite_icon('question-o') +end +``` + +Also see this [real-life usage](https://gitlab.com/gitlab-org/gitlab/-/blob/bdba5446903ff634fb12ba695b2de99b6d6881b5/app/helpers/application_helper.rb#L378) as an example. + +## Who to contact if you have questions For general guidance, contact the [Application Security](https://about.gitlab.com/handbook/security/security-engineering/application-security/) team. -### Related topics +## Related topics - [Log system in GitLab](../administration/logs/index.md) - [Audit event development guidelines](../development/audit_event_guide/index.md)) diff --git a/doc/development/service_measurement.md b/doc/development/service_measurement.md index 9d22e9c376c..f193035560f 100644 --- a/doc/development/service_measurement.md +++ b/doc/development/service_measurement.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab Developers Guide to service measurement diff --git a/doc/development/session.md b/doc/development/session.md index c30364c27f8..ecf9bee836a 100644 --- a/doc/development/session.md +++ b/doc/development/session.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Accessing session data diff --git a/doc/development/shared_files.md b/doc/development/shared_files.md index 3bf18a4d410..f39d3ee98bb 100644 --- a/doc/development/shared_files.md +++ b/doc/development/shared_files.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Shared files diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index 321bd7aeadd..39bcf7a875f 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Shell command development guidelines diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md index d3d9304446e..25c7a50bdcf 100644 --- a/doc/development/shell_scripting_guide/index.md +++ b/doc/development/shell_scripting_guide/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Shell scripting standards and style guidelines diff --git a/doc/development/sidekiq/compatibility_across_updates.md b/doc/development/sidekiq/compatibility_across_updates.md index 5ca6bf773fc..d6f61efbdb1 100644 --- a/doc/development/sidekiq/compatibility_across_updates.md +++ b/doc/development/sidekiq/compatibility_across_updates.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sidekiq Compatibility across Updates diff --git a/doc/development/sidekiq/idempotent_jobs.md b/doc/development/sidekiq/idempotent_jobs.md index 8ccbeee283d..029b18adb46 100644 --- a/doc/development/sidekiq/idempotent_jobs.md +++ b/doc/development/sidekiq/idempotent_jobs.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sidekiq idempotent jobs @@ -30,7 +30,7 @@ an unstarted job with the same arguments is already in the queue. Make sure the worker tests pass using the following shared example: ```ruby -include_examples 'an idempotent worker' do +it_behaves_like 'an idempotent worker' do it 'marks the MR as merged' do # Using subject inside this block will process the job multiple times subject @@ -80,7 +80,7 @@ GitLab supports two deduplication strategies: More [deduplication strategies have been suggested](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/195). If you are implementing a worker that could benefit from a different -strategy, please comment in the issue. +strategy, comment in the issue. #### Until Executing diff --git a/doc/development/sidekiq/index.md b/doc/development/sidekiq/index.md index 508f19a5be7..62e9e9f6b04 100644 --- a/doc/development/sidekiq/index.md +++ b/doc/development/sidekiq/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sidekiq development guidelines diff --git a/doc/development/sidekiq/limited_capacity_worker.md b/doc/development/sidekiq/limited_capacity_worker.md index b1aff829d4d..e8561cb936d 100644 --- a/doc/development/sidekiq/limited_capacity_worker.md +++ b/doc/development/sidekiq/limited_capacity_worker.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sidekiq limited capacity worker diff --git a/doc/development/sidekiq/logging.md b/doc/development/sidekiq/logging.md index 8a2a77b5226..45599e68d81 100644 --- a/doc/development/sidekiq/logging.md +++ b/doc/development/sidekiq/logging.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sidekiq logging diff --git a/doc/development/sidekiq/worker_attributes.md b/doc/development/sidekiq/worker_attributes.md index 814b61c746b..016bf0b6634 100644 --- a/doc/development/sidekiq/worker_attributes.md +++ b/doc/development/sidekiq/worker_attributes.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Sidekiq worker attributes @@ -336,7 +336,7 @@ worker that checks if any paused jobs must be restarted. To use `pause_control`, you can: - Use one of the strategies defined in `lib/gitlab/sidekiq_middleware/pause_control/strategies/`. -- Define a custom strategy in `lib/gitlab/sidekiq_middleware/pause_control/strategies/` and add the strategy to `lib/gitlab/sidekiq_middleware/pause_control/strategies.rb`. +- Define a custom strategy in `lib/gitlab/sidekiq_middleware/pause_control/strategies/` and add the strategy to `lib/gitlab/sidekiq_middleware/pause_control.rb`. For example: diff --git a/doc/development/software_design.md b/doc/development/software_design.md index f3a2c8eee0b..a771e7a9e61 100644 --- a/doc/development/software_design.md +++ b/doc/development/software_design.md @@ -1,7 +1,7 @@ --- stage: none group: Engineering Productivity -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Software design guides diff --git a/doc/development/spam_protection_and_captcha/exploratory_testing.md b/doc/development/spam_protection_and_captcha/exploratory_testing.md index 188c168fca5..788b971c4b9 100644 --- a/doc/development/spam_protection_and_captcha/exploratory_testing.md +++ b/doc/development/spam_protection_and_captcha/exploratory_testing.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Exploratory testing of CAPTCHAs diff --git a/doc/development/spam_protection_and_captcha/graphql_api.md b/doc/development/spam_protection_and_captcha/graphql_api.md index 346648aefbb..dca01aff3c7 100644 --- a/doc/development/spam_protection_and_captcha/graphql_api.md +++ b/doc/development/spam_protection_and_captcha/graphql_api.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GraphQL API spam protection and CAPTCHA support diff --git a/doc/development/spam_protection_and_captcha/index.md b/doc/development/spam_protection_and_captcha/index.md index 732d324f185..f48dc8e9189 100644 --- a/doc/development/spam_protection_and_captcha/index.md +++ b/doc/development/spam_protection_and_captcha/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Spam protection and CAPTCHA diff --git a/doc/development/spam_protection_and_captcha/model_and_services.md b/doc/development/spam_protection_and_captcha/model_and_services.md index 17d90ed7f1e..28d28e75c52 100644 --- a/doc/development/spam_protection_and_captcha/model_and_services.md +++ b/doc/development/spam_protection_and_captcha/model_and_services.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Model and services spam protection and CAPTCHA support diff --git a/doc/development/spam_protection_and_captcha/rest_api.md b/doc/development/spam_protection_and_captcha/rest_api.md index 2a43b585b94..4e5cd2ce3cb 100644 --- a/doc/development/spam_protection_and_captcha/rest_api.md +++ b/doc/development/spam_protection_and_captcha/rest_api.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # REST API spam protection and CAPTCHA support diff --git a/doc/development/spam_protection_and_captcha/web_ui.md b/doc/development/spam_protection_and_captcha/web_ui.md index c134f5e6683..f6e417a6647 100644 --- a/doc/development/spam_protection_and_captcha/web_ui.md +++ b/doc/development/spam_protection_and_captcha/web_ui.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Web UI spam protection and CAPTCHA support diff --git a/doc/development/sql.md b/doc/development/sql.md index d7a5923efce..86892f86e0c 100644 --- a/doc/development/sql.md +++ b/doc/development/sql.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # SQL Query Guidelines @@ -86,7 +86,7 @@ _can_ be used by `ILIKE` / `LIKE` and can lead to greatly improved performance. One downside of these indexes is that they can easily get quite large (depending on the amount of data indexed). -To keep naming of these indexes consistent please use the following naming +To keep naming of these indexes consistent, use the following naming pattern: ```plaintext diff --git a/doc/development/stage_group_observability/dashboards/error_budget_detail.md b/doc/development/stage_group_observability/dashboards/error_budget_detail.md index c45c31c5bd1..64f158ec098 100644 --- a/doc/development/stage_group_observability/dashboards/error_budget_detail.md +++ b/doc/development/stage_group_observability/dashboards/error_budget_detail.md @@ -1,7 +1,7 @@ --- stage: Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Error budget detail dashboard diff --git a/doc/development/stage_group_observability/dashboards/index.md b/doc/development/stage_group_observability/dashboards/index.md index c2da46bde7d..581ab0370cd 100644 --- a/doc/development/stage_group_observability/dashboards/index.md +++ b/doc/development/stage_group_observability/dashboards/index.md @@ -1,7 +1,7 @@ --- stage: Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Dashboards for stage groups diff --git a/doc/development/stage_group_observability/dashboards/stage_group_dashboard.md b/doc/development/stage_group_observability/dashboards/stage_group_dashboard.md index 7c596e544b5..948ad4340a1 100644 --- a/doc/development/stage_group_observability/dashboards/stage_group_dashboard.md +++ b/doc/development/stage_group_observability/dashboards/stage_group_dashboard.md @@ -1,7 +1,7 @@ --- stage: Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Stage group dashboard diff --git a/doc/development/stage_group_observability/index.md b/doc/development/stage_group_observability/index.md index ba17b4cc73a..441e3268044 100644 --- a/doc/development/stage_group_observability/index.md +++ b/doc/development/stage_group_observability/index.md @@ -1,7 +1,7 @@ --- stage: Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Observability for stage groups diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index dbee7acac69..458a5efea42 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -1,8 +1,7 @@ --- -type: reference, dev stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "GitLab development guidelines - testing best practices." --- @@ -386,7 +385,7 @@ NOTE: `stub_method` does not support method existence and method arity checks. WARNING: -`stub_method` is supposed to be used in factories only. It's strongly discouraged to be used elsewhere. Please consider using [RSpec mocks](https://rspec.info/features/3-12/rspec-mocks/) if available. +`stub_method` is supposed to be used in factories only. It's strongly discouraged to be used elsewhere. Consider using [RSpec mocks](https://rspec.info/features/3-12/rspec-mocks/) if available. #### Stubbing member access level @@ -583,7 +582,7 @@ Use the coverage reports to ensure your tests cover 100% of your code. NOTE: Before writing a new system test, -[please consider **not** writing one](testing_levels.md#consider-not-writing-a-system-test)! +[consider **not** writing one](testing_levels.md#consider-not-writing-a-system-test)! - Feature specs should be named `ROLE_ACTION_spec.rb`, such as `user_changes_password_spec.rb`. @@ -1298,7 +1297,7 @@ creates and deletes indices before and after all examples. The `:elastic_delete_by_query` trait was added to reduce runtime for pipelines by creating and deleting indices at the start and end of each context only. The [Elasticsearch delete by query API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html) -is used to delete data in all indices between examples to ensure a clean index. +is used to delete data in all indices (except the migrations index) between examples to ensure a clean index. The `:elastic_clean` trait creates and deletes indices between examples to ensure a clean index. This way, tests are not polluted with non-essential data. If using the `:elastic` or `:elastic_delete_by_query` trait @@ -1336,6 +1335,12 @@ It uses the [Elasticsearch Refresh API](https://www.elastic.co/guide/en/elastics to make sure all operations performed on an index since the last refresh are available for search. This method is typically called after loading data into PostgreSQL to ensure the data is indexed and searchable. +You can use the `SEARCH_SPEC_BENCHMARK` environment variable to benchmark test setup steps: + +```console +SEARCH_SPEC_BENCHMARK=1 bundle exec rspec ee/spec/lib/elastic/latest/merge_request_class_proxy_spec.rb +``` + #### Test Snowplow events WARNING: diff --git a/doc/development/testing_guide/contract/consumer_tests.md b/doc/development/testing_guide/contract/consumer_tests.md index 4a84dafdcf2..de2ef53949b 100644 --- a/doc/development/testing_guide/contract/consumer_tests.md +++ b/doc/development/testing_guide/contract/consumer_tests.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Writing consumer tests diff --git a/doc/development/testing_guide/contract/index.md b/doc/development/testing_guide/contract/index.md index 45933e9cb4f..ece0b6de420 100644 --- a/doc/development/testing_guide/contract/index.md +++ b/doc/development/testing_guide/contract/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Contract testing diff --git a/doc/development/testing_guide/contract/provider_tests.md b/doc/development/testing_guide/contract/provider_tests.md index 86ac6518d2f..22f3d3487ba 100644 --- a/doc/development/testing_guide/contract/provider_tests.md +++ b/doc/development/testing_guide/contract/provider_tests.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Writing provider tests diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md index 4a3aec97d29..b57757c5aac 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Beginner's guide to writing end-to-end tests diff --git a/doc/development/testing_guide/end_to_end/best_practices.md b/doc/development/testing_guide/end_to_end/best_practices.md index 8cf1a46d5d2..cd92f8656e9 100644 --- a/doc/development/testing_guide/end_to_end/best_practices.md +++ b/doc/development/testing_guide/end_to_end/best_practices.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # End-to-end testing Best Practices @@ -128,7 +128,7 @@ end 1. Every `describe`, `context`, and `it` blocks should have a short description attached 1. Keep descriptions as concise as possible. 1. Long descriptions or multiple conditionals could be a sign it should be split up (additional `context` blocks). - 1. The [Documentation Style Guide](../../documentation/styleguide/index.md) gives recommendations on how to write concisely and with [active voice](../../documentation/styleguide/word_list.md#active-voice). + 1. The [Documentation Style Guide](../../documentation/styleguide/index.md) gives recommendations on how to write concisely and with [active voice](../../documentation/styleguide/index.md#active-voice). 1. The outermost `Rspec.describe` block should be [the DevOps stage name](https://about.gitlab.com/handbook/product/categories/#devops-stages) 1. Inside the `Rspec.describe` block is a `describe` block with the name of the feature being tested 1. Optional `context` blocks define what the conditions being tested are @@ -361,7 +361,7 @@ When you add a new test that requires administrator access, apply the RSpec meta When running tests locally or configuring a pipeline, the environment variable `QA_CAN_TEST_ADMIN_FEATURES` can be set to `false` to skip tests that have the `:requires_admin` tag. NOTE: -If the _only_ action in the test that requires administrator access is to toggle a feature flag, please use the `feature_flag` tag instead. More details can be found in [testing with feature flags](feature_flags.md). +If the _only_ action in the test that requires administrator access is to toggle a feature flag, use the `feature_flag` tag instead. More details can be found in [testing with feature flags](feature_flags.md). ## Prefer `Commit` resource over `ProjectPush` diff --git a/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md b/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md index 025f998c0c9..64bb5df5db1 100644 --- a/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md +++ b/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Migration Guide Capybara → Chemlab diff --git a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md index 5cc82916cdd..f78b7208bbf 100644 --- a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md +++ b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Dynamic Element Validation diff --git a/doc/development/testing_guide/end_to_end/execution_context_selection.md b/doc/development/testing_guide/end_to_end/execution_context_selection.md index 0082bb6ee23..f625dc466b9 100644 --- a/doc/development/testing_guide/end_to_end/execution_context_selection.md +++ b/doc/development/testing_guide/end_to_end/execution_context_selection.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Execution context selection diff --git a/doc/development/testing_guide/end_to_end/feature_flags.md b/doc/development/testing_guide/end_to_end/feature_flags.md index 228f63d2354..e11119d2c0b 100644 --- a/doc/development/testing_guide/end_to_end/feature_flags.md +++ b/doc/development/testing_guide/end_to_end/feature_flags.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Testing with feature flags @@ -16,7 +16,7 @@ and `GITLAB_ADMIN_PASSWORD`. ## `feature_flag` RSpec tag -Please be sure to include the `feature_flag` tag so that the test can be skipped on the appropriate environments. +Be sure to include the `feature_flag` tag so that the test can be skipped on the appropriate environments. **Optional metadata:** @@ -181,7 +181,7 @@ active feature flag. To circumvent this behavior, add a wait for elements behind It's also possible to run an entire scenario with a feature flag enabled, without having to edit existing tests or write new ones. -Please see the [QA README](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa#running-tests-with-a-feature-flag-enabled) +See the [QA README](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa#running-tests-with-a-feature-flag-enabled) for details. ## Confirming that end-to-end tests pass with a feature flag enabled @@ -219,4 +219,4 @@ pass on the default branch. The end-to-end tests run on the default branch every If the relevant tests do not enable the feature flag themselves, you can check if the tests will need to be updated by opening a draft merge request that enables the flag by default via a [feature flag definition file](../../feature_flags/index.md#feature-flag-definition-and-validation). That will [automatically execute the end-to-end test suite](#automatic-test-execution-when-a-feature-flag-definition-changes). -The merge request can be closed once the tests pass. If you need assistance to update the tests, please contact the relevant [stable counterpart in the Quality department](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors), or any Software Engineer in Test if there is no stable counterpart for your group. +The merge request can be closed once the tests pass. If you need assistance to update the tests, contact the relevant [stable counterpart in the Quality department](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors), or any Software Engineer in Test if there is no stable counterpart for your group. diff --git a/doc/development/testing_guide/end_to_end/flows.md b/doc/development/testing_guide/end_to_end/flows.md index 58702ceb861..c1d9f935da5 100644 --- a/doc/development/testing_guide/end_to_end/flows.md +++ b/doc/development/testing_guide/end_to_end/flows.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Flows in GitLab QA diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index 30fb1abd7df..33465816ec1 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # End-to-end Testing @@ -78,7 +78,7 @@ subgraph " `gitlab-org/gitlab-qa-mirror` pipeline" and polls for the resulting status. We call this a _status attribution_. 1. In the [`gitlab-org/build/omnibus-gitlab-mirror` pipeline](https://gitlab.com/gitlab-org/build/omnibus-gitlab-mirror): - 1. Docker image is being built and pushed to its Container Registry. + 1. Docker image is being built and pushed to its container registry. 1. Once Docker images are built and pushed jobs in `test` stage are started 1. In the `Test` stage: @@ -266,7 +266,7 @@ use the [GitLab QA orchestrator](https://gitlab.com/gitlab-org/gitlab-qa/tree/ma On the other hand, if you would like to run against a local development GitLab environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/). -Please refer to the instructions in the [QA README](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/README.md#how-can-i-use-it) +Refer to the instructions in the [QA README](https://gitlab.com/gitlab-org/gitlab/-/tree/master/qa/README.md#how-can-i-use-it) and the section below. ### Running tests that require special setup @@ -302,7 +302,7 @@ Continued reading: ## Where can you ask for help? -You can ask question in the `#quality` channel on Slack (GitLab internal) or +You can ask question in the `#test-platform` channel on Slack (GitLab internal) or you can find an issue you would like to work on in [the `gitlab` issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name%5B%5D=QA&label_name%5B%5D=test), or [the `gitlab-qa` issue tracker](https://gitlab.com/gitlab-org/gitlab-qa/-/issues?label_name%5B%5D=new+scenario). diff --git a/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md b/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md deleted file mode 100644 index 240db2cbfe5..00000000000 --- a/doc/development/testing_guide/end_to_end/package_and_test_pipeline.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'test_pipelines.md' -remove_date: '2023-11-08' ---- - -This document was moved to [another location](test_pipelines.md). - -<!-- This redirect file can be deleted after <2023-11-08>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index 3e13aaa4f02..812d2724b72 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Page objects in GitLab QA @@ -303,8 +303,8 @@ from within the `qa` directory. ## Where to ask for help? -If you need more information, ask for help on `#quality` channel on Slack +If you need more information, ask for help on `#test-platform` channel on Slack (internal, GitLab Team only). -If you are not a Team Member, and you still need help to contribute, please +If you are not a Team Member, and you still need help to contribute, open an issue in GitLab CE issue tracker with the `~QA` label. diff --git a/doc/development/testing_guide/end_to_end/resources.md b/doc/development/testing_guide/end_to_end/resources.md index 735bab2fa0a..7ff44f8cddb 100644 --- a/doc/development/testing_guide/end_to_end/resources.md +++ b/doc/development/testing_guide/end_to_end/resources.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Resource classes in GitLab QA @@ -494,14 +494,14 @@ We have a mechanism to [collect](https://gitlab.com/gitlab-org/gitlab/-/blob/443 all resources created during test executions, and another to [handle](https://gitlab.com/gitlab-org/gitlab/-/blob/44345381e89d6bbd440f7b4c680d03e8b75b86de/qa/qa/tools/test_resources_handler.rb#L44) these resources. On [dotcom environments](https://about.gitlab.com/handbook/engineering/infrastructure/environments/#environments), after a test suite finishes in the [QA pipelines](https://about.gitlab.com/handbook/engineering/quality/quality-engineering/debugging-qa-test-failures/#scheduled-qa-test-pipelines), resources from all passing test are automatically deleted in the same pipeline run. Resources from all failed tests are reserved for investigation, -and won't be deleted until the following Saturday by a scheduled pipeline. When introducing new resources, please +and won't be deleted until the following Saturday by a scheduled pipeline. When introducing new resources, also make sure to add any resource that cannot be deleted to the [IGNORED_RESOURCES](https://gitlab.com/gitlab-org/gitlab/-/blob/44345381e89d6bbd440f7b4c680d03e8b75b86de/qa/qa/tools/test_resources_handler.rb#L29) list. ## Where to ask for help? -If you need more information, ask for help on `#quality` channel on Slack +If you need more information, ask for help on `#test-platform` channel on Slack (internal, GitLab Team only). -If you are not a Team Member, and you still need help to contribute, please +If you are not a Team Member, and you still need help to contribute, open an issue in GitLab CE issue tracker with the `~QA` label. diff --git a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md index 93adc492d5a..5d7897331a2 100644 --- a/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md +++ b/doc/development/testing_guide/end_to_end/rspec_metadata_tests.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # RSpec metadata for end-to-end tests diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md index 0544b331b1a..aaea3f8958d 100644 --- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md +++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Running tests that require special setup @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [`jenkins_build_status_spec`](https://gitlab.com/gitlab-org/gitlab/-/blob/24a86debf49f3aed6f2ecfd6e8f9233b3a214181/qa/qa/specs/features/browser_ui/3_create/jenkins/jenkins_build_status_spec.rb) spins up a Jenkins instance in a Docker container with the Jenkins GitLab plugin pre-installed. Due to a license restriction we are unable to distribute this image. -To build a QA compatible image, please visit the [third party images project](https://gitlab.com/gitlab-org/quality/third-party-docker-public), where third party Dockerfiles can be found. +To build a QA compatible image, visit the [third party images project](https://gitlab.com/gitlab-org/quality/third-party-docker-public), where third party Dockerfiles can be found. The project also has instructions for forking and building the images automatically in CI. Some extra environment variables for the location of the forked repository are also needed. @@ -47,7 +47,7 @@ bin/qa Test::Instance::All http://localhost -- qa/specs/features/ee/browser_ui/3 The test automatically spins up a Docker container for Jenkins and tear down once the test completes. -If you need to run Jenkins manually outside of the tests, please refer to the README for the +If you need to run Jenkins manually outside of the tests, refer to the README for the [third party images project](https://gitlab.com/gitlab-org/quality/third-party-docker-public/-/blob/main/jenkins/README.md) ### Troubleshooting @@ -420,7 +420,7 @@ To run these tests locally against the GDK: QA_LOG_LEVEL=debug WEBDRIVER_HEADLESS=false bin/qa Test::Instance::All http://localhost:3000 qa/specs/features/browser_ui/2_plan/email/trigger_email_notification_spec.rb -- --tag orchestrated ``` -For instructions on how to run these tests using the `gitlab-qa` gem, please refer to [the GitLab QA documentation](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#testintegrationsmtp-ceeefull-image-address). +For instructions on how to run these tests using the `gitlab-qa` gem, refer to [the GitLab QA documentation](https://gitlab.com/gitlab-org/gitlab-qa/-/blob/master/docs/what_tests_can_be_run.md#testintegrationsmtp-ceeefull-image-address). ## Guide to the mobile suite @@ -600,3 +600,23 @@ To run the [`login_via_oauth_and_oidc_with_gitlab_as_idp_spec`](https://gitlab.c RELEASE_REGISTRY_URL='registry.gitlab.com' RELEASE_REGISTRY_USERNAME='<your_gitlab_username>' RELEASE_REGISTRY_PASSWORD='<your_gitlab_personal_access_token>' RELEASE='registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:c0ae46db6b31ea231b2de88961cd687acf634179' GITLAB_QA_ADMIN_ACCESS_TOKEN="<your_gdk_admin_personal_access_token>" QA_DEBUG=true CHROME_HEADLESS=false bundle exec bin/qa Test::Instance::All http://gdk.test:3000 qa/specs/features/browser_ui/1_manage/login/login_via_oauth_and_oidc_with_gitlab_as_idp_spec.rb ``` + +## Product Analytics tests + +Product Analytics e2e tests require Product Analytics services running and connected to your GDK. + +In order to run Product Analytics services, devkit can be used. Instructions to set it up and connect to your GDK can be found in the [devkit project's `README.md`](https://gitlab.com/gitlab-org/analytics-section/product-analytics/devkit). + +Additionally, the following setup is required on the GDK: + +- Ultimate license applied. + - [How to request the license](https://about.gitlab.com/handbook/developer-onboarding/#working-on-gitlab-ee-developer-licenses). + - [How to activate GitLab EE with a license file or key](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/administration/license_file.md#activate-gitlab-ee-with-a-license-file-or-key). +- Product Analytics feature flags enabled. The list of feature flags can be [found here](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/user/product_analytics#enable-product-analytics). +- Simulate SaaS enabled. Instructions can be [found here](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/ee_features.md#simulate-a-saas-instance). + +Once Product Analytics services are running and are connected to your GDK, the tests can be executed with: + +```shell +bundle exec rspec qa/specs/features/ee/browser_ui/8_monitor/product_analytics/onboarding_spec.rb +``` diff --git a/doc/development/testing_guide/end_to_end/style_guide.md b/doc/development/testing_guide/end_to_end/style_guide.md index f5a3fa2fc51..966ed851115 100644 --- a/doc/development/testing_guide/end_to_end/style_guide.md +++ b/doc/development/testing_guide/end_to_end/style_guide.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Style guide for writing end-to-end tests @@ -19,10 +19,8 @@ When selecting a single link to navigate, use `click_`. For example: ```ruby -def click_ci_cd_pipelines - within_sidebar do - click_element(:link_pipelines) - end +def click_add_badge_button + click_element :add_badge_button end ``` @@ -38,12 +36,8 @@ When interacting with multiple elements to go to a page, use `go_to_`. For example: ```ruby -def go_to_operations_environments - hover_operations do - within_submenu do - click_element(:operations_environments_link) - end - end +def go_to_applications + click_element('nav-item-link', submenu_item: 'Applications') end ``` @@ -77,7 +71,7 @@ We follow a simple formula roughly based on Hungarian notation. - `_menu_item` NOTE: -If none of the listed types are suitable, please open a merge request to add an appropriate type to the list. +If none of the listed types are suitable, open a merge request to add an appropriate type to the list. ### Examples diff --git a/doc/development/testing_guide/end_to_end/test_infrastructure.md b/doc/development/testing_guide/end_to_end/test_infrastructure.md index 00d4507d35e..3f00885ef96 100644 --- a/doc/development/testing_guide/end_to_end/test_infrastructure.md +++ b/doc/development/testing_guide/end_to_end/test_infrastructure.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # End-to-end Testing Infrastructure for Cloud Integrations diff --git a/doc/development/testing_guide/end_to_end/test_pipelines.md b/doc/development/testing_guide/end_to_end/test_pipelines.md index b47b75e398a..12a0728c65d 100644 --- a/doc/development/testing_guide/end_to_end/test_pipelines.md +++ b/doc/development/testing_guide/end_to_end/test_pipelines.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # End-to-end test pipelines @@ -161,7 +161,7 @@ The pipeline setup consists of several jobs in the main GitLab pipeline: #### `build-gdk-image` [This job](https://gitlab.com/gitlab-org/gitlab/-/blob/07504c34b28ac656537cd60810992aa15e9e91b8/.gitlab/ci/build-images.gitlab-ci.yml#L32) -uses the code from the merge request to build a Docker image that can be used in test jobs to launch a GDK instance in a container. The image is pushed to the Container Registry. +uses the code from the merge request to build a Docker image that can be used in test jobs to launch a GDK instance in a container. The image is pushed to the container registry. The job also runs in pipelines on the default branch to build a base image that includes the GDK and GitLab components. This avoids building the entire image from scratch in merge requests. However, if the merge request includes changes to diff --git a/doc/development/testing_guide/end_to_end/troubleshooting.md b/doc/development/testing_guide/end_to_end/troubleshooting.md index b4c47b90f0b..4b9a2137424 100644 --- a/doc/development/testing_guide/end_to_end/troubleshooting.md +++ b/doc/development/testing_guide/end_to_end/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Troubleshooting end-to-end tests diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 019e0654456..1895b9bdb39 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Flaky tests @@ -233,7 +233,7 @@ Once a test is in quarantine, there are 3 choices: On our CI, we use [`RSpec::Retry`](https://github.com/NoRedInk/rspec-retry) to automatically retry a failing example a few times (see [`spec/spec_helper.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/spec_helper.rb) for the precise retries count). -We also use a custom [`RspecFlaky::Listener`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/gems/rspec_flaky/lib/rspec_flaky/listener.rb). +We also use a custom [`Gitlab::RspecFlaky::Listener`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/gems/gitlab-rspec_flaky/lib/gitlab/rspec_flaky/listener.rb). This listener runs in the `update-tests-metadata` job in `maintenance` scheduled pipelines on the `master` branch, and saves flaky examples to `rspec/flaky/report-suite.json`. The report file is then retrieved by the `retrieve-tests-metadata` job in all pipelines. @@ -333,6 +333,17 @@ If a spec hangs, it might be caused by a [bug in Rails](https://github.com/rails It could help to split the large RSpec files in multiple files in order to narrow down the context and identify the problematic tests. +### Recreate job failure in CI by forcing the job to run the same set of test files + +Reproducing a job failure in CI always helps with troubleshooting why and how a test fails. This require us running the same test files with the same spec order. Since we use Knapsack to distribute tests across parallelized jobs, and files can be distributed differently between two pipelines, we can hardcode this job distribution through the following steps: + +1. Find a job that you want to reproduce, identify the commit that it ran against, set your local `gitlab-org/gitlab` branch to the same commit to ensure we are running with the same copy of the project. +1. In the job log, locate the list of spec files that were distributed by Knapsack - you can search for `Running command: bundle exec rspec`, the last argument of this command should contain a list of file names. Copy this list. +1. Go to `tooling/lib/tooling/parallel_rspec_runner.rb` where the test file distribution happens. Have a look at [this merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137924/diffs) as an example, store the file list you copied from step 2 into a `TEST_FILES` constant and have RSpec run this list by updating the `rspec_command` method as done in the example MR. +1. Skip the tests in `spec/tooling/lib/tooling/parallel_rspec_runner_spec.rb` so it doesn't cause your pipeline to fail early. +1. Since we want to force the pipeline to run against a specific version, we do not want to run a merged results pipeline. We can introduce a merge conflict into the MR to achieve this. +1. To preserve spec ordering, update the `spec/support/rspec_order.rb` file by hard coding `Kernel.srand` with the value shown in the originally failing job, as done [here](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128428/diffs#32f6fa4961481518204e227252552dba7483c3b0_62_62). You can fine the srand value in the job log by searching `Randomized with seed` which is followed by this value. + ## Resources - [Flaky Tests: Are You Sure You Want to Rerun Them?](https://semaphoreci.com/blog/2017/04/20/flaky-tests.html) diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 7e79080bbd1..d14ca15991c 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Frontend testing standards and style guidelines diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index 68d30ff6656..2136a686489 100644 --- a/doc/development/testing_guide/index.md +++ b/doc/development/testing_guide/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Testing standards and style guidelines diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 9da63d0d1d7..d0a6fa8da5f 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Using review apps in the development of GitLab @@ -203,16 +203,16 @@ subgraph "CNG-mirror pipeline" **Additional notes:** - If the `review-deploy` job keeps failing (and a manual retry didn't help), - please post a message in the `#g_qe_engineering_productivity` channel and/or create a `~"Engineering Productivity"` `~"ep::review apps"` `~"type::bug"` + post a message in the `#g_qe_engineering_productivity` channel and/or create a `~"Engineering Productivity"` `~"ep::review apps"` `~"type::bug"` issue with a link to your merge request. The deployment failure can reveal an actual problem introduced in your merge request (that is, this isn't necessarily a transient failure)! - If the `review-qa-smoke` or `review-qa-reliable` job keeps failing (we already retry them once), - please check the job's logs: you could discover an actual problem introduced in + check the job's logs: you could discover an actual problem introduced in your merge request. You can also download the artifacts to see screenshots of the page at the time the failures occurred. If you don't find the cause of the - failure or if it seems unrelated to your change, please post a message in the - `#quality` channel and/or create a ~Quality ~"type::bug" issue with a link to your + failure or if it seems unrelated to your change, post a message in the + `#test-platform` channel and/or create a ~Quality ~"type::bug" issue with a link to your merge request. - The manual `review-stop` can be used to stop a review app manually, and is also started by GitLab once a merge diff --git a/doc/development/testing_guide/smoke.md b/doc/development/testing_guide/smoke.md index 62a09ca864b..0c7cb9219ad 100644 --- a/doc/development/testing_guide/smoke.md +++ b/doc/development/testing_guide/smoke.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Smoke Tests diff --git a/doc/development/testing_guide/test_results_tracking.md b/doc/development/testing_guide/test_results_tracking.md index 92c1e0917c7..4e40d47dab0 100644 --- a/doc/development/testing_guide/test_results_tracking.md +++ b/doc/development/testing_guide/test_results_tracking.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Test results tracking diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 4e4dc671c03..81399c7ce05 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Testing levels diff --git a/doc/development/testing_guide/testing_migrations_guide.md b/doc/development/testing_guide/testing_migrations_guide.md index abe04274b72..ce6ba082f3b 100644 --- a/doc/development/testing_guide/testing_migrations_guide.md +++ b/doc/development/testing_guide/testing_migrations_guide.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Testing Rails migrations at GitLab @@ -84,8 +83,7 @@ end ``` In some cases, you must require multiple migration files to use them in your specs. Here, there's no -pattern between your spec file and the other migration file. You can provide the migration filename -like so: +pattern between your spec file and the other migration file. You can provide the migration file name like so: ```ruby # frozen_string_literal: true @@ -371,7 +369,7 @@ end ## Testing a non-`ActiveRecord::Migration` class To test a non-`ActiveRecord::Migration` test (a background migration), -you must manually provide a required schema version. Please add a +you must manually provide a required schema version. Add a `schema` tag to a context that you want to switch the database schema within. If not set, `schema` defaults to `:latest`. diff --git a/doc/development/testing_guide/testing_rake_tasks.md b/doc/development/testing_guide/testing_rake_tasks.md index 07332f8708b..38d852616b6 100644 --- a/doc/development/testing_guide/testing_rake_tasks.md +++ b/doc/development/testing_guide/testing_rake_tasks.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Testing Rake tasks diff --git a/doc/development/transient/prevention-patterns.md b/doc/development/transient/prevention-patterns.md index 730cc757396..de15d8eba95 100644 --- a/doc/development/transient/prevention-patterns.md +++ b/doc/development/transient/prevention-patterns.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Preventing Transient Bugs diff --git a/doc/development/uploads/index.md b/doc/development/uploads/index.md index 92b52d2b59c..13ef5c34d7e 100644 --- a/doc/development/uploads/index.md +++ b/doc/development/uploads/index.md @@ -1,7 +1,7 @@ --- stage: SaaS Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Uploads development guidelines diff --git a/doc/development/uploads/working_with_uploads.md b/doc/development/uploads/working_with_uploads.md index 6be6e472555..6fa9ed25257 100644 --- a/doc/development/uploads/working_with_uploads.md +++ b/doc/development/uploads/working_with_uploads.md @@ -1,7 +1,7 @@ --- stage: SaaS Platforms group: Scalability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Uploads guide: Adding new uploads diff --git a/doc/development/utilities.md b/doc/development/utilities.md index 83b87d6d289..dbdf13feef8 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab utilities @@ -284,3 +284,54 @@ end ## `ReactiveCaching` Read the documentation on [`ReactiveCaching`](reactive_caching.md). + +## `CircuitBreaker` + +The `Gitlab::CircuitBreaker` can be wrapped around any class that needs to run code with circuit breaker protection. It provides a `run_with_circuit` method that wraps a code block with circuit breaker functionality, which helps prevent cascading failures and improves system resilience. For more information about the circuit breaker pattern, see: + +- [What is Circuit breaker](https://martinfowler.com/bliki/CircuitBreaker.html). +- [The Hystrix documentation on CircuitBreaker](https://github.com/Netflix/Hystrix/wiki/How-it-Works#circuit-breaker). + +### Use CircuitBreaker + +To use the CircuitBreaker wrapper: + +```ruby +class MyService + def call_external_service + Gitlab::CircuitBreaker.run_with_circuit('ServiceName') do + # Code that interacts with external service goes here + + raise Gitlab::CircuitBreaker::InternalServerError # if there is an issue + end + end +end +``` + +The `call_external_service` method is an example method that interacts with an external service. +By wrapping the code that interacts with the external service with `run_with_circuit`, the method is executed within the circuit breaker. + +The method should raise an `InternalServerError` error, which will be counted towards the error threshold if raised during the execution of the code block. +The circuit breaker tracks the number of errors and the rate of requests, +and opens the circuit if it reaches the configured error threshold or volume threshold. +If the circuit is open, subsequent requests fail fast without executing the code block, and the circuit breaker periodically allows a small number of requests through to test the service's availability before closing the circuit again. + +### Configuration + +You need to specify a service name for each unique circuit that is used as the cache key. This should be a `CamelCase` string which identifies the circuit. + +The circuit breaker has defaults that can be overridden per circuit, for example: + +```ruby +Gitlab::CircuitBreaker.run_with_circuit('ServiceName', options = { volume_threshold: 5 }) do + ... +end +``` + +The defaults are: + +- `exceptions`: `[Gitlab::CircuitBreaker::InternalServerError]` +- `error_threshold`: `50` +- `volume_threshold`: `10` +- `sleep_window`: `90` +- `time_window`: `60` diff --git a/doc/development/ux/index.md b/doc/development/ux/index.md index 784a59a3a4a..ab6cd4c64f5 100644 --- a/doc/development/ux/index.md +++ b/doc/development/ux/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Contribute to UX design diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index 5aa6aecd9db..725c8aa45d2 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Value stream analytics development guidelines diff --git a/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md b/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md index 4d2a751e6c6..53c6721b01f 100644 --- a/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md +++ b/doc/development/value_stream_analytics/value_stream_analytics_aggregated_backend.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Aggregated Value Stream Analytics diff --git a/doc/development/vs_code_debugging.md b/doc/development/vs_code_debugging.md index 66f69a74c86..457b3e5f792 100644 --- a/doc/development/vs_code_debugging.md +++ b/doc/development/vs_code_debugging.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # VS Code debugging diff --git a/doc/development/wikis.md b/doc/development/wikis.md index eca43f6df03..8c9064bf7a9 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. description: "GitLab's development guidelines for Wikis" --- diff --git a/doc/development/windows.md b/doc/development/windows.md index 99085b4b5f8..a36e094cbcb 100644 --- a/doc/development/windows.md +++ b/doc/development/windows.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Windows Development diff --git a/doc/development/work_items.md b/doc/development/work_items.md index 73993b1d9ee..0c3bc4611f5 100644 --- a/doc/development/work_items.md +++ b/doc/development/work_items.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Work items and work item types @@ -190,7 +190,7 @@ and incidents) into work items. Eventually (when these resources become regular work items), `base_type` will be removed. Until the architecture of WIT widgets is finalized, we are holding off on the creation of new work item -types. If a new work item type is absolutely necessary, please reach out to a +types. If a new work item type is absolutely necessary, reach out to a member of the [Project Management Engineering Team](https://gitlab.com/gitlab-org/gitlab/-/issues/370599). ### Creating a new work item type in the database diff --git a/doc/development/work_items_widgets.md b/doc/development/work_items_widgets.md index 2e5a09af911..332dfde8a68 100644 --- a/doc/development/work_items_widgets.md +++ b/doc/development/work_items_widgets.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Work items widgets diff --git a/doc/development/workhorse/channel.md b/doc/development/workhorse/channel.md index 2c28cea42a3..667040e20c9 100644 --- a/doc/development/workhorse/channel.md +++ b/doc/development/workhorse/channel.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Websocket channel support for Workhorse diff --git a/doc/development/workhorse/configuration.md b/doc/development/workhorse/configuration.md index d19e85f3f7a..becd65387e8 100644 --- a/doc/development/workhorse/configuration.md +++ b/doc/development/workhorse/configuration.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Workhorse configuration diff --git a/doc/development/workhorse/gitlab_features.md b/doc/development/workhorse/gitlab_features.md index b4146e8b62c..73ee22929ab 100644 --- a/doc/development/workhorse/gitlab_features.md +++ b/doc/development/workhorse/gitlab_features.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Features that rely on Workhorse diff --git a/doc/development/workhorse/index.md b/doc/development/workhorse/index.md index 680dd0c205b..8fe7f027cfd 100644 --- a/doc/development/workhorse/index.md +++ b/doc/development/workhorse/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # GitLab Workhorse diff --git a/doc/development/workhorse/new_features.md b/doc/development/workhorse/new_features.md index dbde06ddee4..0f6c5b763ce 100644 --- a/doc/development/workhorse/new_features.md +++ b/doc/development/workhorse/new_features.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. --- # Adding new features to Workhorse diff --git a/doc/devsecops.md b/doc/devsecops.md index f035121898a..de87cf42a95 100644 --- a/doc/devsecops.md +++ b/doc/devsecops.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.' --- @@ -42,19 +42,19 @@ For details, see [this article about DevSecOps](https://about.gitlab.com/topics/ If your organization is facing any of the following challenges, a DevSecOps approach might be for you. -- **Development, security, and operations teams are siloed.** +- **Development, security, and operations teams are siloed.** If development and operations are isolated from security issues, they can't build secure software. And if security teams aren't part of the development process, they can't identify risks proactively. DevSecOps brings teams together to improve workflows and share ideas. Organizations might even see improved employee morale and retention. -- **Long development cycles are making it difficult to meet customer or stakeholder demands.** +- **Long development cycles are making it difficult to meet customer or stakeholder demands.** One reason for the struggle could be security. DevSecOps implements security at every step of - the development lifecycle, meaning that solid security doesn’t require the whole process to come to a halt. + the development lifecycle, meaning that solid security doesn't require the whole process to come to a halt. -- **You’re migrating to the cloud (or considering it).** +- **You're migrating to the cloud (or considering it).** Moving to the cloud often means bringing on new development processes, tools, and systems. - It’s a great time to make processes faster and more secure — and DevSecOps could make that a lot easier. + It's a great time to make processes faster and more secure — and DevSecOps could make that a lot easier. To get started with DevSecOps, [learn more, and try GitLab Ultimate for free](https://about.gitlab.com/solutions/security-compliance/). diff --git a/doc/downgrade_ee_to_ce/index.md b/doc/downgrade_ee_to_ce/index.md index e541f67cac7..519fbccf9b0 100644 --- a/doc/downgrade_ee_to_ce/index.md +++ b/doc/downgrade_ee_to_ce/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Downgrading from EE to CE diff --git a/doc/drawers/advanced_search_syntax.md b/doc/drawers/advanced_search_syntax.md index 6e732bd3175..6f308d3c6b6 100644 --- a/doc/drawers/advanced_search_syntax.md +++ b/doc/drawers/advanced_search_syntax.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: drawer +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" source: /doc/user/search/advanced_search.md --- diff --git a/doc/drawers/exact_code_search_syntax.md b/doc/drawers/exact_code_search_syntax.md index 034912571cd..ce4a97f9f87 100644 --- a/doc/drawers/exact_code_search_syntax.md +++ b/doc/drawers/exact_code_search_syntax.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: drawer +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" source: /doc/user/search/exact_code_search.md --- diff --git a/doc/editor_extensions/gitlab_cli/index.md b/doc/editor_extensions/gitlab_cli/index.md index 5f5bdfe091e..a0319e64a54 100644 --- a/doc/editor_extensions/gitlab_cli/index.md +++ b/doc/editor_extensions/gitlab_cli/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CLI - `glab` **(FREE ALL)** diff --git a/doc/editor_extensions/index.md b/doc/editor_extensions/index.md index 769db7c5adb..de1e3f21ee6 100644 --- a/doc/editor_extensions/index.md +++ b/doc/editor_extensions/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor Extensions -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Editor and IDE extensions diff --git a/doc/editor_extensions/jetbrains_ide/index.md b/doc/editor_extensions/jetbrains_ide/index.md index c5f8655bc6b..47b25bbf759 100644 --- a/doc/editor_extensions/jetbrains_ide/index.md +++ b/doc/editor_extensions/jetbrains_ide/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor Extensions -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab plugin for JetBrains IDEs diff --git a/doc/editor_extensions/neovim/index.md b/doc/editor_extensions/neovim/index.md index 749c1de252d..6298011aa0e 100644 --- a/doc/editor_extensions/neovim/index.md +++ b/doc/editor_extensions/neovim/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor Extensions -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab plugin for Neovim - `gitlab.vim` diff --git a/doc/editor_extensions/visual_studio/index.md b/doc/editor_extensions/visual_studio/index.md index 6f67738aa5c..038f0f863ed 100644 --- a/doc/editor_extensions/visual_studio/index.md +++ b/doc/editor_extensions/visual_studio/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor Extensions -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab extension for Visual Studio diff --git a/doc/editor_extensions/visual_studio_code/index.md b/doc/editor_extensions/visual_studio_code/index.md index 70d0c79cfbf..4e2fb31c863 100644 --- a/doc/editor_extensions/visual_studio_code/index.md +++ b/doc/editor_extensions/visual_studio_code/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor Extensions -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Workflow extension for VS Code @@ -37,6 +37,7 @@ you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.g - [Features to display or hide](https://gitlab.com/gitlab-org/gitlab-vscode-extension#extension-settings). - [Self-signed certificate](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#self-signed-certificates) information. - [Code Suggestions](../../user/project/repository/code_suggestions/index.md). +- [GitLab Duo Chat](../../user/gitlab_duo_chat.md#gitlab-workflow-extension-for-vs-code). ## Report issues with the extension diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md index 55300d52b71..41d2feb27da 100644 --- a/doc/gitlab-basics/add-file.md +++ b/doc/gitlab-basics/add-file.md @@ -1,77 +1,67 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- -# Add a file to a repository **(FREE ALL)** +# Use Git to add a file to a repository **(FREE ALL)** -Adding files to a repository is a small, but key, task. No matter where the code, -images, or documents were created, Git tracks them after you add them to your repository. +To add a new file from the command line: -## Add an existing file +1. Open a terminal. +1. Change directories until you are in your project's folder. -To add an existing file to your repository, either: + ```shell + cd my-project + ``` -- Upload the file from the GitLab UI. -- Add a file to your repository from the command line, then push the file up to GitLab. +1. Choose a Git branch to work in. + - To create a branch: `git checkout -b <branchname>` + - To switch to an existing branch: `git checkout <branchname>` -### From the UI +1. Copy the file you want to add into the directory where you want to add it. +1. Confirm that your file is in the directory: + - Windows: `dir` + - All other operating systems: `ls` -If you are unfamiliar with the command line, use the -[Web Editor](../user/project/repository/web_editor.md) to upload a file from the GitLab UI: + The filename should be displayed. +1. Check the status of the file: -<!-- Original source for this list: doc/user/project/repository/web_editor.md#upload-a-file --> -<!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> + ```shell + git status + ``` + + The filename should be in red. The file is in your file system, but Git isn't tracking it yet. +1. Tell Git to track the file: -1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **Upload file**. -1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. -1. Select **Upload file**. + ```shell + git add <filename> + ``` -### From the command line +1. Check the status of the file again: -To add a new file from the command line: + ```shell + git status + ``` -1. Open a terminal (or shell) window. -1. Use the "change directory" (`cd`) command to go to your GitLab project's folder. - Run the `cd DESTINATION` command, changing `DESTINATION` to the location of your folder. -1. Choose a Git branch to work in. You can either: - - [Create a new branch](../tutorials/make_first_git_commit/index.md#create-a-branch-and-make-changes) - to add your file into. Don't submit changes directly to the default branch of your - repository unless your project is very small and you're the only person working on it. - - [Switch to an existing branch](start-using-git.md#switch-to-a-branch). -1. Copy the file into the appropriate directory in your project. Use your standard tool - for copying files, such as Finder in macOS, or File Explorer in Windows. -1. In your terminal window, confirm that your file is present in the directory: - - Windows: Use the `dir` command. - - All other operating systems: Use the `ls` command. - You should see the name of the file in the list shown. -1. Check the status of your file with the `git status` command. Your file's name - should be red. Files listed in red are in your file system, but Git isn't tracking them yet. -1. Tell Git to track this file with the `git add FILENAME` command, replacing `FILENAME` - with the name of your file. -1. Check the status of your file again with the `git status` command. Your file's name - should be green. Files listed in green are tracked locally by Git, but still - need to be committed and pushed. -1. Commit (save) your file to your local copy of your project's Git repository: + The filename should be green. The file is tracked locally by Git, but + has not been committed and pushed. +1. Commit the file to your local copy of the project's Git repository: ```shell - git commit -m "DESCRIBE COMMIT IN A FEW WORDS" + git commit -m "Describe the reason for your commit here" ``` -1. Push (send) your changes from your copy of the repository, up to GitLab. - In this command, `origin` refers to the copy of the repository stored at GitLab. - Replace `BRANCHNAME` with the name of your branch: +1. Push your changes from your copy of the repository to GitLab. + In this command, `origin` refers to the remote copy of the repository. + Replace `<branchname>` with the name of your branch: ```shell - git push origin BRANCHNAME + git push origin <branchname> ``` 1. Git prepares, compresses, and sends the data. Lines from the remote repository - (here, GitLab) are prefixed with `remote:` like this: + start with `remote:`: ```plaintext Enumerating objects: 9, done. @@ -81,21 +71,31 @@ To add a new file from the command line: Writing objects: 100% (5/5), 1.84 KiB | 1.84 MiB/s, done. Total 5 (delta 3), reused 0 (delta 0), pack-reused 0 remote: - remote: To create a merge request for BRANCHNAME, visit: - remote: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/new?merge_request%5Bsource_branch%5D=BRANCHNAME + remote: To create a merge request for <branchname>, visit: + remote: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/new?merge_request%5Bsource_branch%5D=<branchname> remote: To https://gitlab.com/gitlab-org/gitlab.git - * [new branch] BRANCHNAME -> BRANCHNAME - branch 'BRANCHNAME' set up to track 'origin/BRANCHNAME'. + * [new branch] <branchname> -> <branchname> + branch '<branchname>' set up to track 'origin/<branchname>'. ``` -Your file is now copied from your local copy of the repository, up to the remote -repository at GitLab. To create a merge request, copy the link sent back from the remote +Your file is copied from your local copy of the repository to the remote +repository. + +To create a merge request, copy the link sent back from the remote repository and paste it into a browser window. -## Add a new file +## Add a file to the last commit + +```shell +git add <filename> +git commit --amend +``` + +Append `--no-edit` to the `commit` command if you do not want to edit the commit +message. -To create a new file (like a `README.md` text file) in your repository, either: +## Related topics -- [Create the file](../user/project/repository/web_editor.md#create-a-file) from the GitLab UI. -- Create the file from the terminal. +- [Add file from the UI](../user/project/repository/index.md#add-a-file-from-the-ui) +- [Add file from the Web IDE](../user/project/repository/web_editor.md#upload-a-file) diff --git a/doc/gitlab-basics/feature_branch_workflow.md b/doc/gitlab-basics/feature_branch_workflow.md index cbca22c1e55..26fe5081b98 100644 --- a/doc/gitlab-basics/feature_branch_workflow.md +++ b/doc/gitlab-basics/feature_branch_workflow.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Feature branch workflow **(FREE ALL)** diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index c46b89f7620..ecdc4aeed06 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto, tutorial +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Introduction to using Git through the command line." --- @@ -62,13 +61,13 @@ If your computer doesn't recognize `git` as a command, you must [install Git](.. ## Configure Git To start using Git from your computer, you must enter your credentials -to identify yourself as the author of your work. The username and email address +to identify yourself as the author of your work. The full name and email address should match the ones you use in GitLab. -1. In your shell, add your user name: +1. In your shell, add your full name: ```shell - git config --global user.name "your_username" + git config --global user.name "John Doe" ``` 1. Add your email address: @@ -140,6 +139,7 @@ You can also Clone with HTTPS when you want to authenticate each time you perform an operation between your computer and GitLab. +[OAuth credential helpers](../user/profile/account/two_factor_authentication.md#oauth-credential-helpers) can decrease the number of times you must manually authenticate, making HTTPS a seamless experience. 1. On the left sidebar, select **Search or go to** and find the project you want to clone. 1. On the right-hand side of the page, select **Clone**, then copy the URL for **Clone with HTTPS**. @@ -222,7 +222,7 @@ To add a remote to your local copy: git remote add origin git@gitlab.com:username/projectpath.git ``` -After you've done that, you can [stage your files](#add-and-commit-local-changes) and [upload them to GitLab](#send-changes-to-gitlabcom). +After you've done that, you can [stage your files](#add-and-commit-local-changes) and [upload them to GitLab](#send-changes-to-gitlab). #### View your remote repositories @@ -354,7 +354,7 @@ As a shortcut, you can add all local changes to staging and commit them with one git commit -a -m "COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT" ``` -### Send changes to GitLab.com +### Send changes to GitLab To push all local changes to the remote repository: @@ -369,7 +369,7 @@ git push origin main ``` Sometimes Git does not allow you to push to a repository. Instead, -you must [force an update](../topics/git/git_rebase.md#force-push). +you must [force an update](../topics/git/git_rebase.md#force-pushing). ### Delete all changes in the branch @@ -438,7 +438,7 @@ changes from the original repository. It is common to call this remote repositor You can now use the `upstream` as a [`<remote>` to `pull` new updates](#download-the-latest-changes-in-the-project) from the original repository, and use the `origin` -to [push local changes](#send-changes-to-gitlabcom) and create merge requests. +to [push local changes](#send-changes-to-gitlab) and create merge requests. <!-- ## Troubleshooting diff --git a/doc/index.md b/doc/index.md index 2c90d2f0970..362bbab3607 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.' --- diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 2c1f2529426..6ed3368fb45 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Read through the GitLab installation methods. --- diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 60591991ea7..3acdaa9a178 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -1,9 +1,8 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to spin up a pre-configured GitLab VM on Microsoft Azure.' -type: howto --- # Install GitLab on Microsoft Azure **(FREE SELF)** @@ -248,9 +247,8 @@ in this section whenever you need to update GitLab. To determine the version of GitLab you're currently running: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Dashboard**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Dashboard**. 1. Find the version under the **Components** table. If there's a newer available version of GitLab that contains one or more diff --git a/doc/install/cloud_providers.md b/doc/install/cloud_providers.md index 36cda77143f..318895b6d89 100644 --- a/doc/install/cloud_providers.md +++ b/doc/install/cloud_providers.md @@ -1,9 +1,8 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Install GitLab on a cloud provider. -type: index --- # Installing GitLab on a cloud provider **(FREE SELF)** diff --git a/doc/install/docker.md b/doc/install/docker.md index 0ba41e06b65..252f34f7120 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Docker images **(FREE SELF)** @@ -42,24 +42,26 @@ To use the GitLab Docker images: ## Set up the volumes location -Before setting everything else, configure a new environment variable `$GITLAB_HOME` -pointing to the directory where the configuration, logs, and data files will reside. -Ensure that the directory exists and appropriate permission have been granted. - -For Linux users, set the path to `/srv/gitlab`: +Before setting everything else, create a directory where the configuration, logs, +and data files will reside. It can be under your user's home directory (for example +`~/gitlab-docker`), or in a directory like `/srv/gitlab`. To create that directory: ```shell -export GITLAB_HOME=/srv/gitlab +sudo mkdir -p /srv/gitlab ``` -For macOS users, use the user's `$HOME/gitlab` directory: +If you're running Docker with a user other than `root`, ensure appropriate +permissions have been granted to that directory. + +Configure a new environment variable `$GITLAB_HOME` that sets the path to the +directory you created: ```shell -export GITLAB_HOME=$HOME/gitlab +export GITLAB_HOME=/srv/gitlab ``` -The `GITLAB_HOME` environment variable should be appended to your shell's profile so it is -applied on all future terminal sessions: +You can also append the `GITLAB_HOME` environment variable to your shell's +profile so it is applied on all future terminal sessions: - Bash: `~/.bash_profile` - ZSH: `~/.zshrc` diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index 7b90d4ad19c..12bc50cdff0 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: 'Learn how to install a GitLab instance on Google Cloud Platform.' --- @@ -133,7 +133,7 @@ SAML, and Kerberos. Here are some documents you might be interested in reading: - [Linux package documentation](https://docs.gitlab.com/omnibus/) - [Integration documentation](../../integration/index.md) - [GitLab Pages configuration](../../administration/pages/index.md) -- [GitLab Container Registry configuration](../../administration/packages/container_registry.md) +- [GitLab container registry configuration](../../administration/packages/container_registry.md) <!-- ## Troubleshooting diff --git a/doc/install/index.md b/doc/install/index.md index 15556117b51..d4d9a399eaf 100644 --- a/doc/install/index.md +++ b/doc/install/index.md @@ -1,9 +1,8 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Read through the GitLab installation methods. -type: index --- # Install GitLab **(FREE SELF)** diff --git a/doc/install/install_methods.md b/doc/install/install_methods.md index 5945e418274..b40d89e957a 100644 --- a/doc/install/install_methods.md +++ b/doc/install/install_methods.md @@ -1,9 +1,8 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: Read through the GitLab installation methods. -type: index --- # Installation methods **(FREE SELF)** diff --git a/doc/install/installation.md b/doc/install/installation.md index c8682fc154f..370f67865ed 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Self-compiled installation **(FREE SELF)** @@ -45,7 +45,7 @@ If the highest number stable branch is unclear, check the [GitLab blog](https:// | Software | Minimum version | Notes | |:------------------------|:----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Ruby](#2-ruby) | `3.0.x` | From GitLab 15.10, Ruby 3.0 is required. You must use the standard MRI implementation of Ruby. We love [JRuby](https://www.jruby.org/) and [Rubinius](https://github.com/rubinius/rubinius#the-rubinius-language-platform), but GitLab needs several Gems that have native extensions. | +| [Ruby](#2-ruby) | `3.1.x` | From GitLab 16.7, Ruby 3.1 is required. You must use the standard MRI implementation of Ruby. We love [JRuby](https://www.jruby.org/) and [Rubinius](https://github.com/rubinius/rubinius#the-rubinius-language-platform), but GitLab needs several Gems that have native extensions. | | [RubyGems](#3-rubygems) | `3.4.x` | A specific RubyGems version is not fully needed, but it's recommended to update so you can enjoy some known performance improvements. | | [Go](#4-go) | `1.20.x` | From GitLab 16.4, Go 1.20 or later is required. | | [Git](#git) | `2.42.x` | From GitLab 16.5, Git 2.42.x and later is required. You should use the [Git version provided by Gitaly](#git). | @@ -726,6 +726,9 @@ sudo -u git -H make ### Install Gitaly ```shell +# Create and restrict access to the git repository data directory +sudo install -d -o git -m 0700 /home/git/repositories + # Fetch Gitaly source with Git and compile with Go cd /home/git/gitlab sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production diff --git a/doc/install/migrate/compare_sm_to_saas.md b/doc/install/migrate/compare_sm_to_saas.md deleted file mode 100644 index b2fcbd5578e..00000000000 --- a/doc/install/migrate/compare_sm_to_saas.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../subscriptions/choosing_subscription.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../subscriptions/choosing_subscription.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/install/next_steps.md b/doc/install/next_steps.md index 4ad6a011cd6..8f5142dd5f5 100644 --- a/doc/install/next_steps.md +++ b/doc/install/next_steps.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Steps after installing GitLab **(FREE SELF)** @@ -21,7 +21,7 @@ installation. - [GitLab Pages](../administration/pages/index.md): Configure GitLab Pages to allow hosting of static sites. - [GitLab Registry](../administration/packages/container_registry.md): Set up the - GitLab Container Registry so every project can have its own space to store Docker + GitLab container registry so every project can have its own space to store Docker images. - [GitLab Dependency Proxy](../administration/packages/dependency_proxy.md): Set up the dependency proxy so you can cache container images from Docker Hub for faster, more reliable builds. diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index bb5a9b27cf5..2c42e3bea02 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OpenShift support diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md index 341a822f2bf..534757a71b8 100644 --- a/doc/install/postgresql_extensions.md +++ b/doc/install/postgresql_extensions.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing PostgreSQL extensions **(FREE SELF)** diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index 07e1f150521..93719fd69ed 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install GitLab under a relative URL **(FREE SELF)** diff --git a/doc/install/requirements.md b/doc/install/requirements.md index d20a5ecc561..fa6be957d99 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Installation system requirements **(FREE SELF)** diff --git a/doc/integration/advanced_search/elasticsearch.md b/doc/integration/advanced_search/elasticsearch.md index ef756be3ba4..0a456e6c73e 100644 --- a/doc/integration/advanced_search/elasticsearch.md +++ b/doc/integration/advanced_search/elasticsearch.md @@ -1,8 +1,7 @@ --- -type: reference stage: Data Stores group: Global Search -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Elasticsearch **(PREMIUM ALL)** @@ -162,15 +161,14 @@ These errors may occur when indexing Git repository data. ## Enable advanced search -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To enable advanced search: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Advanced Search**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. NOTE: To see the **Advanced Search** section, you need an active GitLab Premium @@ -212,9 +210,8 @@ You can only use the **Index all projects** setting to perform initial indexing, not to re-create an index from scratch. To enable advanced search with **Index all projects**: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Advanced Search**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. 1. Select the **Elasticsearch indexing** checkbox, then select **Save changes**. 1. Select **Index all projects**. 1. Optional. Select **Check progress** to see the status of background jobs. @@ -404,9 +401,8 @@ You can improve the language support for Chinese and Japanese languages by utili To enable languages support: 1. Install the desired plugins, refer to [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/plugins/7.9/installation.html) for plugins installation instructions. The plugins must be installed on every node in the cluster, and each node must be restarted after installation. For a list of plugins, see the table later in this section. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Advanced Search**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. 1. Locate **Custom analyzers: language support**. 1. Enable plugins support for **Indexing**. 1. Select **Save changes** for the changes to take effect. @@ -426,9 +422,8 @@ For guidance on what to install, see the following Elasticsearch language plugin To disable the Elasticsearch integration: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Advanced Search**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. 1. Clear the **Elasticsearch indexing** and **Search with Elasticsearch enabled** checkboxes. 1. Select **Save changes**. 1. Optional. For Elasticsearch instances that are still online, delete existing indices: @@ -443,9 +438,8 @@ To disable the Elasticsearch integration: ## Unpause Indexing -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Advanced Search**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. 1. Expand **Advanced Search**. 1. Clear the **Pause Elasticsearch indexing** checkbox. @@ -467,9 +461,8 @@ You can use zero-downtime reindexing to configure index settings or mappings tha To trigger the reindexing process: 1. Sign in to your GitLab instance as an administrator. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Advanced Search**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**. 1. Select **Trigger cluster reindexing**. @@ -483,9 +476,8 @@ While the reindexing is running, you can follow its progress under that same sec #### Elasticsearch zero-downtime reindexing -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Advanced Search**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. 1. Expand **Elasticsearch zero-downtime reindexing**, and you'll find the following options: @@ -532,9 +524,8 @@ Sometimes, you might want to abandon the unfinished reindex job and resume the i bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production ``` -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Advanced Search**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. 1. Expand **Advanced Search**. 1. Clear the **Pause Elasticsearch indexing** checkbox. @@ -603,7 +594,7 @@ This should return something similar to: { "_index": "gitlab-production-migrations", "_type": "_doc", - "_id": "20201105181100", + "_id": "20230209195404", "_score": 1, "_source": { "completed": true @@ -666,7 +657,7 @@ The following are some available Rake tasks: | [`sudo gitlab-rake gitlab:elastic:index_group_entities`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Invokes `gitlab:elastic:index_epics` and `gitlab:elastic:index_group_wikis`. | [`sudo gitlab-rake gitlab:elastic:index_epics`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Indexes all epics from the groups where Elasticsearch is enabled. | [`sudo gitlab-rake gitlab:elastic:index_group_wikis`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Indexes all wikis from the groups where Elasticsearch is enabled. -| [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | +| [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall indexing status of all project repository data (code, commits, and wikis). The status is calculated by dividing the number of indexed projects by the total number of projects and multiplying by 100. This task does not include non-repository data such as issues, merge requests, or milestones. | | [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. This command results in a complete wipe of the index, and it should be used with caution. | | [`sudo gitlab-rake gitlab:elastic:create_empty_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates empty indices (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn't already exist. | | [`sudo gitlab-rake gitlab:elastic:delete_index`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Removes the GitLab indices and aliases (if they exist) on the Elasticsearch instance. | diff --git a/doc/integration/advanced_search/elasticsearch_troubleshooting.md b/doc/integration/advanced_search/elasticsearch_troubleshooting.md index 1531e01577f..7252b9b1b3d 100644 --- a/doc/integration/advanced_search/elasticsearch_troubleshooting.md +++ b/doc/integration/advanced_search/elasticsearch_troubleshooting.md @@ -1,8 +1,7 @@ --- -type: reference stage: Data Stores group: Global Search -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Elasticsearch **(PREMIUM SELF)** @@ -224,10 +223,6 @@ See [Elasticsearch Index Scopes](elasticsearch.md#advanced-search-index-scopes) You must re-run all the Rake tasks to reindex the database, repositories, and wikis. -### The indexing process is taking a very long time - -The more data present in your GitLab instance, the longer the indexing process takes. - ### There are some projects that weren't indexed, but you don't know which ones You can run `sudo gitlab-rake gitlab:elastic:projects_not_indexed` to display projects that aren't indexed. @@ -366,9 +361,36 @@ dig further into these. Feel free to reach out to GitLab support, but this is likely to be something a skilled Elasticsearch administrator has more experience with. +### Slow initial indexing + +The more data your GitLab instance has, the longer the indexing takes. +You can estimate cluster size with the Rake task `sudo gitlab-rake gitlab:elastic:estimate_cluster_size`. + +#### For code documents + +Ensure you have enough Sidekiq nodes and processes to efficiently index code, commits, and wikis. +If your initial indexing is slow, consider [dedicated Sidekiq nodes or processes](../../integration/advanced_search/elasticsearch.md#index-large-instances-with-dedicated-sidekiq-nodes-or-processes). + +#### For non-code documents + +If the initial indexing is slow but Sidekiq has enough nodes and processes, +you can adjust advanced search worker settings in GitLab. +For **Requeue indexing workers**, the default value is `false`. +For **Number of shards for non-code indexing**, the default value is `2`. +These settings limit indexing to 2000 documents per minute. + +To adjust worker settings: + +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Advanced Search**. +1. Expand **Advanced Search**. +1. Select the **Requeue indexing workers** checkbox. +1. In the **Number of shards for non-code indexing** text box, enter a value higher than `2`. +1. Select **Save changes**. + ## Issues with migrations -Please ensure you've read about [Elasticsearch Migrations](../advanced_search/elasticsearch.md#advanced-search-migrations). +Ensure you've read about [Elasticsearch Migrations](../advanced_search/elasticsearch.md#advanced-search-migrations). If there is a halted migration and your [`elasticsearch.log`](../../administration/logs/index.md#elasticsearchlog) file contain errors, this could potentially be a bug/issue. Escalate to GitLab support if retrying migrations does not succeed. @@ -396,7 +418,7 @@ see details in the [update guide](../../update/upgrading_from_source.md). ## `Elasticsearch::Transport::Transport::Errors::BadRequest` -If you have this exception (just like in the case above but the actual message is different) please check if you have the correct Elasticsearch version and you met the other [requirements](elasticsearch.md#system-requirements). +If you have this exception (just like in the case above but the actual message is different), check that you have the correct Elasticsearch version and you met the other [requirements](elasticsearch.md#system-requirements). There is also an easy way to check it automatically with `sudo gitlab-rake gitlab:check` command. ## `Elasticsearch::Transport::Transport::Errors::RequestEntityTooLarge` @@ -420,7 +442,7 @@ Set a custom `gitlab_rails['env']` environment variable, called [`no_proxy`](htt WARNING: Setting the number of replicas to `0` is discouraged (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas needs to be set to an integer value larger than `0`. Failure to do so results in lack of redundancy (losing one node corrupts the index). -If you have a **hard requirement to have a green status for your single node Elasticsearch cluster**, please make sure you understand the risks outlined in the previous paragraph and then run the following query to set the number of replicas to `0`(the cluster no longer tries to create any shard replicas): +If you have a **hard requirement to have a green status for your single node Elasticsearch cluster**, make sure you understand the risks outlined in the previous paragraph and then run the following query to set the number of replicas to `0`(the cluster no longer tries to create any shard replicas): ```shell curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \ @@ -439,7 +461,7 @@ If you're getting a `health check timeout: no Elasticsearch node available` erro Gitlab::Elastic::Indexer::Error: time="2020-01-23T09:13:00Z" level=fatal msg="health check timeout: no Elasticsearch node available" ``` -You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). +You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). After you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](elasticsearch.md#gitlab-advanced-search-rake-tasks)) and [reindex the content of your instance](elasticsearch.md#enable-advanced-search). ## My Elasticsearch cluster has a plugin and the integration is not working @@ -529,3 +551,27 @@ migration has failed with NoMethodError:undefined method `<<' for nil:NilClass, ``` If `BackfillProjectPermissionsInBlobs` is the only halted migration, you can upgrade to the latest patch version of GitLab 16.0, which includes [the fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118494). Otherwise, you can ignore the error as it will not affect the current functionality of advanced search. + +## `ElasticIndexInitialBulkCronWorker` and `ElasticIndexBulkCronWorker` jobs stuck in deduplication + +In GitLab 16.5 and earlier, the `ElasticIndexInitialBulkCronWorker` and `ElasticIndexBulkCronWorker` jobs might get stuck in deduplication. This issue might prevent advanced search from properly indexing documents even after creating a new index. In GitLab 16.6, `idempotent!` was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135817) for bulk cron workers that perform indexing. + +The Sidekiq log might have the following entries: + +```shell +{"severity":"INFO","time":"2023-10-31T10:33:06.998Z","retry":0,"queue":"default","version":0,"queue_namespace":"cronjob","args":[],"class":"ElasticIndexInitialBulkCronWorker", +... +"idempotency_key":"resque:gitlab:duplicate:default:<value>","duplicate-of":"91e8673347d4dc84fbad5319","job_size_bytes":2,"pid":12047,"job_status":"deduplicated","message":"ElasticIndexInitialBulkCronWorker JID-5e1af9180d6e8f991fc773c6: deduplicated: until executing","deduplication.type":"until executing"} +``` + +To resolve this issue: + +1. In a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session), run this command: + + ```shell + idempotency_key = "<idempotency_key_from_log_entry>" + duplicate_key = "resque:gitlab:#{idempotency_key}:cookie:v2" + Gitlab::Redis::Queues.with { |c| c.del(duplicate_key) } + ``` + +1. Replace `<idempotency_key_from_log_entry>` with the actual entry in your log. diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index 94c25a0547b..b8b871d83f2 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Akismet **(FREE ALL)** @@ -30,9 +30,8 @@ To use Akismet: 1. Sign in or create a new account. 1. Select **Show** to reveal the API key, and copy the API key's value. 1. Sign in to GitLab as an administrator. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Reporting**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. Select the **Enable Akismet** checkbox. 1. Fill in the API key from step 3. diff --git a/doc/integration/alicloud.md b/doc/integration/alicloud.md index 660c64352d3..ff9ad50ed77 100644 --- a/doc/integration/alicloud.md +++ b/doc/integration/alicloud.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use AliCloud as an OmniAuth authentication provider **(FREE ALL)** diff --git a/doc/integration/arkose.md b/doc/integration/arkose.md index 99c2c521534..0183ec82355 100644 --- a/doc/integration/arkose.md +++ b/doc/integration/arkose.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Arkose Protect diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 4e90ade6620..7ac22d4ce7d 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Auth0 as an OAuth 2.0 authentication provider **(FREE SELF)** @@ -80,7 +80,7 @@ application. 1. Replace `<your_auth0_client_id>` with the client ID from the Auth0 Console page. 1. Replace `<your_auth0_client_secret>` with the client secret from the Auth0 Console page. -1. Replace `<your_auth0_client_secret>` with the domain from the Auth0 Console page. +1. Replace `<your_auth0_domain>` with the domain from the Auth0 Console page. 1. Reconfigure or restart GitLab, depending on your installation method: - If you installed using the Linux package, [reconfigure GitLab](../administration/restart_gitlab.md#reconfigure-a-linux-package-installation). diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 2bd415d91f6..906c50338aa 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Microsoft Azure as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index d4488242195..cd209157c42 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate your GitLab server with Bitbucket Cloud **(FREE SELF)** diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index 4d26235e65f..c5fe2bc5f0f 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Datadog **(FREE ALL)** @@ -27,9 +27,8 @@ project, group, or instance level: 1. *For project-level or group-level integrations:* In GitLab, go to your project or group. 1. *For instance-level integrations:* 1. Sign in to GitLab as a user with administrator access. - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Integrations**. + 1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Integrations**. 1. Scroll to **Add an integration**, and select **Datadog**. 1. Select **Active** to enable the integration. 1. Specify the [**Datadog site**](https://docs.datadoghq.com/getting_started/site/) to send data to. diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md index 2eb672f7054..9a1d0ac69b4 100644 --- a/doc/integration/ding_talk.md +++ b/doc/integration/ding_talk.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use DingTalk as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 49bd1e362e5..5b5ec99817f 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External issue trackers **(FREE ALL)** diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index a1bc4582d51..62b5e9d400b 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Facebook as an OAuth 2.0 authentication provider **(FREE ALL)** diff --git a/doc/integration/github.md b/doc/integration/github.md index 780e17a30f1..9a92f03d645 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitHub as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 5c4208bb5b1..81edc24f222 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate your server with GitLab.com **(FREE SELF)** diff --git a/doc/integration/gitpod.md b/doc/integration/gitpod.md index 288c2615d66..05ffaa98a42 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -1,8 +1,7 @@ --- -type: reference, how-to stage: Create group: IDE -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Gitpod **(FREE ALL)** @@ -45,8 +44,7 @@ With the Gitpod integration enabled for your GitLab instance, to enable it for y For self-managed GitLab instances, a GitLab administrator must: 1. Enable the Gitpod integration in GitLab: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Gitpod** configuration section. 1. Select the **Enable Gitpod integration** checkbox. diff --git a/doc/integration/glab/index.md b/doc/integration/glab/index.md deleted file mode 100644 index 29cec231d51..00000000000 --- a/doc/integration/glab/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../editor_extensions/gitlab_cli/index.md' -remove_date: '2023-10-31' ---- - -This document was moved to [another location](../../editor_extensions/gitlab_cli/index.md). - -<!-- This redirect file can be deleted after <2023-10-31>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 68db7d37b93..1099065fda1 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gmail actions **(FREE ALL)** diff --git a/doc/integration/google.md b/doc/integration/google.md index ba72e5d1af6..6d701786d9a 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Google OAuth 2.0 as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/integration/img/facebook_api_keys.png b/doc/integration/img/facebook_api_keys.png Binary files differindex fa16ff2c803..81ae1dac431 100644 --- a/doc/integration/img/facebook_api_keys.png +++ b/doc/integration/img/facebook_api_keys.png diff --git a/doc/integration/img/facebook_app_settings.png b/doc/integration/img/facebook_app_settings.png Binary files differindex b2ff3066051..2ddaace2846 100644 --- a/doc/integration/img/facebook_app_settings.png +++ b/doc/integration/img/facebook_app_settings.png diff --git a/doc/integration/index.md b/doc/integration/index.md index b6cf9013228..736f25f71d8 100644 --- a/doc/integration/index.md +++ b/doc/integration/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate with GitLab **(FREE ALL)** diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index b90ae3c3b79..542c75b5b8f 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jenkins **(FREE ALL)** @@ -18,6 +18,12 @@ You should use a Jenkins integration with GitLab when: - You're invested in [Jenkins plugins](https://plugins.jenkins.io/) and choose to keep using Jenkins to build your apps. +This integration can trigger a Jenkins build when a change is pushed to GitLab. + +You cannot use this integration to trigger GitLab CI/CD pipelines from Jenkins. Instead, +use the [pipeline triggers API endpoint](../api/pipeline_triggers.md) in a Jenkins job, +authenticated with a [pipeline trigger token](../ci/triggers/index.md#create-a-pipeline-trigger-token). + After you have configured a Jenkins integration, you trigger a build in Jenkins when you push code to your repository or create a merge request in GitLab. The Jenkins pipeline status displays on merge request widgets and the GitLab diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 1903cca0c63..fa6f94d116c 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira issue integration **(FREE ALL)** @@ -15,8 +15,11 @@ The Jira issue integration connects one or more GitLab projects to a Jira instan Prerequisites: - Your GitLab installation must not use a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configure-a-relative-url-for-gitlab). -- **For Jira Cloud**, you must have a [Jira Cloud API token](#create-a-jira-cloud-api-token) and - the email address you used to create the token. +- **For Jira Cloud**: + - You must have a [Jira Cloud API token](#create-a-jira-cloud-api-token) and the email address you used to create the token. + - If you've enabled + [IP allowlists](https://support.atlassian.com/security-and-access-policies/docs/specify-ip-addresses-for-product-access/), add the + [GitLab.com IP range](../../user/gitlab_com/index.md#ip-range) to the allowlist to [view Jira issues](issues.md#view-jira-issues) in GitLab. - **For Jira Data Center or Jira Server**, you must have one of the following: - [Jira username and password](jira_server_configuration.md). - Jira personal access token (GitLab 16.0 and later). @@ -55,23 +58,48 @@ To configure your project settings in GitLab: - To [transition Jira issues automatically](../../user/project/issues/managing_issues.md#closing-issues-automatically) in GitLab, select the **Enable Jira transitions** checkbox. 1. In the **Jira issue matching** section: - - For **Jira issue regex**, [enter a regex pattern](issues.md#use-regular-expression). - - For **Jira issue prefix**, [enter a prefix](issues.md#use-a-prefix). + - For **Jira issue regex**, [enter a regex pattern](issues.md#define-a-regex-pattern). + - For **Jira issue prefix**, [enter a prefix](issues.md#define-a-prefix). 1. In the **Issues** section: - - To [view Jira issues](issues.md#view-jira-issues) in a GitLab project, select the **Enable Jira issues** checkbox and + - To [view Jira issues](issues.md#view-jira-issues) in GitLab, select the **Enable Jira issues** checkbox and enter a Jira project key. You can only view issues from a single Jira project in a GitLab project. WARNING: When you enable this setting, all users with access to that GitLab project can view all issues from the Jira project you've specified. - - To [create Jira issues for vulnerabilities](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability), select the **Enable Jira issue creation from vulnerabilities** checkbox. + - To [create Jira issues for vulnerabilities](#create-a-jira-issue-for-a-vulnerability), select the **Enable Jira issue creation from vulnerabilities** checkbox. + + NOTE: + You can enable this setting at the project level only. + 1. Optional. Select **Test settings**. 1. Select **Save changes**. Your GitLab project can now interact with all Jira projects in your instance, and the project displays a Jira link that opens the Jira project. +## Create a Jira issue for a vulnerability **(ULTIMATE ALL)** + +Prerequisites: + +- Ensure the Jira issue integration is [configured](#configure-the-integration) and the + **Enable Jira issue creation from vulnerabilities** checkbox is selected. +- You must have a Jira user account with permission to create issues in the target project. + +You can create a Jira issue to track any action taken to resolve or mitigate a vulnerability. + +To create a Jira issue for a vulnerability: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Vulnerability report**. +1. Select the vulnerability's description. +1. Select **Create Jira issue**. + +A Jira issue is created in the project with information from the vulnerability report. + +To create a GitLab issue, see [Create a GitLab issue for a vulnerability](../../user/application_security/vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability). + ## Create a Jira Cloud API token To configure the Jira issue integration for Jira Cloud, you must have a Jira Cloud API token. diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 78cfc406d19..6f6a882031a 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab for Jira Cloud app **(FREE ALL)** @@ -14,6 +14,11 @@ With the [GitLab for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/ You can use the GitLab for Jira Cloud app to link top-level groups or subgroups. It's not possible to directly link projects or personal namespaces. To set up the GitLab for Jira Cloud app on GitLab.com, [install the GitLab for Jira Cloud app](#install-the-gitlab-for-jira-cloud-app). + +After you set up the app, you can use the [project toolchain](https://support.atlassian.com/jira-software-cloud/docs/what-is-the-project-toolchain-in-jira) +developed and maintained by Atlassian to [link GitLab repositories to Jira projects](https://support.atlassian.com/jira-software-cloud/docs/link-repositories-to-a-project/#Link-repositories-using-the-toolchain-feature). +The project toolchain does not affect how development information is synced between GitLab and Jira Cloud. + For Jira Data Center or Jira Server, use the [Jira DVCS connector](dvcs/index.md) developed and maintained by Atlassian. ## GitLab data synced to Jira @@ -97,7 +102,7 @@ and the access token is stored encrypted with `AES256-GCM` on GitLab. When configuring the GitLab for Jira Cloud app on GitLab.com, you might encounter the following issues. -For self-managed GitLab, see [GitLab for Jira Cloud app administration](../../administration/settings/jira_cloud_app.md#troubleshooting). +For self-managed GitLab, see [GitLab for Jira Cloud app administration](../../administration/settings/jira_cloud_app_troubleshooting.md). ### `Failed to link group` diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index 70e3534a32b..280e1ed3581 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira development panel **(FREE ALL)** diff --git a/doc/integration/jira/dvcs/index.md b/doc/integration/jira/dvcs/index.md index 8e624d81b54..97cb8474950 100644 --- a/doc/integration/jira/dvcs/index.md +++ b/doc/integration/jira/dvcs/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira DVCS connector **(FREE ALL)** diff --git a/doc/integration/jira/dvcs/troubleshooting.md b/doc/integration/jira/dvcs/troubleshooting.md index 570237779b4..ee697f1bffd 100644 --- a/doc/integration/jira/dvcs/troubleshooting.md +++ b/doc/integration/jira/dvcs/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Jira DVCS connector **(FREE ALL)** @@ -132,13 +132,13 @@ Failed to execute request [https://gitlab.com/api/v4/projects/:id/merge_requests {"message":"403 Forbidden"} ``` -If you find a `{"message":"403 Forbidden"}` error, it is possible that this specific project has some [GitLab features disabled](../../../user/project/settings/index.md#configure-project-features-and-permissions). +If you find a `{"message":"403 Forbidden"}` error, it is possible that this specific project has some [GitLab features disabled](../../../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions). In the example above, the merge requests feature is disabled. To resolve the issue, enable the relevant feature: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Use the toggles to enable the features as needed. @@ -147,7 +147,7 @@ To resolve the issue, enable the relevant feature: To find webhook logs in a DVCS-linked project: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > Webhooks**. +1. Select **Settings > Webhooks**. 1. Scroll down to **Project Hooks**. 1. Next to the log that points to your Jira instance, select **Edit**. 1. Scroll down to **Recent events**. diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index a723ae2a249..05350bd2ac8 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -1,23 +1,23 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira **(FREE ALL)** -If your organization uses [Jira](https://www.atlassian.com/software/jira), -you can [migrate your issues from Jira to GitLab](../../user/project/import/jira.md). +You can [import your Jira issues to GitLab](../../user/project/import/jira.md). If you want to continue to use Jira, you can integrate Jira with GitLab instead. ## Jira integrations -GitLab offers two types of Jira integrations. You can use one or both integrations -[depending on the capabilities you need](#jira-integration-capabilities). +GitLab offers two Jira integrations. You can use one or both integrations +[depending on the features you need](#feature-availability). ### Jira issue integration -You can use the [Jira issue integration](configure.md) developed by GitLab with Jira Cloud, Jira Data Center, or Jira Server. With this integration, you can: +You can use the [Jira issue integration](configure.md) developed by GitLab with +Jira Cloud, Jira Data Center, or Jira Server. With this integration, you can: - View and search Jira issues directly in GitLab. - Refer to Jira issues by ID in GitLab commits and merge requests. @@ -25,38 +25,40 @@ You can use the [Jira issue integration](configure.md) developed by GitLab with ### Jira development panel -You can use the [Jira development panel](development_panel.md) to [view GitLab activity for an issue](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) +You can use the [Jira development panel](development_panel.md) to +[view GitLab activity for an issue](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) including related branches, commits, and merge requests. To configure the Jira development panel: - **For Jira Cloud**, use the [GitLab for Jira Cloud app](connect-app.md) developed and maintained by GitLab. - **For Jira Data Center or Jira Server**, use the [Jira DVCS connector](dvcs/index.md) developed and maintained by Atlassian. -## Jira integration capabilities +## Feature availability -This table shows the capabilities available with the Jira issue integration and the Jira development panel: +This table shows the features available with the Jira issue integration and the Jira development panel: -| Capability | Jira issue integration | Jira development panel | +| Feature | Jira issue integration | Jira development panel | |-|-|-| -| Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created | **{check-circle}** Yes | **{dotted-circle}** No | -| Mention a Jira issue ID in GitLab, and the Jira issue shows the GitLab issue or merge request | **{check-circle}** Yes, a Jira comment with the GitLab issue or merge request title links to GitLab. The first mention is also added to the Jira issue under **Web links** | **{check-circle}** Yes, in the issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) | -| Mention a Jira issue ID in a GitLab commit message, and the Jira issue shows the commit message | **{check-circle}** Yes, the entire commit message is displayed in the Jira issue as a comment and under **Web links**. Each message links back to the commit in GitLab | **{check-circle}** Yes, in the issue's development panel and optionally with a custom comment on the Jira issue by using [Jira Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) | -| Mention a Jira issue ID in a GitLab branch name, and the Jira issue shows the branch name | **{dotted-circle}** No | **{check-circle}** Yes, in the issue's development panel | -| Add time tracking to a Jira issue | **{dotted-circle}** No | **{check-circle}** Yes, time can be specified by using Jira Smart Commits | -| Use a Git commit or merge request to transition or close a Jira issue |**{check-circle}** Yes, only a single transition type. Typically configured to close the issue by setting it to **Done** | **{check-circle}** Yes, transition to any state by using Jira Smart Commits | -| [View a list of Jira issues](issues.md#view-jira-issues) | **{check-circle}** Yes | **{dotted-circle}** No | -| [Create a Jira issue for a vulnerability](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability) | **{check-circle}** Yes | **{dotted-circle}** No | -| Create a GitLab branch from a Jira issue | **{dotted-circle}** No | **{check-circle}** Yes, in the issue's development panel | -| Sync GitLab deployments to Jira issues | **{dotted-circle}** No | **{check-circle}** Yes, in the issue's development panel. Mention a Jira issue ID in a GitLab merge request, branch name, or any of the last 5,000 commits made to the branch after the last successful deployment to the environment | +| Mention a Jira issue ID in a GitLab commit or merge request, and a link to the Jira issue is created. | **{check-circle}** Yes | **{dotted-circle}** No | +| Mention a Jira issue ID in GitLab, and the Jira issue shows the GitLab issue or merge request. | **{check-circle}** Yes, a Jira comment with the GitLab issue or merge request title links to GitLab. The first mention is also added to **Web links** in the Jira issue. | **{check-circle}** Yes, in the Jira issue's [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/). | +| Mention a Jira issue ID in a GitLab commit, and the Jira issue shows the commit message. | **{check-circle}** Yes, the entire commit message is displayed in the Jira issue as a comment and in **Web links**. Each message links back to the commit in GitLab. | **{check-circle}** Yes, in the Jira issue's development panel. A custom comment is possible with [Jira Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html). | +| Mention a Jira issue ID in a GitLab branch name, and the Jira issue shows the branch name. | **{dotted-circle}** No | **{check-circle}** Yes, in the Jira issue's development panel. | +| Add time tracking to a Jira issue. | **{dotted-circle}** No | **{check-circle}** Yes, with Jira Smart Commits. | +| Use a GitLab commit or merge request to transition a Jira issue. |**{check-circle}** Yes, only a single transition. Typically used to close the Jira issue. | **{check-circle}** Yes, transition the Jira issue to any state with Jira Smart Commits. | +| [View a list of Jira issues](issues.md#view-jira-issues). | **{check-circle}** Yes | **{dotted-circle}** No | +| [Create a Jira issue for a vulnerability](configure.md#create-a-jira-issue-for-a-vulnerability). | **{check-circle}** Yes | **{dotted-circle}** No | +| Create a GitLab branch from a Jira issue. | **{dotted-circle}** No | **{check-circle}** Yes, in the Jira issue's development panel. | +| Mention a Jira issue ID in a GitLab merge request, branch name, or any of the last 5,000 commits to the branch after the last successful deployment to the environment to sync a GitLab deployment to a Jira issue. | **{dotted-circle}** No | **{check-circle}** Yes, in the Jira issue's development panel. | ## Privacy considerations -All Jira integrations share data with Jira to make it visible outside of GitLab. -If you integrate a private GitLab project with Jira, the private data is -shared with users who have access to your Jira project. +All Jira integrations share data outside of GitLab. +If you integrate a private GitLab project with Jira, the private +data is shared with users who have access to your Jira project. -The [Jira issue integration](configure.md) posts GitLab data in the form of comments in Jira issues. -The GitLab for Jira Cloud app and Jira DVCS connector share this data through the [Jira development panel](development_panel.md). -This method provides more fine-grained access control because access can be restricted to certain user groups or roles. +The [Jira issue integration](configure.md) posts GitLab data as comments on Jira issues. +The [GitLab for Jira Cloud app](connect-app.md) and the [Jira DVCS connector](dvcs/index.md) +share GitLab data through the [Jira development panel](development_panel.md). +With the Jira development panel, you can restrict access to certain user groups or roles. ## Related topics diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index f6716f49ea5..9385ec63373 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira issue management **(FREE ALL)** @@ -67,12 +67,16 @@ Jira issue can't be merged. The merge request displays the message You can configure custom rules for how GitLab matches Jira issue keys by defining: -- [A regex pattern](#use-regular-expression) -- [A prefix](#use-a-prefix) +- [A regex pattern](#define-a-regex-pattern) +- [A prefix](#define-a-prefix) -When you don't configure custom rules, the [default behavior](https://gitlab.com/gitlab-org/gitlab/-/blob/710d83af298d8896f2b940faf48a46d2feb4cbaf/lib/gitlab/regex.rb#L552) is used. For more information, see the [RE2 wiki](https://github.com/google/re2/wiki/Syntax). +When you do not configure custom rules, the +[default behavior](https://gitlab.com/gitlab-org/gitlab/-/blob/9b062706ac6203f0fa897a9baf5c8e9be1876c74/lib/gitlab/regex.rb#L245) is used. -### Use regular expression +### Define a regex pattern + +You can use a regular expression (regex) to match Jira issue keys. +The regex pattern must follow the [RE2 syntax](https://github.com/google/re2/wiki/Syntax). To define a regex pattern for Jira issue keys: @@ -83,12 +87,14 @@ To define a regex pattern for Jira issue keys: 1. In the **Jira issue regex** text box, enter a regex pattern. 1. Select **Save changes**. -For more information, see the [Atlassian documentation](https://confluence.atlassian.com/adminjiraserver073/changing-the-project-key-format-861253229.html). +For more information, see the +[Atlassian documentation](https://confluence.atlassian.com/adminjiraserver073/changing-the-project-key-format-861253229.html). -### Use a prefix +### Define a prefix -You can define a prefix for GitLab to match Jira issue keys. For example, if your Jira issue ID is `ALPHA-1` -and you've set a `JIRA#` prefix, GitLab matches `JIRA#ALPHA-1` rather than `ALPHA-1`. +You can use a prefix to match Jira issue keys. +For example, if your Jira issue key is `ALPHA-1` and you define a `JIRA#` prefix, +GitLab matches `JIRA#ALPHA-1` rather than `ALPHA-1`. To define a prefix for Jira issue keys: @@ -140,7 +146,7 @@ provided your GitLab administrator [has configured the integration](configure.md To view Jira issues: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Plan > Jira issues**. +1. Select **Plan > Jira issues**. The issues are sorted by **Created date** by default, with the most recently created issues listed at the top. @@ -212,7 +218,3 @@ adding a comment to the Jira issue: 1. Refer to the [Configure GitLab](configure.md) instructions. 1. Clear the **Enable comments** checkbox. - -## Related topics - -- [Create a Jira issue for a vulnerability](../../user/application_security/vulnerabilities/index.md#create-a-jira-issue-for-a-vulnerability) diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 7788714b966..fab00d18fcc 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create Jira credentials **(FREE ALL)** @@ -15,7 +15,7 @@ To create Jira credentials, here's what we're going to do: 1. [Create a Jira group for the user](#create-a-jira-group-for-the-user). 1. [Create a permission scheme for the group](#create-a-permission-scheme-for-the-group). -Prerequisite: +Prerequisites: - You must have [site administrator](https://support.atlassian.com/user-management/docs/give-users-admin-permissions/#Make-someone-a-site-admin) access to the Jira instance. diff --git a/doc/integration/jira/troubleshooting.md b/doc/integration/jira/troubleshooting.md index cf637484b5f..6c8b49b4159 100644 --- a/doc/integration/jira/troubleshooting.md +++ b/doc/integration/jira/troubleshooting.md @@ -1,18 +1,14 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Troubleshooting Jira **(FREE ALL)** +# Troubleshooting Jira issue integration **(FREE ALL)** -This page contains a list of common issues you might encounter when working with Jira integrations. +This page contains a list of common issues you might encounter when working with the [Jira issue integration](configure.md). -## Jira issue integration - -When working with the [Jira issue integration](configure.md), you might encounter the following issues. - -### GitLab cannot link to a Jira issue +## GitLab cannot link to a Jira issue When you mention a Jira issue ID in GitLab, the issue link might be missing. [`sidekiq.log`](../../administration/logs/index.md#sidekiq-logs) might contain the following exception: @@ -23,7 +19,7 @@ No Link Issue Permission for issue 'JIRA-1234' To resolve this issue, ensure the Jira user you created for the [Jira issue integration](configure.md) has permission to link issues. -### GitLab cannot comment on a Jira issue +## GitLab cannot comment on a Jira issue If GitLab cannot comment on a Jira issue, ensure the Jira user you created for the [Jira issue integration](configure.md) has permission to: @@ -35,10 +31,13 @@ If you [restrict IP addresses for Jira access](https://support.atlassian.com/sec For the root cause, check the [`integrations_json.log`](../../administration/logs/index.md#integrations_jsonlog) file. When GitLab tries to comment on a Jira issue, an `Error sending message` log entry might appear. -In GitLab 16.1 and later, when an error occurs, the [`integrations_json.log`](../../administration/logs/index.md#integrations_jsonlog) file contains `client_*` keys in the outgoing API request to Jira. +In GitLab 16.1 and later, when an error occurs, the `integrations_json.log` file contains `client_*` keys in the outgoing API request to Jira. You can use the `client_*` keys to check the [Atlassian API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-group-issues) for why the error has occurred. -In the following example, Jira responds with a `404` because the Jira issue `ALPHA-1` does not exist: +In the following example, Jira responds with a `404 Not Found`. This error might happen if: + +- The Jira user you created for the Jira issue integration does not have permission to view the issue. +- The Jira issue ID you specified does not exist. ```json { @@ -53,7 +52,19 @@ In the following example, Jira responds with a `404` because the Jira issue `ALP } ``` -### GitLab cannot close a Jira issue +For more information about returned status codes, see the [Jira Cloud platform REST API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-get-response). + +### Using `curl` to verify access to a Jira issue + +To verify that a Jira user can access a specific Jira issue, run the following script: + +```shell +curl --verbose --user "$USER:$API_TOKEN" "https://$ATLASSIAN_SUBDOMAIN.atlassian.net/rest/api/2/issue/$JIRA_ISSUE" +``` + +If the user can access the issue, Jira responds with a `200 OK` and the returned JSON includes the Jira issue details. + +## GitLab cannot close a Jira issue If GitLab cannot close a Jira issue: @@ -64,28 +75,54 @@ If GitLab cannot close a Jira issue: - Check the Jira issue resolution field is not set. - Check the issue is not struck through in Jira lists. -### CAPTCHA after failed sign-in attempts +## CAPTCHA after failed sign-in attempts + +CAPTCHA might be triggered after consecutive failed sign-in attempts. +These failed attempts might lead to a `401 Unauthorized` when testing the Jira issue integration settings. +If CAPTCHA has been triggered, you cannot use the Jira REST API +to authenticate with the Jira site. + +To resolve this issue, sign in to your Jira instance and complete the CAPTCHA. + +## Integration does not work for an imported project -CAPTCHA might be triggered after several consecutive failed sign-in attempts, -which might lead to a `401 unauthorized` error when testing your Jira integration. -If CAPTCHA has been triggered, you can't use the Jira REST API to -authenticate with the Jira site. +The Jira issue integration might not work for a project that has been imported. +For more information, see [issue 341571](https://gitlab.com/gitlab-org/gitlab/-/issues/341571). -To fix this error, sign in to your Jira instance -and complete the CAPTCHA. +To resolve this issue, disable and then re-enable the integration. -### Integration does not work for an imported project +## `certificate verify failed` when testing the integration settings -There is a [known bug](https://gitlab.com/gitlab-org/gitlab/-/issues/341571) -where the Jira integration sometimes does not work for a project that has been imported. -As a workaround, disable the integration and then re-enable it. +When testing the Jira issue integration settings, you might get the following error: -### Change all Jira projects to instance-level or group-level values +```plaintext +Connection failed. Check your integration settings. SSL_connect returned=1 errno=0 peeraddr=<jira.example.com> state=error: certificate verify failed (unable to get local issuer certificate) +``` + +This error might also appear in the [`integrations_json.log`](../../administration/logs/index.md#integrations_jsonlog) file: + +```json +{ + "severity":"ERROR", + "integration_class":"Integrations::Jira", + "message":"Error sending message", + "exception.class":"OpenSSL::SSL::SSLError", + "exception.message":"SSL_connect returned=1 errno=0 peeraddr=x.x.x.x:443 state=error: certificate verify failed (unable to get local issuer certificate)", +} +``` + +The error occurs because the Jira certificate is not publicly trusted or the certificate chain is incomplete. +Until this issue is resolved, GitLab does not connect to Jira. + +To resolve this issue, see +[Common SSL errors](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html#common-ssl-errors). + +## Change all Jira projects to instance-level or group-level values WARNING: Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. -#### Change all projects instance wide +### Change all projects on the instance To change all Jira projects to use instance-level integration settings: @@ -116,7 +153,7 @@ To change all Jira projects to use instance-level integration settings: 1. Modify and save the instance-level integration from the UI to propagate the changes to all group-level and project-level integrations. -#### Change all projects in a group +### Change all projects in a group To change all Jira projects in a group (and its subgroups) to use group-level integration settings: @@ -126,7 +163,7 @@ To change all Jira projects in a group (and its subgroups) to use group-level in def reset_integration(target) integration = target.integrations.find_by(type: Integrations::Jira) - return if integration.nil? # Skip if the project has no Jira integration + return if integration.nil? # Skip if the project has no Jira issue integration return unless integration.inherit_from_id.nil? # Skip integrations that are already inheriting default_integration = Integration.default_integration(integration.type, target) @@ -152,7 +189,7 @@ To change all Jira projects in a group (and its subgroups) to use group-level in end ``` -### Update the Jira integration password for all projects +## Update the Jira issue integration password for all projects WARNING: Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. @@ -185,7 +222,7 @@ If that's the case, ensure the [**Due date** field is visible for issues](https: ### `An error occurred while requesting data from Jira` -When you try to view the Jira issue list in GitLab, you might see this message: +When you try to view the Jira issue list in GitLab, you might get this message: ```plaintext An error occurred while requesting data from Jira @@ -202,7 +239,7 @@ Your Jira project key must not have [restricted words and characters](https://co ### Jira credentials not allowed to access the data -When you try to view the Jira issue list in GitLab, you might see this message: +When you try to view the Jira issue list in GitLab, you might get this message: ```plaintext The credentials for accessing Jira are not allowed to access the data. Check your Jira integration credentials and try again. @@ -233,3 +270,5 @@ Both methods should return a JSON response: - `total` gives a count of the issues that match the Jira project key. - `issues` contains an array of the issues that match the Jira project key. + +For more information about returned status codes, see the [Jira Cloud platform REST API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-get-response). diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index a01d31421ec..b5515a730d3 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Use Kerberos as an OAuth 2.0 authentication provider **(FREE SELF)** @@ -106,9 +106,8 @@ set up GitLab to create a new account when a Kerberos user tries to sign in. If you're an administrator, you can link a Kerberos account to an existing GitLab account. To do so: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. 1. Select a user, then select the **Identities** tab. 1. From the **Provider** dropdown list, select **Kerberos**. 1. Make sure the **Identifier** corresponds to the Kerberos username. @@ -148,8 +147,7 @@ With that information at hand: ``` 1. As an administrator, you can confirm the new, blocked account: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Overview > Users** and review the **Blocked** tab. 1. You can enable the user. 1. If `block_auto_created_users` is false, the Kerberos user is diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index c8a58f0692f..689b9305dac 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Mattermost @@ -80,6 +80,27 @@ where `mattermost-nginx.crt` is the SSL certificate and `mattermost-nginx.key` i Once the configuration is set, run `sudo gitlab-ctl reconfigure` to apply the changes. +## Running GitLab Mattermost with an external PostgreSQL service + +By default, Mattermost uses the Linux package bundled PostgreSQL service. If you want to use Mattermost with an external PostgreSQL service, it requires its own specific configuration. An existing [external PostgreSQL connection configuration used by GitLab](../../administration/postgresql/external.md) is not automatically inherited for Mattermost. + +1. Edit `/etc/gitlab/gitlab.rb` and specify the following configuration: + + ```ruby + mattermost['sql_driver_name'] = 'postgres' + mattermost['sql_data_source'] = "user=gitlab_mattermost host=<hostname-of-postgresql-service> port=5432 sslmode=required dbname=<mattermost_production> password=<user-password>" + ``` + +1. Create a PostgreSQL user matching the `user` value, and `password` value that you have defined in `mattermost['sql_data_source']`. +1. Create a PostgreSQL database matching the `dbname` value that was used. +1. Ensure that the `user` has permissions to the database that was created with `dbname`. + +1. Reconfigure GitLab and restart Mattermost to apply the changes: + + ```shell + sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart mattermost + ``` + ## Running GitLab Mattermost on its own server If you want to run GitLab and GitLab Mattermost on two separate servers the GitLab services are still set up on your GitLab Mattermost server, but they do not accept user requests or @@ -338,6 +359,7 @@ Below is a list of Mattermost version changes for GitLab 14.0 and later: | GitLab version | Mattermost version | Notes | | :------------- | :----------------- | ---------------------------------------------------------------------------------------- | +| 16.7 | 9.3 | | | 16.6 | 9.1 | | | 16.5 | 9.0 | | | 16.4 | 8.1 | | diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 6bcecffaeda..5062d847dd1 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Generic OAuth2 gem as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index c4792d1dc28..30e14e95d3b 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure GitLab as an OAuth 2.0 authentication identity provider @@ -75,9 +75,8 @@ To create a new application for a group: To create an application for your GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Applications**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Applications**. 1. Select **New application**. When creating application in the **Admin Area** , mark it as **trusted**. @@ -99,7 +98,7 @@ different actions. See the following table for all available scopes. | Scope | Description | |--------------------| ----------- | -| `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | +| `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry. | | `read_user` | Grants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users. | | `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | | `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 15019c93902..ab43a14d169 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OmniAuth **(FREE SELF)** @@ -257,9 +257,8 @@ By default, sign-in is enabled for all the OAuth providers configured in `config To enable or disable an OmniAuth provider: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Sign-in restrictions**. 1. In the **Enabled OAuth authentication sources** section, select or clear the checkbox for each provider you want to enable or disable. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index 5fde49c511a..e638a4343b7 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab as OpenID Connect identity provider **(FREE ALL)** diff --git a/doc/integration/partner_marketplace.md b/doc/integration/partner_marketplace.md index 76988af99b2..36aef0a0a90 100644 --- a/doc/integration/partner_marketplace.md +++ b/doc/integration/partner_marketplace.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Provision -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Marketplace partners diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 1158ab8135f..bee6381a078 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # reCAPTCHA **(FREE SELF)** @@ -17,9 +17,8 @@ To use reCAPTCHA, first create a site and private key. 1. Go to the [Google reCAPTCHA page](https://www.google.com/recaptcha/admin). 1. To get reCAPTCHA v2 keys, fill in the form and select **Submit**. 1. Sign in to your GitLab server as an administrator. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Reporting**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Reporting**. 1. Expand **Spam and Anti-bot Protection**. 1. In the reCAPTCHA fields, enter the keys you obtained in the previous steps. 1. Select the **Enable reCAPTCHA** checkbox. diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 29bd6d1f9c3..8e95702196a 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Salesforce as an OAuth 2.0 authentication provider **(FREE SELF)** diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 0c07d203ab0..3423b1bde6d 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAML SSO for self-managed GitLab instances **(FREE SELF)** @@ -39,13 +38,15 @@ For more information on: gitlab_rails['omniauth_block_auto_created_users'] = false ``` -1. Optional. You can automatically link SAML users with existing GitLab users if their - email addresses match by adding the following setting in `/etc/gitlab/gitlab.rb`: +1. Optional. You should automatically link a first-time SAML sign-in with existing GitLab users if their + email addresses match. To do this, add the following setting in `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['omniauth_auto_link_saml_user'] = true ``` + Only the GitLab account's primary email address is matched against the email in the SAML response. + Alternatively, a user can manually link their SAML identity to an existing GitLab account by [enabling OmniAuth for an existing user](omniauth.md#enable-omniauth-for-an-existing-user). @@ -716,12 +717,17 @@ your provider's support. ### Configure assertions -| Field | Supported default keys | -|-----------------|------------------------| -| Email (required)| `email`, `mail` | -| Full Name | `name` | -| First Name | `first_name`, `firstname`, `firstName` | -| Last Name | `last_name`, `lastname`, `lastName` | +> Microsoft Azure/Entra ID attribute support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420766) in GitLab 16.7. + +NOTE: +The attributes are case-sensitive. + +| Field | Supported default keys | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Email (required)| `email`, `mail`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress` | +| Full Name | `name`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/name` | +| First Name | `first_name`, `firstname`, `firstName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/givenname` | +| Last Name | `last_name`, `lastname`, `lastName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/surname` | See [`attribute_statements`](#map-saml-response-attribute-names) for: diff --git a/doc/integration/security_partners/index.md b/doc/integration/security_partners/index.md deleted file mode 100644 index 49244d68ace..00000000000 --- a/doc/integration/security_partners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../index.md#security-improvements' -remove_date: '2023-10-05' ---- - -This document was moved to [another location](../index.md#security-improvements). - -<!-- This redirect file can be deleted after <2023-10-05>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md deleted file mode 100644 index e36ee164002..00000000000 --- a/doc/integration/slash_commands.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../user/project/integrations/gitlab_slack_application.md#slash-commands' -remove_date: '2023-09-19' ---- - -This document was moved to [another location](../user/project/integrations/gitlab_slack_application.md#slash-commands). - -<!-- This redirect file can be deleted after 2023-09-19. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 729dbade1d1..f6fb387f016 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, how-to +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Sourcegraph **(FREE ALL)** @@ -49,9 +48,8 @@ You can skip this step if you already have your GitLab repositories searchable i ### Configure your GitLab instance with Sourcegraph -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Sourcegraph** configuration section. 1. Check **Enable Sourcegraph**. 1. Set the Sourcegraph URL to your Sourcegraph instance, such as `https://sourcegraph.example.com`. diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index d855091b988..17b848987c9 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Trello Power-Ups **(FREE ALL)** diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 114c640569e..ce606c7d7de 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Twitter OAuth 1.0a OmniAuth Provider (deprecated) **(FREE SELF)** diff --git a/doc/integration/vault.md b/doc/integration/vault.md index 4a5dc578e99..54ade6c1066 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Vault as a GitLab OpenID Connect authentication provider **(FREE ALL)** diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md index d98c8e54964..6c2607d7f99 100644 --- a/doc/legal/corporate_contributor_license_agreement.md +++ b/doc/legal/corporate_contributor_license_agreement.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- vale off --> diff --git a/doc/legal/developer_certificate_of_origin.md b/doc/legal/developer_certificate_of_origin.md index eec89ce403e..3d649437ea9 100644 --- a/doc/legal/developer_certificate_of_origin.md +++ b/doc/legal/developer_certificate_of_origin.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- vale off --> diff --git a/doc/legal/index.md b/doc/legal/index.md index 17a17ba5509..3a800449188 100644 --- a/doc/legal/index.md +++ b/doc/legal/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Legal diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md index 5a6116befe0..e4b5706cf16 100644 --- a/doc/legal/individual_contributor_license_agreement.md +++ b/doc/legal/individual_contributor_license_agreement.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- vale off --> diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index 1ebbb047c01..a46998c11d8 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -1,14 +1,14 @@ --- -stage: Analyze +stage: Monitor group: Observability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Error Tracking **(FREE ALL)** Error Tracking allows developers to discover and view errors generated by their application. Because error information is surfaced where the code is developed, this increases efficiency and awareness. Users can choose between [GitLab Integrated error tracking](#integrated-error-tracking) and [Sentry based](#sentry-error-tracking) backends. -To leave feedback about Error Tracking bugs or functionality, please comment in the [feedback issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/2362) or open a [new issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/new). +To leave feedback about Error Tracking bugs or functionality, comment in the [feedback issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/2362) or open a [new issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/new). ## How error tracking works @@ -215,7 +215,7 @@ When working with Error Tracking, you might encounter the following issues. ### Error `Connection failed. Check auth token and try again` -If the Monitor feature is disabled in the [project settings](../user/project/settings/index.md#configure-project-features-and-permissions), +If the Monitor feature is disabled in the [project settings](../user/project/settings/project_features_permissions.md#configure-project-features-and-permissions), you might see an error when you try to [enable Sentry integration for a project](#enable-sentry-integration-for-a-project). The resulting request to `/project/path/-/error_tracking/projects.json?api_host=https:%2F%2Fsentry.example.com%2F&token=<token>` returns a 404 status. diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index fe21f0db1c7..a55c7b54346 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Feature flags **(FREE ALL)** @@ -431,7 +431,7 @@ The polling rate is configurable in SDKs. Provided that all clients are requesti For applications looking for more scalable solution, you should use [Unleash Proxy](#unleash-proxy-example). On GitLab.com, you should use Unleash Proxy to reduce the chance of being rate limited across endpoints. This proxy server sits between the server and clients. It makes requests to the server on behalf of the client groups, -so the number of outbound requests can be greatly reduced. +so the number of outbound requests can be greatly reduced. If you still get `429` responses, increase the `UNLEASH_FETCH_INTERVAL` value in the Unleash Proxy. There is also an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/295472) to give more capacity to the current rate limit. diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index f92739580bd..0e03b422f9b 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Alerts **(FREE ALL)** diff --git a/doc/operations/incident_management/escalation_policies.md b/doc/operations/incident_management/escalation_policies.md index 604e223cf55..a636ef1c665 100644 --- a/doc/operations/incident_management/escalation_policies.md +++ b/doc/operations/incident_management/escalation_policies.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Escalation Policies **(PREMIUM ALL)** @@ -15,7 +15,7 @@ where you manage [On-call schedules](oncall_schedules.md). ## Add an escalation policy -Prerequisite: +Prerequisites: - You must have at least the Maintainer role. - You must have an [on-call schedule](oncall_schedules.md). diff --git a/doc/operations/incident_management/incident_timeline_events.md b/doc/operations/incident_management/incident_timeline_events.md index f5322e0a7cc..baea158b234 100644 --- a/doc/operations/incident_management/incident_timeline_events.md +++ b/doc/operations/incident_management/incident_timeline_events.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Timeline events @@ -85,7 +85,7 @@ of an incident. ### When labels change **(EXPERIMENT)** -> [Introduced]([issue-link](https://gitlab.com/gitlab-org/gitlab/-/issues/365489)) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_timeline_events_from_labels`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365489) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_timeline_events_from_labels`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `incident_timeline_events_from_labels`. diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 43df69a3b39..601349a00b0 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incidents **(FREE ALL)** diff --git a/doc/operations/incident_management/index.md b/doc/operations/incident_management/index.md index 1cae066ce32..fa219b8202d 100644 --- a/doc/operations/incident_management/index.md +++ b/doc/operations/incident_management/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incident management **(FREE ALL)** diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md index 8691d78c4c9..516dba2fe1d 100644 --- a/doc/operations/incident_management/integrations.md +++ b/doc/operations/incident_management/integrations.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrations **(FREE ALL)** diff --git a/doc/operations/incident_management/linked_resources.md b/doc/operations/incident_management/linked_resources.md index 57fcb31e3ba..4b44ca018bd 100644 --- a/doc/operations/incident_management/linked_resources.md +++ b/doc/operations/incident_management/linked_resources.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked resources in incidents **(PREMIUM ALL)** diff --git a/doc/operations/incident_management/manage_incidents.md b/doc/operations/incident_management/manage_incidents.md index 1b48de9e478..4b86fb3fb4e 100644 --- a/doc/operations/incident_management/manage_incidents.md +++ b/doc/operations/incident_management/manage_incidents.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage incidents **(FREE ALL)** diff --git a/doc/operations/incident_management/oncall_schedules.md b/doc/operations/incident_management/oncall_schedules.md index 255cc79b3ce..fb001bd3bf5 100644 --- a/doc/operations/incident_management/oncall_schedules.md +++ b/doc/operations/incident_management/oncall_schedules.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # On-call Schedule Management **(PREMIUM ALL)** @@ -22,7 +22,7 @@ To use on-call schedules: Set up an on-call schedule for your team to add rotations to. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role. diff --git a/doc/operations/incident_management/paging.md b/doc/operations/incident_management/paging.md index 845c17d974a..550dbb57488 100644 --- a/doc/operations/incident_management/paging.md +++ b/doc/operations/incident_management/paging.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Paging and notifications **(FREE ALL)** diff --git a/doc/operations/incident_management/slack.md b/doc/operations/incident_management/slack.md index 100aaa0d9bc..709b7bd31e8 100644 --- a/doc/operations/incident_management/slack.md +++ b/doc/operations/incident_management/slack.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incident management for Slack **(FREE SAAS BETA)** diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index 1d376301250..ac65d76bc75 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Status Page **(ULTIMATE ALL)** @@ -39,7 +39,7 @@ To configure a GitLab Status Page you must: Only AWS S3 is supported as a deploy target. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role. diff --git a/doc/operations/index.md b/doc/operations/index.md index 766047e1f29..0ea5922d378 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitor application performance **(FREE ALL)** diff --git a/doc/operations/tracing.md b/doc/operations/tracing.md index 1df644f4de4..cb31fdd8025 100644 --- a/doc/operations/tracing.md +++ b/doc/operations/tracing.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Observability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Distributed tracing **(ULTIMATE SAAS EXPERIMENT)** @@ -16,7 +16,7 @@ The feature is not ready for production use. With distributed tracing, you can troubleshoot application performance issues by inspecting how a request moves through different services and systems, the timing of each operation, and any errors or logs as they occur. Tracing is particularly useful in the context of microservice applications, which group multiple independent services collaborating to fulfill user requests. -This feature is an [Experiment](../policy/experiment-beta-support.md). For more information, see the [group direction page](https://about.gitlab.com/direction/analytics/observability/). To leave feedback about tracing bugs or functionality, please comment in the [feedback issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/2363) or open a [new issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/new). +This feature is an [Experiment](../policy/experiment-beta-support.md). For more information, see the [group direction page](https://about.gitlab.com/direction/analytics/observability/). To leave feedback about tracing bugs or functionality, comment in the [feedback issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/2363) or open a [new issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/new). ## Configure distributed tracing for a project diff --git a/doc/policy/experiment-beta-support.md b/doc/policy/experiment-beta-support.md index 41ffaec3aa4..0c58380d304 100644 --- a/doc/policy/experiment-beta-support.md +++ b/doc/policy/experiment-beta-support.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Support for Experiment, Beta, and Generally Available features **(PREMIUM ALL)** @@ -31,7 +31,6 @@ Experimental features are: - UX not finalized, might be just quick action access. - Not announced in a release post. - Can be promoted in the user interface through [discovery moments](https://design.gitlab.com/usability/feature-management#discovery-moments), if needed. -- Feedback issue to engage with team. ## Beta diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index bb27fcb27e0..8e4541a58a7 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -1,8 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab release and maintenance policy diff --git a/doc/raketasks/backup_gitlab.md b/doc/raketasks/backup_gitlab.md deleted file mode 100644 index 231312b3833..00000000000 --- a/doc/raketasks/backup_gitlab.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -stage: Systems -group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -redirect_to: '../administration/backup_restore/backup_gitlab.md' -remove_date: '2023-09-26' ---- - -This document was moved to [another location](../administration/backup_restore/backup_gitlab.md). - -<!-- This redirect file can be deleted after <2023-09-26>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md deleted file mode 100644 index 97cafefb45d..00000000000 --- a/doc/raketasks/backup_restore.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -stage: Systems -group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -redirect_to: '../administration/backup_restore/index.md' -remove_date: '2023-09-26' ---- - -This document was moved to [another location](../administration/backup_restore/index.md). - -<!-- This redirect file can be deleted after <2023-09-26>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 5ffed097a51..0be68a35b3c 100644 --- a/doc/raketasks/cleanup.md +++ b/doc/raketasks/cleanup.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Clean up Rake tasks **(FREE SELF)** @@ -216,7 +216,7 @@ sudo gitlab-rake gitlab:cleanup:sessions:active_sessions_lookup_keys bundle exec rake gitlab:cleanup:sessions:active_sessions_lookup_keys RAILS_ENV=production ``` -## Container Registry garbage collection +## Container registry garbage collection Container Registry can use considerable amounts of disk space. To clear up unused layers, the registry includes a [garbage collect command](../administration/packages/container_registry.md#container-registry-garbage-collection). diff --git a/doc/raketasks/index.md b/doc/raketasks/index.md index 29b154774da..cff95b61d8c 100644 --- a/doc/raketasks/index.md +++ b/doc/raketasks/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rake tasks **(FREE SELF)** diff --git a/doc/raketasks/list_repos.md b/doc/raketasks/list_repos.md index b404e4dec60..671baa18f98 100644 --- a/doc/raketasks/list_repos.md +++ b/doc/raketasks/list_repos.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!--- start_remove The following content will be removed on remove_date: '2024-05-16' --> @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # List repository directories Rake task (deprecated) **(FREE SELF)** WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384361) in GitLab 16.4 and is planned for removal in 17.0. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384361) in GitLab 16.7 and is planned for removal in 17.0. [If migrating GitLab, use backup and restore](../administration/operations/moving_repositories.md#recommended-approach-in-all-cases) instead. diff --git a/doc/raketasks/migrate_snippets.md b/doc/raketasks/migrate_snippets.md deleted file mode 100644 index c845d9bed73..00000000000 --- a/doc/raketasks/migrate_snippets.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/raketasks/restore_gitlab.md b/doc/raketasks/restore_gitlab.md deleted file mode 100644 index 434e256de35..00000000000 --- a/doc/raketasks/restore_gitlab.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -stage: Systems -group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -redirect_to: '../administration/backup_restore/restore_gitlab.md' -remove_date: '2023-09-26' ---- - -This document was moved to [another location](../administration/backup_restore/restore_gitlab.md). - -<!-- This redirect file can be deleted after <2023-09-26>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/raketasks/spdx.md b/doc/raketasks/spdx.md index 423bd909982..ee02ef87342 100644 --- a/doc/raketasks/spdx.md +++ b/doc/raketasks/spdx.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SPDX license list import Rake task **(ULTIMATE SELF)** diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md index fa7d0813001..332d93ef207 100644 --- a/doc/raketasks/user_management.md +++ b/doc/raketasks/user_management.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User management Rake tasks **(FREE SELF)** diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index 3bd9d7e2d2e..c8576b2cffd 100644 --- a/doc/raketasks/web_hooks.md +++ b/doc/raketasks/web_hooks.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webhooks administration Rake tasks **(FREE SELF)** diff --git a/doc/raketasks/x509_signatures.md b/doc/raketasks/x509_signatures.md index ec85c400d49..6cdec4b5b36 100644 --- a/doc/raketasks/x509_signatures.md +++ b/doc/raketasks/x509_signatures.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # X.509 signatures Rake task **(FREE SELF)** diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md index 1354af15f7c..8d515b55a48 100644 --- a/doc/security/asset_proxy.md +++ b/doc/security/asset_proxy.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Proxying assets **(FREE SELF)** diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index 7cf46300bc2..8b538166a02 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How we manage the TLS protocol CRIME vulnerability **(FREE SELF)** diff --git a/doc/security/email_verification.md b/doc/security/email_verification.md index 67d8764a118..667ee85bb01 100644 --- a/doc/security/email_verification.md +++ b/doc/security/email_verification.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Account email verification **(FREE ALL)** diff --git a/doc/security/hardening.md b/doc/security/hardening.md index 45146fb0715..0310d2abbe0 100644 --- a/doc/security/hardening.md +++ b/doc/security/hardening.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Hardening Recommendations **(FREE SELF)** diff --git a/doc/security/hardening_application_recommendations.md b/doc/security/hardening_application_recommendations.md index 40e99495ea7..857e322191e 100644 --- a/doc/security/hardening_application_recommendations.md +++ b/doc/security/hardening_application_recommendations.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Hardening - Application Recommendations @@ -14,9 +13,8 @@ web interface. ## System hooks -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **System Hooks**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **System Hooks**. In a typical hardened environment, internal information is not transmitted or stored outside of the system. For an offline environment system, this is @@ -33,9 +31,8 @@ encouraged for communications through system hooks. ## Push rules -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Push Rules**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Push Rules**. Ensure that the following items are selected: @@ -48,9 +45,8 @@ The adjustments help limit pushes to established and authorized users. ## Deploy keys -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Deploy Keys**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Deploy Keys**. Public deploy keys at are used to give read or read/write access to **all** projects on the instance, and are intended for remote automation to access @@ -61,9 +57,8 @@ the documentation on [deploy keys](../user/project/deploy_keys/index.md) and ## General -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. Hardening adjustments can be made in 4 sections. @@ -168,7 +163,7 @@ checkbox next to **Two-factor authentication** (2FA) is selected. The default setting for **Two-factor grace period** is 48 hours. This should be adjusted to a much lower value, such as 8 hours. -Ensure the checkbox next to **Enable admin mode** is selected so that **Admin Mode** is +Ensure the checkbox next to **Enable Admin Mode** is selected so that **Admin Mode** is active. This requires users with Admin access to have to use additional authentication in order to perform administrative tasks, enforcing additional 2FA by the user. @@ -180,9 +175,8 @@ For more detailed information, see ## Integrations -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Integrations**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Integrations**. In general, as long as administrators control and monitor usage, integrations are fine in a hardened environment. Be cautious about integrations that allow @@ -192,9 +186,8 @@ process or authenticated user. ## Metrics and profiling -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Metrics and profiling**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Metrics and profiling**. The main focus for hardening is **Usage statistics**: @@ -210,9 +203,8 @@ help you make an informed decision, see ## Network -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Network**. For any setting that enables rate limiting, make sure it is selected. Default values should be fine. Additionally there are numerous settings that enable access, and all diff --git a/doc/security/hardening_cicd_recommendations.md b/doc/security/hardening_cicd_recommendations.md index 1f72803d7a7..4d0a85c362d 100644 --- a/doc/security/hardening_cicd_recommendations.md +++ b/doc/security/hardening_cicd_recommendations.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Hardening - CI/CD Recommendations diff --git a/doc/security/hardening_configuration_recommendations.md b/doc/security/hardening_configuration_recommendations.md index ed2e589d159..c4eae062ef7 100644 --- a/doc/security/hardening_configuration_recommendations.md +++ b/doc/security/hardening_configuration_recommendations.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Hardening - Configuration Recommendations @@ -149,13 +148,13 @@ If the GitLab instance is configured for sending out email notifications to user configure S/MIME signing to help the recipients ensure that the emails are legitimate. Follow the instructions on [signing outgoing email](../administration/smime_signing_email.md). -## Container Registry +## Container registry -If Lets Encrypt is configured, the Container Registry is enabled by default. This +If Lets Encrypt is configured, the container registry is enabled by default. This allows projects to store their own Docker images. Follow the instructions for -configuring the [Container Registry](../administration/packages/container_registry.md), +configuring the [container registry](../administration/packages/container_registry.md), so you can do things like restrict automatic enablement on new projects and -disabling the Container Registry entirely. You may have to adjust firewall rules to +disabling the container registry entirely. You may have to adjust firewall rules to allow access - if a completely standalone system, you should restrict access to the Container Registry to localhost only. Specific examples of ports used and their configuration are also included in the documentation. diff --git a/doc/security/hardening_general_concepts.md b/doc/security/hardening_general_concepts.md index 22154b59441..0ba8822dc5f 100644 --- a/doc/security/hardening_general_concepts.md +++ b/doc/security/hardening_general_concepts.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Hardening - General Concepts diff --git a/doc/security/hardening_operating_system_recommendations.md b/doc/security/hardening_operating_system_recommendations.md index cd228410bdd..8f5786ffb0b 100644 --- a/doc/security/hardening_operating_system_recommendations.md +++ b/doc/security/hardening_operating_system_recommendations.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Hardening - Operating System Recommendations diff --git a/doc/security/identity_verification.md b/doc/security/identity_verification.md index b6932d88820..443fa1d65a7 100644 --- a/doc/security/identity_verification.md +++ b/doc/security/identity_verification.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Identity verification **(FREE ALL)** @@ -42,4 +42,4 @@ You cannot verify an account with a credit card number associated with a banned ## Related topics - [Identity verification development documentation](../development/identity_verification.md) -- [Changing risk assessment support](https://about.gitlab.com/handbook/support/workflows/reinstating-blocked-accounts.html#change-risk-assessment-credit-card-verification) +- [Changing risk assessment support](https://handbook.gitlab.com/handbook/support/workflows/reinstating-blocked-accounts/#change-risk-assessment-credit-card-verification) diff --git a/doc/security/index.md b/doc/security/index.md index 6a4d2e35ee6..8fd55fd08ff 100644 --- a/doc/security/index.md +++ b/doc/security/index.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure your installation **(FREE ALL)** @@ -24,6 +23,7 @@ type: index - [Proxying images](asset_proxy.md) - [CI/CD variables](../ci/variables/index.md#cicd-variable-security) - [Token overview](token_overview.md) +- [Rotate secrets of third-party integrations](rotate_integrations_secrets.md) - [Maximum decompressed file size for imported archives](../administration/settings/import_and_export_settings.md#maximum-decompressed-file-size-for-imported-archives) - [Responding to security incidents](responding_to_security_incidents.md) diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 9422cb73dce..be7c6104876 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Information exclusivity **(FREE ALL)** diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index 9503ad4098a..177d5564e7d 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom password length limits **(FREE SELF)** @@ -24,9 +23,8 @@ The user password length is set to a minimum of 8 characters by default. To change the minimum password length using GitLab UI: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Enter a **Minimum password length** value greater than or equal to `8`. 1. Select **Save changes**. diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md index 807c59fedf4..9a9f5bbcd92 100644 --- a/doc/security/password_storage.md +++ b/doc/security/password_storage.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Password and OAuth token storage **(FREE ALL)** diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md index b8bb7289e82..c3944b83c69 100644 --- a/doc/security/passwords_for_integrated_authentication_methods.md +++ b/doc/security/passwords_for_integrated_authentication_methods.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Generated passwords for users created through integrated authentication **(FREE ALL)** diff --git a/doc/security/project_import_decompressed_archive_size_limits.md b/doc/security/project_import_decompressed_archive_size_limits.md deleted file mode 100644 index a4749d0e5f9..00000000000 --- a/doc/security/project_import_decompressed_archive_size_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../administration/settings/import_and_export_settings.md#maximum-decompressed-file-size-for-imported-archives' -remove_date: '2023-11-02' ---- - -This document was moved to [another location](../administration/settings/import_and_export_settings.md#maximum-decompressed-file-size-for-imported-archives). - -<!-- This redirect file can be deleted after <2023-11-02>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index 2f916ec34b5..d9485ca1266 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits **(FREE SELF)** diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index 9835509897e..ffee1208f2a 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reset a user's password **(FREE SELF)** @@ -20,9 +19,8 @@ The user's new password must meet all [password requirements](../user/profile/us To reset a user's password in the UI: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. 1. For the user whose password you want to update, select **Edit**. 1. In the **Password** area, type a password and password confirmation. 1. Select **Save changes**. diff --git a/doc/security/responding_to_security_incidents.md b/doc/security/responding_to_security_incidents.md index 353a1289481..24a9aaa597a 100644 --- a/doc/security/responding_to_security_incidents.md +++ b/doc/security/responding_to_security_incidents.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Responding to security incidents **(FREE SELF)** @@ -10,6 +9,10 @@ type: reference, howto When a security incident occurs, you should follow the processes defined by your organization. However, you might consider some additional steps. These suggestions are intended to supplement existing security incident response processes within your organization. +Administrators can choose to +[provide public security contact information](../administration/settings/security_contact_information.md) +to support receiving reports of security issues from security researchers. + ## Suspected compromised user account If you suspect that a user account or bot account has been compromised, consider taking the following steps: @@ -48,7 +51,7 @@ If you suspect that your GitLab instance has been compromised, consider taking t - Review the [Credentials Inventory](../administration/credentials_inventory.md), if available to you. - Change any sensitive credentials, variables, tokens, and secrets. For example, those located in instance configuration, database, CI/CD pipelines, or elsewhere. -- Upgrade to the latest version of GitLab and adopt a plan to upgrade after every security patch release. +- Update to the latest version of GitLab and adopt a plan to update after every security patch release. In addition, the suggestions below are common steps taken in incident response plans when servers are compromised by malicious actors. diff --git a/doc/security/rotate_integrations_secrets.md b/doc/security/rotate_integrations_secrets.md new file mode 100644 index 00000000000..a3370d7287a --- /dev/null +++ b/doc/security/rotate_integrations_secrets.md @@ -0,0 +1,17 @@ +--- +stage: Govern +group: Authentication +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Rotate secrets of third-party integrations **(FREE SELF)** + +Rotating secrets of third-party integrations is an important security practice +that helps mitigate the risks associated with leaked secrets, such as +unauthorized access and potential data breaches. + +You should rotate the secrets of all third-party integrations at least yearly. +An incomplete list of such secrets: + +- [FortiAuthenticator](../user/profile/account/two_factor_authentication.md#enable-one-time-password-using-fortiauthenticator) +- [FortiToken Cloud](../user/profile/account/two_factor_authentication.md#enable-one-time-password-using-fortitoken-cloud) diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 3d520d24929..465389eb1ca 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Restrict allowed SSH key technologies and minimum length **(FREE SELF)** @@ -20,10 +19,9 @@ limit the allowed SSH key algorithms. GitLab allows you to restrict the allowed SSH key technology as well as specify the minimum key length for each technology: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General** . -1. Expand the **Visibility and access controls** section: +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General** . +1. Expand **Visibility and access controls**:  diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index 82e16694470..4555459e7c5 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Token overview **(FREE ALL)** @@ -235,7 +234,7 @@ The following tables show the prefixes for each type of token where applicable. | Impersonation token | Not applicable. | | Project access token | Not applicable. | | Group access token | Not applicable. | -| Deploy token | Not applicable. | +| Deploy token | `gldt-` ([Added in GitLab 16.7](https://gitlab.com/gitlab-org/gitlab/-/issues/376752)) | | Deploy key | Not applicable. | | Runner registration token | Not applicable. | | Runner authentication token | `glrt-` | diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 41844256510..c7d6796a212 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -1,8 +1,7 @@ --- -type: howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Enforce two-factor authentication **(FREE ALL)** @@ -34,10 +33,9 @@ You can use the UI or the API to enforce 2FA for all users. ### Use the UI -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Sign-in restrictions** section: +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. +1. Expand **Sign-in restrictions**: - Select **Enforce two-factor authentication** to enable this feature. - In **Two-factor grace period**, enter a number of hours. If you want to enforce 2FA on next sign-in attempt, enter `0`. diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index 8184bdfdd8c..179fd5eae3e 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Locked users **(FREE SELF)** @@ -38,9 +37,8 @@ If 2FA is enabled, users are locked after three failed sign-in attempts. Account ## Unlock a user from the Admin Area -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. 1. Use the search bar to find the locked user. 1. From the **User administration** dropdown list, select **Unlock**. diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 0d061411b35..1863c6e21ba 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -1,8 +1,7 @@ --- -type: howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Make new users confirm email **(FREE SELF)** @@ -11,9 +10,8 @@ GitLab can be configured to require confirmation of a user's email address when the user signs up. When this setting is enabled, the user is unable to sign in until they confirm their email address. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Sign-up restrictions** and look for the **Email confirmation settings** options. ## Confirmation token expiry diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index 91a21454fe5..e73bdf4ced2 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User file uploads **(FREE ALL)** @@ -40,7 +39,7 @@ Only authenticated project members can view non-image attachments (including PDF To apply authentication requirements to image files in private or internal projects: -Prerequisite: +Prerequisites: - You must have the Maintainer or Owner role for the project. - Your project visibility settings must be **Private** or **Internal**. @@ -61,7 +60,7 @@ You cannot select this option for public projects. You should delete an uploaded file when that file contains sensitive or confidential information. When you have deleted that file, users cannot access the file and the direct URL returns a 404 error. -Project Owners and Maintainers can use the [interactive GraphiQL explorer](../api/graphql/index.md#graphiql) to access a [GraphQL endpoint](../api/graphql/reference/index.md#mutationuploaddelete) and delete an uploaded file. +Project Owners and Maintainers can use the [interactive GraphQL explorer](../api/graphql/index.md#interactive-graphql-explorer) to access a [GraphQL endpoint](../api/graphql/reference/index.md#mutationuploaddelete) and delete an uploaded file. For example: diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index d2c3e2174c1..3f16f0f6a65 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Filtering outbound requests **(FREE SELF)** @@ -38,7 +37,7 @@ can get the GitLab server to make `POST` HTTP requests to endpoints that delete ### Allow requests to the local network from webhooks and integrations -Prerequisite: +Prerequisites: - You must have administrator access to the instance. @@ -50,23 +49,21 @@ To prevent exploitation of insecure internal web services, all webhook and integ To allow access to these addresses: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Outbound requests**. 1. Select the **Allow requests to the local network from webhooks and integrations** checkbox. ### Prevent requests to the local network from system hooks -Prerequisite: +Prerequisites: - You must have administrator access to the instance. [System hooks](../administration/system_hooks.md) can make requests to the local network by default. To prevent system hook requests to the local network: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Outbound requests**. 1. Clear the **Allow requests to the local network from system hooks** checkbox. @@ -74,15 +71,14 @@ Prerequisite: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377371) in GitLab 15.10. -Prerequisite: +Prerequisites: - You must have administrator access to the GitLab instance. To filter requests by blocking many requests: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Outbound requests**. 1. Select the **Block all requests, except for IP addresses, IP ranges, and domain names defined in the allowlist** checkbox. @@ -100,15 +96,14 @@ rules. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44496) in GitLab 12.2. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To allow outbound requests to certain IP addresses and domains: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > Network**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Network**. 1. Expand **Outbound requests**. 1. In **Local IP addresses and domain names that hooks and integrations can access**, enter your IP addresses and domains. diff --git a/doc/solutions/cloud/aws/gitlab_aws_integration.md b/doc/solutions/cloud/aws/gitlab_aws_integration.md index ba0b9717562..11add88f7c0 100644 --- a/doc/solutions/cloud/aws/gitlab_aws_integration.md +++ b/doc/solutions/cloud/aws/gitlab_aws_integration.md @@ -11,6 +11,8 @@ Learn how to integrate GitLab and AWS. This content is intended for GitLab team members as well as members of the wider community. +When content that is badged for GitLab SaaS ( **(SAAS)** ) or Self-Managed ( **(SELF)** ) it means that the link applies to only that type of GitLab instance implementation. Unbadged content works for any type of GitLab implementation. + This page attempts to index the ways in which GitLab can integrate with AWS. It does so whether the integration is the result of configuring general functionality, was built in to AWS or GitLab or is provided as a solution. | Text Tag | Configuration / Built / Solution | Support/Maintenance | @@ -21,83 +23,113 @@ This page attempts to index the ways in which GitLab can integrate with AWS. It | `[GitLab Built]` | Built into GitLab by Product Team to Address AWS Integration | GitLab | | `[AWS Solution]` | Built as Solution Example by AWS or AWS Partners | Community/Example | | `[GitLab Solution]` | Built as Solution Example by GitLab or GitLab Partners | Community/Example | -| `[CI Solution]` | Built, at least in part, using GitLab CI and therefore <br />more customer customizable. | Items tagged `[CI Solution will]` <br />also carry one of the other tags <br />that indicates the maintenance status. | +| `[CI Solution]` | Built, at least in part, using GitLab CI and therefore <br />more customer customizable. | Items tagged `[CI Solution]` will <br />also carry one of the other tags <br />that indicate the maintenance status. | + +## Table of Contents + +[TOC] ## Integrations For Development Activities +These integrations have to do with using GitLab to build application workloads and deploy them to AWS. + ### SCM Integrations - **AWS CodeStar Connections** - enables SCM connections to multiple AWS Services. **Currently for GitLab.com SaaS only**. [Configure GitLab](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-gitlab.html). [Supported Providers](https://docs.aws.amazon.com/dtconsole/latest/userguide/supported-versions-connections.html). [Supported AWS Services](https://docs.aws.amazon.com/dtconsole/latest/userguide/integrations-connections.html) - each one may have to make updates to support GitLab, so here is the subset that currently support GitLab `[AWS Built]` - [AWS CodePipeline Integration](https://docs.aws.amazon.com/codepipeline/latest/userguide/connections-gitlab.html) - use GitLab as source for CodePipeline. `[AWS Built]` - - **AWS CodeBuild Integration** - indirectly through CodePipeline support. `[AWS Built]` + - **AWS CodeBuild Integration** - indirectly through CodePipeline support. `[AWS Built]` - **Amazon CodeWhisperer Customization Capability** [can connect to a GitLab repo](https://aws.amazon.com/blogs/aws/new-customization-capability-in-amazon-codewhisperer-generates-even-better-suggestions-preview/). `[AWS Built]` - **AWS Service Catalog** directly inherits CodeStar Connections, there is not any specific documentation about GitLab since it just uses any GitLab CodeStar Connection that has been created in the account. `[AWS Built]` - **AWS Proton** directly inherits CodeStar Connections, there is not any specific documentation about GitLab since it just uses any GitLab CodeStar Connection that has been created in the account. `[AWS Built]` - **AWS Glue Notebook Jobs** directly inherit CodeStar Connections, there is not any specific documentation about GitLab since it just uses any GitLab CodeStar Connection that has been created in the account. `[AWS Built]` - - **Amazon SageMaker MLOps Projects** are done in CodePipeline and so directly inherit CodeStar Connections ([as noted here](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-projects-walkthrough-3rdgit.html#sagemaker-proejcts-walkthrough-connect-3rdgit)), there is not any specific documentation about GitLab since it just uses any GitLab CodeStar Connection that has been created in the account. `[AWS Built]` + - **Amazon SageMaker MLOps Projects** are done in CodePipeline and so directly inherit CodeStar Connections ([as noted here](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-projects-walkthrough-3rdgit.html#sagemaker-proejcts-walkthrough-connect-3rdgit)), there is not any specific documentation about GitLab since it just uses any GitLab CodeStar Connection that has been created in the account. `[AWS Built]` - **Amazon SageMaker Notebooks** [allow Git repositories to be specified by the Git clone URL](https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-git-resource.html) and configuration of a secret - so GitLab is configurable. `[AWS Configuration]` - - **AWS CloudFormation** publishing of public extensions - **not yet supported**. `[AWS Built]` - - **Amazon CodeGuru Reviewer Repositories** - **not yet supported**. `[AWS Built]` + - **AWS CloudFormation** publishing of public extensions - **not yet supported**. `[AWS Built]` + - **Amazon CodeGuru Reviewer Repositories** - **not yet supported**. `[AWS Built]` - [GitLab Push Mirroring to CodeCommit](../../../user/project/repository/mirror/push.md#set-up-a-push-mirror-from-gitlab-to-aws-codecommit) Workaround enables GitLab repositories to leverage CodePipeline SCM Triggers. GitLab can already leverage S3 and Container Triggers for CodePipeline. **Still required for Self-Managed and Dedicated for the time being.** `[GitLab Configuration]` ### CI Integrations - **Direct CI Integrations That Use Keys, IAM or OIDC/JWT to Authenticate to AWS Services from GitLab Runners** - - **Amazon CodeGuru Reviewer CI workflows using GitLab CI** - can be done, not yet documented. `[AWS Solution]` `[CI Solution]` - - [Amazon CodeGuru Secure Scanning using GitLab CI](https://docs.aws.amazon.com/codeguru/latest/security-ug/get-started-gitlab.html) `[AWS Solution]` `[CI Solution]` + - **Amazon CodeGuru Reviewer CI workflows using GitLab CI** - can be done, not yet documented. `[AWS Solution]` `[CI Solution]` + - [Amazon CodeGuru Secure Scanning using GitLab CI](https://docs.aws.amazon.com/codeguru/latest/security-ug/get-started-gitlab.html) `[AWS Solution]` `[CI Solution]` ### CD and Operations Integrations -- **AWS CodeDeploy Integration** - indirectly through CodePipeline support. `[AWS Built]` +- **AWS CodeDeploy Integration** - indirectly through CodePipeline support. `[AWS Built]` - [Integrate EKS clusters for application deployment](../../../user/infrastructure/clusters/connect/new_eks_cluster.md). `[GitLab Built]` -## Solutions For Specific Development Frameworks and Ecosystems +## End-to-End Solutions for development and deployment if specific development frameworks and ecosystems Generally solutions demonstrate end-to-end capabilities for the development framework - leveraging all relevant integration techniques to show the art of maximum value for using GitLab and AWS together. -### Serverless Development +### Serverless -- [Serverless Framework Deployment to AWS with GitLab Serverless SAST Scanning and Managed DevOps Environments](https://gitlab.com/guided-explorations/aws/serverless/serverless-framework-aws) - working example code and tutorials. `[GitLab Solution]` `[CI Solution]` +- [Serverless Framework Deployment to AWS with GitLab Serverless SAST Scanning and Lifecycle Managed DevOps Environments](https://gitlab.com/guided-explorations/aws/serverless/serverless-framework-aws) - working example code and tutorials. `[GitLab Solution]` `[CI Solution]` - [Tutorial: Serverless Framework Deployment to AWS with GitLab Serverless SAST Scanning](https://gitlab.com/guided-explorations/aws/serverless/serverless-framework-aws/-/blob/master/TUTORIAL.md) `[GitLab Solution]` `[CI Solution]` - [Tutorial: Secure Serverless Framework Development with GitLab Security Policy Approval Rules and Managed DevOps Environments](https://gitlab.com/guided-explorations/aws/serverless/serverless-framework-aws/-/blob/master/TUTORIAL2-SecurityAndManagedEnvs.md) `[GitLab Solution]` `[CI Solution]` -### Infrastructure as Code +### Terraform -- [Terraform Deployment to AWS with GitLab MR Managed DevOps Environments](https://gitlab.com/guided-explorations/aws/terraform/terraform-web-server-cluster) +- [Terraform Deployment to AWS with GitLab Lifecycle Managed DevOps Environments](https://gitlab.com/guided-explorations/aws/terraform/terraform-web-server-cluster) - [Tutorial: Terraform Deployment to AWS with GitLab IaC SAST Scanning](https://gitlab.com/guided-explorations/aws/terraform/terraform-web-server-cluster/-/blob/prod/TUTORIAL.md) `[GitLab Solution]` `[CI Solution]` - [Terraform Deployment to AWS with GitLab Security Policy Approval Rules and Managed DevOps Environments](https://gitlab.com/guided-explorations/aws/terraform/terraform-web-server-cluster/-/blob/prod/TUTORIAL2-SecurityAndManagedEnvs.md) `[GitLab Solution]` `[CI Solution]` -- [Tutorial: CloudFormation Deployment With GitLab MR Managed DevOps Environments](https://gitlab.com/guided-explorations/aws/cloudformation-deploy) `[GitLab Solution]` `[CI Solution]` -### .Net on AWS +#### CloudFormation + +[CloudFormation Development and Deployment With GitLab Lifecycle Managed DevOps Environments Working Code](https://gitlab.com/guided-explorations/aws/cloudformation-deploy) `[GitLab Solution]` `[CI Solution]` + +### CDK + +- [Building Cross-Account Deployment in GitLab Pipelines Using AWS CDK](https://aws.amazon.com/blogs/apn/building-cross-account-deployment-in-gitlab-pipelines-using-aws-cdk/) `[AWS Solution]` `[CI Solution]` + +### .NET on AWS - [Working Example Code for Scaling .NET Framework 4.x Runners on AWS](https://gitlab.com/guided-explorations/aws/dotnet-aws-toolkit) `[GitLab Solution]` `[CI Solution]` -- [Video Walkthrough of Code and Building a .NET Framework 4.x Project](https://www.youtube.com/watch?v=_4r79ZLmDuo) `[GitLab Solution]` `[CI Solution]` +- [Video Walkthrough of Code and Building a .NET Framework 4.x Project](https://www.youtube.com/watch?v=_4r79ZLmDuo) `[GitLab Solution]` `[CI Solution]` -## Authentication Integration +## System to system integration of GitLab and AWS + +AWS Identity providers (IDP) can be configured to authenticate into GitLab or GitLab can function as an IDP into AWS accounts. + +Top level groups on GitLab.com are also known as "Namespaces" and naming one after your company is the first step to setting up a tenant for your organization on GitLab.com. Namespaces can be configured for special functionality like SSO which then integrates your IDP into GitLab. + +### User authentication and authorization between GitLab and AWS + +- [SAML SSO for GitLab.com groups](../../../user/group/saml_sso/index.md) `[GitLab Configuration]` **(SAAS)** +- [Integrate LDAP with GitLab](../../../administration/auth/ldap/index.md) `[GitLab Configuration]` **(SELF)** + +### Runner workload authentication and authorization integration - [Runner Job Authentication using Open ID & JWT Authentication](../../../ci/cloud_services/aws/index.md). `[GitLab Built]` - [Configure OpenID Connect between GitLab and AWS](https://gitlab.com/guided-explorations/aws/configure-openid-connect-in-aws) `[GitLab Solution]` `[CI Solution]` - [OIDC and Multi-Account Deployment with GitLab and ECS](https://gitlab.com/guided-explorations/aws/oidc-and-multi-account-deployment-with-ecs) `[GitLab Solution]` `[CI Solution]` -## GitLab Instance Compute & Operations Integration +## GitLab infrastructure workloads deployed on AWS + +While GitLab can be deployed on a single box for up to 500 users, when it is horizontally scaled for very large user counts like 50,000 it expands into being a complex, many tiered platform that benefits from deployment to AWS. GitLab is supports and is regularly tested being backed by AWS services. GitLab is deployable to Ec2 for traditional scaling and to AWS EKS in a Cloud Native Hybrid implementation. It is called Hybrid because specific service layers cannot be placed in a container cluster due to the workload shapes that are common to Git (and common to how Git processes behave handles that workload variety). + +### GitLab Instance Compute & Operations Integration - Installing GitLab Self-Managed on AWS + - [AWS Services that can be used when deploying GitLab](gitlab_instance_on_aws.md) - GitLab Single EC2 Instance. `[GitLab Built]` - [Using 5 Seat AWS marketplace subscription](gitlab_single_box_on_aws.md#marketplace-subscription) - [Using Prepared AMIs](gitlab_single_box_on_aws.md#official-gitlab-releases-as-amis) - Bring Your Own License for Enterprise Edition. - GitLab Cloud Native Hybrid Scaled on AWS EKS and Paas. `[GitLab Built]` - - Using GitLab Environment Toolkit (GET) - `[GitLab Solution]` + - [Using GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/gitlab-environment-toolkit) - `[GitLab Solution]` - GitLab Instance Scaled on AWS EC2 and PaaS. `[GitLab Built]` - - Using GitLab Environment Toolkit (GET) - `[GitLab Solution]` + - [Using GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/gitlab-environment-toolkit) - `[GitLab Solution]` - [Amazon Managed Grafana](https://docs.aws.amazon.com/grafana/latest/userguide/gitlab-AMG-datasource.html) for GitLab self-managed Prometheus metrics. `[AWS Built]` -## GitLab Runner on AWS Compute +### GitLab Runner on AWS Compute +- [GitLab Runner Autoscaler](https://docs.gitlab.com/runner/runner_autoscale/) - core technology built by GitLab Runner team. `[GitLab Built]` +- [GitLab Runner Infrastructure Toolkit (GRIT)](https://gitlab.com/gitlab-org/ci-cd/runner-tools/grit) - managed infrastructure as code stewarded by the GitLab Runner team. Needed to deploy things like the GitLab Runner Autoscaler. `[GitLab Built]` - [Autoscaling GitLab Runner on AWS EC2](https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/). `[GitLab Built]` - [GitLab HA Scaling Runner Vending Machine for AWS EC2 ASG](https://gitlab.com/guided-explorations/aws/gitlab-runner-autoscaling-aws-asg/). `[GitLab Solution]` - Runner vending machine training resources. - - [GitLab EKS Fargate Runners](https://gitlab.com/guided-explorations/aws/eks-runner-configs/gitlab-runner-eks-fargate/-/blob/main/README.md). `[GitLab Solution]` diff --git a/doc/solutions/cloud/aws/gitlab_aws_partner_designations.md b/doc/solutions/cloud/aws/gitlab_aws_partner_designations.md index c48c3f95f9d..076fbec4940 100644 --- a/doc/solutions/cloud/aws/gitlab_aws_partner_designations.md +++ b/doc/solutions/cloud/aws/gitlab_aws_partner_designations.md @@ -17,11 +17,11 @@ This competency validates that GitLab delivers DevOps solutions that work with a ## DevSecOps Specialty Category -[AWS Program Information](https://aws.amazon.com/blogs/apn/aws-devops-competency-expands-to-include-devsecops-category/) [GitLab Announcement](https://about.gitlab.com/blog/2023/09/25/aws-devsecops-competency-partner/) +The DevSecOps qualification is a category of the DevOps Software Competency that demonstrates that GitLab is a substantial solution in helping organizations meet their DevSecOps maturity goals. GitLab was reviewed for meeting these additional qualifications before being granted this designation. [AWS Program Information](https://aws.amazon.com/blogs/apn/aws-devops-competency-expands-to-include-devsecops-category/) [GitLab Announcement](https://about.gitlab.com/blog/2023/09/25/aws-devsecops-competency-partner/) ## Public Sector Partner -This designation indicates that GitLab has been deemed qualified to work with AWS Public Sector customers. In fact, we have an entire organization dedicated to this practice. [AWS Program Information](https://aws.amazon.com/partners/programs/public-sector/) +This designation indicates that GitLab has been deemed qualified to work with AWS Public Sector customers. GitLab has a dedicated organization to address public sector specific needs. [AWS Program Information](https://aws.amazon.com/partners/programs/public-sector/) ## AWS Graviton diff --git a/doc/solutions/cloud/aws/gitlab_instance_on_aws.md b/doc/solutions/cloud/aws/gitlab_instance_on_aws.md index 320c317d446..de0ffcdc259 100644 --- a/doc/solutions/cloud/aws/gitlab_instance_on_aws.md +++ b/doc/solutions/cloud/aws/gitlab_instance_on_aws.md @@ -6,7 +6,7 @@ info: This page is owned by the Solutions Architecture team. {::options parse_block_html="true" /} -# Provision GitLab Instances on AWS EKS **(FREE SELF)** +# Provision GitLab Instances on AWS ## Available Infrastructure as Code for GitLab Instance Installation on AWS @@ -16,7 +16,7 @@ You can use the GitLab Environment Toolkit to deploy a Cloud Native Hybrid envir ### Two and Three Zone High Availability -While GitLab Reference Architectures generally encourage three zone redundancy, AWS Quick Starts and AWS Well Architected consider two zone redundancy as AWS Well Architected. Individual implementations should weigh the costs of two and three zone configurations against their own high availability requirements for a final configuration. +While GitLab Reference Architectures generally encourage three zone redundancy, the AWS Well Architected framework consider two zone redundancy as AWS Well Architected. Individual implementations should weigh the costs of two and three zone configurations against their own high availability requirements for a final configuration. Gitaly Cluster uses a consistency voting system to implement strong consistency between synchronized nodes. Regardless of the number of availability zones implemented, there will always need to be a minimum of three Gitaly and three Praefect nodes in the cluster to avoid voting stalemates cause by an even number of nodes. @@ -28,28 +28,27 @@ These services have been tested with GitLab. Some services, such as log aggregation, outbound email are not specified by GitLab, but where provided are noted. -| GitLab Services | AWS PaaS (Tested) | Provided by AWS Cloud <br />Native Hybrid Quick Start | -| ------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------ | -| <u>Tested PaaS Mentioned in Reference Architectures</u> | | | -| **PostgreSQL Database** | Amazon RDS PostgreSQL | Yes. | -| **Redis Caching** | Redis ElastiCache | Yes. | -| **Gitaly Cluster (Git Repository Storage)**<br />(Including Praefect and PostgreSQL) | ASG and Instances | Yes - ASG and Instances<br />**Note: Gitaly cannot be put into a Kubernetes Cluster.** | -| **All GitLab storages besides Git Repository Storage**<br />(Includes Git-LFS which is S3 Compatible) | AWS S3 | Yes | -| | | | -| <u>Tested PaaS for Supplemental Services</u> | | | -| **Front End Load Balancing** | AWS ELB | Yes | -| **Internal Load Balancing** | AWS ELB | Yes | -| **Outbound Email Services** | AWS Simple Email Service (SES) | Yes | -| **Certificate Authority and Management** | AWS Certificate Manager (ACM) | Yes | -| **DNS** | AWS Route53 (tested) | Yes | -| **GitLab and Infrastructure Log Aggregation** | AWS CloudWatch Logs | Yes (ContainerInsights Agent for EKS) | -| **Infrastructure Performance Metrics** | AWS CloudWatch Metrics | Yes | -| | | | -| <u>Supplemental Services and Configurations (Tested)</u> | | | -| **Prometheus for GitLab** | AWS EKS (Cloud Native Only) | Yes | -| **Grafana for GitLab** | AWS EKS (Cloud Native Only) | Yes | -| **Administrative Access to GitLab Backend** | Bastion Host in VPC | Yes - HA - Preconfigured for Cluster Management. | -| **Encryption (In Transit / At Rest)** | AWS KMS | Yes | -| **Secrets Storage for Provisioning** | AWS Secrets Manager | Yes | -| **Configuration Data for Provisioning** | AWS Parameter Store | Yes | -| **AutoScaling Kubernetes** | EKS AutoScaling Agent | Yes | +| GitLab Services | AWS PaaS (Tested) | +| ------------------------------------------------------------ | ------------------------------ | +| <u>Tested PaaS Mentioned in Reference Architectures</u> | | +| **PostgreSQL Database** | Amazon RDS PostgreSQL | +| **Redis Caching** | Redis ElastiCache | +| **Gitaly Cluster (Git Repository Storage)**<br />(Including Praefect and PostgreSQL) | ASG and Instances | +| **All GitLab storages besides Git Repository Storage**<br />(Includes Git-LFS which is S3 Compatible) | AWS S3 | +| | | +| <u>Tested PaaS for Supplemental Services</u> | | +| **Front End Load Balancing** | AWS ELB | +| **Internal Load Balancing** | AWS ELB | +| **Outbound Email Services** | AWS Simple Email Service (SES) | +| **Certificate Authority and Management** | AWS Certificate Manager (ACM) | +| **DNS** | AWS Route53 (tested) | +| **GitLab and Infrastructure Log Aggregation** | AWS CloudWatch Logs | +| **Infrastructure Performance Metrics** | AWS CloudWatch Metrics | +| | | +| <u>Supplemental Services and Configurations</u> | | +| **Prometheus for GitLab** | AWS EKS (Cloud Native Only) | +| **Grafana for GitLab** | AWS EKS (Cloud Native Only) | +| **Encryption (In Transit / At Rest)** | AWS KMS | +| **Secrets Storage for Provisioning** | AWS Secrets Manager | +| **Configuration Data for Provisioning** | AWS Parameter Store | +| **AutoScaling Kubernetes** | EKS AutoScaling Agent | diff --git a/doc/solutions/cloud/aws/index.md b/doc/solutions/cloud/aws/index.md index 7e9eed235ff..360b4161d49 100644 --- a/doc/solutions/cloud/aws/index.md +++ b/doc/solutions/cloud/aws/index.md @@ -8,20 +8,20 @@ info: This page is owned by the Solutions Architecture team. This documentation covers solutions relating to leveraging GitLab with and on Amazon Web Services (AWS). -- [GitLab partnership certifications and designations from AWS](gitlab_aws_integration.md) -- [GitLab AWS Integration Index](gitlab_aws_partner_designations.md) +- [GitLab partnership certifications and designations from AWS](gitlab_aws_partner_designations.md) +- [GitLab AWS Integration Index](gitlab_aws_integration.md) - [GitLab Instances on AWS EKS](gitlab_instance_on_aws.md) -- [SRE Considerations Gitaly on AWS](gitaly_sre_for_aws.md) +- [SRE Considerations for Gitaly on AWS](gitaly_sre_for_aws.md) - [Provision GitLab on a single EC2 instance in AWS](gitlab_single_box_on_aws.md) ## Cloud platform well architected compliance -Testing-backed architectural qualification is a fundamental concept behind implementation patterns: +Testing-backed architectural qualification is a fundamental concept behind Cloud solution implementations: -- Implementation patterns maintain GitLab Reference Architecture compliance and provide [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) (GPT) reports to demonstrate adherence to them. -- Implementation patterns may be qualified by and/or contributed to by the technology vendor. For instance, an implementation pattern for AWS may be officially reviewed by AWS. -- Implementation patterns may specify and test Cloud Platform PaaS services for suitability for GitLab. This testing can be coordinated and help qualify these technologies for Reference Architectures. For instance, qualifying compatibility with and availability of runtime versions of top level PaaS such as those for PostgreSQL and Redis. -- Implementation patterns can provided qualified testing for platform limitations, for example, ensuring Gitaly Cluster can work correctly on specific Cloud Platform availability zone latency and throughput characteristics or qualifying what levels of available platform partner local disk performance is workable for Gitaly server to operate with integrity. +- Cloud solution implementations maintain GitLab Reference Architecture compliance and provide [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) (GPT) reports to demonstrate adherence to them. +- Cloud solution implementations may be qualified by and/or contributed to by the technology vendor. For instance, an implementation pattern for AWS may be officially reviewed by AWS. +- Cloud solution implementations may specify and test Cloud Platform PaaS services for suitability for GitLab. This testing can be coordinated and help qualify these technologies for Reference Architectures. For instance, qualifying compatibility with and availability of runtime versions of top level PaaS such as those for PostgreSQL and Redis. +- Cloud solution implementations can provided qualified testing for platform limitations, for example, ensuring Gitaly Cluster can work correctly on specific Cloud Platform availability zone latency and throughput characteristics or qualifying what levels of available platform partner local disk performance is workable for Gitaly server to operate with integrity. ## AWS known issues list @@ -35,34 +35,36 @@ See the [GitLab AWS known issues list](https://gitlab.com/gitlab-com/alliances/a ## Platform partner specificity -Implementation patterns enable platform-specific terminology, best practice architecture, and platform-specific build manifests: +Cloud solution implementations enable platform-specific terminology, best practice architecture, and platform-specific build manifests: -- Implementation patterns are more vendor specific. For instance, advising specific compute instances / VMs / nodes instead of vCPUs or other generalized measures. -- Implementation patterns are oriented to implementing good architecture for the vendor in view. -- Implementation patterns are written to an audience who is familiar with building on the infrastructure that the implementation pattern targets. For example, if the implementation pattern is for GCP, the specific terminology of GCP is used - including using the specific names for PaaS services. -- Implementation patterns can test and qualify if the versions of PaaS available are compatible with GitLab (for example, PostgreSQL, Redis, etc.). +- Cloud solution implementations are more vendor specific. For instance, advising specific compute instances / VMs / nodes instead of vCPUs or other generalized measures. +- Cloud solution implementations are oriented to implementing good architecture for the vendor in view. +- Cloud solution implementations are written to an audience who is familiar with building on the infrastructure that the implementation pattern targets. For example, if the implementation pattern is for GCP, the specific terminology of GCP is used - including using the specific names for PaaS services. +- Cloud solution implementations can test and qualify if the versions of PaaS available are compatible with GitLab (for example, PostgreSQL, Redis, etc.). -## Platform as a Service (PaaS) specification and usage +## AWS Platform as a Service (PaaS) specification and usage -Platform as a Service options are a huge portion of the value provided by Cloud Platforms as they simplify operational complexity and reduce the SRE and security skilling required to operate advanced, highly available technology services. Implementation patterns can be pre-qualified against the partner PaaS options. +Platform as a Service options are a huge portion of the value provided by Cloud Platforms as they simplify operational complexity and reduce the SRE and security skilling required to operate advanced, highly available technology services. Cloud solution implementations can be pre-qualified against the partner PaaS options. -- Implementation patterns help implementers understand what PaaS options are known to work and how to choose between PaaS solutions when a single platform has more than one PaaS option for the same GitLab role. +- Cloud solution implementations help implementers understand what PaaS options are known to work and how to choose between PaaS solutions when a single platform has more than one PaaS option for the same GitLab role. - For instance, where reference architectures do not have a specific recommendation on what technology is leveraged for GitLab outbound email services or what the sizing should be - a Reference Implementation may advise using a cloud providers Email as a Service (PaaS) and possibly even with specific settings. +You can read more at [AWS services are usable to deploy GitLab infrastruture](gitlab_instance_on_aws.md). + ## Cost optimizing engineering Cost engineering is a fundamental aspect of Cloud Architecture and frequently the savings capabilities available on a platform exert strong influence on how to build out scaled computing. -- Implementation patterns may engineer specifically for the savings models available on a platform provider. An AWS example would be maximizing the occurrence of a specific instance type for taking advantage of reserved instances. -- Implementation patterns may leverage ephemeral compute where appropriate and with appropriate customer guidelines. For instance, a Kubernetes node group dedicated to runners on ephemeral compute (with appropriate GitLab Runner tagging to indicate the compute type). -- Implementation patterns may include vendor specific cost calculators. +- Cloud solution implementations may engineer specifically for the savings models available on a platform provider. An AWS example would be maximizing the occurrence of a specific instance type for taking advantage of reserved instances. +- Cloud solution implementations may leverage ephemeral compute where appropriate and with appropriate customer guidelines. For instance, a Kubernetes node group dedicated to runners on ephemeral compute (with appropriate GitLab Runner tagging to indicate the compute type). +- Cloud solution implementations may include vendor specific cost calculators. ## Actionability and automatability orientation -Implementation patterns are one step closer to specifics that can be used as a source for build instructions and automation code: +Cloud solution implementations are one step closer to specifics that can be used as a source for build instructions and automation code: -- Implementation patterns enable builders to generate a list of vendor specific resources required to implement GitLab for a given Reference Architecture. -- Implementation patterns enable builders to use manual instructions or to create automation to build out the reference implementation. +- Cloud solution implementations enable builders to generate a list of vendor specific resources required to implement GitLab for a given Reference Architecture. +- Cloud solution implementations enable builders to use manual instructions or to create automation to build out the reference implementation. ## Intended audiences and contributors diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md index 90e0e77cb9a..e1c5bbcadc2 100644 --- a/doc/subscriptions/bronze_starter.md +++ b/doc/subscriptions/bronze_starter.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Purchase -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Features available to Starter and Bronze subscribers diff --git a/doc/subscriptions/choosing_subscription.md b/doc/subscriptions/choosing_subscription.md index ad42eecc9c1..aa7ba3a9042 100644 --- a/doc/subscriptions/choosing_subscription.md +++ b/doc/subscriptions/choosing_subscription.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Purchase -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Choosing a GitLab subscription diff --git a/doc/subscriptions/community_programs.md b/doc/subscriptions/community_programs.md index a1d50dcb239..309a100de7a 100644 --- a/doc/subscriptions/community_programs.md +++ b/doc/subscriptions/community_programs.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Purchase -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Community programs @@ -46,7 +46,7 @@ Benefits of the GitLab Open Source Program apply to all projects in a GitLab nam #### Screenshot 1: License overview 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select your project avatar. If you haven't specified an avatar for your project, the avatar displays as a single letter. +1. Select your project avatar. If you haven't specified an avatar for your project, the avatar displays as a single letter. 1. Take a screenshot of the project overview that clearly displays the license you've chosen for your project.  diff --git a/doc/subscriptions/customers_portal.md b/doc/subscriptions/customers_portal.md index 45a4324f45d..10de69242d9 100644 --- a/doc/subscriptions/customers_portal.md +++ b/doc/subscriptions/customers_portal.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Purchase -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # The Customers Portal @@ -29,8 +29,8 @@ To sign in to Customers Portal with your email and to receive a one-time sign-in 1. Navigate to [Customers Portal](https://customers.gitlab.com/customers/sign_in). 1. Select **Sign in with your email**. -1. Provide the **Email** for your Customers Portal account. You will receive - an email with a one-time, sign-in link for your Customers Portal account. +1. Provide the **Email** for your Customers Portal profile. You will receive + an email with a one-time, sign-in link for your Customers Portal profile. 1. In the email you received, select **Sign in**. NOTE: @@ -42,23 +42,22 @@ The first time you sign in to the Customers Portal with a one-time sign-in link, you must confirm your email address to maintain access to the Customers Portal. If you sign in to the Customers Portal through GitLab.com, you don't need to confirm your email address. -You must also confirm any updates to the account email address. You will receive +You must also confirm any updates to the profile email address. You will receive an automatic email with instructions about how to confirm, which you can [resend](https://customers.gitlab.com/customers/confirmation/new) if required. -## Change account owner information +## Change profile owner information -The account owner's personal details are used on invoices. The account owner's email address is used for the [Customers Portal legacy sign-in](#sign-in-to-customers-portal) and license-related email. +The profile owner's personal details are used on invoices. The profile owner's email address is used for the [Customers Portal legacy sign-in](#sign-in-to-customers-portal) and license-related email. -To change account owner information, including name, billing address, and email address: +To change profile details, including name, billing address, and email address: 1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select **My account > Account details**. -1. Expand the **Personal details** section. -1. Edit the personal details. +1. Select **My profile > Profile settings**. +1. Edit **Your personal details**. 1. Select **Save changes**. -If you want to transfer ownership of the Customers Portal account +If you want to transfer ownership of the Customers Portal profile to another person, after you enter that person's personal details, you must also: - [Change the linked GitLab.com account](#change-the-linked-account), if you have one linked. @@ -68,9 +67,8 @@ to another person, after you enter that person's personal details, you must also To change your company details, including company name and VAT number: 1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select **My account > Account details**. -1. Expand the **Company details** section. -1. Edit the company details. +1. Select **My profile > Profile settings**. +1. Edit **Your company details**. 1. Select **Save changes**. ## Change your payment method @@ -79,13 +77,13 @@ Purchases in the Customers Portal require a credit card on record as a payment m multiple credit cards to your account, so that purchases for different products are charged to the correct card. -If you would like to use an alternative method to pay, please +If you would like to use an alternative method to pay, [contact our Sales team](https://about.gitlab.com/sales/). To change your payment method: 1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select **My account > Payment methods**. +1. Select **My profile > Payment methods**. 1. **Edit** an existing payment method's information or **Add new payment method**. 1. Select **Save Changes**. @@ -95,34 +93,34 @@ Automatic renewal of a subscription is charged to your default payment method. T method as the default: 1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select **My account > Payment methods**. +1. Select **My profile > Payment methods**. 1. **Edit** the selected payment method and check the **Make default payment method** checkbox. 1. Select **Save Changes**. ## Link a GitLab.com account -Follow this guideline if you have a legacy Customers Portal account and use an email and password to log in. +Follow this guideline if you have a legacy Customers Portal profile and use an email and password to log in. -To link a GitLab.com account to your Customers Portal account: +To link a GitLab.com account to your Customers Portal profile: 1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in?legacy=true) using email and password. -1. On the Customers Portal page, select **My account > Account details**. +1. On the Customers Portal page, select **My profile > Profile settings**. 1. Under **Your GitLab.com account**, select **Link account**. -1. Sign in to the [GitLab.com](https://gitlab.com/users/sign_in) account you want to link to the Customers Portal account. +1. Sign in to the [GitLab.com](https://gitlab.com/users/sign_in) account you want to link to the Customers Portal profile. ## Change the linked account -Customers are required to use their GitLab.com account to register for a new Customers Portal account. +Customers are required to use their GitLab.com account to register for a new Customers Portal profile. -If you have a legacy Customers Portal account that is not linked to a GitLab.com account, you may still [sign in](https://customers.gitlab.com/customers/sign_in?legacy=true) using an email and password. However, you should [create](https://gitlab.com/users/sign_up) and [link a GitLab.com account](#change-the-linked-account) to ensure continued access to the Customers Portal. +If you have a legacy Customers Portal profile that is not linked to a GitLab.com account, you may still [sign in](https://customers.gitlab.com/customers/sign_in?legacy=true) using an email and password. However, you should [create](https://gitlab.com/users/sign_up) and [link a GitLab.com account](#change-the-linked-account) to ensure continued access to the Customers Portal. -To change the GitLab.com account linked to your Customers Portal account: +To change the GitLab.com account linked to your Customers Portal profile: 1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). 1. In a separate browser tab, go to [GitLab.com](https://gitlab.com/users/sign_in) and ensure you are not logged in. -1. On the Customers Portal page, select **My account > Account details**. +1. On the Customers Portal page, select **My profile > Profile settings**. 1. Under **Your GitLab.com account**, select **Change linked account**. -1. Sign in to the [GitLab.com](https://gitlab.com/users/sign_in) account you want to link to the Customers Portal account. +1. Sign in to the [GitLab.com](https://gitlab.com/users/sign_in) account you want to link to the Customers Portal profile. ## Customers that purchased through a reseller diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index 317cdb1e1d5..9299028e56a 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -1,8 +1,7 @@ --- stage: Fulfillment group: Purchase -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab SaaS subscription **(PREMIUM SAAS)** @@ -42,7 +41,7 @@ To subscribe to GitLab SaaS: ## View your GitLab SaaS subscription -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -192,7 +191,7 @@ To add seats to a subscription: 1. Select **Add more seats** on the relevant subscription card. 1. Enter the number of additional users. 1. Review the **Purchase summary** section. The system lists the total price for all users on the - system and a credit for what you've already paid. You are only be charged for the net change. + system and a credit for what you've already paid. You are only charged for the net change. 1. Enter your payment information. 1. Select **Purchase seats**. @@ -267,6 +266,17 @@ Only one namespace can be linked to a subscription. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo, see [Linking GitLab Subscription to the Namespace](https://youtu.be/8iOsN8ajBUw). +### Transfer restrictions + +Changing the linked namespace is not supported for all subscription types. + +You cannot transfer: + +- A subscription with compute minutes. +- An expired or trial subscription. +- A subscription to a namespace which already has a Premium or Ultimate plan. +- A subscription from a namespace with multiple subscriptions. + ## Upgrade your GitLab SaaS subscription tier To upgrade your [GitLab tier](https://about.gitlab.com/pricing/): @@ -356,7 +366,7 @@ If you have difficulty during the renewal process, contact the There are several options to renew a subscription for fewer seats, as long as the seat total is equal to or greater than the billable user quantity at the time of renewal: -1. Turn off auto-renewal to avoid renewing at a higher seat quantity. +1. [Turn off auto-renewal](#enable-or-disable-automatic-subscription-renewal) to avoid renewing at a higher seat quantity. 1. [Manually renew](#renew-or-change-a-gitlab-saas-subscription) within 15 days of subscription renewal date, and specify the desired seat quantity. 1. Work with the Sales team to renew your subscription. @@ -365,7 +375,7 @@ There are several options to renew a subscription for fewer seats, as long as th Contacts can renew a subscription, cancel a subscription, or transfer the subscription to a different namespace. For information about how to transfer ownership of the Customers Portal account to another person, see -[Change account owner information](../customers_portal.md#change-account-owner-information). +[Change profile owner information](../customers_portal.md#change-profile-owner-information). To add a secondary contact for your subscription: @@ -401,7 +411,7 @@ locked. Projects can only be unlocked by purchasing more storage subscription un ### Purchase more storage and transfer -Prerequisite: +Prerequisites: - You must have the Owner role. @@ -457,6 +467,20 @@ To confirm the available storage, go to your group, and then select The **Purchased storage available** total is incremented by the amount purchased. All locked projects are unlocked and their excess usage is deducted from the additional storage. +## Enterprise Agile Planning + +GitLab Enterprise Agile Planning is an add-on that helps bring non-technical users into the same +DevSecOps platform where engineers build, test, secure, and deploy code. +The add-on enables cross-team collaboration between developers and non-developers without having to +purchase full GitLab licenses for non-engineering team members. +With Enterprise Agile Planning seats, non-engineering team members can participate in planning +workflows, measure software delivery velocity and impact with Value Stream Analytics, and use +executive dashboards to drive organizational visibility. + +### Purchase additional Enterprise Agile Planning seats + +Contact your [GitLab sales representative](https://about.gitlab.com/sales/) for more information. + ## Contact Support Learn more about: diff --git a/doc/subscriptions/gitlab_dedicated/index.md b/doc/subscriptions/gitlab_dedicated/index.md index 07abfb223ef..0f2fdb43512 100644 --- a/doc/subscriptions/gitlab_dedicated/index.md +++ b/doc/subscriptions/gitlab_dedicated/index.md @@ -1,7 +1,7 @@ --- stage: SaaS Platforms group: GitLab Dedicated -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Dedicated @@ -120,7 +120,6 @@ The following GitLab application features are not available: - LDAP, Smartcard, or Kerberos authentication - Multiple login providers -- Advanced search - GitLab Pages - FortiAuthenticator, or FortiToken 2FA - Reply-by email @@ -128,7 +127,8 @@ The following GitLab application features are not available: - GitLab-managed runners (hosted runners) - GitLab AI capabilities (Refer to our [direction page](https://about.gitlab.com/direction/saas-platforms/dedicated/#supporting-ai-features-on-gitlab-dedicated) for more information) - Features other than [available features](#available-features) that must be configured outside of the GitLab user interface -- [Feature Flags](../../administration/feature_flags.md) and functionality behind them +- Interacting with GitLab [Feature Flags](../../administration/feature_flags.md) +- Any functionality or feature behind a Feature Flag that is toggled `off` by default The following features will not be supported: @@ -150,7 +150,7 @@ The following operational features are not available: ### Available AWS regions -The following is a list of AWS regions verified for use in GitLab Dedicated. Regions must support io2 volumes and meet other requirements. If there is a region you are interested in that is not on this list, please reach out through your account representative or [GitLab Support](https://about.gitlab.com/support/) to inquire about its availability. This list will be updated from time to time as additional regions are verified. +The following is a list of AWS regions verified for use in GitLab Dedicated. Regions must support io2 volumes and meet other requirements. If there is a region you are interested in that is not on this list, reach out through your account representative or [GitLab Support](https://about.gitlab.com/support/) to inquire about its availability. This list will be updated from time to time as additional regions are verified. - Asia Pacific (Singapore) - Asia Pacific (Sydney) diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 8577fdb460d..8d2ddb4f370 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -1,8 +1,7 @@ --- stage: Fulfillment group: Purchase -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Subscribe to GitLab **(PREMIUM ALL)** @@ -10,7 +9,7 @@ type: index, reference Choose and manage the subscription that's right for you and your organization. - [Choose a subscription](choosing_subscription.md) -- [Compare self-managed to SaaS](../install/migrate/compare_sm_to_saas.md) +- [Compare self-managed to SaaS](choosing_subscription.md) - [GitLab SaaS](gitlab_com/index.md) - [GitLab self-managed](self_managed/index.md) - [GitLab Dedicated](gitlab_dedicated/index.md) diff --git a/doc/subscriptions/quarterly_reconciliation.md b/doc/subscriptions/quarterly_reconciliation.md index 1962ce02647..87a4b65833c 100644 --- a/doc/subscriptions/quarterly_reconciliation.md +++ b/doc/subscriptions/quarterly_reconciliation.md @@ -1,7 +1,7 @@ --- stage: Fulfillment group: Purchase -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Quarterly reconciliation and annual true-ups **(PREMIUM ALL)** @@ -81,13 +81,15 @@ sent and subject to your payment terms. ### Troubleshooting failed payment -If your credit card is declined during the reconciliation process, an email will be sent with the subject `Your GitLab subscription failed to reconcile`. Please follow these instructions to update your payment information, and the reconciliation will be automatically retried: +If your credit card is declined during the reconciliation process, an email will be sent with the subject `Your GitLab subscription failed to reconcile`. Follow these instructions to update your payment information, and the reconciliation will be automatically retried: 1. Log in to your account at `https://customers.gitlab.com`. 1. Go to **Payment Methods**. 1. Select **Add New Payment Method**. 1. Make sure that the payment method is set as **Default**. +Reconciliation is retried automatically as soon as the payment method is updated. + ## Quarterly reconciliation eligibility ### You are automatically enrolled in quarterly reconciliation if diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index a1573132ab2..e9a6f3720d2 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -1,8 +1,7 @@ --- stage: Fulfillment group: Purchase -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab self-managed subscription **(PREMIUM SELF)** @@ -37,8 +36,7 @@ Prorated charges are not possible without a quarterly usage report. View the amount of users in your instance to determine if they exceed the amount paid for in your subscription. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Users**. The lists of users are displayed. @@ -51,12 +49,10 @@ A user is not counted as a billable user if: - They are [deactivated](../../administration/moderate_users.md#deactivate-a-user) or [blocked](../../administration/moderate_users.md#block-a-user). - If the user occupied a seat prior to being deactivated or blocked, - the user is included in the number of [maximum users](#maximum-users). - They are [pending approval](../../administration/moderate_users.md#users-pending-approval). - They have only the [Minimal Access role](../../user/permissions.md#users-with-minimal-access) on self-managed Ultimate subscriptions or any GitLab.com subscriptions. -- They have the [Guest or Minimal Access roles on an Ultimate subscription](#free-guest-users). -- They have project or group memberships on an Ultimate subscription. +- They have only the [Guest or Minimal Access roles on an Ultimate subscription](#free-guest-users). +- They do not have project or group memberships on an Ultimate subscription. - The account is a GitLab-created service account: - [Ghost User](../../user/profile/account/delete_account.md#associated-records). - Bots such as: @@ -69,7 +65,7 @@ The amount of **Billable users** is reported once a day in the Admin Area. ### Maximum users -The number of _maximum users_ reflects the highest number of billable users for the current license period. +The number of _maximum users_ reflects the highest peak of billable users for the current license period. ### Users over subscription @@ -220,8 +216,7 @@ Example of a license sync request: You can manually synchronize your subscription details at any time. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. 1. In the **Subscription details** section, select **Sync subscription details**. @@ -231,8 +226,7 @@ A job is queued. When the job finishes, the subscription details are updated. If you are an administrator, you can view the status of your subscription: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. The **Subscription** page includes the following details: @@ -256,8 +250,7 @@ It also displays the following information: If you are an administrator, you can export your license usage into a CSV: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Subscription**. 1. In the upper-right corner, select **Export license usage file**. @@ -324,9 +317,10 @@ You purchase a subscription for 10 users. |:---------------------------------------------------|:-----------------|:--------------| | Ten users occupy all 10 seats. | 10 | 10 | | Two new users join. | 12 | 12 | -| Three users leave and their accounts are removed. | 9 | 12 | +| Three users leave and their accounts are blocked. | 9 | 12 | +| Four new users join. | 13 | 13 | -Users over subscription = 12 - 10 (Maximum users - users in license) +Users over subscription = 13 - 10 (Maximum users - users in license) ### Add seats to a subscription @@ -336,13 +330,13 @@ period is prorated from the date of purchase through the end of the subscription To add seats to a subscription: -1. Log in to the [Customers Portal](https://customers.gitlab.com/). -1. Navigate to the **Manage Purchases** page. +1. Sign in to the [Customers Portal](https://customers.gitlab.com/). +1. Go to the **Manage Purchases** page. 1. Select **Add more seats** on the relevant subscription card. 1. Enter the number of additional users. -1. Select **Proceed to checkout**. -1. Review the **Subscription Upgrade Detail**. The system lists the total price for all users on the system and a credit for what you've already paid. You are only be charged for the net change. -1. Select **Confirm Upgrade**. +1. Review the **Purchase summary** section. The system lists the total price for all users on the system and a credit for what you've already paid. You are only charged for the net change. +1. Enter your payment information. +1. Select **Purchase seats**. A payment receipt is emailed to you, which you can also access in the Customers Portal under [**View invoices**](https://customers.gitlab.com/receipts). @@ -359,9 +353,7 @@ You should follow these steps during renewal: 1. Prior to the renewal date, prune any inactive or unwanted users by [blocking them](../../administration/moderate_users.md#block-a-user). 1. Determine if you have a need for user growth in the upcoming subscription. -1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) and select the **Renew** button beneath your existing subscription. -The **Renew** button remains disabled (grayed-out) until 15 days before a subscription expires. -You can hover your mouse on the **Renew** button to see the date when it will become active. +1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) and beneath your existing subscription, select **Renew**. The **Renew** button displays only 15 days before a subscription expires. If there are more than 15 days before the subscription expires, select **Subscription actions** (**{ellipsis_v}**), then select **Renew subscription** to view the date when you can renew. NOTE: If you need to change your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team with [the sales contact form](https://about.gitlab.com/sales/) for assistance as this can't be done in the Customers Portal. @@ -396,10 +388,8 @@ You can view and download your renewal invoice on the Customers Portal [View inv To view or change automatic subscription renewal (at the same tier as the previous period), sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in), and: -- If a **Turn on auto-renew** button is displayed, your subscription was canceled - previously. Select it to resume automatic renewal. -- If a **Cancel subscription** button is displayed, your subscription is set to automatically - renew at the end of the subscription period. Select it to cancel automatic renewal. +- If the subscription card displays `Expires on DATE`, your subscription is not set to automatically renew. To enable automatic renewal, in **Subscription actions** (**{ellipsis_v}**), select **Turn on auto-renew**. +- If the subscription card displays `Autorenews on DATE`, your subscription is set to automatically renew at the end of the subscription period. To cancel automatic renewal, in **Subscription actions** (**{ellipsis_v}**), select **Cancel subscription**. If you have difficulty during the renewal process, contact the [Support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. @@ -408,7 +398,7 @@ If you have difficulty during the renewal process, contact the There are several options to renew a subscription for fewer seats, as long as the seat total is equal to or greater than the billable user quantity at the time of renewal: -1. Turn off auto-renewal to avoid renewing at a higher seat quantity. +1. [Turn off auto-renewal](#enable-or-disable-automatic-subscription-renewal) to avoid renewing at a higher seat quantity. 1. [Manually renew](#renew-subscription-manually) within 15 days of subscription renewal date, and specify the desired seat quantity. 1. Work with the Sales team to renew your subscription. @@ -416,9 +406,8 @@ There are several options to renew a subscription for fewer seats, as long as th To upgrade your [GitLab tier](https://about.gitlab.com/pricing/): -1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select the **Upgrade** button on the relevant subscription card on the - [Manage purchases](https://customers.gitlab.com/subscriptions) page. +1. Sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). +1. Select **Upgrade** on the relevant subscription card. 1. Select the desired upgrade. 1. Confirm the active form of payment, or add a new form of payment. 1. Select the **I accept the Privacy Policy and Terms of Service** checkbox. @@ -438,7 +427,7 @@ The new tier takes effect when the new license is activated. Contacts can renew a subscription, cancel a subscription, or transfer the subscription to a different namespace. For information about how to transfer ownership of the Customers Portal account to another person, see -[Change account owner information](../customers_portal.md#change-account-owner-information). +[Change profile owner information](../customers_portal.md#change-profile-owner-information). To add a secondary contact for your subscription: @@ -473,6 +462,10 @@ existing feature requests in the [GitLab](https://gitlab.com/gitlab-org/gitlab/- These issues are the best avenue for getting updates on specific product plans and for communicating directly with the relevant GitLab team members. +## Storage + +The amount of storage and transfer for self-managed instances has no application limits. Administrators are responsible for the underlying infrastructure costs and can set [repository size limits](../../administration/settings/account_and_limit_settings.md#repository-size-limit). + ## Troubleshooting ### Subscription data fails to synchronize diff --git a/doc/topics/autodevops/cicd_variables.md b/doc/topics/autodevops/cicd_variables.md index 4fa2ee10c75..9d50d0dabab 100644 --- a/doc/topics/autodevops/cicd_variables.md +++ b/doc/topics/autodevops/cicd_variables.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD variables @@ -133,7 +133,7 @@ Auto DevOps detects CI/CD variables starting with `K8S_SECRET_`, and makes them available to the deployed application as environment variables. -Prerequisite: +Prerequisites: - The variable value must be a single line. diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_ec2.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_ec2.md index 381326d68ea..b43d334380b 100644 --- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_ec2.md +++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_ec2.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Auto DevOps to deploy to EC2 diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_ecs.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_ecs.md index 6ac8f87940e..80079a15ed5 100644 --- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_ecs.md +++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_ecs.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Auto DevOps to deploy to Amazon ECS diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md index d0a7814348c..486b1334a82 100644 --- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md +++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_eks.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Auto DevOps to deploy an application to Amazon Elastic Kubernetes Service (EKS) @@ -178,8 +178,6 @@ The jobs are separated into stages: - Jobs suffixed with `-sast` run static analysis on the current code to check for potential security issues, and are allowed to fail ([Auto SAST](../stages.md#auto-sast)) - The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](../stages.md#auto-secret-detection)) - - The `license_scanning` job is deprecated and does not produce any results. It is allowed to fail - ([Auto License Compliance](../stages.md#auto-license-compliance-deprecated)) - **Review** - Pipelines on the default branch include this stage with a `dast_environment_deploy` job. To learn more, see [Dynamic Application Security Testing (DAST)](../../../user/application_security/dast/index.md). diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md index d50bdcfa056..572e08f355b 100644 --- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md +++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE ALL)** @@ -77,7 +77,7 @@ Now you have an application project you are going to deploy to the GKE cluster. Now we need to configure the GitLab agent for Kubernetes for us to be able to use it to deploy the application project. 1. Go to the project [we created to manage the cluster](#create-a-kubernetes-cluster). -1. Navigate to the [agent configuration file](../../../user/clusters/agent/install/index.md#create-an-agent-configuration-file) (`.gitlab/agents/gke-agent/config.yaml`) and edit it. +1. Navigate to the [agent configuration file](../../../user/clusters/agent/install/index.md#create-an-agent-configuration-file) (`.gitlab/agents/<agent-name>/config.yaml`) and edit it. 1. Configure `ci_access:projects` attribute. Use application's project path as `id`: ```yaml @@ -127,7 +127,7 @@ Follow these steps to configure the base domain and other settings required for 1. On the left sidebar, select **Settings > CI/CD** and expand **Variables**. - Add a key called `KUBE_INGRESS_BASE_DOMAIN` with the application deployment domain as the value. For this example, use the domain `<IP address>.nip.io`. - Add a key called `KUBE_NAMESPACE` with a value of the Kubernetes namespace for your deployments to target. You can use different namespaces per environment. Configure the environment, use the environment scope. - - Add a key called `KUBE_CONTEXT` with a value like `path/to/agent/project:gke-agent`. Select the environment scope of your choice. + - Add a key called `KUBE_CONTEXT` with the value `<path/to/agent/project>:<agent-name>`. Select the environment scope of your choice. - Select **Save changes**. ## Enable Auto DevOps and run the pipeline @@ -182,8 +182,6 @@ The jobs are separated into stages: - Jobs suffixed with `-sast` run static analysis on the current code to check for potential security issues, and are allowed to fail ([Auto SAST](../stages.md#auto-sast)) - The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](../stages.md#auto-secret-detection)) - - The `license_scanning` job is deprecated and does not produce any results. It is allowed to fail - ([Auto License Compliance](../stages.md#auto-license-compliance-deprecated)) - **Review** - Pipelines on the default branch include this stage with a `dast_environment_deploy` job. For more information, see [Dynamic Application Security Testing (DAST)](../../../user/application_security/dast/index.md). diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 2e6672e3ab0..630123510a9 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customize Auto DevOps **(FREE ALL)** diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 4191ba257ca..0413ec32283 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auto DevOps **(FREE ALL)** @@ -37,7 +37,6 @@ Auto DevOps supports development during each of the [DevOps stages](stages.md). | Test | [Auto Code Intelligence](stages.md#auto-code-intelligence) | | Test | [Auto Code Quality](stages.md#auto-code-quality) | | Test | [Auto Container Scanning](stages.md#auto-container-scanning) | -| Test | [Auto License Compliance](stages.md#auto-license-compliance-deprecated) | | Deploy | [Auto Review Apps](stages.md#auto-review-apps) | | Deploy | [Auto Deploy](stages.md#auto-deploy) | | Secure | [Auto Dynamic Application Security Testing (DAST)](stages.md#auto-dast) | @@ -164,8 +163,7 @@ Prerequisites: To enable Auto DevOps for your instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > CI/CD**. 1. Expand **Auto DevOps**. 1. Select the **Default to Auto DevOps pipeline** checkbox. @@ -207,7 +205,7 @@ match your new GitLab version: There is no guarantee that you can use a private container registry with Auto DevOps. -Instead, use the [GitLab Container Registry](../../user/packages/container_registry/index.md) with Auto DevOps to +Instead, use the [GitLab container registry](../../user/packages/container_registry/index.md) with Auto DevOps to simplify configuration and prevent any unforeseen issues. ## Install applications behind a proxy @@ -220,7 +218,7 @@ installation pods at runtime. ## Related topics -- [Continuous methodologies](../../ci/introduction/index.md) +- [Continuous methodologies](../../ci/index.md) - [Docker](https://docs.docker.com) - [GitLab Runner](https://docs.gitlab.com/runner/) - [Helm](https://helm.sh/docs/) diff --git a/doc/topics/autodevops/multiple_clusters_auto_devops.md b/doc/topics/autodevops/multiple_clusters_auto_devops.md index 2cb748ab2e9..dbdabae90d9 100644 --- a/doc/topics/autodevops/multiple_clusters_auto_devops.md +++ b/doc/topics/autodevops/multiple_clusters_auto_devops.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple Kubernetes clusters for Auto DevOps **(FREE ALL)** diff --git a/doc/topics/autodevops/prepare_deployment.md b/doc/topics/autodevops/prepare_deployment.md index 1dced373461..da33d6d8761 100644 --- a/doc/topics/autodevops/prepare_deployment.md +++ b/doc/topics/autodevops/prepare_deployment.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Prepare Auto DevOps for deployment **(FREE ALL)** @@ -12,10 +12,8 @@ recommend that you prepare them before enabling Auto DevOps. ## Deployment strategy -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. - When using Auto DevOps to deploy your applications, choose the -[continuous deployment strategy](../../ci/introduction/index.md) +[continuous deployment strategy](../../ci/index.md) that works best for your needs: | Deployment strategy | Setup | Methodology | diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index a0aaba99a59..1b9c1b0cb9e 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Requirements for Auto DevOps **(FREE ALL)** @@ -30,7 +30,7 @@ To prepare the deployment: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. When using Auto DevOps to deploy your applications, choose the -[continuous deployment strategy](../../ci/introduction/index.md) +[continuous deployment strategy](../../ci/index.md) that works best for your needs: | Deployment strategy | Setup | Methodology | diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index ec587dfc974..541dfbe04fa 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Stages of Auto DevOps **(FREE ALL)** @@ -240,18 +240,6 @@ check out. The merge request widget displays any security warnings detected, For more information, see [Dependency Scanning](../../user/application_security/dependency_scanning/index.md). -<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> - -## Auto License Compliance (deprecated) **(ULTIMATE ALL)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9, -in GitLab 16.3 we [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/421363) support for the License Compliance report. -Auto License Compliance is still present in the pipeline, but won't produce any results. - -Use Auto Dependency Scanning instead. - -<!--- end_remove --> - ## Auto Container Scanning Vulnerability static analysis for containers uses [Trivy](https://aquasecurity.github.io/trivy/latest/) diff --git a/doc/topics/autodevops/troubleshooting.md b/doc/topics/autodevops/troubleshooting.md index 11b5265b9a3..bff21c19165 100644 --- a/doc/topics/autodevops/troubleshooting.md +++ b/doc/topics/autodevops/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Auto DevOps **(FREE ALL)** diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index dc18f863844..3a58d493657 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading deployments for newer Auto Deploy dependencies **(FREE ALL)** diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index d2410da76aa..9daddfbe7c5 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading PostgreSQL for Auto DevOps **(FREE ALL)** diff --git a/doc/topics/build_your_application.md b/doc/topics/build_your_application.md index 02335c77b73..430ef9ec57d 100644 --- a/doc/topics/build_your_application.md +++ b/doc/topics/build_your_application.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use CI/CD to build your application **(FREE ALL)** diff --git a/doc/topics/cron/index.md b/doc/topics/cron/index.md index ca1bc7f40f2..057ae82e6ad 100644 --- a/doc/topics/cron/index.md +++ b/doc/topics/cron/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cron @@ -38,7 +38,7 @@ are valid: - Run once a day at midnight: `0 0 * * *` - Run once a week at midnight on Sunday morning: `0 0 * * 0` - Run once a month at midnight of the first day of the month: `0 0 1 * *` -- Run once a month on the 22nd: `0 0 22 * *`) +- Run once a month on the 22nd: `0 0 22 * *` - Run once a month on the 2nd Monday: `0 0 * * 1#2` - Run once a year at midnight of 1 January: `0 0 1 1 *` - Run every other Sunday at 0900 hours: `0 9 * * sun%2` diff --git a/doc/topics/git/cherry_picking.md b/doc/topics/git/cherry_picking.md index 7f0da5a594e..fe7bd333f88 100644 --- a/doc/topics/git/cherry_picking.md +++ b/doc/topics/git/cherry_picking.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cherry-pick a Git commit **(FREE ALL)** diff --git a/doc/topics/git/get_started.md b/doc/topics/git/get_started.md new file mode 100644 index 00000000000..c2738f9e748 --- /dev/null +++ b/doc/topics/git/get_started.md @@ -0,0 +1,85 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Get started with Git + +You can use Git from a command line to interact with GitLab. + +## Common terms + +If you're new to Git, start by reviewing some of the most commonly used terms. + +### Repository + +Files are stored in a **repository**. A repository is similar to how you +store files in a folder or directory on your computer. + +- A **remote repository** refers to the files in GitLab. +- A **local copy** refers to the files on your computer. + +The word **repository** is often shortened to **repo**. + +In GitLab, a repository is part of a **project**. + +**Get started:** + +- [Learn more about repositories](../../user/project/repository/index.md). +- [Tutorial: Make your first Git commit](../../tutorials/make_first_git_commit/index.md). + +### Clone + +To create a copy of a remote repository's files on your computer, you **clone** it. +When you clone a repository, you can sync the repository with the remote repository in GitLab. +You can modify the files locally and upload the changes to the remote repository on GitLab. + +**Get started:** + +- [Clone a repository from GitLab to your local machine](../../gitlab-basics/start-using-git.md#clone-a-repository). + +### Pull + +When the remote repository changes, your local copy is behind. You can update your local copy with the new +changes in the remote repository. +This action is known as **pulling** from the remote, because you use the command `git pull`. + +**Get started**: + +- [Download the latest changes in the project](../../gitlab-basics/start-using-git.md#download-the-latest-changes-in-the-project). + +### Push + +After you save a local copy of a repository and modify the files on your computer, you can upload the +changes to GitLab. This action is known as **pushing** to the remote, because you use the command +`git push`. + +**Get started**: + +- [Send changes to GitLab](../../gitlab-basics/start-using-git.md#send-changes-to-gitlab). + +### Fork + +When you want to contribute to someone else's repository, you make a copy of it. +This copy is called a **fork**. + +When you create a fork of a repository, you create a copy of the project in your own +namespace in the remote repository. +You then have write permissions to modify the project files and settings. + +For example, you can fork this project in to your namespace: + +- <https://gitlab.com/gitlab-tests/sample-project/> + +You now have your own copy of the repository. You can view the namespace in the URL, for example: + +- `https://gitlab.com/your-namespace/sample-project/` + +Then you can clone the repository to your local machine, work on the files, and submit changes back to the +original repository. + +**Get started** + +- [Learn more about forks](../../user/project/repository/forking_workflow.md). +- [Learn more about namespaces](../../user/namespace/index.md). diff --git a/doc/topics/git/git_add.md b/doc/topics/git/git_add.md index db85e75a6a8..5d4c38bf320 100644 --- a/doc/topics/git/git_add.md +++ b/doc/topics/git/git_add.md @@ -1,39 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../../gitlab-basics/add-file.md' +remove_date: '2024-02-03' --- -# Git add **(FREE ALL)** +This document was moved to [another location](../../gitlab-basics/add-file.md). -Adds content to the index or staging area. - -- Adds a list of file: - - ```shell - git add <files> - ``` - -- Adds all files including deleted ones: - - ```shell - git add -A - ``` - -- Add all text files in current dir: - - ```shell - git add *.txt - ``` - -- Add all text file in the project: - - ```shell - git add "*.txt*" - ``` - -- Adds all files in directory: - - ```shell - git add views/layouts/ - ``` +<!-- This redirect file can be deleted after <2024-02-03>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 78275746de5..63ac1d845e0 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.md @@ -1,102 +1,113 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: concepts, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" description: "Introduction to Git rebase and force push, methods to resolve merge conflicts through the command line." --- # Git rebase and force push **(FREE ALL)** -This guide helps you to get started with rebases, force pushes, and fixing -[merge conflicts](../../user/project/merge_requests/conflicts.md) locally. -Before you attempt a force push or a rebase, make sure you are familiar with -[Git through the command line](../../gitlab-basics/start-using-git.md). +In Git, a rebase updates your branch with the contents of another branch. +A rebase confirms that changes in your branch don't conflict with +changes in the target branch. -WARNING: -`git rebase` rewrites the commit history. It **can be harmful** to do it in -shared branches. It can cause complex and hard to resolve -[merge conflicts](../../user/project/merge_requests/conflicts.md). In -these cases, instead of rebasing your branch against the default branch, -consider pulling it instead (`git pull origin master`). Pulling has similar -effects with less risk compromising the work of your contributors. +If you have a [merge conflict](../../user/project/merge_requests/conflicts.md), +you can rebase to fix it. -In Git, a rebase updates your feature branch with the contents of another branch. -This step is important for Git-based development strategies. Use a rebase to confirm -that your branch's changes don't conflict with any changes added to your target branch -_after_ you created your feature branch. +## What happens during rebase When you rebase: -1. Git imports all the commits submitted to your target branch _after_ you initially created - your feature branch from it. -1. Git stacks the commits you have in your feature branch on top of all +1. Git imports all the commits submitted to your target branch after you initially created + your branch from it. +1. Git stacks the commits you have in your branch on top of all the commits it imported from that branch: - +  While most rebases are performed against `main`, you can rebase against any other branch, such as `release-15-3`. You can also specify a different remote repository (such as `upstream`) instead of `origin`. -## Back up a branch before rebase +WARNING: +`git rebase` rewrites the commit history. It **can be harmful** to do it in +shared branches. It can cause complex and hard to resolve +merge conflicts. Instead of rebasing your branch against the default branch, +consider pulling it instead (`git pull origin master`). Pulling has similar +effects with less risk of compromising others' work. -To back up a branch before taking any destructive action, like a rebase or force push: +## Rebase by using Git -1. Open your feature branch in the terminal: `git checkout my-feature` -1. Create a backup branch: `git branch my-feature-backup` - Any changes added to `my-feature` after this point are lost - if you restore from the backup branch. +When you use Git to rebase, each commit is applied to your branch. +When merge conflicts occur, you are prompted to address them. -Your branch is backed up, and you can try a rebase or a force push. -If anything goes wrong, restore your branch from its backup: +If you want more advanced options for your commits, +do [an interactive rebase](#rebase-interactively-by-using-git). -1. Make sure you're in the correct branch (`my-feature`): `git checkout my-feature` -1. Reset it against `my-feature-backup`: `git reset --hard my-feature-backup` +Prerequisites: -## Rebase a branch +- You must have permission to force push to branches. -[Rebases](https://git-scm.com/docs/git-rebase) are very common operations in -Git, and have these options: +To use Git to rebase your branch against the target branch: -- **Regular rebases.** This type of rebase can be done through the - [command line](#regular-rebase) and [the GitLab UI](#from-the-gitlab-ui). -- [**Interactive rebases**](#interactive-rebase) give more flexibility by - enabling you to specify how to handle each commit. Interactive rebases - must be done on the command line. +1. Open a terminal and change to your project. +1. Ensure you have the latest contents of the target branch. + In this example, the target branch is `main`: -Any user who rebases a branch is treated as having added commits to that branch. -If a project is configured to -[**prevent approvals by users who add commits**](../../user/project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits), -a user who rebases a branch cannot also approve its merge request. + ```shell + git fetch origin main + ``` -### Regular rebase +1. Check out your branch: -Standard rebases replay the previous commits on a branch without changes, stopping -only if merge conflicts occur. + ```shell + git checkout my-branch + ``` -Prerequisites: +1. Optional. Create a backup of your branch: -- You must have permission to force push branches. + ```shell + git branch my-branch-backup + ``` -To update your branch `my-feature` with recent changes from your -[default branch](../../user/project/repository/branches/default.md) (here, using `main`): + Changes added to `my-branch` after this point are lost + if you restore from the backup branch. -1. Fetch the latest changes from `main`: `git fetch origin main` -1. Check out your feature branch: `git checkout my-feature` -1. Rebase it against `main`: `git rebase origin/main` -1. [Force push](#force-push) to your branch. +1. Rebase against the main branch: -If there are merge conflicts, Git prompts you to fix them before continuing the rebase. + ```shell + git rebase origin/main + ``` -### From the GitLab UI +1. If merge conflicts exist: + 1. Fix the conflicts in your editor. -The `/rebase` [quick action](../../user/project/quick_actions.md#issues-merge-requests-and-epics) -rebases your feature branch directly from its merge request if all of these -conditions are met: + 1. Add the files: -- No merge conflicts exist for your feature branch. -- You have the **Developer** role for the source project. This role grants you + ```shell + git add . + ``` + + 1. Continue the rebase: + + ```shell + git rebase --continue + ``` + +1. Force push your changes to the target branch, while protecting others' commits: + + ```shell + git push origin my-branch --force-with-lease + ``` + +## Rebase from the UI + +You can rebase a merge request from the GitLab UI. + +Prerequisites: + +- No merge conflicts must exist. +- You must have at least the **Developer** role for the source project. This role grants you permission to push to the source branch for the source project. - If the merge request is in a fork, the fork must allow commits [from members of the upstream project](../../user/project/merge_requests/allow_collaboration.md). @@ -107,91 +118,112 @@ To rebase from the UI: 1. Type `/rebase` in a comment. 1. Select **Comment**. -GitLab schedules a rebase of the feature branch against the default branch and +GitLab schedules a rebase of the branch against the default branch and executes it as soon as possible. -### Interactive rebase - -Use an interactive rebase (the `--interactive` flag, or `-i`) to simultaneously -update a branch while you modify how its commits are handled. -For example, to edit the last five commits in your branch (`HEAD~5`), run: - -```shell -git rebase -i HEAD~5 -``` - -Git opens the last five commits in your terminal text editor, oldest commit first. -Each commit shows the action to take on it, the SHA, and the commit title: - -```shell -pick 111111111111 Second round of structural revisions -pick 222222222222 Update inbound link to this changed page -pick 333333333333 Shifts from H4 to H3 -pick 444444444444 Adds revisions from editorial -pick 555555555555 Revisions continue to build the concept part out - -# Rebase 111111111111..222222222222 onto zzzzzzzzzzzz (5 commands) -# -# Commands: -# p, pick <commit> = use commit -# r, reword <commit> = use commit, but edit the commit message -# e, edit <commit> = use commit, but stop for amending -# s, squash <commit> = use commit, but meld into previous commit -# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous -``` - -After the list of commits, a commented-out section shows some common actions you -can take on a commit: - -- **Pick** a commit to use it with no changes. The default option. -- **Reword** a commit message. -- **Edit** a commit to use it, but pause the rebase to amend (add changes to) it. -- **Squash** multiple commits together to simplify the commit history - of your feature branch. - -Replace the keyword `pick` according to -the operation you want to perform in each commit. To do so, edit -the commits in your terminal's text editor. - -For example, with [Vim](https://www.vim.org/) as the text editor in -a macOS Zsh shell, you can `squash` or `fixup` (combine) all of the commits together: - -NOTE: -The steps for editing through the command line can be slightly -different depending on your operating system and the shell you use. - -1. Press <kbd>i</kbd> on your keyboard to switch to Vim's editing mode. -1. Use your keyboard arrows to edit the **second** commit keyword - from `pick` to `squash` or `fixup` (or `s` or `f`). Do the same to the remaining commits. - Leave the first commit **unchanged** (`pick`) as we want to squash - all other commits into it. -1. Press <kbd>Escape</kbd> to leave the editing mode. -1. Type `:wq` to "write" (save) and "quit". +## Rebase interactively by using Git + +Use an interactive rebase when you want to specify how to handle each commit. +You must do an interactive rebase from the command line. + +Prerequisites: + +- [Vim](https://www.vim.org/) must be your text editor to follow these instructions. + +To rebase interactively: + +1. Open a terminal and change to your project. +1. Ensure you have the latest contents of the target branch. + In this example, the target branch is `main`: + + ```shell + git fetch origin main + ``` + +1. Check out your branch: + + ```shell + git checkout my-branch + ``` + +1. Optional. Create a backup of your branch: + + ```shell + git branch my-branch-backup + ``` + + Changes added to `my-branch` after this point are lost + if you restore from the backup branch. + +1. In the GitLab UI, in your merge request, confirm how many commits + you want to rebase by viewing the **Commits** tab. + +1. Open these commits. For example, to edit the last five commits in your branch (`HEAD~5`), type: + + ```shell + git rebase -i HEAD~5 + ``` + + Git opens the last five commits in your terminal text editor, oldest commit first. + Each commit shows the action to take on it, the SHA, and the commit title: + + ```shell + pick 111111111111 Second round of structural revisions + pick 222222222222 Update inbound link to this changed page + pick 333333333333 Shifts from H4 to H3 + pick 444444444444 Adds revisions from editorial + pick 555555555555 Revisions continue to build the concept part out + + # Rebase 111111111111..222222222222 onto zzzzzzzzzzzz (5 commands) + # + # Commands: + # p, pick <commit> = use commit + # r, reword <commit> = use commit, but edit the commit message + # e, edit <commit> = use commit, but stop for amending + # s, squash <commit> = use commit, but meld into previous commit + # f, fixup [-C | -c] <commit> = like "squash" but keep only the previous + ``` + +1. Switch to Vim's edit mode by pressing <kbd>i</kbd>. +1. Move to the second commit in the list by using your keyboard arrows. +1. Change the word `pick` to `squash` or `fixup` (or `s` or `f`). +1. Do the same for the remaining commits. Leave the first commit as `pick`. +1. End edit mode, save, and quit: + + - Press <kbd>ESC</kbd>. + - Type `:wq`. + 1. When squashing, Git outputs the commit message so you have a chance to edit it: + - All lines starting with `#` are ignored and not included in the commit - message. Everything else is included. - - To leave it as it is, type `:wq`. To edit the commit message: switch to the - editing mode, edit the commit message, and save it as you just did. -1. If you haven't pushed your commits to the remote branch before rebasing, - push your changes without a force push. If you had pushed these commits already, - [force push](#force-push) instead. + message. Everything else is included. + - To leave it as-is, type `:wq`. To edit the commit message, switch to + edit mode, edit the commit message, and save. + +1. Commit to the target branch. -#### Configure squash options for a project + - If you didn't push your commits to the target branch before rebasing, + push your changes without a force push: -Keeping the default branch commit history clean doesn't require you to -manually squash all your commits on each merge request. GitLab provides -[squash and merge](../../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project), -options at a project level. + ```shell + git push origin my-branch + ``` -## Force push + - If you pushed these commits already, use a force push: + + ```shell + git push origin my-branch --force-with-lease + ``` + +## Force pushing Complex operations in Git require you to force an update to the remote branch. Operations like squashing commits, resetting a branch, or rebasing a branch rewrite the history of your branch. Git requires a forced update to help safeguard against these more destructive changes from happening accidentally. -Force pushing is not recommended on shared branches, as you risk destroying the -changes of others. +Force pushing is not recommended on shared branches, because you risk destroying +others' changes. If the branch you want to force push is [protected](../../user/project/protected_branches.md), you can't force push to it unless you either: @@ -202,27 +234,32 @@ you can't force push to it unless you either: Then you can force push and protect it again. -### `--force-with-lease` flag +## Restore your backed up branch + +Your branch is backed up, and you can try a rebase or a force push. +If anything goes wrong, restore your branch from its backup: + +1. Make sure you're in the correct branch: -The [`--force-with-lease`](https://git-scm.com/docs/git-push#Documentation/git-push.txt---force-with-leaseltrefnamegt) -flag force pushes. Because it preserves any new commits added to the remote -branch by other people, it is safer than `--force`: + ```shell + git checkout my-branch + ``` -```shell -git push --force-with-lease origin my-feature -``` +1. Reset your branch against the backup: -### `--force` flag + ```shell + git reset --hard my-branch-backup + ``` -The `--force` flag forces pushes, but does not preserve any new commits added to -the remote branch by other people. To use this method, pass the flag `--force` or `-f` -to the `push` command: +## Approving after rebase -```shell -git push --force origin my-feature -``` +If you rebase a branch, you've added commits. +If your project is configured to +[prevent approvals by users who add commits](../../user/project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits), +you can't approve a merge request if you have rebased it. ## Related topics - [Numerous undo possibilities in Git](numerous_undo_possibilities_in_git/index.md#undo-staged-local-changes-without-modifying-history) - [Git documentation for branches and rebases](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) +- [Project squash and merge settings](../../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 52e8e2e1259..5a93f0fcd69 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -1,79 +1,52 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.' +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Installing Git **(FREE ALL)** -To begin contributing to GitLab projects, you must install the appropriate Git client -on your computer. Information about [installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -is also available at the official Git website. +To begin contributing to GitLab projects, you must download and install the Git client on your computer. -## Supported operating systems +This page provides information on installing Git on the following operating systems: -Git is available for the following operating systems: +- macOS +- Ubuntu Linux +- Microsoft Windows -- [macOS](#macos) -- [Ubuntu Linux](#ubuntu-linux) -- [Microsoft Windows](#windows) +For information on downloading and installing Git on other operating systems, see the +[official Git website](https://git-scm.com/downloads). -### macOS +## Install and update Git on macOS -A version of Git is supplied by macOS. You can use this version, or install the latest -version of Git on macOS by downloading it from the project website. We recommend -installing Git with [Homebrew](https://brew.sh/index.html). With Homebrew, you can -access an extensive selection of libraries and applications, with their dependencies -managed for you. +Though a version of Git is supplied by macOS, you should install the latest version of Git. A common way to +install Git is with [Homebrew](https://brew.sh/index.html). -Prerequisites: +To install the latest version of Git on macOS with Homebrew: -- 15 GB of available disk space for Homebrew and Xcode. -- Extra disk space for any additional development libraries. - -To install Git on macOS: - -1. Open a terminal and install Xcode Command Line Tools: - - ```shell - xcode-select --install - ``` - - Alternatively, you can install the entire [Xcode](https://developer.apple.com/xcode/) - package through the macOS App Store. - -1. Select **Install** to download and install Xcode Command Line Tools. -1. Install Homebrew according to the [official Homebrew installation instructions](https://brew.sh/index.html). -1. Install Git by running `brew install git` from your terminal. -1. In a terminal, verify that Git works on your computer: +1. If you've never installed Homebrew before, follow the + [Homebrew installation instructions](https://brew.sh/index.html). +1. In a terminal, install Git by running `brew install git`. +1. Verify that Git works on your computer: ```shell git --version ``` -#### macOS update - -Periodically you may need to update the version of Git installed by -[Homebrew](/ee/topics/git/how_to_install_git/index.md#macos). To do so, -open a terminal and run these commands: +Keep Git up to date by periodically running the following command: ```shell -brew update -brew upgrade git +brew update && brew upgrade git ``` -To verify you are on the updated version, run `git --version` to display -your current version of Git. +## Install and update Git on Ubuntu Linux -### Ubuntu Linux +Though a version of Git is supplied by Ubuntu, you should install the latest version of Git. The latest version is +available using a Personal Package Archive (PPA). -On Ubuntu and other Linux operating systems, use the built-in package manager -to install Git: +To install the latest version of Git on Ubuntu Linux with a PPA: -1. Open a terminal and run these commands to install the latest Git -from the officially - maintained package archives: +1. In a terminal, configure the required PPA, update the list of Ubuntu packages, and install `git`: ```shell sudo apt-add-repository ppa:git-core/ppa @@ -81,32 +54,23 @@ from the officially sudo apt-get install git ``` -1. To verify that Git works on your computer, run: +1. Verify that Git works on your computer: ```shell git --version ``` -#### Ubuntu Linux Update +Keep Git up to date by periodically running the following command: -Periodically it may be necessary to update Git installed. To do so, run the same [commands](/ee/topics/git/how_to_install_git/index.md#ubuntu-linux). +```shell +sudo apt-get update && sudo apt-get install git +``` -### Windows +## Install Git on Microsoft Windows -Go to the [Git website](https://git-scm.com/), and then download and install Git for Windows. +For information on downloading and installing Git on Microsoft Windows, see the +[official Git documentation](https://git-scm.com/download/win). ## After you install Git After you successfully install Git on your computer, read about [adding an SSH key to GitLab](../../../user/ssh.md). - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index e349cf0bb92..c7b1832c8b8 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: index +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Git **(FREE ALL)** @@ -38,7 +37,7 @@ appropriate for when you're ready to start learning Git by doing: - [How to install Git](how_to_install_git/index.md) - [Start using Git on the command line](../../gitlab-basics/start-using-git.md) - Tutorial: [Make your first Git commit](../../tutorials/make_first_git_commit/index.md) -- Tutorial: [How to update Git commit messages](../../tutorials/update_commit_messages/index.md) +- Tutorial: [Update Git commit messages](../../tutorials/update_commit_messages/index.md) - The [GitLab CLI](https://gitlab.com/gitlab-org/cli/) A typical Git user encounters these concepts soon after starting to use Git: diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 23d972e9aa7..fb2aa8df6b7 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Git Large File Storage (LFS) **(FREE ALL)** @@ -51,7 +50,7 @@ your operating system. GitLab requires version 1.0.1 or later of the Git LFS cli - Any Git LFS request asks for HTTPS credentials, so we recommend a good Git credentials store. - Git LFS always assumes HTTPS so if you have GitLab server on HTTP you must - [add the URL to Git configuration manually](#troubleshooting). + [add the URL to Git configuration manually](troubleshooting.md#getsockopt-connection-refused). - [Group wikis](../../../user/project/wiki/group.md) do not support Git LFS. ## How LFS objects affect repository size @@ -164,158 +163,4 @@ Technical details about how this works can be found in the [development document - Blog post: [Getting started with Git LFS](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/) - [Git LFS developer information](../../../development/lfs.md) - [GitLab Git Large File Storage (LFS) Administration](../../../administration/lfs/index.md) for self-managed instances - -## Troubleshooting - -### Encountered `n` files that should have been pointers, but weren't - -This error indicates the files are expected to be tracked by LFS, but -the repository is not tracking them as LFS. This issue can be one -potential reason for this error: -[Files not tracked with LFS when uploaded through the web interface](https://gitlab.com/gitlab-org/gitlab/-/issues/326342#note_586820485) - -To resolve the problem, migrate the affected file (or files) and push back to the repository: - -1. Migrate the file to LFS: - - ```shell - git lfs migrate import --yes --no-rewrite "<your-file>" - ``` - -1. Push back to your repository: - - ```shell - git push - ``` - -1. Optional. Clean up your `.git` folder: - - ```shell - git reflog expire --expire-unreachable=now --all - git gc --prune=now - ``` - -### error: Repository or object not found - -This error can occur for a few reasons, including: - -- You don't have permissions to access certain LFS object - -Check if you have permissions to push to the project or fetch from the project. - -- Project is not allowed to access the LFS object - -LFS object you are trying to push to the project or fetch from the project is not -available to the project anymore. Probably the object was removed from the server. - -- Local Git repository is using deprecated LFS API - -### Invalid status for `<url>` : 501 - -Git LFS logs the failures into a log file. -To view this log file, while in project directory: - -```shell -git lfs logs last -``` - -If the status `error 501` is shown, it is because: - -- Git LFS is not enabled in project settings. Check your project settings and - enable Git LFS. - -- Git LFS support is not enabled on the GitLab server. Check with your GitLab - administrator why Git LFS is not enabled on the server. See - [LFS administration documentation](../../../administration/lfs/index.md) for instructions - on how to enable LFS support. - -- Git LFS client version is not supported by GitLab server. Check your Git LFS - version with `git lfs version`. Check the Git configuration of the project for traces - of deprecated API with `git lfs -l`. If `batch = false` is set in the configuration, - remove the line and try to update your Git LFS client. Only version 1.0.1 and - newer are supported. - -### `getsockopt: connection refused` - -If you push an LFS object to a project and receive an error like this, -the LFS client is trying to reach GitLab through HTTPS. However, your GitLab -instance is being served on HTTP: - -```plaintext -Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused -``` - -This behavior is caused by Git LFS using HTTPS connections by default when a -`lfsurl` is not set in the Git configuration. - -To prevent this from happening, set the LFS URL in project Git configuration: - -```shell -git config --add lfs.url "http://gitlab.example.com/group/my-sample-project.git/info/lfs" -``` - -### Credentials are always required when pushing an object - -NOTE: -With 8.12 GitLab added LFS support to SSH. The Git LFS communication -still goes over HTTP, but now the SSH client passes the correct credentials -to the Git LFS client. No action is required by the user. - -Git LFS authenticates the user with HTTP Basic Authentication on every push for -every object, so user HTTPS credentials are required. - -By default, Git has support for remembering the credentials for each repository -you use. For more information, see the [official Git documentation](https://git-scm.com/docs/gitcredentials). - -For example, you can tell Git to remember the password for a period of time in -which you expect to push the objects: - -```shell -git config --global credential.helper 'cache --timeout=3600' -``` - -This remembers the credentials for an hour, after which Git operations -require re-authentication. - -If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. -For Windows, you can use `wincred` or Microsoft's [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases). - -More details about various methods of storing the user credentials can be found -on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). - -### LFS objects are missing on push - -GitLab checks files to detect LFS pointers on push. If LFS pointers are detected, GitLab tries to verify that those files already exist in LFS on GitLab. - -Verify that LFS is installed locally and consider a manual push with `git lfs push --all`. - -If you are storing LFS files outside of GitLab you can disable LFS on the project by setting `lfs_enabled: false` with the [projects API](../../../api/projects.md#edit-project). - -### Hosting LFS objects externally - -It is possible to host LFS objects externally by setting a custom LFS URL with `git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs`. - -You might choose to do this if you are using an appliance like a Nexus Repository to store LFS data. If you choose to use an external LFS store, -GitLab can't verify LFS objects. Pushes then fail if you have GitLab LFS support enabled. - -To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md), which also disables GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS). - -### I/O timeout when pushing LFS objects - -You might get an error that states: - -```shell -LFS: Put "http://your-instance.com/root/project.git/gitlab-lfs/objects/cc29e205d04a4062d0fb131700e8bfc8e54c44d0176a8dca22f40b24ef26d325/15": read tcp your-instance-ip:54544->your-instance-ip:443: i/o timeout -error: failed to push some refs to 'ssh://your-instance.com:2222/root/project.git' -``` - -When network conditions are unstable, the Git LFS client might time out when trying to upload files -if network conditions are unstable. - -The workaround is to set the client activity timeout a higher value. - -For example, to set the timeout to 60 seconds: - -```shell -git config lfs.activitytimeout 60 -``` +- [Troubleshooting Git LFS](troubleshooting.md) diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index d14d0db6087..9887650c5f0 100644 --- a/doc/topics/git/lfs/migrate_to_git_lfs.md +++ b/doc/topics/git/lfs/migrate_to_git_lfs.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "How to migrate an existing Git repository to Git LFS with BFG." --- diff --git a/doc/topics/git/lfs/troubleshooting.md b/doc/topics/git/lfs/troubleshooting.md new file mode 100644 index 00000000000..63bf6368e79 --- /dev/null +++ b/doc/topics/git/lfs/troubleshooting.md @@ -0,0 +1,162 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" +--- + +# Troubleshooting Git LFS + +When working with Git LFS, you might encounter the following issues. + +## Encountered `n` files that should have been pointers, but weren't + +This error indicates the files are expected to be tracked by LFS, but +the repository is not tracking them as LFS. This issue can be one +potential reason for this error: +[Files not tracked with LFS when uploaded through the web interface](https://gitlab.com/gitlab-org/gitlab/-/issues/326342#note_586820485) + +To resolve the problem, migrate the affected file (or files) and push back to the repository: + +1. Migrate the file to LFS: + + ```shell + git lfs migrate import --yes --no-rewrite "<your-file>" + ``` + +1. Push back to your repository: + + ```shell + git push + ``` + +1. Optional. Clean up your `.git` folder: + + ```shell + git reflog expire --expire-unreachable=now --all + git gc --prune=now + ``` + +## error: Repository or object not found + +This error can occur for a few reasons, including: + +- You don't have permissions to access certain LFS object + +Check if you have permissions to push to the project or fetch from the project. + +- Project is not allowed to access the LFS object + +LFS object you are trying to push to the project or fetch from the project is not +available to the project anymore. Probably the object was removed from the server. + +- Local Git repository is using deprecated LFS API + +## Invalid status for `<url>` : 501 + +Git LFS logs the failures into a log file. +To view this log file, while in project directory: + +```shell +git lfs logs last +``` + +If the status `error 501` is shown, it is because: + +- Git LFS is not enabled in project settings. Check your project settings and + enable Git LFS. + +- Git LFS support is not enabled on the GitLab server. Check with your GitLab + administrator why Git LFS is not enabled on the server. See + [LFS administration documentation](../../../administration/lfs/index.md) for instructions + on how to enable LFS support. + +- Git LFS client version is not supported by GitLab server. Check your Git LFS + version with `git lfs version`. Check the Git configuration of the project for traces + of deprecated API with `git lfs -l`. If `batch = false` is set in the configuration, + remove the line and try to update your Git LFS client. Only version 1.0.1 and + newer are supported. + +## `getsockopt: connection refused` + +If you push an LFS object to a project and receive an error like this, +the LFS client is trying to reach GitLab through HTTPS. However, your GitLab +instance is being served on HTTP: + +```plaintext +Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused +``` + +This behavior is caused by Git LFS using HTTPS connections by default when a +`lfsurl` is not set in the Git configuration. + +To prevent this from happening, set the LFS URL in project Git configuration: + +```shell +git config --add lfs.url "http://gitlab.example.com/group/my-sample-project.git/info/lfs" +``` + +## Credentials are always required when pushing an object + +NOTE: +With 8.12 GitLab added LFS support to SSH. The Git LFS communication +still goes over HTTP, but now the SSH client passes the correct credentials +to the Git LFS client. No action is required by the user. + +Git LFS authenticates the user with HTTP Basic Authentication on every push for +every object, so user HTTPS credentials are required. + +By default, Git has support for remembering the credentials for each repository +you use. For more information, see the [official Git documentation](https://git-scm.com/docs/gitcredentials). + +For example, you can tell Git to remember the password for a period of time in +which you expect to push the objects: + +```shell +git config --global credential.helper 'cache --timeout=3600' +``` + +This remembers the credentials for an hour, after which Git operations +require re-authentication. + +If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. +For Windows, you can use `wincred` or Microsoft's [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases). + +More details about various methods of storing the user credentials can be found +on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). + +## LFS objects are missing on push + +GitLab checks files to detect LFS pointers on push. If LFS pointers are detected, GitLab tries to verify that those files already exist in LFS on GitLab. + +Verify that LFS is installed locally and consider a manual push with `git lfs push --all`. + +If you are storing LFS files outside of GitLab you can disable LFS on the project by setting `lfs_enabled: false` with the [projects API](../../../api/projects.md#edit-project). + +## Hosting LFS objects externally + +It is possible to host LFS objects externally by setting a custom LFS URL with `git config -f .lfsconfig lfs.url https://example.com/<project>.git/info/lfs`. + +You might choose to do this if you are using an appliance like a Nexus Repository to store LFS data. If you choose to use an external LFS store, +GitLab can't verify LFS objects. Pushes then fail if you have GitLab LFS support enabled. + +To stop push failure, LFS support can be disabled in the [Project settings](../../../user/project/settings/index.md), which also disables GitLab LFS value-adds (Verifying LFS objects, UI integration for LFS). + +## I/O timeout when pushing LFS objects + +You might get an error that states: + +```shell +LFS: Put "http://your-instance.com/root/project.git/gitlab-lfs/objects/cc29e205d04a4062d0fb131700e8bfc8e54c44d0176a8dca22f40b24ef26d325/15": read tcp your-instance-ip:54544->your-instance-ip:443: i/o timeout +error: failed to push some refs to 'ssh://your-instance.com:2222/root/project.git' +``` + +When network conditions are unstable, the Git LFS client might time out when trying to upload files +if network conditions are unstable. + +The workaround is to set the client activity timeout a higher value. + +For example, to set the timeout to 60 seconds: + +```shell +git config lfs.activitytimeout 60 +``` diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 8c42a394106..bf0f9f243d0 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -1,26 +1,12 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Undo options in Git **(FREE ALL)** -[Nothing in Git is deleted](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery), -so when you work in Git, you can undo your work. - -All version control systems have options for undoing work. However, -because of the de-centralized nature of Git, these options are multiplied. -The actions you take are based on the -[stage of development](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) -you are in. - -For more information about working with Git and GitLab: - -- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Learn why [North Western Mutual chose GitLab](https://youtu.be/kPNMyxKRRoM) for their enterprise source code management. -- Learn how to [get started with Git](https://about.gitlab.com/resources/whitepaper-moving-to-git/). -- For more advanced examples, refer to the [Git book](https://git-scm.com/book/en/v2). +Git provides options for undoing changes. The method for undoing a change depends on whether the change is unstaged, staged, committed, or pushed. ## When you can undo changes diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index add276ad49d..bc73cc36b96 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Partial clone **(FREE ALL)** diff --git a/doc/topics/git/rollback_commits.md b/doc/topics/git/rollback_commits.md index b86b7dbfca5..51be4cb6191 100644 --- a/doc/topics/git/rollback_commits.md +++ b/doc/topics/git/rollback_commits.md @@ -1,72 +1,111 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Roll back commits **(FREE ALL)** -## Undo Commits +In Git, if you make a mistake, you can undo or roll back your changes. +For more details, see [Undo options](numerous_undo_possibilities_in_git/index.md). -- Undo last commit putting everything back into the staging area: +## Undo commits by removing them + +- Undo your last commit and put everything back in the staging area: ```shell git reset --soft HEAD^ ``` -- Add files and change message with: +- Add files and change the commit message: ```shell git commit --amend -m "New Message" ``` -- Undo last and remove changes: +- Undo the last change and remove all other changes, + if you did not push yet: ```shell git reset --hard HEAD^ ``` -- Same as last one but for two commits back: +- Undo the last change and remove the last two commits, + if you did not push yet: ```shell git reset --hard HEAD^^ ``` -**Don't reset after pushing** +### Git reset sample workflow + +The following is a common Git reset workflow: + +1. Edit a file. +1. Check the status of the branch: + + ```shell + git status + ``` + +1. Commit the changes to the branch with a wrong commit message: + + ```shell + git commit -am "kjkfjkg" + ``` + +1. Check the Git log: + + ```shell + git log + ``` + +1. Amend the commit with the correct commit message: + + ```shell + git commit --amend -m "New comment added" + ``` + +1. Check the Git log again: + + ```shell + git log + ``` + +1. Soft reset the branch: + + ```shell + git reset --soft HEAD^ + ``` + +1. Check the Git log again: + + ```shell + git log + ``` + +1. Pull updates for the branch from the remote: + + ```shell + git pull origin <branch> + ``` -## Reset Workflow +1. Push changes for the branch to the remote: -1. Edit file again 'edit_this_file.rb' -1. Check status -1. Add and commit with wrong message -1. Check log -1. Amend commit -1. Check log -1. Soft reset -1. Check log -1. Pull for updates -1. Push changes + ```shell + git push origin <branch> + ``` -## Commands +## Undo commits with a new replacement commit ```shell -# Change file edit_this_file.rb -git status -git commit -am "kjkfjkg" -git log -git commit --amend -m "New comment added" -git log -git reset --soft HEAD^ -git log -git pull origin master -git push origin master +git revert <commit-sha> ``` -## Note +## The difference between `git revert` and `git reset` -- `git revert` vs `git reset` -- Reset removes the commit while revert removes the changes but leaves the commit -- Revert is safer considering we can revert a revert +- The `git reset` command removes the commit. The `git revert` command removes the changes but leaves the commit. +- The `git revert` command is safer, because you can revert a revert. ```shell # Changed file diff --git a/doc/topics/git/stash.md b/doc/topics/git/stash.md index 84a09385bf6..b8288d32be5 100644 --- a/doc/topics/git/stash.md +++ b/doc/topics/git/stash.md @@ -1,13 +1,13 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git stash **(FREE ALL)** -We use `git stash` to store our changes when they are not ready to be committed, -but we must change to a different branch. +Use `git stash` when you want to change to a different branch, and you +want to store changes that are not ready to be committed. - Stash: @@ -27,7 +27,7 @@ but we must change to a different branch. git stash apply stash@{3} ``` -- Every time we save a stash it gets stacked so by using `list` we can see all our +- Every time you save a stash, it gets stacked. Use `list` to see all of the stashes. ```shell @@ -36,7 +36,7 @@ but we must change to a different branch. git stash list --stat ``` -- To clean our stack, manually remove them: +- To clean the stack, manually remove them: ```shell # drop top stash @@ -47,24 +47,24 @@ but we must change to a different branch. git stash clear ``` -- Apply and drop on one command: +- Use one command to apply and drop: ```shell git stash pop ``` -- If we meet conflicts, either reset or commit our changes. -- Conflicts through `pop` doesn't drop a stash afterwards. +- If you have conflicts, either reset or commit your changes. +- Conflicts through `pop` don't drop a stash afterwards. -## Git Stash sample workflow +## Git stash sample workflow -1. Modify a file -1. Stage file -1. Stash it -1. View our stash list -1. Confirm no pending changes through status -1. Apply with pop -1. View list to confirm changes +1. Modify a file. +1. Stage file. +1. Stash it. +1. View the stash list. +1. Confirm no pending changes through `git status`. +1. Apply with `git stash pop`. +1. View list to confirm changes. ```shell # Modify edit_this_file.rb file diff --git a/doc/topics/git/terminology.md b/doc/topics/git/terminology.md index cef9b7cc35b..788bdd1b8a9 100644 --- a/doc/topics/git/terminology.md +++ b/doc/topics/git/terminology.md @@ -1,62 +1,11 @@ --- -stage: Create -group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'get_started.md' +remove_date: '2024-02-03' --- -# Git concepts +This document was moved to [another location](get_started.md). -The following are commonly-used Git concepts. - -## Repository - -In GitLab, files are stored in a **repository**. A repository is similar to how you -store files in a folder or directory on your computer. - -- A **remote repository** refers to the files in GitLab. -- A **local copy** refers to the files on your computer. - -<!-- vale gitlab.Spelling = NO --> -<!-- vale gitlab.SubstitutionWarning = NO --> -Often, the word "repository" is shortened to "repo". -<!-- vale gitlab.Spelling = YES --> -<!-- vale gitlab.SubstitutionWarning = YES --> - -In GitLab, a repository is contained in a **project**. - -## Fork - -When you want to contribute to someone else's repository, you make a copy of it. -This copy is called a [**fork**](../../user/project/repository/forking_workflow.md#create-a-fork). -The process is called "creating a fork." - -When you fork a repository, you create a copy of the project in your own -[namespace](../../user/namespace/index.md). You then have write permissions to modify the project files -and settings. - -For example, you can fork this project, <https://gitlab.com/gitlab-tests/sample-project/>, into your namespace. -You now have your own copy of the repository. You can view the namespace in the URL, for example -`https://gitlab.com/your-namespace/sample-project/`. -Then you can clone the repository to your local machine, work on the files, and submit changes back to the -original repository. - -## Difference between download and clone - -To create a copy of a remote repository's files on your computer, you can either -**download** or **clone** the repository. If you download it, you cannot sync the repository with the -remote repository on GitLab. - -[Cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) a repository is the same as downloading, except it preserves the Git connection -with the remote repository. You can then modify the files locally and -upload the changes to the remote repository on GitLab. - -## Pull and push - -After you save a local copy of a repository and modify the files on your computer, you can upload the -changes to GitLab. This action is known as **pushing** to the remote, because you use the command -[`git push`](../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom). - -When the remote repository changes, your local copy is behind. You can update your local copy with the new -changes in the remote repository. -This action is known as **pulling** from the remote, because you use the command -[`git pull`](../../gitlab-basics/start-using-git.md#download-the-latest-changes-in-the-project). +<!-- This redirect file can be deleted after <2024-02-03>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index d29300d5810..dd3a2efc11b 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Troubleshooting Git **(FREE ALL)** @@ -11,6 +10,38 @@ Sometimes things don't work the way they should or as you might expect when you're using Git. Here are some tips on troubleshooting and resolving issues with Git. +## Debugging + +When troubleshooting problems with Git, try these debugging techniques. + +### Use a custom SSH key for a Git command + +```shell +GIT_SSH_COMMAND="ssh -i ~/.ssh/gitlabadmin" git <command> +``` + +### Debug problems with cloning + +For Git over SSH: + +```shell +GIT_SSH_COMMAND="ssh -vvv" git clone <git@url> +``` + +For Git over HTTPS: + +```shell +GIT_TRACE_PACKET=1 GIT_TRACE=2 GIT_CURL_VERBOSE=1 git clone <url> +``` + +### Debug Git with traces + +Git includes a complete set of [traces for debugging Git commands](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_debugging), for example: + +- `GIT_TRACE_PERFORMANCE=1`: enables tracing of performance data, showing how long each particular `git` invocation takes. +- `GIT_TRACE_SETUP=1`: enables tracing of what `git` is discovering about the repository and environment it's interacting with. +- `GIT_TRACE_PACKET=1`: enables packet-level tracing for network operations. + ## Broken pipe errors on `git push` 'Broken pipe' errors can occur when attempting to push to a remote repository. @@ -337,7 +368,7 @@ details. This second request should succeed, and result in a `200 OK` log entry. If a `401` log entry lacks a corresponding `200` log entry, the Git client is likely using either: - An incorrect password. -- An expired or revoked token.an incorrect +- An expired or revoked token. If not rectified, you could encounter [`403` (Forbidden) errors](#403-error-when-performing-git-operations-over-http) diff --git a/doc/topics/git/unstage.md b/doc/topics/git/unstage.md index 028f34b2433..95958600fb4 100644 --- a/doc/topics/git/unstage.md +++ b/doc/topics/git/unstage.md @@ -1,28 +1,43 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unstage a file in Git **(FREE ALL)** When you _stage_ a file in Git, you instruct Git to track changes to the file in -preparation for a commit. To instruct Git to disregard changes to a file, and not +preparation for a commit. To disregard changes to a file, and not include it in your next commit, _unstage_ the file. -- To remove files from stage use `reset HEAD`, where HEAD is the last commit of - the current branch. This unstages the file but maintains the modifications. +## Unstage a file + +- To remove files from staging, but keep your changes: ```shell git reset HEAD <file> ``` -- To revert the file back to the state it was in before the changes: +- To unstage the last three commits: + + ```shell + git reset HEAD^3 + ``` + +- To unstage changes to a certain file from HEAD: ```shell - git checkout -- <file> + git reset <filename> ``` +After you unstage the file, to revert the file back to the state it was in before the changes: + +```shell +git checkout -- <file> +``` + +## Remove a file + - To remove a file from disk and repository, use `git rm`. To remove a directory, use the `-r` flag: ```shell diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index 305008e2642..a397ec749d0 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -1,138 +1,21 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Frequently used Git commands **(FREE ALL)** -The GitLab support team has collected these commands to help you. You may not -need them frequently. +The following commands are frequently used. -## Remotes +## Add another URL to a remote -### Add another URL to a remote, so both remotes get updated on each push +Add another URL to a remote, so both remotes get updated on each push: ```shell git remote set-url --add <remote_name> <remote_url> ``` -## Staging and reverting changes - -### Remove last commit and leave the changes in unstaged - -```shell -git reset --soft HEAD^ -``` - -### Unstage a certain number of commits from HEAD - -To unstage 3 commits, for example, run: - -```shell -git reset HEAD^3 -``` - -### Unstage changes to a certain file from HEAD - -```shell -git reset <filename> -``` - -### Revert a file to HEAD state and remove changes - -To revert changes to a file, you can use either: - -- `git checkout <filename>` -- `git reset --hard <filename>` - -### Undo a previous commit by creating a new replacement commit - -```shell -git revert <commit-sha> -``` - -### Create a new message for last commit - -```shell -git commit --amend -``` - -### Create a new message for older commits - -WARNING: -Changing commit history can disrupt others' work if they have cloned, forked, or have active branches. -Only amend pushed commits if you're sure it's safe. -To learn more, see [Git rebase and force push](git_rebase.md). - -```shell -git rebase -i HEAD~n -``` - -Replace `n` with the number of commits you want to go back. - -This opens your text editor with a list of commits. -In the editor, replace `pick` with `reword` for each commit you want to change the message: - -```shell -reword 1fc6c95 original commit message -pick 6b2481b another commit message -pick 5c1291b another commit message -``` - -After saving and closing the file, you can update each message in a new editor window. - -After updating your commits, you must push them to the repository. -As this rewrites history, a force push is required. -To prevent unintentional overwrites, use `--force-with-lease`: - -```shell -git push --force-with-lease -``` - -### Add a file to the last commit - -```shell -git add <filename> -git commit --amend -``` - -Append `--no-edit` to the `commit` command if you do not want to edit the commit -message. - -## Stashing - -### Stash changes - -```shell -git stash save -``` - -The default behavior of `stash` is to save, so you can also use just: - -```shell -git stash -``` - -### Unstash your changes - -```shell -git stash apply -``` - -### Discard your stashed changes - -```shell -git stash drop -``` - -### Apply and drop your stashed changes - -```shell -git stash pop -``` - ## Refs and Log ### Use reflog to show the log of reference changes to HEAD @@ -174,36 +57,6 @@ gitk <file> gitk --follow <file> ``` -## Debugging - -### Use a custom SSH key for a Git command - -```shell -GIT_SSH_COMMAND="ssh -i ~/.ssh/gitlabadmin" git <command> -``` - -### Debug cloning - -With SSH: - -```shell -GIT_SSH_COMMAND="ssh -vvv" git clone <git@url> -``` - -With HTTPS: - -```shell -GIT_TRACE_PACKET=1 GIT_TRACE=2 GIT_CURL_VERBOSE=1 git clone <url> -``` - -### Debugging with Git embedded traces - -Git includes a complete set of [traces for debugging Git commands](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_debugging), for example: - -- `GIT_TRACE_PERFORMANCE=1`: enables tracing of performance data, showing how long each particular `git` invocation takes. -- `GIT_TRACE_SETUP=1`: enables tracing of what `git` is discovering about the repository and environment it's interacting with. -- `GIT_TRACE_PACKET=1`: enables packet-level tracing for network operations. - ## Rebasing ### Rebase your branch onto the default @@ -245,4 +98,4 @@ questions that you know someone might ask. Each scenario can be a third-level heading, for example `### Getting error message X`. If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. -->
\ No newline at end of file +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index e9feb75dd5c..5eba213cbd4 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -1,11 +1,11 @@ --- redirect_to: 'https://about.gitlab.com/blog/2023/07/27/gitlab-flow-duo/' -remove_date: '2023-10-27' +remove_date: '2024-07-27' --- This document was moved to [another location](https://about.gitlab.com/blog/2023/07/27/gitlab-flow-duo/). -<!-- This redirect file can be deleted after <2023-10-27>. --> +<!-- This redirect file can be deleted after <2024-07-27>. --> <!-- Redirects that point to other docs in the same project expire in three months. --> <!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/topics/manage_code.md b/doc/topics/manage_code.md index 0f1bfc73b27..5fbdbee7017 100644 --- a/doc/topics/manage_code.md +++ b/doc/topics/manage_code.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage your code **(FREE ALL)** diff --git a/doc/topics/offline/index.md b/doc/topics/offline/index.md index 56b523c9c6f..b29a06463ba 100644 --- a/doc/topics/offline/index.md +++ b/doc/topics/offline/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Offline GitLab **(FREE SELF)** diff --git a/doc/topics/offline/quick_start_guide.md b/doc/topics/offline/quick_start_guide.md index 4ff9975b317..b6340d905d4 100644 --- a/doc/topics/offline/quick_start_guide.md +++ b/doc/topics/offline/quick_start_guide.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install an offline self-managed GitLab instance **(FREE SELF)** @@ -98,7 +98,7 @@ Follow these steps to enable SSL for your fresh instance. These steps reflect th sudo gitlab-ctl reconfigure ``` -## Enabling the GitLab Container Registry +## Enabling the GitLab container registry Follow these steps to enable the container registry. These steps reflect those for [configuring the container registry under an existing domain](../../administration/packages/container_registry.md#configure-container-registry-under-an-existing-gitlab-domain): diff --git a/doc/topics/plan_and_track.md b/doc/topics/plan_and_track.md index 2ad46799316..3712d73929c 100644 --- a/doc/topics/plan_and_track.md +++ b/doc/topics/plan_and_track.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Plan and track work **(FREE ALL)** diff --git a/doc/topics/release_your_application.md b/doc/topics/release_your_application.md index e0580d52765..27c5cc50e5f 100644 --- a/doc/topics/release_your_application.md +++ b/doc/topics/release_your_application.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy and release your application **(FREE ALL)** diff --git a/doc/topics/set_up_organization.md b/doc/topics/set_up_organization.md index a8498ff970c..84d7bb1add0 100644 --- a/doc/topics/set_up_organization.md +++ b/doc/topics/set_up_organization.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up your organization **(FREE ALL)** diff --git a/doc/tutorials/agile_sprint/index.md b/doc/tutorials/agile_sprint/index.md index ea4234b118f..4c35182269b 100644 --- a/doc/tutorials/agile_sprint/index.md +++ b/doc/tutorials/agile_sprint/index.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Use GitLab to run an Agile iteration diff --git a/doc/tutorials/automate_runner_creation/index.md b/doc/tutorials/automate_runner_creation/index.md index 1241b760e2f..38261933d52 100644 --- a/doc/tutorials/automate_runner_creation/index.md +++ b/doc/tutorials/automate_runner_creation/index.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Automate runner creation and registration **(FREE ALL)** @@ -106,7 +106,7 @@ Before you begin, you need: is displayed in the project or group overview page, under the project or group name. -Use the access token in the [`POST /user/runners`](../../api/users.md#create-a-runner) +Use the access token in the [`POST /user/runners`](../../api/users.md#create-a-runner-linked-to-a-user) REST endpoint to create a runner: 1. Use `curl` to invoke the endpoint to create a runner: @@ -212,9 +212,8 @@ runners to Google Compute Engine: Now that you've automated your runner creation and automation, you can view the runners that use the same configuration in the GitLab UI. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **CI/CD > Runners**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **CI/CD > Runners**. 1. In the search box, enter the runner description or search the list of runners. 1. To view the runners that use the same configuration, in the **Details** tab, next to **Runners**, select **Show details**. diff --git a/doc/tutorials/boards_for_teams/index.md b/doc/tutorials/boards_for_teams/index.md index d4c44fb8967..8407605ecde 100644 --- a/doc/tutorials/boards_for_teams/index.md +++ b/doc/tutorials/boards_for_teams/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Set up issue boards for team hand-off **(PREMIUM ALL)** diff --git a/doc/tutorials/build_application.md b/doc/tutorials/build_application.md index 5f4b9da2aa3..9c10a755292 100644 --- a/doc/tutorials/build_application.md +++ b/doc/tutorials/build_application.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorials: Build your application @@ -15,7 +15,7 @@ Use CI/CD pipelines to automatically build, test, and deploy your code. | [Create and run your first GitLab CI/CD pipeline](../ci/quick_start/index.md) | Create a `.gitlab-ci.yml` file and start a pipeline. | **{star}** | | [Create a complex pipeline](../ci/quick_start/tutorial.md) | Learn about the most commonly used GitLab CI/CD keywords by building an increasingly complex pipeline. | | | <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Get started: Learn about CI/CD](https://www.youtube.com/watch?v=sIegJaLy2ug) (9m 02s) | Learn about the `.gitlab-ci.yml` file and how it's used. | **{star}** | -| [GitLab CI/CD](https://levelup.gitlab.com/courses/continuous-integration-and-delivery-ci-cd-with-gitlab) | Learn about GitLab CI/CD and build a pipeline in this self-paced course. | **{star}** | +| [GitLab CI Fundamentals](https://levelup.gitlab.com/learn/learning-path/gitlab-ci-fundamentals) | Learn about GitLab CI/CD and build a pipeline in this self-paced course. | **{star}** | | <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [CI deep dive](https://www.youtube.com/watch?v=ZVUbmVac-m8&list=PL05JrBw4t0KorkxIFgZGnzzxjZRCGROt_&index=27) (22m 51s) | Take a closer look at pipelines and continuous integration concepts. | | | [Set up CI/CD in the cloud](../ci/examples/index.md#cicd-in-the-cloud) | Learn how to set up CI/CD in different cloud-based environments. | | | [Find CI/CD examples and templates](../ci/examples/index.md#cicd-examples) | Use these examples and templates to set up CI/CD for your use case. | | diff --git a/doc/tutorials/compliance_pipeline/index.md b/doc/tutorials/compliance_pipeline/index.md index bc06e44fd48..c906b99cd18 100644 --- a/doc/tutorials/compliance_pipeline/index.md +++ b/doc/tutorials/compliance_pipeline/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Create a compliance pipeline **(ULTIMATE ALL)** diff --git a/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md b/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md index 9184ded230b..d73a00f1dfe 100644 --- a/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md +++ b/doc/tutorials/configure_gitlab_runner_to_use_gke/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Configure GitLab Runner to use the Google Kubernetes Engine **(FREE ALL)** diff --git a/doc/tutorials/container_scanning/index.md b/doc/tutorials/container_scanning/index.md index d1966cbb788..31eb14f0a50 100644 --- a/doc/tutorials/container_scanning/index.md +++ b/doc/tutorials/container_scanning/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition Analysis -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Scan a Docker container for vulnerabilities **(FREE ALL)** diff --git a/doc/tutorials/convert_personal_namespace_to_group/index.md b/doc/tutorials/convert_personal_namespace_to_group/index.md index 39bfebb7f4e..57acf14d981 100644 --- a/doc/tutorials/convert_personal_namespace_to_group/index.md +++ b/doc/tutorials/convert_personal_namespace_to_group/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Convert a personal namespace into a group **(FREE SAAS)** diff --git a/doc/tutorials/create_register_first_runner/index.md b/doc/tutorials/create_register_first_runner/index.md index 33e9f422125..5b57d8f35ea 100644 --- a/doc/tutorials/create_register_first_runner/index.md +++ b/doc/tutorials/create_register_first_runner/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create, register, and run your own project runner **(FREE ALL)** @@ -90,7 +90,7 @@ To create a project runner: 1. Expand the **Runners** section. 1. Select **New project runner**. 1. Select your operating system. -1. In the **Tags** section, select the **Run untagged** checkbox. [Tags](../../ci/runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) specify which jobs +1. In the **Tags** section, select the **Run untagged** checkbox. [Tags](../../ci/runners/configure_runners.md#control-jobs-that-a-runner-can-run) specify which jobs the runner can run and are optional. 1. Select **Create runner**. 1. Follow the on-screen instructions to register the runner from the command line. When prompted: diff --git a/doc/tutorials/dependency_scanning.md b/doc/tutorials/dependency_scanning.md index c513ce205d8..08f6d228ae7 100644 --- a/doc/tutorials/dependency_scanning.md +++ b/doc/tutorials/dependency_scanning.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Set up dependency scanning **(ULTIMATE SAAS)** diff --git a/doc/tutorials/develop.md b/doc/tutorials/develop.md index 349b0899027..bc0015b2d29 100644 --- a/doc/tutorials/develop.md +++ b/doc/tutorials/develop.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorials: Develop with GitLab diff --git a/doc/tutorials/export_sbom.md b/doc/tutorials/export_sbom.md index 716140045fb..474bd117b02 100644 --- a/doc/tutorials/export_sbom.md +++ b/doc/tutorials/export_sbom.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Export dependency list in SBOM format **(ULTIMATE ALL)** diff --git a/doc/tutorials/fuzz_testing/index.md b/doc/tutorials/fuzz_testing/index.md index 252a3501a32..b19cc07ede7 100644 --- a/doc/tutorials/fuzz_testing/index.md +++ b/doc/tutorials/fuzz_testing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Perform fuzz testing in GitLab **(ULTIMATE ALL)** diff --git a/doc/tutorials/gitlab_navigation.md b/doc/tutorials/gitlab_navigation.md index dc07805c426..738518e1aa7 100644 --- a/doc/tutorials/gitlab_navigation.md +++ b/doc/tutorials/gitlab_navigation.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorials: Find your way around GitLab @@ -16,5 +16,5 @@ and running quickly. | [Use the left sidebar to navigate GitLab](left_sidebar/index.md) | Start navigating the GitLab UI. | **{star}** | | [Use Markdown at GitLab](../user/markdown.md) | GitLab Flavored Markdown (GLFM) is used in many areas of GitLab, for example, in merge requests. | **{star}** | | <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Learn GitLab project walkthrough](https://www.youtube.com/watch?v=-oaI2WEKdI4&list=PL05JrBw4t0KofkHq4GZJ05FnNGa11PQ4d) (59m 2s) | Step through the tutorial-style issues in the **Learn GitLab** project. If you don't have this project, download [the export file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/project_templates/learn_gitlab_ultimate.tar.gz) and [import it to a new project](../user/project/settings/import_export.md#import-a-project-and-its-data). | | -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [GitLab Continuous Delivery overview](https://www.youtube.com/watch?v=g-gO93PMZvk&list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED&index=134) (17m 2s) | Learn how to use GitLab features to continuously build, test, and deploy iterative code changes. | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [GitLab Continuous Delivery overview](https://www.youtube.com/watch?v=M7rBDZYsx8U&list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED&index=193) (17m 2s) | Learn how to use GitLab features to continuously build, test, and deploy iterative code changes. | | | [Productivity tips](https://about.gitlab.com/blog/2021/02/18/improve-your-gitlab-productivity-with-these-10-tips/) | Get tips to help make you a productive GitLab user. | | diff --git a/doc/tutorials/hugo/index.md b/doc/tutorials/hugo/index.md index cd2bc32e94b..b9331270ea1 100644 --- a/doc/tutorials/hugo/index.md +++ b/doc/tutorials/hugo/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Build, test, and deploy your Hugo site with GitLab diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md index b06cd224d0c..8f02744b371 100644 --- a/doc/tutorials/index.md +++ b/doc/tutorials/index.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Learn GitLab with tutorials diff --git a/doc/tutorials/infrastructure.md b/doc/tutorials/infrastructure.md index ee4fc748c0e..49cd0e95230 100644 --- a/doc/tutorials/infrastructure.md +++ b/doc/tutorials/infrastructure.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorials: Manage your infrastructure diff --git a/doc/tutorials/install_gitlab_single_node/index.md b/doc/tutorials/install_gitlab_single_node/index.md index 5b81e10ddb1..06f3369b1fb 100644 --- a/doc/tutorials/install_gitlab_single_node/index.md +++ b/doc/tutorials/install_gitlab_single_node/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Install and secure a single node GitLab instance **(FREE SELF)** diff --git a/doc/tutorials/issue_triage/index.md b/doc/tutorials/issue_triage/index.md index fec0e0f82c3..5d0dd1dbec1 100644 --- a/doc/tutorials/issue_triage/index.md +++ b/doc/tutorials/issue_triage/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Set up a single project for issue triage **(FREE ALL)** diff --git a/doc/tutorials/learn_git.md b/doc/tutorials/learn_git.md index afc4ef90ffc..2ebc1f3fd0e 100644 --- a/doc/tutorials/learn_git.md +++ b/doc/tutorials/learn_git.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorials: Learn Git diff --git a/doc/tutorials/left_sidebar/img/admin_area_v16_4.png b/doc/tutorials/left_sidebar/img/admin_area_v16_4.png Binary files differdeleted file mode 100644 index d7757319506..00000000000 --- a/doc/tutorials/left_sidebar/img/admin_area_v16_4.png +++ /dev/null diff --git a/doc/tutorials/left_sidebar/img/admin_area_v16_7.png b/doc/tutorials/left_sidebar/img/admin_area_v16_7.png Binary files differnew file mode 100644 index 00000000000..2026934a3c6 --- /dev/null +++ b/doc/tutorials/left_sidebar/img/admin_area_v16_7.png diff --git a/doc/tutorials/left_sidebar/img/your_work_v16_4.png b/doc/tutorials/left_sidebar/img/your_work_v16_4.png Binary files differindex 7c02a250ce6..f7295c985f6 100644 --- a/doc/tutorials/left_sidebar/img/your_work_v16_4.png +++ b/doc/tutorials/left_sidebar/img/your_work_v16_4.png diff --git a/doc/tutorials/left_sidebar/index.md b/doc/tutorials/left_sidebar/index.md index be631a20d50..b4833a26ca6 100644 --- a/doc/tutorials/left_sidebar/index.md +++ b/doc/tutorials/left_sidebar/index.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Use the left sidebar to navigate GitLab **(FREE ALL)** @@ -82,6 +82,6 @@ Then, on the left sidebar, **Your work** is displayed. ## Go to the Admin Area -The Admin Area is also available on the left sidebar when you select **Search or go to**: +The Admin Area is also available on the left sidebar at the bottom: - + diff --git a/doc/tutorials/make_first_git_commit/index.md b/doc/tutorials/make_first_git_commit/index.md index 92bf2572078..1663fa08ad6 100644 --- a/doc/tutorials/make_first_git_commit/index.md +++ b/doc/tutorials/make_first_git_commit/index.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Make your first Git commit diff --git a/doc/tutorials/manage_user/index.md b/doc/tutorials/manage_user/index.md index b60fd300b5d..836d1b71c1d 100644 --- a/doc/tutorials/manage_user/index.md +++ b/doc/tutorials/manage_user/index.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Set up your organization **(FREE SELF)** @@ -106,9 +106,8 @@ for the organization. You will now manually create the users for your organization. These are test users. To create the first test user, Alex Smith: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Overview > Users**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Overview > Users**. 1. Select **New user**. 1. Complete the required fields: - **Name**: `Alex Smith` @@ -424,36 +423,3 @@ directly to the project. You have successfully added three users who are members of subgroups to a project in the parent group, and given those users specific roles in the project and parent group. - -## Change the visibility of individual features in a project - -You have already seen how you can control access to and permissions in groups and -projects by assigning roles. - -You can also change the visibility of individual features in a project. You cannot -do this for groups. - -1. On the left sidebar, select **Search or go to** and find the **Release 2.0** project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. In **Project visibility**, you can who can see the project in the public access - directory. Because the parent group is private, you can only select **Private**. - -You will now use the toggle by each feature to turn features on or off, or change access for. - -1. For **Issues**, leave the feature turned on. -1. In the **Repository** section: - - Leave **Merge requests** and **Forks** turned on. - - Turn off **Git Large File Storage (LFS)** and **CI/CD**. -1. For **Analytics**, **Security and Compliance**, **Wiki**, **Snippets**, and - **Package registry**, leave these features turned on. -1. Turn off **Monitor**, **Environments**, **Feature flags**, **Infrastructure**, - and **Releases**. -1. Select the **Disable email notifications** checkbox. Leave the other checkboxes as is. -1. Select **Save changes**. - -You have changed the visibility of individual features in a project. Now, regardless -of role, the members of this project cannot access the features that you have turned off. - -In this tutorial, you've set up your groups, subgroups, projects, and members -with roles precisely to reflect the structure and workflow of your organization. diff --git a/doc/tutorials/more_tutorials.md b/doc/tutorials/more_tutorials.md index 19b3a709ab7..e3fce230b70 100644 --- a/doc/tutorials/more_tutorials.md +++ b/doc/tutorials/more_tutorials.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Find more tutorial content @@ -11,7 +11,7 @@ If you're learning about GitLab, to find more tutorial content: - Find learning tracks and certification options at [Level Up](https://levelup.gitlab.com/). GitLab learning platform login required (email and password for non-GitLab team members). -- Find recent tutorials on the GitLab blog by [searching by the `tutorial` tag](https://about.gitlab.com/blog/tags.html#tutorial). +- Find recent tutorials on the [GitLab blog](https://about.gitlab.com/blog/). - Browse the **GitLab Snapshots** [playlist on YouTube](https://www.youtube.com/playlist?list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED) to find video tutorials. diff --git a/doc/tutorials/move_personal_project_to_group/index.md b/doc/tutorials/move_personal_project_to_group/index.md index 73d22de6983..0abbba3874e 100644 --- a/doc/tutorials/move_personal_project_to_group/index.md +++ b/doc/tutorials/move_personal_project_to_group/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Move your personal project to a group **(FREE SAAS)** @@ -70,7 +70,7 @@ project. NOTE: For more information about these migration steps, -see [Transferring your project into another namespace](../../user/project/settings/index.md#transfer-a-project-to-another-namespace). +see [Transferring your project into another namespace](../../user/project/settings/migrate_projects.md#transfer-a-project-to-another-namespace). A migration might result in follow-up work to update the project path in your related resources and tools, such as websites and package managers. diff --git a/doc/tutorials/plan_and_track.md b/doc/tutorials/plan_and_track.md index c5c2919cac7..b3ec1fb4755 100644 --- a/doc/tutorials/plan_and_track.md +++ b/doc/tutorials/plan_and_track.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorials: Plan and track your work @@ -11,9 +11,10 @@ issues, epics, and more. | Topic | Description | Good for beginners | |-------|-------------|--------------------| -| [GitLab Agile Project Management](https://levelup.gitlab.com/courses/gitlab-agile-project-management) | Learn how to use planning features to manage your projects in this self-paced course. | **{star}** | +| [GitLab Agile Project Management](https://levelup.gitlab.com/courses/gitlab-agile-project-management-s2) | Learn how to use planning features to manage your projects in this self-paced course. | **{star}** | | [Build a protected workflow for your project](protected_workflow/index.md) | Set up a workflow for your teams, and enforce protections with approval rules. | | | [Run an agile iteration](agile_sprint/index.md) | Use group, projects, and iterations to run an agile development iteration. | | [Set up a single project for issue triage](issue_triage/index.md) | Use labels to set up a project for issue triage. | **{star}** | | [Set up issue boards for team hand-off](boards_for_teams/index.md) | Use issue boards and scoped labels to set up collaboration across many teams. | **{star}** | -| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Epics and Issue Boards](https://www.youtube.com/watch?v=I1bFIAQBHB8) | Find out how to use epics and issue boards for project management. | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Epics and issue boards](https://www.youtube.com/watch?v=eQUnHwbKEkY) | Find out how to use epics and issue boards for project management. | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Portfolio Planning - Portfolio Management](https://www.youtube.com/watch?v=d9scVJUIF4c) | Find out how manage your portfolio with requirements, issues, epics, milestones, and time tracking. | | diff --git a/doc/tutorials/product_analytics_onboarding_website_project/index.md b/doc/tutorials/product_analytics_onboarding_website_project/index.md index c0c3d7bb3d9..b6039cd687b 100644 --- a/doc/tutorials/product_analytics_onboarding_website_project/index.md +++ b/doc/tutorials/product_analytics_onboarding_website_project/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Product Analytics -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Set up product analytics in a GitLab Pages website project **(ULTIMATE ALL EXPERIMENT)** diff --git a/doc/tutorials/protected_workflow/index.md b/doc/tutorials/protected_workflow/index.md index 64138b15315..8e9ed3e952a 100644 --- a/doc/tutorials/protected_workflow/index.md +++ b/doc/tutorials/protected_workflow/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- <!-- vale gitlab.FutureTense = NO --> @@ -258,7 +258,7 @@ to protect multiple branches: to files they work on, toggle **Require approval from code owners**. 1. Select **Protect**. 1. In the table of branches, find the rule marked as `Default`. (Depending on - your version of GitLab, this branch may be named `main` or `master`.) Set the + your version of GitLab, this branch might be named `main` or `master`.) Set the values for this branch to match the settings you used for the `1.*` rule. Your rules are now in place, even though no `1.*` branches exist yet: diff --git a/doc/tutorials/scan_execution_policy/index.md b/doc/tutorials/scan_execution_policy/index.md index e9c58b07c85..1e2c91e6c45 100644 --- a/doc/tutorials/scan_execution_policy/index.md +++ b/doc/tutorials/scan_execution_policy/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Set up a scan execution policy **(ULTIMATE ALL)** diff --git a/doc/tutorials/scan_result_policy/index.md b/doc/tutorials/scan_result_policy/index.md index 46005bd8e56..8f31510dfbc 100644 --- a/doc/tutorials/scan_result_policy/index.md +++ b/doc/tutorials/scan_result_policy/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Set up a scan result policy **(ULTIMATE ALL)** @@ -30,6 +30,7 @@ The namespace used for this tutorial must: - **Project name**: `sast-scan-result-policy`. - Select the **Enable Static Application Security Testing (SAST)** checkbox. 1. Select **Create project**. +1. Go to the newly created project and create [protected branches](../../user/project/protected_branches.md). ## Add a scan result policy diff --git a/doc/tutorials/secure_application.md b/doc/tutorials/secure_application.md index 606ca4d2909..4868ec53ed3 100644 --- a/doc/tutorials/secure_application.md +++ b/doc/tutorials/secure_application.md @@ -1,7 +1,7 @@ --- stage: none group: Tutorials -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorials: Secure your application and check compliance diff --git a/doc/tutorials/update_commit_messages/index.md b/doc/tutorials/update_commit_messages/index.md index 76acba95e04..0228b33e3de 100644 --- a/doc/tutorials/update_commit_messages/index.md +++ b/doc/tutorials/update_commit_messages/index.md @@ -1,23 +1,23 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- -# Tutorial: How to update Git commit messages **(FREE ALL)** +# Tutorial: Update Git commit messages **(FREE ALL)** Occasionally, after you've made a few commits to your branch, you realize you need to update one or more commit messages. Perhaps you found a typo, or some automation warned you that your commit message didn't completely align with a project's [commit message guidelines](../../development/contributing/merge_request_workflow.md#commit-messages-guidelines). -Updating the message can be tricky if you don't have much practice with using Git +Updating the message can be tricky if you don't have much practice using Git from the command-line interface (CLI). But don't worry, even if you have only ever worked in -the GitLab UI, we'll walk you through the steps to use the CLI. +the GitLab UI, you can follow these steps to use the CLI. This tutorial explains how to rewrite commit messages in both cases: -- If you work from just the GitLab UI, start at step 1. +- If you work in the GitLab UI only, start at step 1. - If you already have your repository cloned locally, you can skip to step 2. To rewrite any number of commit messages: @@ -44,14 +44,14 @@ You must have: you should first verify with them that it's OK to update the commits. Some organizations might have rules against rewriting commits, as it is considered a destructive change. -You need to authenticate with GitLab to overwrite the commit messages in the final step. +You must authenticate with GitLab to overwrite the commit messages in the final step. If your GitLab account uses basic username and password authentication, you must have [two factor authentication (2FA)](../../user/profile/account/two_factor_authentication.md) disabled to authenticate from the CLI. Alternatively, you can [use an SSH key to authenticate with GitLab](../../user/ssh.md). ## Clone your repository to your local machine -The first thing you need to do is get the repository on your local machine: +The first step is to get a clone of the repository on your local machine: 1. In GitLab, on your project's overview page, on the top right, select **Clone**. 1. In the dropdown list, copy the URL for your repository by selecting **{copy-to-clipboard}** next to: @@ -71,7 +71,7 @@ Now your repository is on your computer, ready for your Git CLI commands! ## Fetch and check out your branch -Next we need to check out the branch that contains the commits to update. +Next, you need to check out the branch that contains the commits to update. 1. Assuming you are still at the same place in the CLI as the previous step, change to your project directory with `cd`: @@ -99,9 +99,9 @@ Next we need to check out the branch that contains the commits to update. ## Update the commit messages -Now we are ready to update the commit messages: +Now you are ready to update the commit messages: -1. In GitLab, see how far back in the commit history you need to go: +1. In GitLab, check how far back in the commit history you need to go: - If you already have a merge request open for your branch, you can check the **Commits** tab and use the total number of commits. @@ -158,7 +158,7 @@ Now we are ready to update the commit messages: 1. Save the edited text. Press <kbd>Escape</kbd> to exit `INSERT` mode, then type `:wq` and <kbd>Enter</kbd> to save and exit. -1. Git now goes through each commit one at a time and applies the commands we selected. +1. Git now goes through each commit one at a time and applies the commands you selected. Any commits with `pick` are added back to the branch unchanged. When Git reaches a commit with `reword`, it stops and again opens up the text editor. Now it's time to finally update the text of the commit message! @@ -189,7 +189,8 @@ Now we are ready to update the commit messages: Now all that's left is to push these changes up to GitLab: -1. From the CLI, force push the changes to overwrite what exists in the branch in GitLab. +1. From the CLI, push the changes back to GitLab. You must use the `-f` "force push" option, + because the commits were updated and a force push overwrites the old commits in GitLab. ```shell git push -f origin diff --git a/doc/tutorials/website_project_with_analytics/index.md b/doc/tutorials/website_project_with_analytics/index.md index 90e85d0f88c..1f11c5a4593 100644 --- a/doc/tutorials/website_project_with_analytics/index.md +++ b/doc/tutorials/website_project_with_analytics/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Tutorial: Set up an analytics-powered website project **(ULTIMATE ALL)** @@ -70,7 +70,7 @@ To invite a user to the `My website` project: 1. Select **Invite**. The invited user should now be a member of the project. -You can [view, filter, and search for members](../../user/project/members/index.md#filter-and-sort-members) of your project. +You can [view, filter, and search for members](../../user/project/members/index.md#filter-and-sort-project-members) of your project. ## Create project labels diff --git a/doc/update/background_migrations.md b/doc/update/background_migrations.md index 5a4b19016f8..8f7e4cc7b1d 100644 --- a/doc/update/background_migrations.md +++ b/doc/update/background_migrations.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Database -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Background migrations and upgrades **(FREE SELF)** @@ -67,8 +67,7 @@ Prerequisites: To check the status of batched background migrations: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Monitoring > Background Migrations**. 1. Select **Queued** or **Finalizing** to see incomplete migrations, and **Failed** for failed migrations. @@ -96,6 +95,15 @@ To query the database directly for the status of batched background migrations: WHERE status <> 3; ``` +Alternatively, you can wrap the query with `gitlab-psql -c "<QUERY>"` to check the status of +batched background migrations: + +```shell +gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status <> 3;" +``` + +If the query returns zero rows, all batched background migrations are complete. + ### Enable or disable advanced features Batched background migrations provide feature flags that enable you to customize @@ -217,8 +225,7 @@ Prerequisites: - You must have administrator access to the instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Monitoring > Background Migrations**. 1. Select the **Failed** tab. This displays a list of failed batched background migrations. 1. Select the failed **Migration** to see the migration parameters and the jobs that failed. @@ -233,8 +240,7 @@ Prerequisites: - You must have administrator access to the instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Monitoring > Background Migrations**. 1. Select the **Failed** tab. This displays a list of failed batched background migrations. 1. Select a failed batched background migration to retry by clicking on the retry button (**{retry}**). diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index 333dad86086..cba85b1acd9 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -1,7 +1,7 @@ --- stage: none group: none -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" toc: false --- @@ -69,7 +69,7 @@ The configuration arguments disabled for authentication tokens are: - `--run-untagged` - `--tag-list` -This change is a breaking change. You should use an [authentication token](../ci/runners/register_runner.md) in the `gitlab-runner register` command instead. +This change is a breaking change. You should use an [authentication token](../ci/runners/runners_scope.html) in the `gitlab-runner register` command instead. </div> @@ -96,7 +96,7 @@ The configuration arguments disabled for authentication tokens are: - `--tag-list` - `--maintenance-note` -This change is a breaking change. You should [create a runner in the UI](../ci/runners/register_runner.md) to add configurations, and use the authentication token in the `gitlab-runner register` command instead. +This change is a breaking change. You should [create a runner in the UI](../ci/runners/runners_scope.html) to add configurations, and use the authentication token in the `gitlab-runner register` command instead. </div> @@ -259,7 +259,7 @@ the aliasing for the `CiRunnerUpgradeStatusType` type will be removed. <div class="deprecation breaking-change" data-milestone="17.0"> -### Container Registry support for the Swift and OSS storage drivers +### Container registry support for the Swift and OSS storage drivers <div class="deprecation-notes"> - Announced in GitLab <span class="milestone">16.6</span> @@ -317,6 +317,38 @@ In 16.3, the names of these settings were changed to clarify their meanings: the <div class="deprecation breaking-change" data-milestone="17.0"> +### Dependency Proxy: Access tokens to have additional scope checks + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.7</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/431386). +</div> + +When using the Dependency Proxy for containers with a group access token or personal access token, `docker login` and `docker pull` requests with insufficient scopes for Dependency Proxy are not rejected. + +GitLab 17.0 adds checks for group or personal access tokens authenticating with the dependency proxy for containers. This is a breaking change, because tokens without the required scopes will fail. + +To help avoid being impacted by this breaking change, create new access tokens with the [required scopes](https://docs.gitlab.com/ee/user/packages/dependency_proxy/#authenticate-with-the-dependency-proxy), and update your workflow variables and scripts with those new tokens. + +</div> + +<div class="deprecation " data-milestone="17.0"> + +### Deprecate GraphQL fields related to the temporary storage increase + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.7</span> +- Removal in GitLab <span class="milestone">17.0</span> +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/385720). +</div> + +The GraphQL fields, `isTemporaryStorageIncreaseEnabled` and `temporaryStorageIncreaseEndsOn`, have been deprecated. These GraphQL fields are related to the temporary storage increase project. The project has been cancelled and the fields were not used. + +</div> + +<div class="deprecation breaking-change" data-milestone="17.0"> + ### Deprecate Windows CMD in GitLab Runner <div class="deprecation-notes"> @@ -685,7 +717,7 @@ In GitLab 16.0 and later: <div class="deprecation breaking-change" data-milestone="17.0"> -### Internal Container Registry API tag deletion endpoint +### Internal container registry API tag deletion endpoint <div class="deprecation-notes"> - Announced in GitLab <span class="milestone">16.4</span> @@ -695,7 +727,7 @@ In GitLab 16.0 and later: The [Docker Registry HTTP API V2 Spec](https://docs.docker.com/registry/spec/api/), later replaced by the [OCI Distribution Spec](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) did not include a tag delete operation, and an unsafe and slow workaround (involving deleting manifests, not tags) had to be used to achieve the same end. -Tag deletion is an important function, so we added a tag deletion operation to the GitLab Container Registry, extending the V2 API beyond the scope of the Docker and OCI distribution spec. +Tag deletion is an important function, so we added a tag deletion operation to the GitLab container registry, extending the V2 API beyond the scope of the Docker and OCI distribution spec. Since then, the OCI Distribution Spec has had some updates and it now has a tag delete operation, using the [`DELETE /v2/<name>/manifests/<tag>` endpoint](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#deleting-tags). @@ -703,7 +735,7 @@ This leaves the container registry with two endpoints that provide the exact sam Support for the custom GitLab tag delete endpoint is deprecated in GitLab 16.4, and it will be removed in GitLab 17.0. -This endpoint is used by the **internal** Container Registry application API, not the public [GitLab Container Registry API](https://docs.gitlab.com/ee/api/container_registry.html). No action should be required by the majority of container registry users. All the GitLab UI and API functionality related to tag deletions will remain intact as we transition to the new OCI-compliant endpoint. +This endpoint is used by the **internal** container registry application API, not the public [GitLab container registry API](https://docs.gitlab.com/ee/api/container_registry.html). No action should be required by the majority of container registry users. All the GitLab UI and API functionality related to tag deletions will remain intact as we transition to the new OCI-compliant endpoint. If you do access the internal container registry API and use the original tag deletion endpoint, you must update to the new endpoint. @@ -711,6 +743,20 @@ If you do access the internal container registry API and use the original tag de <div class="deprecation breaking-change" data-milestone="17.0"> +### JWT `/-/jwks` instance endpoint is deprecated + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.7</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/221031). +</div> + +With the [deprecation of old JSON web token versions](https://docs.gitlab.com/ee/update/deprecations.html?removal_milestone=17.0#old-versions-of-json-web-tokens-are-deprecated) in GitLab 17.0, the associated `/-/jwks` endpoint which is an alias for `/oauth/discovery/keys` is no longer necessary and will be removed. Please replace any uses of `/-/jwks` with `/oauth/discovery/keys`, for example change `https://gitlab.example.com/-/jwks` to `https://gitlab.example.com/oauth/discovery/keys`. + +</div> + +<div class="deprecation breaking-change" data-milestone="17.0"> + ### Legacy Geo Prometheus metrics <div class="deprecation-notes"> @@ -738,6 +784,23 @@ The table below lists the deprecated metrics and their respective replacements. <div class="deprecation breaking-change" data-milestone="17.0"> +### List repository directories Rake task + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">16.7</span> +- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/384361). +</div> + +The `gitlab-rake gitlab:list_repos` Rake task does not work and will be removed in GitLab 17.0. +If you're migrating GitLab, use +[backup and restore](https://docs.gitlab.com/ee/administration/operations/moving_repositories.html#recommended-approach-in-all-cases) +instead. + +</div> + +<div class="deprecation breaking-change" data-milestone="17.0"> + ### Maintainer role providing the ability to change Package settings using GraphQL API <div class="deprecation-notes"> @@ -936,7 +999,7 @@ The configuration arguments disabled for authentication tokens are: - `--tag-list` - `--maintenance-note` -This change is a breaking change. You should [create a runner in the UI](../ci/runners/register_runner.md) to add configurations, and use the authentication token in the `gitlab-runner register` command instead. +This change is a breaking change. You should [create a runner in the UI](../ci/runners/runners_scope.html) to add configurations, and use the authentication token in the `gitlab-runner register` command instead. </div> @@ -1322,6 +1385,41 @@ To prepare for GitLab 15.8 and later, you should: </div> </div> +<div class="milestone-wrapper" data-milestone="16.7"> + +## GitLab 16.7 + +<div class="deprecation breaking-change" data-milestone="16.7"> + +### Shimo integration + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">15.7</span> +- Removal in GitLab <span class="milestone">16.7</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/377824). +</div> + +The [Shimo Workspace integration](https://docs.gitlab.com/ee/user/project/integrations/shimo.html) has been deprecated +and will be moved to the JiHu GitLab codebase. + +</div> + +<div class="deprecation breaking-change" data-milestone="16.7"> + +### `user_email_lookup_limit` API field + +<div class="deprecation-notes"> +- Announced in GitLab <span class="milestone">14.9</span> +- Removal in GitLab <span class="milestone">16.7</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) +</div> + +The `user_email_lookup_limit` [API field](https://docs.gitlab.com/ee/api/settings.html) is deprecated in GitLab 14.9 and removed in GitLab 16.7. Until the feature is removed, `user_email_lookup_limit` is aliased to `search_rate_limit` and existing workflows still work. + +Any API calls to change the rate limits for `user_email_lookup_limit` must use `search_rate_limit` instead. + +</div> +</div> + <div class="milestone-wrapper" data-milestone="16.6"> ## GitLab 16.6 @@ -1682,29 +1780,29 @@ config file locations instead, for example `config/redis.cache.yml` or <div class="deprecation breaking-change" data-milestone="16.0"> -### Container Registry pull-through cache +### Container Scanning variables that reference Docker <div class="deprecation-notes"> -- Announced in GitLab <span class="milestone">15.8</span> +- Announced in GitLab <span class="milestone">15.4</span> - Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) -- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/container-registry/-/issues/842). +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/371840). </div> -The Container Registry [pull-through cache](https://docs.docker.com/registry/recipes/mirror/) is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. The pull-through cache is part of the upstream [Docker Distribution project](https://github.com/distribution/distribution). However, we are removing the pull-through cache in favor of the GitLab Dependency Proxy, which allows you to proxy and cache container images from Docker Hub. Removing the pull-through cache allows us also to remove the upstream client code without sacrificing functionality. +All Container Scanning variables that are prefixed by `DOCKER_` in variable name are deprecated. This includes the `DOCKER_IMAGE`, `DOCKER_PASSWORD`, `DOCKER_USER`, and `DOCKERFILE_PATH` variables. Support for these variables will be removed in the GitLab 16.0 release. Use the [new variable names](https://docs.gitlab.com/ee/user/application_security/container_scanning/#available-cicd-variables) `CS_IMAGE`, `CS_REGISTRY_PASSWORD`, `CS_REGISTRY_USER`, and `CS_DOCKERFILE_PATH` in place of the deprecated names. </div> <div class="deprecation breaking-change" data-milestone="16.0"> -### Container Scanning variables that reference Docker +### Container registry pull-through cache <div class="deprecation-notes"> -- Announced in GitLab <span class="milestone">15.4</span> +- Announced in GitLab <span class="milestone">15.8</span> - Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) -- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/371840). +- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/container-registry/-/issues/842). </div> -All Container Scanning variables that are prefixed by `DOCKER_` in variable name are deprecated. This includes the `DOCKER_IMAGE`, `DOCKER_PASSWORD`, `DOCKER_USER`, and `DOCKERFILE_PATH` variables. Support for these variables will be removed in the GitLab 16.0 release. Use the [new variable names](https://docs.gitlab.com/ee/user/application_security/container_scanning/#available-cicd-variables) `CS_IMAGE`, `CS_REGISTRY_PASSWORD`, `CS_REGISTRY_USER`, and `CS_DOCKERFILE_PATH` in place of the deprecated names. +The container registry [pull-through cache](https://docs.docker.com/registry/recipes/mirror/) is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. The pull-through cache is part of the upstream [Docker Distribution project](https://github.com/distribution/distribution). However, we are removing the pull-through cache in favor of the GitLab Dependency Proxy, which allows you to proxy and cache container images from Docker Hub. Removing the pull-through cache allows us also to remove the upstream client code without sacrificing functionality. </div> @@ -2617,21 +2715,6 @@ For more information, refer to [security report validation](https://docs.gitlab. <div class="deprecation breaking-change" data-milestone="16.0"> -### Shimo integration - -<div class="deprecation-notes"> -- Announced in GitLab <span class="milestone">15.7</span> -- Removal in GitLab <span class="milestone">16.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) -- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/377824). -</div> - -The [Shimo Workspace integration](https://docs.gitlab.com/ee/user/project/integrations/shimo.html) has been deprecated -and will be moved to the JiHu GitLab codebase. - -</div> - -<div class="deprecation breaking-change" data-milestone="16.0"> - ### Starboard directive in the config for the GitLab Agent for Kubernetes <div class="deprecation-notes"> @@ -2820,13 +2903,13 @@ You can use the vulnerabilityFindingDismiss GraphQL mutation to set the status o Using third-party container registries with GitLab as an auth endpoint is deprecated in GitLab 15.8 and the [end of support](https://docs.gitlab.com/ee/development/deprecation_guidelines/#terminology) is scheduled for GitLab 16.0. This impacts self-managed customers that have connected their external registry to the GitLab user interface to find, view, and delete container images. -Supporting both GitLab's Container Registry as well as third-party container registries is challenging for maintenance, code quality, and backward compatibility. This hinders our ability to stay [efficient](https://about.gitlab.com/handbook/values/#efficiency). As a result we will not support this functionality moving forward. +Supporting both GitLab's container registry as well as third-party container registries is challenging for maintenance, code quality, and backward compatibility. This hinders our ability to stay [efficient](https://about.gitlab.com/handbook/values/#efficiency). As a result we will not support this functionality moving forward. This change will not impact your ability to pull and push container images to external registries using pipelines. -Since we released the new [GitLab Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/5523) version for GitLab.com, we've started to implement additional features that are not available in third-party container registries. These new features have allowed us to achieve significant performance improvements, such as [cleanup policies](https://gitlab.com/groups/gitlab-org/-/epics/8379). We are focusing on delivering [new features](https://gitlab.com/groups/gitlab-org/-/epics/5136), most of which will require functionalities only available on the GitLab Container Registry. This deprecation allows us to reduce fragmentation and user frustration in the long term by focusing on delivering a more robust integrated registry experience and feature set. +Since we released the new [GitLab container registry](https://gitlab.com/groups/gitlab-org/-/epics/5523) version for GitLab.com, we've started to implement additional features that are not available in third-party container registries. These new features have allowed us to achieve significant performance improvements, such as [cleanup policies](https://gitlab.com/groups/gitlab-org/-/epics/8379). We are focusing on delivering [new features](https://gitlab.com/groups/gitlab-org/-/epics/5136), most of which will require functionalities only available on the GitLab container registry. This deprecation allows us to reduce fragmentation and user frustration in the long term by focusing on delivering a more robust integrated registry experience and feature set. -Moving forward, we'll continue to invest in developing and releasing new features that will only be available in the GitLab Container Registry. +Moving forward, we'll continue to invest in developing and releasing new features that will only be available in the GitLab container registry. </div> @@ -3734,12 +3817,12 @@ an inline argument expression). - Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> -The GitLab Package stage offers a Package Registry, Container Registry, and Dependency Proxy to help you manage all of your dependencies using GitLab. Each of these product categories has a variety of settings that can be adjusted using the API. +The GitLab Package stage offers a Package Registry, container registry, and Dependency Proxy to help you manage all of your dependencies using GitLab. Each of these product categories has a variety of settings that can be adjusted using the API. The permissions model for GraphQL is being updated. After 15.0, users with the Guest, Reporter, and Developer role can no longer update these settings: - [Package Registry settings](https://docs.gitlab.com/ee/api/graphql/reference/#packagesettings) -- [Container Registry cleanup policy](https://docs.gitlab.com/ee/api/graphql/reference/#containerexpirationpolicy) +- [Container registry cleanup policy](https://docs.gitlab.com/ee/api/graphql/reference/#containerexpirationpolicy) - [Dependency Proxy time-to-live policy](https://docs.gitlab.com/ee/api/graphql/reference/#dependencyproxyimagettlgrouppolicy) - [Enabling the Dependency Proxy for your group](https://docs.gitlab.com/ee/api/graphql/reference/#dependencyproxysetting) @@ -4335,7 +4418,7 @@ Tracing in GitLab is an integration with Jaeger, an open-source end-to-end distr <div class="deprecation breaking-change" data-milestone="15.0"> -### Update to the Container Registry group-level API +### Update to the container registry group-level API <div class="deprecation-notes"> - Announced in GitLab <span class="milestone">14.5</span> @@ -4343,7 +4426,7 @@ Tracing in GitLab is an integration with Jaeger, an open-source end-to-end distr - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336912). </div> -In milestone 15.0, support for the `tags` and `tags_count` parameters will be removed from the Container Registry API that [gets registry repositories from a group](../api/container_registry.md#within-a-group). +In milestone 15.0, support for the `tags` and `tags_count` parameters will be removed from the container registry API that [gets registry repositories from a group](../api/container_registry.md#within-a-group). The `GET /groups/:id/registry/repositories` endpoint will remain, but won't return any info about tags. To get the info about tags, you can use the existing `GET /registry/repositories/:id` endpoint, which will continue to support the `tags` and `tag_count` options as it does today. The latter must be called once per image repository. @@ -4558,33 +4641,18 @@ If you have explicitly excluded bundler-audit using DS_EXCLUDED_ANALYZERS you wi <div class="deprecation breaking-change" data-milestone="15.0"> -### htpasswd Authentication for the Container Registry +### htpasswd Authentication for the container registry <div class="deprecation-notes"> - Announced in GitLab <span class="milestone">14.9</span> - Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) </div> -The Container Registry supports [authentication](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/configuration.md#auth) with `htpasswd`. It relies on an [Apache `htpasswd` file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html), with passwords hashed using `bcrypt`. +The container registry supports [authentication](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/configuration.md#auth) with `htpasswd`. It relies on an [Apache `htpasswd` file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html), with passwords hashed using `bcrypt`. Since it isn't used in the context of GitLab (the product), `htpasswd` authentication will be deprecated in GitLab 14.9 and removed in GitLab 15.0. </div> - -<div class="deprecation breaking-change" data-milestone="15.0"> - -### user_email_lookup_limit API field - -<div class="deprecation-notes"> -- Announced in GitLab <span class="milestone">14.9</span> -- Removal in GitLab <span class="milestone">15.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change)) -</div> - -The `user_email_lookup_limit` [API field](https://docs.gitlab.com/ee/api/settings.html) is deprecated and will be removed in GitLab 15.0. Until GitLab 15.0, `user_email_lookup_limit` is aliased to `search_rate_limit` and existing workflows will continue to work. - -Any API calls attempting to change the rate limits for `user_email_lookup_limit` should use `search_rate_limit` instead. - -</div> </div> <div class="milestone-wrapper" data-milestone="14.10"> diff --git a/doc/update/index.md b/doc/update/index.md index f7e3a0e3403..c0a6b64a1ac 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading GitLab **(FREE SELF)** @@ -195,7 +195,7 @@ When upgrading: - GitLab 16: [`16.0.x`](versions/gitlab_16_changes.md#1600) (only instances with [lots of users](versions/gitlab_16_changes.md#long-running-user-type-data-change) or [large pipeline variables history](versions/gitlab_16_changes.md#1610)) > - [`16.1`](versions/gitlab_16_changes.md#1610)(instances with NPM packages in their Package Registry) > + [`16.1`](versions/gitlab_16_changes.md#1610) (instances with NPM packages in their package registry) > [`16.2.x`](versions/gitlab_16_changes.md#1620) (only instances with [large pipeline variables history](versions/gitlab_16_changes.md#1630)) > [`16.3`](versions/gitlab_16_changes.md#1630) > [latest `16.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases). @@ -218,7 +218,7 @@ upgrade stops allow required background migrations to finish. During GitLab 16.x, we are scheduling required upgrade stops beforehand so users can better plan out appropriate upgrade stops and downtime when necessary. -The first scheduled required upgrade stop has been announced for 16.3.x. When planning upgrades, please take this into account. +The first scheduled required upgrade stop has been announced for 16.3.x. When planning upgrades, take this into account. ### Earlier GitLab versions diff --git a/doc/update/package/convert_to_ee.md b/doc/update/package/convert_to_ee.md index 31de896349c..5a76c85e915 100644 --- a/doc/update/package/convert_to_ee.md +++ b/doc/update/package/convert_to_ee.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Convert Community Edition to Enterprise Edition **(FREE SELF)** diff --git a/doc/update/package/downgrade.md b/doc/update/package/downgrade.md index 0e01a1bfcd8..ee2ff4ea4bf 100644 --- a/doc/update/package/downgrade.md +++ b/doc/update/package/downgrade.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Downgrade **(FREE SELF)** diff --git a/doc/update/package/index.md b/doc/update/package/index.md index 19d308bce6b..93967a30660 100644 --- a/doc/update/package/index.md +++ b/doc/update/package/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrade GitLab by using the GitLab package **(FREE SELF)** diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index e626764aee5..96a2654c579 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Universal update guide for patch versions for self-compiled installations **(FREE SELF)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Make sure you view [this update guide](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/update/patch_versions.md) from the tag (version) of GitLab you would like to install. In most cases this should be the highest numbered production tag (without `rc` in it). -You can select the tag in the version dropdown list in the upper-left corner of GitLab (below the menu bar). +You can select the tag in the version dropdown list in the upper-left corner of GitLab. ### 0. Backup diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index 25578dbef59..00ee87ac96c 100644 --- a/doc/update/plan_your_upgrade.md +++ b/doc/update/plan_your_upgrade.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab upgrade plan **(FREE SELF)** @@ -118,8 +118,7 @@ to your instance and then upgrade it for any relevant features you're using. [turning on maintenance mode](../administration/maintenance_mode/index.md) during the upgrade. - About PostgreSQL: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**.. 1. Look for the version of PostgreSQL you are using. If [a PostgreSQL upgrade is needed](../administration/package_information/postgresql_versions.md), account for the relevant diff --git a/doc/update/removals.md b/doc/update/removals.md deleted file mode 100644 index 56f8b34fd27..00000000000 --- a/doc/update/removals.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'deprecations.md' -remove_date: '2023-09-28' ---- - -This document was moved to [another location](deprecations.md). - -<!-- This redirect file can be deleted after <2023-09-28>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/update/terminology.md b/doc/update/terminology.md index 6babbdbc991..56d5b13461a 100644 --- a/doc/update/terminology.md +++ b/doc/update/terminology.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deprecation terms diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index 6dabc078119..ad18c8cf818 100644 --- a/doc/update/upgrading_from_ce_to_ee.md +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading from Community Edition to Enterprise Edition for self-compiled installations **(FREE SELF)** diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index db735ef49a4..d705c43dc86 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading self-compiled installations **(FREE SELF)** @@ -61,7 +61,7 @@ sudo service gitlab stop ### 3. Update Ruby -From GitLab 15.10, we only support Ruby 3.0.x and dropped support for Ruby 2.7. Be sure to upgrade if necessary. +From GitLab 16.7, we only support Ruby 3.1.x and dropped support for Ruby 3.0. Be sure to upgrade if necessary. You can check which version you are running with `ruby -v`. [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/). diff --git a/doc/update/versions/gitlab_14_changes.md b/doc/update/versions/gitlab_14_changes.md index de5e7f37835..3244e63df2d 100644 --- a/doc/update/versions/gitlab_14_changes.md +++ b/doc/update/versions/gitlab_14_changes.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab 14 changes **(FREE SELF)** @@ -565,7 +565,7 @@ that may remain stuck permanently in a **pending** state when the instance lacks For information on how to fix this, see [Troubleshooting - Failed syncs with GitLab-managed object storage replication](../../administration/geo/replication/troubleshooting.md#failed-syncs-with-gitlab-managed-object-storage-replication). -- We found an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336013) where the Container Registry replication +- We found an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336013) where the container registry replication wasn't fully working if you used multi-arch images. In case of a multi-arch image, only the primary architecture (for example `amd64`) would be replicated to the secondary site. This has been [fixed in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67624) and was backported to 14.2 and 14.1, but manual steps are required to force a re-sync. @@ -598,7 +598,7 @@ that may remain stuck permanently in a **pending** state when the instance lacks end ``` - If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your Container Registry, + If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your container registry, we recommend [upgrading](../../administration/geo/replication/upgrading_the_geo_sites.md) to at least GitLab 14.1. ## 14.2.0 @@ -666,7 +666,7 @@ that may remain stuck permanently in a **pending** state when the instance lacks For information on how to fix this, see [Troubleshooting - Failed syncs with GitLab-managed object storage replication](../../administration/geo/replication/troubleshooting.md#failed-syncs-with-gitlab-managed-object-storage-replication). -- We found an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336013) where the Container Registry replication +- We found an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336013) where the container registry replication wasn't fully working if you used multi-arch images. In case of a multi-arch image, only the primary architecture (for example `amd64`) would be replicated to the secondary site. This has been [fixed in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67624) and was backported to 14.2 and 14.1, but manual steps are required to force a re-sync. @@ -699,7 +699,7 @@ that may remain stuck permanently in a **pending** state when the instance lacks end ``` - If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your Container Registry, + If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your container registry, we recommend [upgrading](../../administration/geo/replication/upgrading_the_geo_sites.md) to at least GitLab 14.1. ## 14.1.0 @@ -733,7 +733,7 @@ that may remain stuck permanently in a **pending** state when the instance lacks ### Geo installations **(PREMIUM SELF)** -- We found an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336013) where the Container Registry replication +- We found an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336013) where the container registry replication wasn't fully working if you used multi-arch images. In case of a multi-arch image, only the primary architecture (for example `amd64`) would be replicated to the secondary site. This has been [fixed in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67624) and was backported to 14.2 and 14.1, but manual steps are required to force a re-sync. @@ -766,7 +766,7 @@ that may remain stuck permanently in a **pending** state when the instance lacks end ``` - If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your Container Registry, + If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your container registry, we recommend [upgrading](../../administration/geo/replication/upgrading_the_geo_sites.md) to at least GitLab 14.1. - We found an issue where [Primary sites cannot be removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/338231). diff --git a/doc/update/versions/gitlab_15_changes.md b/doc/update/versions/gitlab_15_changes.md index bd5efef8f1b..df00ca1b46c 100644 --- a/doc/update/versions/gitlab_15_changes.md +++ b/doc/update/versions/gitlab_15_changes.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab 15 changes **(FREE SELF)** diff --git a/doc/update/versions/gitlab_16_changes.md b/doc/update/versions/gitlab_16_changes.md index 836f5d188c5..57f613dd073 100644 --- a/doc/update/versions/gitlab_16_changes.md +++ b/doc/update/versions/gitlab_16_changes.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab 16 changes **(FREE SELF)** @@ -16,6 +16,7 @@ For more information about upgrading GitLab Helm Chart, see [the release notes f ## Issues to be aware of when upgrading from 15.11 +- [PostgreSQL 12 is not supported starting from GitLab 16](../../update/deprecations.md#postgresql-12-deprecated). Upgrade PostgreSQL to at least version 13.6 before upgrading to GitLab 16.0 or later. - Some GitLab installations must upgrade to GitLab 16.0 before upgrading to any other version. For more information, see [Long-running user type data change](#long-running-user-type-data-change). - Other installations can skip 16.0, 16.1, and 16.2 as the first required stop on the upgrade path is 16.3. Review the notes for those intermediate @@ -30,9 +31,57 @@ For more information about upgrading GitLab Helm Chart, see [the release notes f - [Praefect configuration structure change](#praefect-configuration-structure-change). - [Gitaly configuration structure change](#gitaly-configuration-structure-change). +## 16.7.0 + +### Linux package installations + +Specific information applies to Linux package installations: + +- As of GitLab 16.7, PostgreSQL 14 is the default version installed with the Linux package. + During a package upgrade, the database isn't upgraded to PostgreSQL 14. + If you want to upgrade to PostgreSQL 14, [you must do it manually](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). + + PostgreSQL 14 isn't supported on Geo deployments and is [planned](https://gitlab.com/groups/gitlab-org/-/epics/9065) + for future releases. + + If you want to use PostgreSQL 13, you must set `postgresql['version'] = 13` in `/etc/gitlab/gitlab.rb`. + +## 16.6.0 + +- Old [CI Environment destroy jobs may be spawned](https://gitlab.com/gitlab-org/gitlab/-/issues/433264#) after upgrading to GitLab 16.6. + ## 16.5.0 - Git 2.42.0 and later is required by Gitaly. For self-compiled installations, you should use the [Git version provided by Gitaly](../../install/installation.md#git). +- A regression may sometimes cause an [HTTP 500 error when navigating a group](https://gitlab.com/gitlab-org/gitlab/-/issues/431659). Upgrading to GitLab 16.6 or later resolves the issue. +- A regression may cause [Unselected Advanced Search facets to not load](https://gitlab.com/gitlab-org/gitlab/-/issues/428246). Upgrading to 16.6 or later resolves the issue. + +### Linux package installations + +- SSH clone URLs can be customized by setting `gitlab_rails['gitlab_ssh_host']` + in `/etc/gitlab/gitlab.rb`. This setting must now be a + [valid hostname](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132238). + Previously, it could be an arbitrary string that was used to show a + custom hostname and port in the repository clone URL. + + For example, prior to GitLab 16.5, the following setting worked: + + ```ruby + gitlab_rails['gitlab_ssh_host'] = "gitlab.example.com:2222" + ``` + + Starting with GitLab 16.5, the hostname and port must be specified separately: + + ```ruby + gitlab_rails['gitlab_ssh_host'] = "gitlab.example.com" + gitlab_rails['gitlab_shell_ssh_port'] = 2222 + ``` + + After you change the setting, make sure to reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` ### Geo installations @@ -58,7 +107,7 @@ Specific information applies to installations using Geo: For more information, see [issue 429617](https://gitlab.com/gitlab-org/gitlab/-/issues/429617). -- [Object storage verification](https://about.gitlab.com/releases/2023/09/22/gitlab-16-4-released/#geo-verifies-object-storage) was added in GitLab 16.4. Due to an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/429242) some Geo installations are reporting high memory usage which can lead to the GitLab application on the primary becoming unresponsive. +- [Object storage verification](https://about.gitlab.com/releases/2023/09/22/gitlab-16-4-released/#geo-verifies-object-storage) was added in GitLab 16.4. Due to an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/429242) some Geo installations are reporting high memory usage which can lead to the GitLab application on the primary becoming unresponsive. Your installation may be impacted if you have configured it to use [object storage](../../administration/object_storage.md) and have enabled [GitLab-managed object storage replication](../../administration/geo/replication/object_storage.md#enabling-gitlab-managed-object-storage-replication) @@ -70,11 +119,23 @@ Specific information applies to installations using Geo: ``` **Affected releases**: - + + | Affected minor releases | Affected patch releases | Fixed in | + | ----------------------- | ----------------------- | -------- | + | 16.4 | 16.4.0 - 16.4.2 | 16.4.3 | + | 16.5 | 16.5.0 - 16.5.1 | 16.5.2 | + +- After [Group Wiki](../../user/project/wiki/group.md) verification was added in GitLab 16.3, missing Group Wiki repositories are being incorrectly flagged as failing verification. This issue is not a result of an actual replication/verification failure but an invalid internal state for these missing repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for these Group Wiki repositories. + + See details of the problem and workaround in issue [#426571](https://gitlab.com/gitlab-org/gitlab/-/issues/426571) + + **Affected releases**: + | Affected minor releases | Affected patch releases | Fixed in | | ------ | ------ | ------ | + | 16.3 | All | None | | 16.4 | All | None | - | 16.5 | All | None | + | 16.5 | 16.5.0 - 16.5.1 | 16.5.2 | ## 16.4.0 @@ -119,7 +180,7 @@ Specific information applies to installations using Geo: To find out if a push rule belongs to a project, group, or instance, run this script in the [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session): - + ```ruby # replace `delete_branch_regex` with a name of the field used in constraint long_rules = PushRule.where("length(delete_branch_regex) > 511") @@ -176,7 +237,7 @@ Specific information applies to installations using Geo: For more information, see [issue 429617](https://gitlab.com/gitlab-org/gitlab/-/issues/429617). -- [Object storage verification](https://about.gitlab.com/releases/2023/09/22/gitlab-16-4-released/#geo-verifies-object-storage) was added in GitLab 16.4. Due to an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/429242) some Geo installations are reporting high memory usage which can lead to the GitLab application on the primary becoming unresponsive. +- [Object storage verification](https://about.gitlab.com/releases/2023/09/22/gitlab-16-4-released/#geo-verifies-object-storage) was added in GitLab 16.4. Due to an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/429242) some Geo installations are reporting high memory usage which can lead to the GitLab application on the primary becoming unresponsive. Your installation may be impacted if you have configured it to use [object storage](../../administration/object_storage.md) and have enabled [GitLab-managed object storage replication](../../administration/geo/replication/object_storage.md#enabling-gitlab-managed-object-storage-replication) @@ -188,11 +249,11 @@ Specific information applies to installations using Geo: ``` **Affected releases**: - + | Affected minor releases | Affected patch releases | Fixed in | - | ------ | ------ | ------ | - | 16.4 | All | None | - | 16.5 | All | None | + | ----------------------- | ----------------------- | -------- | + | 16.4 | 16.4.0 - 16.4.2 | 16.4.3 | + | 16.5 | 16.5.0 - 16.5.1 | 16.5.2 | - An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/419370) with sync states getting stuck in pending state results in replication being stuck indefinitely for impacted items leading to risk of data loss in the event of a failover. This mostly impact repository syncs but can also can also affect container registry syncs. You are advised to upgrade to a fixed version to avoid risk of data loss. @@ -203,6 +264,18 @@ Specific information applies to installations using Geo: | 16.3 | 16.3.0 - 16.3.5 | 16.3.6 | | 16.4 | 16.4.0 - 16.4.1 | 16.4.2 | +- After [Group Wiki](../../user/project/wiki/group.md) verification was added in GitLab 16.3, missing Group Wiki repositories are being incorrectly flagged as failing verification. This issue is not a result of an actual replication/verification failure but an invalid internal state for these missing repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for these Group Wiki repositories. + + See details of the problem and workaround in issue [#426571](https://gitlab.com/gitlab-org/gitlab/-/issues/426571) + + **Affected releases**: + + | Affected minor releases | Affected patch releases | Fixed in | + | ------ | ------ | ------ | + | 16.3 | All | None | + | 16.4 | All | None | + | 16.5 | 16.5.0 - 16.5.1 | 16.5.2 | + ## 16.3.0 - **Update to GitLab 16.3.5 or later**. This avoids [issue 425971](https://gitlab.com/gitlab-org/gitlab/-/issues/425971) that causes an excessive use of database disk space for GitLab 16.3.3 and 16.3.4. @@ -212,8 +285,8 @@ Specific information applies to installations using Geo: - For Go applications, [`crypto/tls`: verifying certificate chains containing large RSA keys is slow (CVE-2023-29409)](https://github.com/golang/go/issues/61460) introduced a hard limit of 8192 bits for RSA keys. In the context of Go applications at GitLab, RSA keys can be configured for: - - [Container Registry](../../administration/packages/container_registry.md) - - [Gitaly](../../administration/gitaly/configure_gitaly.md#enable-tls-support) + - [Container registry](../../administration/packages/container_registry.md) + - [Gitaly](../../administration/gitaly/tls_support.md) - [GitLab Pages](../../user/project/pages/custom_domains_ssl_tls_certification/index.md#manual-addition-of-ssltls-certificates) - [Workhorse](../../development/workhorse/configuration.md#tls-support) @@ -299,6 +372,18 @@ Specific information applies to installations using Geo: | 16.3 | 16.3.0 - 16.3.5 | 16.3.6 | | 16.4 | 16.4.0 - 16.4.1 | 16.4.2 | +- After [Group Wiki](../../user/project/wiki/group.md) verification was added in GitLab 16.3, missing Group Wiki repositories are being incorrectly flagged as failing verification. This issue is not a result of an actual replication/verification failure but an invalid internal state for these missing repositories inside Geo and results in errors in the logs and the verification progress reporting a failed state for these Group Wiki repositories. + + See details of the problem and workaround in issue [#426571](https://gitlab.com/gitlab-org/gitlab/-/issues/426571) + + **Affected releases**: + + | Affected minor releases | Affected patch releases | Fixed in | + | ------ | ------ | ------ | + | 16.3 | All | None | + | 16.4 | All | None | + | 16.5 | 16.5.0 - 16.5.1 | 16.5.2 | + ## 16.2.0 - Legacy LDAP configuration settings may cause @@ -471,7 +556,11 @@ by this issue. [throw errors on startup](../../install/docker.md#threaderror-cant-create-thread-operation-not-permitted). - Starting with 16.0, GitLab self-managed installations now have two database connections by default, instead of one. This change doubles the number of PostgreSQL connections. It makes self-managed versions of GitLab behave similarly to GitLab.com, and is a step toward enabling a separate database for CI features for self-managed versions of GitLab. Before upgrading to 16.0, determine if you need to [increase max connections for PostgreSQL](https://docs.gitlab.com/omnibus/settings/database.html#configuring-multiple-database-connections). - This change applies to installation methods with Linux packages (Omnibus), GitLab Helm chart, GitLab Operator, GitLab Docker images, and self-compiled installations. -- Container registry using Azure storage might be empty with zero tags. You can fix this by following the [breaking change instructions](../deprecations.md#azure-storage-driver-defaults-to-the-correct-root-prefix). + - The second database connection can be disabled: + - [Linux package and Docker installations](https://docs.gitlab.com/omnibus/settings/database.html#configuring-multiple-database-connections). + - [Helm chart and GitLab Operator installations](https://docs.gitlab.com/charts/charts/globals.html#configure-multiple-database-connections). + - [Self-compiled installations](../../install/installation.md#configure-gitlab-db-settings). +- Container registry using Azure storage might be empty with zero tags. You can fix this by following the [breaking change instructions](../deprecations.md#azure-storage-driver-defaults-to-the-correct-root-prefix). ### Linux package installations diff --git a/doc/update/with_downtime.md b/doc/update/with_downtime.md index 9145003eff4..bd8c17fae50 100644 --- a/doc/update/with_downtime.md +++ b/doc/update/with_downtime.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multi-node upgrades with downtime **(FREE SELF)** diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index 7a0f49b6fe7..6ecd23a0dc8 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -1,7 +1,7 @@ --- stage: Systems group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Zero downtime upgrades **(FREE SELF)** diff --git a/doc/user/admin_area/analytics/dev_ops_reports.md b/doc/user/admin_area/analytics/dev_ops_reports.md deleted file mode 100644 index 30ba2ad3e7b..00000000000 --- a/doc/user/admin_area/analytics/dev_ops_reports.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/analytics/dev_ops_reports.md' -remove_date: '2023-10-06' ---- - -This document was moved to [another location](../../../administration/analytics/dev_ops_reports.md). - -<!-- This redirect file can be deleted after <2023-10-06>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md deleted file mode 100644 index f5849f0b876..00000000000 --- a/doc/user/admin_area/analytics/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/analytics/index.md' -remove_date: '2023-10-06' ---- - -This document was moved to [another location](../../../administration/analytics/index.md). - -<!-- This redirect file can be deleted after <2023-10-06>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md deleted file mode 100644 index 12eb44d6ebc..00000000000 --- a/doc/user/admin_area/analytics/usage_trends.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/analytics/usage_trends.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../../administration/analytics/usage_trends.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md deleted file mode 100644 index 6a3760bc62d..00000000000 --- a/doc/user/admin_area/appearance.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/appearance.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../administration/appearance.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md deleted file mode 100644 index 4893b94ce50..00000000000 --- a/doc/user/admin_area/broadcast_messages.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/broadcast_messages.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../administration/broadcast_messages.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md deleted file mode 100644 index f38eed5de43..00000000000 --- a/doc/user/admin_area/credentials_inventory.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/credentials_inventory.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../administration/credentials_inventory.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md deleted file mode 100644 index dc773b0aaca..00000000000 --- a/doc/user/admin_area/custom_project_templates.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/custom_project_templates.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/custom_project_templates.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md deleted file mode 100644 index 54d7d82af98..00000000000 --- a/doc/user/admin_area/diff_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/diff_limits.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/diff_limits.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/email_from_gitlab.md b/doc/user/admin_area/email_from_gitlab.md deleted file mode 100644 index e5194f05381..00000000000 --- a/doc/user/admin_area/email_from_gitlab.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/email_from_gitlab.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/email_from_gitlab.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/external_users.md b/doc/user/admin_area/external_users.md deleted file mode 100644 index ec28f109384..00000000000 --- a/doc/user/admin_area/external_users.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/external_users.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/external_users.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/geo_sites.md b/doc/user/admin_area/geo_sites.md deleted file mode 100644 index cd0f2f5646a..00000000000 --- a/doc/user/admin_area/geo_sites.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/geo_sites.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../administration/geo_sites.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md deleted file mode 100644 index a729cefa7b8..00000000000 --- a/doc/user/admin_area/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/admin_area.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/admin_area.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md deleted file mode 100644 index 724c9885801..00000000000 --- a/doc/user/admin_area/labels.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/labels.md' -remove_date: '2023-10-05' ---- - -This document was moved to [another location](../../administration/labels.md). - -<!-- This redirect file can be deleted after <2023-10-05>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md deleted file mode 100644 index 636f5cb2831..00000000000 --- a/doc/user/admin_area/license.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/license.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/license.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md deleted file mode 100644 index 4835d656cfa..00000000000 --- a/doc/user/admin_area/license_file.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/license_file.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/license_file.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md deleted file mode 100644 index de079d08d3a..00000000000 --- a/doc/user/admin_area/merge_requests_approvals.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/merge_requests_approvals.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../administration/merge_requests_approvals.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md deleted file mode 100644 index 3390c4791be..00000000000 --- a/doc/user/admin_area/moderate_users.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/moderate_users.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../administration/moderate_users.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md deleted file mode 100644 index bda326d4daf..00000000000 --- a/doc/user/admin_area/monitoring/health_check.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/monitoring/health_check.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/monitoring/health_check.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md deleted file mode 100644 index 0e607b03b82..00000000000 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/reporting/git_abuse_rate_limit.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/reporting/git_abuse_rate_limit.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/reporting/ip_addr_restrictions.md b/doc/user/admin_area/reporting/ip_addr_restrictions.md deleted file mode 100644 index 85783640b28..00000000000 --- a/doc/user/admin_area/reporting/ip_addr_restrictions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/reporting/ip_addr_restrictions.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/reporting/ip_addr_restrictions.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md deleted file mode 100644 index 043481b6255..00000000000 --- a/doc/user/admin_area/reporting/spamcheck.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/reporting/spamcheck.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/reporting/spamcheck.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md deleted file mode 100644 index 0e01025896e..00000000000 --- a/doc/user/admin_area/review_abuse_reports.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/review_abuse_reports.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/review_abuse_reports.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md deleted file mode 100644 index 2deed61388b..00000000000 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/account_and_limit_settings.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/account_and_limit_settings.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md deleted file mode 100644 index 72cf369146e..00000000000 --- a/doc/user/admin_area/settings/continuous_integration.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/continuous_integration.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/continuous_integration.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md deleted file mode 100644 index 984eeb24bd1..00000000000 --- a/doc/user/admin_area/settings/deprecated_api_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/deprecated_api_rate_limits.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/deprecated_api_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md deleted file mode 100644 index f90aa7cc865..00000000000 --- a/doc/user/admin_area/settings/email.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/email.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/email.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md deleted file mode 100644 index 02b1ebadc9b..00000000000 --- a/doc/user/admin_area/settings/external_authorization.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/external_authorization.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/external_authorization.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md deleted file mode 100644 index c87cac2b8ac..00000000000 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/files_api_rate_limits.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/files_api_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md deleted file mode 100644 index 8e99005509a..00000000000 --- a/doc/user/admin_area/settings/floc.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/floc.md' -remove_date: '2023-10-06' ---- - -This document was moved to [another location](../../../administration/settings/floc.md). - -<!-- This redirect file can be deleted after <2023-10-06>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md deleted file mode 100644 index 8d7840b804c..00000000000 --- a/doc/user/admin_area/settings/git_lfs_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/git_lfs_rate_limits.md' -remove_date: '2023-10-06' ---- - -This document was moved to [another location](../../../administration/settings/git_lfs_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-06>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md deleted file mode 100644 index 572a9c55642..00000000000 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/gitaly_timeouts.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../../administration/settings/gitaly_timeouts.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md deleted file mode 100644 index 38fe5c3b54c..00000000000 --- a/doc/user/admin_area/settings/help_page.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/help_page.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../../administration/settings/help_page.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md deleted file mode 100644 index ad55f424d81..00000000000 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/import_export_rate_limits.md' -remove_date: '2023-10-07' ---- - -This document was moved to [another location](../../../administration/settings/import_export_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-07>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/incident_management_rate_limits.md b/doc/user/admin_area/settings/incident_management_rate_limits.md deleted file mode 100644 index ad11d6f7f36..00000000000 --- a/doc/user/admin_area/settings/incident_management_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/incident_management_rate_limits.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../../administration/settings/incident_management_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md deleted file mode 100644 index 37112e6897f..00000000000 --- a/doc/user/admin_area/settings/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/index.md' -remove_date: '2023-10-10' ---- - -This document was moved to [another location](../../../administration/settings/index.md). - -<!-- This redirect file can be deleted after <2023-10-10>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md deleted file mode 100644 index 752630ea922..00000000000 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/instance_template_repository.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../../administration/settings/instance_template_repository.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md deleted file mode 100644 index 269864bdd49..00000000000 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/package_registry_rate_limits.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../../administration/settings/package_registry_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md deleted file mode 100644 index eff19caabbe..00000000000 --- a/doc/user/admin_area/settings/project_integration_management.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/project_integration_management.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../../administration/settings/project_integration_management.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md deleted file mode 100644 index 519d035244a..00000000000 --- a/doc/user/admin_area/settings/protected_paths.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/protected_paths.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/protected_paths.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md deleted file mode 100644 index b7e059cf820..00000000000 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/push_event_activities_limit.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/push_event_activities_limit.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md deleted file mode 100644 index aca30177c54..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_issues_creation.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_issues_creation.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md deleted file mode 100644 index 6d5c93f8554..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_notes_creation.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_notes_creation.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md deleted file mode 100644 index c469a77f7d2..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_pipelines_creation.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_pipelines_creation.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_projects_api.md b/doc/user/admin_area/settings/rate_limit_on_projects_api.md deleted file mode 100644 index 12577ba44b1..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_projects_api.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_projects_api.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_projects_api.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limit_on_users_api.md b/doc/user/admin_area/settings/rate_limit_on_users_api.md deleted file mode 100644 index 80acbf21023..00000000000 --- a/doc/user/admin_area/settings/rate_limit_on_users_api.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limit_on_users_api.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limit_on_users_api.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limits_on_git_ssh_operations.md b/doc/user/admin_area/settings/rate_limits_on_git_ssh_operations.md deleted file mode 100644 index b60a78d1f49..00000000000 --- a/doc/user/admin_area/settings/rate_limits_on_git_ssh_operations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limits_on_git_ssh_operations.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limits_on_git_ssh_operations.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md deleted file mode 100644 index 5cfee536a58..00000000000 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/rate_limits_on_raw_endpoints.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/rate_limits_on_raw_endpoints.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/scim_setup.md b/doc/user/admin_area/settings/scim_setup.md deleted file mode 100644 index 4ebd8a84f8a..00000000000 --- a/doc/user/admin_area/settings/scim_setup.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/scim_setup.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../../../administration/settings/scim_setup.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/security_and_compliance.md b/doc/user/admin_area/settings/security_and_compliance.md deleted file mode 100644 index 8c1e514c575..00000000000 --- a/doc/user/admin_area/settings/security_and_compliance.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/security_and_compliance.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/security_and_compliance.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md deleted file mode 100644 index 81be26ec8e0..00000000000 --- a/doc/user/admin_area/settings/sidekiq_job_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/sidekiq_job_limits.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/sidekiq_job_limits.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md deleted file mode 100644 index c3957ed97eb..00000000000 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/sign_in_restrictions.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/sign_in_restrictions.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md deleted file mode 100644 index 553caa9ff0d..00000000000 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/sign_up_restrictions.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/sign_up_restrictions.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/slack_app.md b/doc/user/admin_area/settings/slack_app.md deleted file mode 100644 index 86762edd1a9..00000000000 --- a/doc/user/admin_area/settings/slack_app.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/slack_app.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/slack_app.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md deleted file mode 100644 index 444eeeb15ea..00000000000 --- a/doc/user/admin_area/settings/terms.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/terms.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/terms.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/terraform_limits.md b/doc/user/admin_area/settings/terraform_limits.md deleted file mode 100644 index 8fed7589bb7..00000000000 --- a/doc/user/admin_area/settings/terraform_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/terraform_limits.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/terraform_limits.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md deleted file mode 100644 index 54c5b36bbc0..00000000000 --- a/doc/user/admin_area/settings/third_party_offers.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/third_party_offers.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/third_party_offers.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md deleted file mode 100644 index 5b2afd3ad90..00000000000 --- a/doc/user/admin_area/settings/usage_statistics.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/usage_statistics.md' -remove_date: '2023-10-13' ---- - -This document was moved to [another location](../../../administration/settings/usage_statistics.md). - -<!-- This redirect file can be deleted after <2023-10-13>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md deleted file mode 100644 index fae47358879..00000000000 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/user_and_ip_rate_limits.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/user_and_ip_rate_limits.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md deleted file mode 100644 index c9ff105f8c9..00000000000 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../administration/settings/visibility_and_access_controls.md' -remove_date: '2023-10-14' ---- - -This document was moved to [another location](../../../administration/settings/visibility_and_access_controls.md). - -<!-- This redirect file can be deleted after <2023-10-14>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md deleted file mode 100644 index b0b4facd7db..00000000000 --- a/doc/user/admin_area/user_cohorts.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../administration/user_cohorts.md' -remove_date: '2023-10-11' ---- - -This document was moved to [another location](../../administration/user_cohorts.md). - -<!-- This redirect file can be deleted after <2023-10-11>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/ai_features.md b/doc/user/ai_features.md index 222752a4561..71b5617a4a9 100644 --- a/doc/user/ai_features.md +++ b/doc/user/ai_features.md @@ -1,8 +1,7 @@ --- stage: AI-powered group: AI Model Validation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Duo @@ -13,22 +12,23 @@ type: index, reference GitLab is creating AI-assisted features across our DevSecOps platform. These features aim to help increase velocity and solve key pain points across the software development lifecycle. -| Feature | Purpose | Large Language Model | Current availability | Maturity | -|-|-|-|-|-| -| [Suggested Reviewers](project/merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) | Assists in creating faster and higher-quality reviews by automatically suggesting reviewers for your merge request. | GitLab creates a machine learning model for each project, which is used to generate reviewers <br><br> [View the issue](https://gitlab.com/gitlab-org/modelops/applied-ml/applied-ml-updates/-/issues/10) | SaaS only <br><br> Ultimate tier | [Generally Available (GA)](../policy/experiment-beta-support.md#generally-available-ga) | -| [Code Suggestions](project/repository/code_suggestions/index.md) | Helps you write code more efficiently by viewing code suggestions as you type. | For Code Completion: Vertex AI Codey [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion) <br><br> For Code Generation: Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model)| [SaaS: All tiers](project/repository/code_suggestions/saas.md) <br><br> [Self-managed: Premium and Ultimate with Cloud Licensing](project/repository/code_suggestions/self_managed.md) | [Beta](../policy/experiment-beta-support.md#beta) | -| [Vulnerability summary](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | Helps you remediate vulnerabilities more efficiently, boost your skills, and write more secure code. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) <br><br> Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) if degraded performance | SaaS only <br><br> Ultimate tier | [Beta](../policy/experiment-beta-support.md#beta) | -| [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | Helps you understand code by explaining it in English language. | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-chat) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [GitLab Duo Chat](gitlab_duo_chat.md) | Process and generate text and code in a conversational manner. Helps you quickly identify useful information in large volumes of text in issues, epics, code, and GitLab documentation. | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) <br><br> Vertex AI Codey [`textembedding-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | Assists you with predicting productivity metrics and identifying anomalies across your software development lifecycle. | Statistical forecasting | SaaS only <br> Self-managed <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Discussion summary](#summarize-issue-discussions-with-discussion-summary) | Assists with quickly getting everyone up to speed on lengthy conversations to help ensure you are all on the same page. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Merge request summary](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) | Efficiently communicate the impact of your merge request changes. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Code review summary](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) | Helps ease merge request handoff between authors and reviewers and help reviewers efficiently understand suggestions. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Merge request template population](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) | Generate a description for the merge request based on the contents of the template. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Test generation](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) | Automates repetitive tasks and helps catch bugs early. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Git suggestions](https://gitlab.com/gitlab-org/gitlab/-/issues/409636) | Helps you discover or recall Git commands when and where you need them. | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-chat) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Root cause analysis](#root-cause-analysis) | Assists you in determining the root cause for a pipeline failure and failed CI/CD build. | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | -| [Issue description generation](#summarize-an-issue-with-issue-description-generation) | Generate issue descriptions. | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) | SaaS only <br><br> Ultimate tier | [Experiment](../policy/experiment-beta-support.md#experiment) | +| Goal | Feature | Tier/Offering/Status | +|---|---|---| +| Helps you discover or recall Git commands when and where you need them. | [Git suggestions](https://gitlab.com/gitlab-org/gitlab/-/issues/409636) | **(ULTIMATE SAAS EXPERIMENT)** | +| Assists with quickly getting everyone up to speed on lengthy conversations to help ensure you are all on the same page. | [Discussion summary](#summarize-issue-discussions-with-discussion-summary) | **(ULTIMATE SAAS EXPERIMENT)** | +| Generates issue descriptions. | [Issue description generation](#summarize-an-issue-with-issue-description-generation) | **(ULTIMATE SAAS EXPERIMENT)** | +| Helps you write code more efficiently by viewing code suggestions as you type. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=hCAyCTacdAQ) | [Code Suggestions](project/repository/code_suggestions/index.md) | For SaaS: **(FREE BETA)**<br><br> For self-managed: **(ULTIMATE BETA)** | +| Automates repetitive tasks and helps catch bugs early. | [Test generation](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) | **(ULTIMATE SAAS EXPERIMENT)** | +| Generates a description for the merge request based on the contents of the template. | [Merge request template population](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) | **(ULTIMATE SAAS EXPERIMENT)** | +| Assists in creating faster and higher-quality reviews by automatically suggesting reviewers for your merge request. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=ivwZQgh4Rxw) | [Suggested Reviewers](project/merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) | **(ULTIMATE SAAS)** | +| Efficiently communicates the impact of your merge request changes. | [Merge request summary](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) | **(ULTIMATE SAAS EXPERIMENT)** | +| Helps ease merge request handoff between authors and reviewers and help reviewers efficiently understand suggestions. | [Code review summary](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) | **(ULTIMATE SAAS EXPERIMENT)** | +| Helps you remediate vulnerabilities more efficiently, boost your skills, and write more secure code. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=6sDf73QOav8) | [Vulnerability summary](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | **(ULTIMATE SAAS BETA)** | +| Generates a merge request containing the changes required to mitigate a vulnerability. | [Vulnerability resolution](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | **(ULTIMATE SAAS EXPERIMENT)** | +| Helps you understand code by explaining it in English language. <br><br><i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Watch overview](https://www.youtube.com/watch?v=1izKaLmmaCA) | [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | **(ULTIMATE SAAS EXPERIMENT)** | +| Processes and generates text and code in a conversational manner. Helps you quickly identify useful information in large volumes of text in issues, epics, code, and GitLab documentation. | [GitLab Duo Chat](gitlab_duo_chat.md) | **(ULTIMATE SAAS BETA)** | +| Assists you in determining the root cause for a pipeline failure and failed CI/CD build. | [Root cause analysis](#root-cause-analysis) | **(ULTIMATE SAAS EXPERIMENT)** | +| Assists you with predicting productivity metrics and identifying anomalies across your software development lifecycle. | [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | **(ULTIMATE ALL EXPERIMENT)** | ## Enable AI/ML features @@ -82,7 +82,7 @@ You can also have code explained in the context of a merge request. To explain code in a merge request: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Code > Merge requests**, then select your merge request. +1. Select **Code > Merge requests**, then select your merge request. 1. On the secondary menu, select **Changes**. 1. On the file you would like explained, select the three dots (**{ellipsis_v}**) and select **View File @ $SHA**. @@ -182,9 +182,29 @@ Provide feedback on this experimental feature in [issue 409844](https://gitlab.c **Data usage**: When you use this feature, the text you enter is sent to the large language model referenced above. -### GitLab Duo Chat **(ULTIMATE SAAS EXPERIMENT)** - -For details about this Experimental feature, see [GitLab Duo Chat](gitlab_duo_chat.md). +### GitLab Duo Chat **(ULTIMATE SAAS BETA)** + +For details about this Beta feature, see [GitLab Duo Chat](gitlab_duo_chat.md). + +## Language models + +| Feature | Large Language Model | +|---|---| +| [Git suggestions](https://gitlab.com/gitlab-org/gitlab/-/issues/409636) | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-chat) | +| [Discussion summary](#summarize-issue-discussions-with-discussion-summary) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Issue description generation](#summarize-an-issue-with-issue-description-generation) | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) | +| [Code Suggestions](project/repository/code_suggestions/index.md) | For Code Completion: Vertex AI Codey [`code-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-completion) For Code Generation: Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) | +| [Test generation](project/merge_requests/ai_in_merge_requests.md#generate-suggested-tests-in-merge-requests) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Merge request template population](project/merge_requests/ai_in_merge_requests.md#fill-in-merge-request-templates) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Suggested Reviewers](project/merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) | GitLab creates a machine learning model for each project, which is used to generate reviewers [View the issue](https://gitlab.com/gitlab-org/modelops/applied-ml/applied-ml-updates/-/issues/10) | +| [Merge request summary](project/merge_requests/ai_in_merge_requests.md#summarize-merge-request-changes) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Code review summary](project/merge_requests/ai_in_merge_requests.md#summarize-my-merge-request-review) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Vulnerability summary](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) if degraded performance | +| [Vulnerability resolution](application_security/vulnerabilities/index.md#explaining-a-vulnerability) | Vertex AI Codey [`code-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-generation) | +| [Code explanation](#explain-code-in-the-web-ui-with-code-explanation) | Vertex AI Codey [`codechat-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/code-chat) | +| [GitLab Duo Chat](gitlab_duo_chat.md) | Anthropic [`Claude-2`](https://docs.anthropic.com/claude/reference/selecting-a-model) Vertex AI Codey [`textembedding-gecko`](https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings) | +| [Root cause analysis](#root-cause-analysis) | Vertex AI Codey [`text-bison`](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/text) | +| [Value stream forecasting](#forecast-deployment-frequency-with-value-stream-forecasting) | Statistical forecasting | ## Data usage @@ -209,7 +229,7 @@ The below reflects the current retention periods of GitLab AI model [Sub-Process - Anthropic retains input and output data for 30 days. - Google discards input and output data immediately after the output is provided. Google currently does not store data for abuse monitoring. -All of these AI providers are under data protection agreements with GitLab that prohibit the use of Customer Content for their own purposes, except to perform their independent legal obligations. +All of these AI providers are under data protection agreements with GitLab that prohibit the use of Customer Content for their own purposes, except to perform their independent legal obligations. ### Telemetry diff --git a/doc/user/analytics/analytics_dashboards.md b/doc/user/analytics/analytics_dashboards.md index 8bed8018eb8..0699be4e0ad 100644 --- a/doc/user/analytics/analytics_dashboards.md +++ b/doc/user/analytics/analytics_dashboards.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Analytics dashboards **(ULTIMATE ALL EXPERIMENT)** @@ -64,12 +64,8 @@ Your dashboard files are versioned in source control with the rest of a project' ## Dashboard designer -> Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +> - Introduced in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `combined_analytics_dashboards_editor`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/411407) in GitLab 16.6. Feature flag `combined_analytics_dashboards_editor` removed. You can use the dashboard designer to: @@ -81,12 +77,8 @@ You can use the dashboard designer to: ## Visualization designer -> Introduced in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `combined_analytics_visualization_editor`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_visualization_editor`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +> - Introduced in GitLab 16.4 [with a flag](../../administration/feature_flags.md) named `combined_analytics_visualization_editor`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/425048) in GitLab 16.7. Feature flag `combined_analytics_visualization_editor` removed. NOTE: This feature is only compatible with the [product analytics](../product_analytics/index.md) data source. @@ -98,7 +90,7 @@ You can use the dashboard designer to: ## View project dashboards -Prerequisite: +Prerequisites: - You must have at least the Developer role for the project. @@ -108,6 +100,60 @@ To view a list of dashboards (both built-in and custom) for a project: 1. Select **Analyze > Analytics dashboards**. 1. From the list of available dashboards, select the dashboard you want to view. +### View the value streams dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137483) in GitLab 16.7 [with a flag](../../administration/feature_flags.md) named `project_analytics_dashboard_dynamic_vsd`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards` and `project_analytics_dashboard_dynamic_vsd`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the project. +- Overview background aggregation for Value Streams Dashboards must be enabled. + +To view the Value Streams Dashboard as an analytics dashboard for a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Analyze > Analytics dashboards**. +1. From the list of available dashboards, select **Value Streams Dashboard**. + +## View group dashboards + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390542) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `group_analytics_dashboards`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the group. + +To view a list of dashboards (both built-in and custom) for a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Analyze > Analytics dashboards**. +1. From the list of available dashboards, select the dashboard you want to view. + +### View the value streams dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132839) in GitLab 16.6 [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboard_dynamic_vsd`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `group_analytics_dashboard_dynamic_vsd`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +To view the Value Streams Dashboard as an analytics dashboard for a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Analyze > Analytics dashboards**. +1. From the list of available dashboards, select **Value Streams Dashboard**. + ## Change the location of dashboards You can change the location of your project or group dashboards. @@ -231,7 +277,7 @@ To create a custom visualization: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Analyze > Analytics dashboards**. -1. Select **Visualization Designer**. +1. Select **Visualization designer**. 1. In the **Visualization title** field, enter the name of your visualization. 1. From the **Visualization type** dropdown list, select a visualization type. 1. In the **What metric do you want to visualize?** section, select the metric you want to query. diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 61bc77e4469..360559fad60 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD analytics **(FREE ALL)** @@ -30,6 +30,17 @@ View pipeline duration history: ## View CI/CD analytics +You can view CI/CD analytics for a group or project. + +### For a group **(ULTIMATE ALL)** + +To view CI/CD analytics: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Analyze > CI/CD analytics**. + +### For a project **(FREE ALL)** + To view CI/CD analytics: 1. On the left sidebar, select **Search or go to** and find your project. @@ -44,7 +55,7 @@ frequency to the `production` environment. The environment must be part of the [production deployment tier](../../ci/environments/index.md#deployment-tier-of-environments) for its deployment information to appear on the graphs. - Deployment frequency is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. +Deployment frequency is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. The deployment frequency chart is available for groups and projects. @@ -68,7 +79,7 @@ merge requests to be deployed to a production environment. This chart is availab - For time periods in which no merge requests were deployed, the charts render a red, dashed line. - Lead time for changes is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. +Lead time for changes is one of the four DORA metrics that DevOps teams use for measuring excellence in software delivery. To view the lead time for changes chart: diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index e5b475d0e45..43c6d381874 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -2,7 +2,7 @@ description: "Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code review analytics **(PREMIUM ALL)** @@ -24,11 +24,11 @@ and improve your code review process. - Few comments and approvers may indicate a lack of available team members. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a video explanation, see [Code review analytics: Faster code review](https://www.youtube.com/watch?v=OkLaWhYkASM). +For a video explanation, see [Code review analytics: Faster code review](https://www.youtube.com/watch?v=849o0XD991M). ## View code review analytics -Prerequisite: +Prerequisites: - You must have at least the Reporter role. diff --git a/doc/user/analytics/contributor_analytics.md b/doc/user/analytics/contributor_analytics.md new file mode 100644 index 00000000000..26dd79533a3 --- /dev/null +++ b/doc/user/analytics/contributor_analytics.md @@ -0,0 +1,48 @@ +--- +stage: Plan +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Contributor analytics **(FREE ALL)** + +Contributor analytics give you an overview of the commits made by projects members to a project over time. + +## View contributor analytics + +The contributor analytics page displays a line chart with the number of commits to the selected project branch over time, +and line charts with the number of commits by each project member. + +To view contributor analytics for a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Analyze > Contributor analytics**. +1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. +1. To view the number of commits made on a specific day, hover over the line chart. +1. Optional. To display commits only for a specific time period, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: + + - To change the start date, slide the left pause icon to the left or right. + - To change the end date, slide the right pause icon to the left or right. + +## View project commit history + +To view a list of commits made by project members per day: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Analyze > Contributor analytics**. +1. Select **History**. +1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. +1. To view the number of commits made by the members on a specific day, hover over the line chart. +1. Optional. Filter the results. + + - To filter by author, from the **Author** dropdown list, select the user whose commits you want to view. + - To filter by commit message, in the text box, enter your search criteria. + +## Retrieve project commits as an RSS feed + +To view the list of commits to the project as an RSS feed in Atom format: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Analyze > Contributor analytics**. +1. Select **History**. +1. In the upper-right corner, select the feed symbol (**{rss}**). diff --git a/doc/user/analytics/contributor_statistics.md b/doc/user/analytics/contributor_statistics.md index ee10522e80b..b6f195e22ad 100644 --- a/doc/user/analytics/contributor_statistics.md +++ b/doc/user/analytics/contributor_statistics.md @@ -1,48 +1,11 @@ --- -stage: Plan -group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: 'contributor_analytics.md' +remove_date: '2023-03-06' --- -# Contributor statistics **(FREE ALL)** +This document was moved to [another location](contributor_analytics.md). -Contributor statistics give you an overview of the commits made by projects members to a project over time. - -## View contributor statistics - -The contributor statistics page displays a line chart with the number of commits to the selected project branch over time, -and line charts with the number of commits by each project member. - -To view contributor statistics for a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Analyze > Contributor statistics**. -1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. -1. To view the number of commits made on a specific day, hover over the line chart. -1. Optional. To display commits only for a specific time period, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: - - - To change the start date, slide the left pause icon to the left or right. - - To change the end date, slide the right pause icon to the left or right. - -## View project commit history - -To view a list of commits made by project members per day: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Analyze > Contributor statistics**. -1. Select **History**. -1. From the **Branches** (**main**) dropdown list, select the branch you want to view commits for. -1. To view the number of commits made by the members on a specific day, hover over the line chart. -1. Optional. Filter the results. - - - To filter by author, from the **Author** dropdown list, select the user whose commits you want to view. - - To filter by commit message, in the text box, enter your search criteria. - -## Retrieve project commits as an RSS feed - -To view the list of commits to the project as an RSS feed in Atom format: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Analyze > Contributor statistics**. -1. Select **History**. -1. In the upper-right corner, select the feed symbol (**{rss}**). +<!-- This redirect file can be deleted after <YYYY-MM-DD>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/analytics/dora_metrics.md b/doc/user/analytics/dora_metrics.md index e90bfd690ca..53a25acbca5 100644 --- a/doc/user/analytics/dora_metrics.md +++ b/doc/user/analytics/dora_metrics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DevOps Research and Assessment (DORA) metrics **(ULTIMATE ALL)** @@ -21,14 +21,14 @@ DORA includes four key metrics, divided into two core areas of DevOps: For software leaders, tracking velocity alongside quality metrics ensures they're not sacrificing quality for speed. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a video explanation, see [DORA metrics: User analytics](https://www.youtube.com/watch?v=lM_FbVYuN8s) and [GitLab speed run: DORA metrics](https://www.youtube.com/watch?v=1BrcMV6rCDw). +For a video explanation, see [DORA metrics: User analytics](https://www.youtube.com/watch?v=jYQSH4EY6_U) and [GitLab speed run: DORA metrics](https://www.youtube.com/watch?v=1BrcMV6rCDw). ## DORA metrics in Value Stream Analytics The four DORA metrics are available out-of-the-box in the [Value Streams Dashboard](value_streams_dashboard.md). This helps you visualize the engineering work in the context of end-to-end value delivery. -The One DevOps Platform [Value Stream Management](https://gitlab.com/gitlab-org/gitlab/-/value_stream_analytics) provides end-to-end visibility to the entire software delivery lifecycle. +The One DevOps Platform [Value Stream Management](https://gitlab.com/gitlab-org/gitlab/-/value_stream_analytics) provides end-to-end visibility into the entire software delivery lifecycle. This enables teams and managers to understand all aspects of productivity, quality, and delivery, without the ["toolchain tax"](https://about.gitlab.com/solutions/value-stream-management/). ## Deployment frequency @@ -42,7 +42,7 @@ High deployment frequency means you can get feedback sooner and iterate faster t ### How deployment frequency is calculated -In GitLab, Deployment frequency is measured by the average number of deployments per day to a given environment, based on the deployment's end time (its `finished_at` property). +In GitLab, deployment frequency is measured by the average number of deployments per day to a given environment, based on the deployment's end time (its `finished_at` property). GitLab calculates the deployment frequency from the number of finished deployments on the given day. Only successful deployments (`Deployment.statuses = success`) are counted. The calculation takes into account the production `environment tier` or the environments named `production/prod`. The environment must be part of the production deployment tier for its deployment information to appear on the graphs. @@ -51,28 +51,29 @@ The calculation takes into account the production `environment tier` or the envi The first step is to benchmark the cadence of code releases between groups and projects. Next, you should consider: -- Add more automated testing. -- Add more automated code validation. -- Break the changes down into smaller iterations. +- Adding automated testing. +- Adding automated code validation. +- Breaking the changes down into smaller iterations. ## Lead time for changes Lead time for changes is the amount of time it takes a code change to get into production. -"Lead time for changes" is not the same as "Lead time". In the value stream, "Lead time" measures the time it takes for work on an issue to move from the moment it's requested (Issue created) to the moment it's fulfilled and delivered (Issue closed). +**Lead time for changes** is not the same as **Lead time**. In the value stream, lead time measures the time it takes for work on an issue to move from the moment it's requested (Issue created) to the moment it's fulfilled and delivered (Issue closed). -For software leaders, Lead time for changes reflects the efficiency of CI/CD pipelines and visualizes how quickly work is delivered to customers. +For software leaders, lead time for changes reflects the efficiency of CI/CD pipelines and visualizes how quickly work is delivered to customers. Over time, the lead time for changes should decrease, while your team's performance should increase. Low lead time for changes means more efficient CI/CD pipelines. -In GitLab, Lead time for changes is measure by the `Median time it takes for a merge request to get merged into production (from master)`. -By default, Lead time for changes measures only one-branch operations with multiple deployment jobs (for example, jobs moving from development to staging to production jobs on the main branch). +In GitLab, lead time for changes is measured by the `Median time it takes for a merge request to get merged into production (from master)`. + +By default, lead time for changes measures only one-branch operations with multiple deployment jobs (for example, jobs moving from development to staging to production jobs on the main branch). When a merge request gets merged in staging and then merge to production, GitLab processes them as two deployed merge requests, not one. ### How lead time for changes is calculated -GitLab calculates Lead time for changes based on the number of seconds to successfully deliver a commit into production - **from** code committed **to** code successfully running in production, without adding the `coding_time` to the calculation. +GitLab calculates lead time for changes based on the number of seconds to successfully deliver a commit into production - **from** code committed **to** code successfully running in production, without adding the `coding_time` to the calculation. -By default, Lead time for changes supports measuring only one branch operation with multiple deployment jobs (for example, from development to staging to production on the default branch). When a merge request gets merged on staging, and then on production, GitLab interprets them as two deployed merge requests, not one. +By default, lead time for changes supports measuring only one branch operation with multiple deployment jobs (for example, from development to staging to production on the default branch). When a merge request gets merged on staging, and then on production, GitLab interprets them as two deployed merge requests, not one. ### How to improve lead time for changes @@ -80,18 +81,18 @@ The first step is to benchmark the CI/CD pipelines' efficiency between groups an - Using Value Stream Analytics to identify bottlenecks in the processes. - Breaking the changes down into smaller iterations. -- Adding more automation. +- Adding automation. ## Time to restore service Time to restore service is the amount of time it takes an organization to recover from a failure in production. -For software leaders, Time to restore service reflects how long it takes an organization to recover from a failure in production. -Low Time to restore service means the organization can take risks with new innovative features to drive competitive advantages and increase business results. +For software leaders, time to restore service reflects how long it takes an organization to recover from a failure in production. +Low time to restore service means the organization can take risks with new innovative features to drive competitive advantages and increase business results. ### How time to restore service is calculated -In GitLab, Time to restore service is measured as the median time an incident was open for on a production environment. +In GitLab, time to restore service is measured as the median time an incident was open for on a production environment. GitLab calculates the number of seconds an incident was open on a production environment in the given time period. This assumes: - [GitLab incidents](../../operations/incident_management/incidents.md) are tracked. @@ -114,8 +115,8 @@ High change failure rate may indicate an inefficient deployment process or insuf ### How change failure rate is calculated -In GitLab, Change failure rate is measured as the percentage of deployments that cause an incident in production in the given time period. -GitLab calculates this by the number of incidents divided by the number of deployments to a production environment. This assumes: +In GitLab, change failure rate is measured as the percentage of deployments that cause an incident in production in the given time period. +GitLab calculates this as the number of incidents divided by the number of deployments to a production environment. This assumes: - [GitLab incidents](../../operations/incident_management/incidents.md) are tracked. - All incidents are related to a production environment. @@ -124,13 +125,11 @@ more than one incident. ### How to improve change failure rate -The first step is to benchmark the quality and stability, between groups and projects. - -To improve this metric, you should consider: +The first step is to benchmark the quality and stability, between groups and projects. Next, you should consider: - Finding the right balance between stability and throughput (Deployment frequency and Lead time for changes), and not sacrificing quality for speed. - Improving the efficacy of code review processes. -- Adding more automated testing. +- Adding automated testing. ## DORA custom calculation rules **(ULTIMATE ALL EXPERIMENT)** @@ -140,14 +139,14 @@ FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `dora_configuration`. On GitLab.com, this feature is not available. -This feature is an [Experiment](../../policy/experiment-beta-support.md). +This feature is an [Experiment](../../policy/experiment-beta-support.md). To join the list of users testing this feature, [here is a suggested test flow](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96561#steps-to-check-on-localhost). If you find a bug, [open an issue here](https://gitlab.com/groups/gitlab-org/-/epics/11490). To share your use cases and feedback, comment in [epic 11490](https://gitlab.com/groups/gitlab-org/-/epics/11490). -### DORA Lead Time For Changes - multi-branch rule +### Multi-branch rule for lead time for changes -Unlike the default [calculation of Lead time for changes](#how-lead-time-for-changes-is-calculated), this calculation rule allows measuring multi-branch operations with a single deployment job for each operation. +Unlike the default [calculation of lead time for changes](#how-lead-time-for-changes-is-calculated), this calculation rule allows measuring multi-branch operations with a single deployment job for each operation. For example, from development job on development branch, to staging job on staging branch, to production job on production branch. This calculation rule has been implemented by updating the `dora_configurations` table with the target branches that are part of the development flow. @@ -167,23 +166,22 @@ Dora::Configuration.create!(project: my_project, ltfc_target_branches: \['master To retrieve DORA data, use the [GraphQL](../../api/graphql/reference/index.md) or the [REST](../../api/dora/metrics.md) APIs. +## Measure DORA metrics + ### Measure DORA metrics without using GitLab CI/CD pipelines Deployment frequency is calculated based on the deployments record, which is created for typical push-based deployments. These deployment records are not created for pull-based deployments, for example when Container Images are connected to GitLab with an agent. -To track DORA metrics in these cases, you can [create a deployment record](../../api/deployments.md#create-a-deployment) using the Deployments API. See also the documentation page for [Track deployments of an external deployment tool](../../ci/environments/external_deployment_tools.md). +To track DORA metrics in these cases, you can [create a deployment record](../../api/deployments.md#create-a-deployment) using the Deployments API. For more information, see [Track deployments of an external deployment tool](../../ci/environments/external_deployment_tools.md). ### Measure DORA metrics with Jira -- Deployment frequency and Lead time for changes are calculated based on GitLab CI/CD and Merge Requests (MRs), and do not require Jira data. -- Time to restore service and Change failure rate require GitLab incidents for the calculation. For more information, see [Measure DORA Time to restore service and Change failure rate with external incidents](#measure-dora-time-to-restore-service-and-change-failure-rate-with-external-incidents). +- Deployment frequency and lead time for changes are calculated based on GitLab CI/CD and Merge Requests (MRs), and do not require Jira data. +- Time to restore service and change failure rate require [GitLab incidents](../../operations/incident_management/manage_incidents.md) for the calculation. For more information, see [Measure DORA Time to restore service and Change failure rate with external incidents](#measure-dora-time-to-restore-service-and-change-failure-rate-with-external-incidents). ### Measure DORA Time to restore service and Change failure rate with external incidents -[Time to restore service](#time-to-restore-service) and [Change failure rate](#change-failure-rate) -require [GitLab incidents](../../operations/incident_management/manage_incidents.md) to calculate the metrics. - For PagerDuty, you can set up a [webhook to automatically create a GitLab incident for each PagerDuty incident](../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook). This configuration requires you to make changes in both PagerDuty and GitLab. diff --git a/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png b/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png Binary files differnew file mode 100644 index 00000000000..519e56acaa5 --- /dev/null +++ b/doc/user/analytics/img/enhanced_issue_analytics_v16_7.png diff --git a/doc/user/analytics/img/issues_closed_analytics_v16_4.png b/doc/user/analytics/img/issues_closed_analytics_v16_4.png Binary files differdeleted file mode 100644 index 5e1fe4eaa8c..00000000000 --- a/doc/user/analytics/img/issues_closed_analytics_v16_4.png +++ /dev/null diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index f096d1e2882..d58426bd76b 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,13 +1,13 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Analyze GitLab usage **(FREE ALL)** GitLab provides different types of analytics insights at the instance, group, and project level. -These insights appear on the left sidebar, under [**Analyze**](../project/settings/index.md#disable-project-analytics). +These insights appear on the left sidebar, under [**Analyze**](../project/settings/project_features_permissions.md#disable-project-analytics). ## Instance-level analytics @@ -33,12 +33,11 @@ Use group-level analytics to get insights into your groups': Use project-level analytics to get insights into your projects': -- [Analytics dashboards](analytics_dashboards.md), enabled with the `combined_analytics_dashboards_editor` - [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development) +- [Analytics dashboards](analytics_dashboards.md) - [Security Dashboards](../application_security/security_dashboard/index.md) - [CI/CD analytics and DORA metrics](ci_cd_analytics.md) - [Code review analytics](code_review_analytics.md) -- [Contributor statistics](../../user/analytics/contributor_statistics.md) +- [Contributor analytics](../../user/analytics/contributor_analytics.md) - [Insights](../project/insights/index.md) - [Issue analytics](../../user/analytics/issue_analytics.md) - [Merge request analytics](merge_request_analytics.md), enabled with the `project_merge_request_analytics` diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 8f29c008d75..b8aa23a0af2 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue analytics for projects **(PREMIUM ALL)** @@ -50,7 +49,7 @@ available. This feature is not ready for production use. Enhanced issue analytics display the additional metric "Issues closed", which represents the total number of resolved issues in your project over a selected period. You can use this metric to improve the overall turn-around time and value delivered to your customers. - + ## Drill into the information diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 0f8eb9ac211..5b5b1ec002d 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -2,7 +2,7 @@ description: "Merge request analytics help you understand the efficiency of your code review process, and the productivity of your team." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request analytics **(PREMIUM ALL)** @@ -23,7 +23,7 @@ You can use merge request analytics to identify: ## View merge request analytics -Prerequisite: +Prerequisites: - You must have at least the Reporter role. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index a17eb08c53c..2644f8466c0 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Productivity analytics **(PREMIUM ALL)** @@ -22,14 +22,14 @@ To view merge request data for projects, use [Merge request analytics](../analyt ## View productivity analytics -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the group. 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. 1. Optional. Filter results: - 1. Select a project from the dropdown list. + 1. From the **Projects** dropdown list, select a project. 1. To filter results by author, milestone, or label, select **Filter results...** and enter a value. 1. To adjust the date range: @@ -38,19 +38,16 @@ Prerequisite: ## View time metrics for merge requests -Use the following charts in productivity analytics to view the velocity of your merge requests: - -- **Time to merge**: number of days it took for a -merge requests to merge after they were created. -- **Trendline**: number of merge requests that were merged in a specific time period. +To view time metrics for merge requests: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. - -To filter time metrics: - -1. To filter the **Trendline** chart, in the **Time to merge** chart, select a column. -1. To view a specific merge request, below the charts, select a merge request from the **List**. + Time metrics are displayed on the following charts: + - **Time to merge**: number of days it took for a merge requests to merge after they were created. + - **Trendline**: number of merge requests that were merged in a specific time period. +1. Optional. Filter the results: + - To filter the **Trendline** chart, in the **Time to merge** chart, select a bar. + - To view a specific merge request, below the charts, from the **List** table select a merge request. ## View commit statistics @@ -58,11 +55,9 @@ To view commit statistics for your group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Analyze > Productivity analytics**. -1. Under the **Trendline** scatterplot, view the commit statistics: + Commit statistics are displayed under the **Trendline** scatterplot: - The left histogram shows the number of hours between commits, comments, and merges. - The right histogram shows the number of commits and changes per merge request. - -To filter commit statistics: - -1. To view different types of commit data, select the dropdown list next to each histogram. -1. To view a specific merge request, below the charts, select a merge request from the **List**. +1. Optional. Filter results: + - To view different types of commit data, from the dropdown list next to each histogram, select an option. + - To view a specific merge request, below the charts, from the **List** table select a merge request. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 26bce8a20c2..93171dc3136 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository analytics for projects **(FREE ALL)** diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index b5358cc81c8..a50eab42a2d 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Value Streams Dashboard **(ULTIMATE ALL)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Released in GitLab 15.11 as an Open [Beta](../../policy/experiment-beta-support.md#beta) feature [with a flag](../../administration/feature_flags.md) named `group_analytics_dashboards_page`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/392734) in GitLab 16.0. Feature flag `group_analytics_dashboards_page` removed. -To help us improve the Value Streams Dashboard, please share feedback about your experience in this [survey](https://gitlab.fra1.qualtrics.com/jfe/form/SV_50guMGNU2HhLeT4). +To help us improve the Value Streams Dashboard, share feedback about your experience in this [survey](https://gitlab.fra1.qualtrics.com/jfe/form/SV_50guMGNU2HhLeT4). For more information, see also the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). The Value Streams Dashboard is a customizable dashboard you can use to identify trends, patterns, and opportunities for digital transformation improvements. @@ -29,6 +29,8 @@ With the Value Streams Dashboard, you can: - Understand security exposure. - Drill down into individual projects or metrics to take actions for improvement. +The Value Streams Dashboard has a default configuration, but you can also [customize the dashboard panels](#customize-the-dashboard-panels). + ## DevSecOps metrics comparison panel The DevSecOps metrics comparison displays DORA4, vulnerability, and flow metrics for a group or project in the @@ -71,6 +73,21 @@ For example, if a project has a high score for Deployment Frequency (Velocity), These scoring are based on Google's classifications in the [DORA 2022 Accelerate State of DevOps Report](https://cloud.google.com/blog/products/devops-sre/dora-2022-accelerate-state-of-devops-report-now-out). +### Filter by project topics + +When used in combination with a [YAML configuration](#using-yaml-configuration), you can filter the projects shown based on their assigned [topics](../project/settings/project_features_permissions.md#project-topics). + +```yaml +panels: + - data: + namespace: group/my-custom-group + filter_project_topics: + - JavaScript + - Vue.js +``` + +If multiple topics are provided, all topics will need to match for the project to be included in the results. + ## Enable or disable overview background aggregation **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/120610) in GitLab 16.1 [with a flag](../../administration/feature_flags.md) named `modify_value_stream_dashboard_settings`. Disabled by default. @@ -81,7 +98,7 @@ On self-managed GitLab, by default this feature is available. To hide the featur On GitLab.com, this feature is not available. This feature is not ready for production use. -Prerequisite: +Prerequisites: - You must have administrator access to the instance. @@ -96,7 +113,7 @@ To retrieve aggregated usage counts in the group, use the [GraphQL API](../../ap ## View the value streams dashboard -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the group. - Overview background aggregation for Value Streams Dashboards must be enabled. @@ -115,6 +132,8 @@ To view the value streams dashboard: 1. Below the **Filter results** text box, in the **Lifecycle metrics** row, select **Value Streams Dashboard / DORA**. 1. Optional. To open the new page, append this path `/analytics/dashboards/value_streams_dashboard` to the group URL (for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards/value_streams_dashboard`). +You can also view the Value Streams Dashboard rendered as an analytics dashboard for a [group](analytics_dashboards.md#view-group-dashboards) or [project](analytics_dashboards.md#view-project-dashboards). + ## Customize the dashboard panels You can customize the Value Streams Dashboard and configure what subgroups and projects to include in the page. @@ -136,7 +155,7 @@ Query parameters can still be used to override the YAML configuration. First, you need to set up the project. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the group. @@ -203,6 +222,7 @@ panels: For an overview of editing label filters in the configuration file, see [GitLab Value Streams Dashboard - Label filters demo](https://www.youtube.com/watch?v=4qDAHCxCfik). Label filters are appended as query parameters to the URL of the drill-down report of each eligible metric and automatically applied. +If the comparison panel from the configuration file is enabled with `filter_labels`, the drill-down links inherit the labels from the panel filter. ## Dashboard metrics and drill-down reports diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index b82ea30b463..9c16c70c78f 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # HTTP Archive format **(ULTIMATE ALL)** diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 1bac636ac3f..735b2356780 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web API Fuzz Testing **(ULTIMATE ALL)** @@ -2724,7 +2723,7 @@ ERROR: Job failed: failed to pull image "registry.example.com/my-target-app:late **Solution** -Authentication credentials are provided using the methods outlined in the [Access an image from a private Container Registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a third party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. +Authentication credentials are provided using the methods outlined in the [Access an image from a private container registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a third party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. The following example uses the [statically defined credentials](../../../ci/docker/using_docker_images.md#use-statically-defined-credentials) authentication method. In this example the container registry is `registry.example.com` and image is `my-target-app:latest`. diff --git a/doc/user/application_security/api_security/api_discovery/index.md b/doc/user/application_security/api_security/api_discovery/index.md index 0d7bb2830e9..3e1e9d5bfc7 100644 --- a/doc/user/application_security/api_security/api_discovery/index.md +++ b/doc/user/application_security/api_security/api_discovery/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # API Discovery **(ULTIMATE ALL)** diff --git a/doc/user/application_security/api_security/index.md b/doc/user/application_security/api_security/index.md index 37549d5db51..da771b03335 100644 --- a/doc/user/application_security/api_security/index.md +++ b/doc/user/application_security/api_security/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # API Security **(ULTIMATE ALL)** diff --git a/doc/user/application_security/breach_and_attack_simulation/index.md b/doc/user/application_security/breach_and_attack_simulation/index.md index dab625bc169..61b9c8af59b 100644 --- a/doc/user/application_security/breach_and_attack_simulation/index.md +++ b/doc/user/application_security/breach_and_attack_simulation/index.md @@ -2,7 +2,6 @@ stage: Secure group: Incubation info: Breach and Attack Simulation is a GitLab Incubation Engineering program. No technical writer assigned to this group. -type: reference, howto --- # Breach and Attack Simulation **(ULTIMATE ALL)** @@ -91,7 +90,7 @@ To enable Breach and Attack Simulation features inside of an existing DAST job: extends: .dast_with_bas ``` -1. Disable the `dast+job` job included in the BAS template by setting `DAST_BAS_DISABLED`: +1. Disable the `dast_with_bas` job included in the BAS template by setting `DAST_BAS_DISABLED`: ```yaml variables: @@ -129,6 +128,9 @@ Perform Out-of-Band Application Security Testing (OAST) for certain [active chec services: # NOTE: services overwrites rather than merges so it must be referenced to merge. - !reference [.dast_with_bas_using_services, services] + # NOTE: Link your application container to the dast job and + # access it with the hostname yourapp. See more about Docker services at + # https://docs.gitlab.com/ee/user/application_security/dast/#docker-services - name: $CI_REGISTRY_IMAGE alias: yourapp ``` diff --git a/doc/user/application_security/comparison_dependency_and_container_scanning.md b/doc/user/application_security/comparison_dependency_and_container_scanning.md index d02d94b7a3e..43f7c04f99b 100644 --- a/doc/user/application_security/comparison_dependency_and_container_scanning.md +++ b/doc/user/application_security/comparison_dependency_and_container_scanning.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Scanning compared to Container Scanning diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 98b91ce584d..008b5b54cca 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Security configuration **(FREE ALL)** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index ac03f08e23b..8af262e564b 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Container Scanning **(FREE ALL)** @@ -263,17 +262,17 @@ including a large number of false positives. | `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | -| `CS_IMAGE_SUFFIX` | `""` | Suffix added to `CS_ANALYZER_IMAGE`. If set to `-fips`, `FIPS-enabled` image is used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7630) in GitLab 14.10. | All | +| `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| `CS_IGNORE_STATUSES` | `""` | Force the analyzer to ignore vulnerability findings with specified statuses in a comma-delimited list. For `trivy`, the following values are allowed: `unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life`. For `grype`, the following values are allowed: `fixed,not-fixed,unknown,wont-fix` | All | | `CS_IGNORE_UNFIXED` | `"false"` | Ignore vulnerabilities that are not fixed. | All | -| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | -| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, and `CRITICAL`. | Trivy | | `CS_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | +| `CS_IMAGE_SUFFIX` | `""` | Suffix added to `CS_ANALYZER_IMAGE`. If set to `-fips`, `FIPS-enabled` image is used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7630) in GitLab 14.10. | All | +| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | All | +| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_REGISTRY_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_REGISTRY_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | -| `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | -| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | All | +| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, and `CRITICAL`. | Trivy | | `CS_TRIVY_JAVA_DB` | `"ghcr.io/aquasecurity/trivy-java-db"` | Specify an alternate location for the [trivy-java-db](https://github.com/aquasecurity/trivy-java-db) vulnerability database. | Trivy | -| `CS_IGNORE_STATUSES` | `""` | Force the analyzer to ignore vulnerability findings with specified statuses in a comma-delimited list. For `trivy`, the following values are allowed: `unknown,not_affected,affected,fixed,under_investigation,will_not_fix,fix_deferred,end_of_life`. For `grype`, the following values are allowed: `fixed,not-fixed,unknown,wont-fix` | All | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. | All | ### Supported distributions @@ -534,7 +533,7 @@ To use container scanning in an offline environment, you need: - To configure a local Docker container registry with copies of the container scanning images. You can find these images in their respective registries: -| GitLab Analyzer | Container Registry | +| GitLab Analyzer | Container registry | | --- | --- | | [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) | [Container-Scanning container registry](https://gitlab.com/security-products/container-scanning/container_registry/) | @@ -671,7 +670,10 @@ mirror trivy java db: - oras push $CI_REGISTRY_IMAGE:1 --config /dev/null:application/vnd.aquasec.trivy.config.v1+json javadb.tar.gz:application/vnd.aquasec.trivy.javadb.layer.v1.tar+gzip ``` -If the above container registry is `gitlab.example.com/trivy-java-db-mirror`, then the container scanning job should be configured in the following way: +The vulnerability database is not a regular Docker image, so it is not possible to pull it by using `docker pull`. +The image shows an error if you navigate to it in the GitLab UI. + +If the above container registry is `gitlab.example.com/trivy-java-db-mirror`, then the container scanning job should be configured in the following way. Do not add the tag `:1` at the end, it is added by `trivy`: ```yaml include: @@ -679,7 +681,7 @@ include: container_scanning: variables: - CS_TRIVY_JAVA_DB: gitlab.example.com/trivy-java-db-mirror:1 + CS_TRIVY_JAVA_DB: gitlab.example.com/trivy-java-db-mirror ``` ## Running the standalone container scanning tool diff --git a/doc/user/application_security/continuous_vulnerability_scanning/index.md b/doc/user/application_security/continuous_vulnerability_scanning/index.md index e31fc5f7eb0..4d6d48012ae 100644 --- a/doc/user/application_security/continuous_vulnerability_scanning/index.md +++ b/doc/user/application_security/continuous_vulnerability_scanning/index.md @@ -1,16 +1,13 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Continuous Vulnerability Scanning **(ULTIMATE EXPERIMENT)** +# Continuous Vulnerability Scanning **(ULTIMATE ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371063) in GitLab 16.4 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) with two [features flags](../../../administration/feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. Enabled by default. - -NOTE: -This feature is an [Experiment](../../../policy/experiment-beta-support.md#experiment) and subject to change without notice. -If you have any feedback, you can let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/425072). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371063) in GitLab 16.4 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) with two [features flags](../../../administration/feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427424) in GitLab 16.7 with an additional feature flag named `global_dependency_scanning_on_advisory_ingestion`. Enabled by default. FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flags](../../feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. @@ -27,9 +24,8 @@ Continuous Vulnerability Scanning detects vulnerabilities in the latest CycloneD To enable Continuous Vulnerability Scanning: -- Enable the Continuous Vulnerability Scanning setting in the project's [security configuration](../configuration/index.md). - Enable [Dependency Scanning](../dependency_scanning/index.md#configuration) and ensure that its prerequisites are met. -- On GitLab self-managed only, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then please refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance. +- On GitLab self-managed only, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance. ### Running in an offline environment diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 599203dedcc..8972d659c26 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Coverage-guided fuzz testing **(ULTIMATE ALL)** diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index bbe97081a55..efa1003fb4a 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -1,8 +1,7 @@ --- -type: tutorial stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CVE ID request **(FREE SAAS)** diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index c245361a731..854526c4235 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST authentication **(ULTIMATE ALL)** @@ -53,7 +52,7 @@ To run a DAST authenticated scan: #### Form authentication - You are using either the [DAST proxy-based analyzer](proxy-based.md) or the [DAST browser-based analyzer](browser_based.md). -- You know the URL of the login form of your application. Alternatively, you know how to go to the login form from the authentication URL (see [clicking to go to the login form](#clicking-to-go-to-the-login-form)). +- You know the URL of the login form of your application. Alternatively, you know how to go to the login form from the authentication URL (see [clicking to go to the login form](#click-to-go-to-the-login-form)). - You know the [selectors](#finding-an-elements-selector) of the username and password HTML fields that DAST uses to input the respective values. - You know the element's [selector](#finding-an-elements-selector) that submits the login form when selected. @@ -81,6 +80,7 @@ To run a DAST authenticated scan: | `DAST_USERNAME` <sup>1</sup> | string | The username to authenticate to in the website. Example: `admin` | | `DAST_USERNAME_FIELD` <sup>1</sup> | [selector](#finding-an-elements-selector) | A selector describing the element used to enter the username on the login form. Example: `name:username` | | `DAST_AUTH_DISABLE_CLEAR_FIELDS` | boolean | Disables clearing of username and password fields before attempting manual login. Set to `false` by default. | +| `DAST_AFTER_LOGIN_ACTIONS` | string | Comma separated list of actions to be run after login but before login verification. Currently supports "click" actions. Example: `click(on=id:change_to_bar_graph),click(on=css:input[name=username])` | | 1. Available to an on-demand proxy-based DAST scan. 1. Not available to proxy-based scans. @@ -192,7 +192,7 @@ authentication using the [single-step](#configuration-for-a-single-step-login-fo DAST supports authentication processes where a user is redirected to an external Identity Provider's site to log in. Check the [known limitations](#known-limitations) of DAST authentication to determine if your SSO authentication process is supported. -### Clicking to go to the login form +### Click to go to the login form Define `DAST_BROWSER_PATH_TO_LOGIN_FORM` to provide a path of elements to click on from the `DAST_AUTH_URL` so that DAST can access the login form. This method is suitable for applications that show the login form in a pop-up (modal) window or when the login form does not @@ -211,6 +211,25 @@ dast: DAST_BROWSER_PATH_TO_LOGIN_FORM: "css:.navigation-menu,css:.login-menu-item" ``` +### Perform additional actions after submitting the username and password + +Define `DAST_AFTER_LOGIN_ACTIONS` to provide a sequence of actions required to complete the login process after the username and password forms have been submitted. For example, this can be used to dismiss a modal dialog (such as a "keep me signed in?" prompt) that appears after the submit button is pressed. + +DAST verifies authentication is successful and records authentication tokens once after-login actions have been executed. + +For example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + DAST_AUTH_URL: "https://example.com/login" + DAST_AFTER_LOGIN_ACTIONS: "click(on=id:modal-yes)" +``` + ### Excluding logout URLs If DAST crawls the logout URL while running an authenticated scan, the user is logged out, resulting in the remainder of the scan being unauthenticated. @@ -385,191 +404,4 @@ dast: ## Troubleshooting -The [logs](#read-the-logs) provide insight into what DAST is doing and expecting during the authentication process. For more detailed -information, configure the [authentication report](#configure-the-authentication-report). - -For more information about particular error messages or situations see [known problems](#known-problems). - -The browser-based analyzer is used to authenticate the user. For advanced troubleshooting, see [browser-based troubleshooting](browser_based_troubleshooting.md). - -### Read the logs - -The console output of the DAST CI/CD job shows information about the authentication process using the `AUTH` log module. -For example, the following log shows failed authentication for a multi-step login form. -Authentication failed because a home page should be displayed after login. Instead, the login form was still present. - -```plaintext -2022-11-16T13:43:02.000 INF AUTH attempting to authenticate -2022-11-16T13:43:02.000 INF AUTH loading login page LoginURL=https://example.com/login -2022-11-16T13:43:10.000 INF AUTH multi-step authentication detected -2022-11-16T13:43:15.000 INF AUTH verifying if user submit was successful true_when="HTTP status code < 400" -2022-11-16T13:43:15.000 INF AUTH requirement is satisfied, no login HTTP message detected want="HTTP status code < 400" -2022-11-16T13:43:20.000 INF AUTH verifying if login attempt was successful true_when="HTTP status code < 400 and has authentication token and no login form found (no element found when searching using selector css:[id=email] or css:[id=password] or css:[id=submit])" -2022-11-24T14:43:20.000 INF AUTH requirement is satisfied, HTTP login request returned status code 200 url=https://example.com/user/login?error=invalid%20credentials want="HTTP status code < 400" -2022-11-16T13:43:21.000 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[id=email] or css:[id=password] or css:[id=submit])" -2022-11-16T13:43:21.000 INF AUTH login attempt failed error="authentication failed: failed to authenticate user" -``` - -### Configure the authentication report - -WARNING: -The authentication report can contain sensitive information such as the credentials used to perform the login. - -An authentication report can be saved as a CI/CD job artifact to assist with understanding the cause of an authentication failure. - -The report contains steps performed during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots. - - - -An example configuration where the authentication debug report is exported may look like the following: - -```yaml -dast: - variables: - DAST_WEBSITE: "https://example.com" - DAST_AUTH_REPORT: "true" - artifacts: - paths: [gl-dast-debug-auth-report.html] - when: always -``` - -### Known problems - -#### Login form not found - -DAST failed to find a login form when loading the login page, often because the authentication URL could not be loaded. -The log reports a fatal error such as: - -```plaintext -2022-12-07T12:44:02.838 INF AUTH loading login page LoginURL=[authentication URL] -2022-12-07T12:44:11.119 FTL MAIN authentication failed: login form not found -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) to inspect HTTP response. -- Check the target application authentication is deployed and running. -- Check the `DAST_AUTH_URL` is correct. -- Check the GitLab Runner can access the `DAST_AUTH_URL`. -- Check the `DAST_BROWSER_PATH_TO_LOGIN_FORM` is valid if used. - -#### Scan doesn't crawl authenticated pages - -If DAST captures the wrong [authentication tokens](#authentication-tokens) during the authentication process then -the scan can't crawl authenticated pages. Names of cookies and storage authentication tokens are written to the log. For example: - -```plaintext -2022-11-24T14:42:31.492 INF AUTH authentication token cookies names=["sessionID"] -2022-11-24T14:42:31.492 INF AUTH authentication token storage events keys=["token"] -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the login worked as expected. -- Verify the logged authentication tokens are those used by your application. -- If using cookies to store authentication tokens, set the names of the authentication token cookies using `DAST_AUTH_COOKIES`. - -#### Unable to find elements with selector - -DAST failed to find the username, password, first submit button, or submit button elements. The log reports a fatal error such as: - -```plaintext -2022-12-07T13:14:11.545 FTL MAIN authentication failed: unable to find elements with selector: css:#username -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) to use the screenshot from the `Login page` to verify that the page loaded correctly. -- Load the login page in a browser and verify the [selectors](#finding-an-elements-selector) configured in `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, and `DAST_SUBMIT_FIELD` are correct. - -#### Failed to authenticate user - -DAST failed to authenticate due to a failed login verification check. The log reports a fatal error such as: - -```plaintext -2022-12-07T06:39:49.483 INF AUTH verifying if login attempt was successful true_when="HTTP status code < 400 and has authentication token and no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" -2022-12-07T06:39:49.484 INF AUTH requirement is satisfied, HTTP login request returned status code 303 url=http://auth-manual:8090/login want="HTTP status code < 400" -2022-12-07T06:39:49.513 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" -2022-12-07T06:39:49.589 INF AUTH login attempt failed error="authentication failed: failed to authenticate user" -2022-12-07T06:39:53.626 FTL MAIN authentication failed: failed to authenticate user -``` - -Suggested actions: - -- Look in the log for the `requirement is unsatisfied`. Respond to the appropriate error. - -#### Requirement unsatisfied, login form was found - -Applications typically display a dashboard when the user logs in and the login form with an error message when the -username or password is incorrect. - -This error occurs when DAST detects the login form on the page displayed after authenticating the user, -indicating that the login attempt failed. - -```plaintext -2022-12-07T06:39:49.513 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" -``` - -Suggested actions: - -- Verify that the username and password/authentication credentials used are correct. -- Generate the [authentication report](#configure-the-authentication-report) and verify the `Request` for the `Login submit` is correct. -- It's possible that the authentication report `Login submit` request and response are empty. This occurs when there is no request that would result - in a full page reload, such as a request made when submitting a HTML form. This occurs when using websockets or AJAX to submit the login form. -- If the page displayed following user authentication genuinely has elements matching the login form selectors, configure `DAST_AUTH_VERIFICATION_URL` - or `DAST_AUTH_VERIFICATION_SELECTOR` to use an alternate method of verifying the login attempt. - -#### Requirement unsatisfied, selector returned no results - -DAST cannot find an element matching the selector provided in `DAST_AUTH_VERIFICATION_SELECTOR` on the page displayed following user login. - -```plaintext -2022-12-07T06:39:33.239 INF AUTH requirement is unsatisfied, searching DOM using selector returned no results want="has element css:[name=welcome]" -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the expected page is displayed. -- Ensure the `DAST_AUTH_VERIFICATION_SELECTOR` [selector](#finding-an-elements-selector) is correct. - -#### Requirement unsatisfied, browser not at URL - -DAST detected that the page displayed following user login has a URL different to what was expected according to `DAST_AUTH_VERIFICATION_URL`. - -```plaintext -2022-12-07T11:28:00.241 INF AUTH requirement is unsatisfied, browser is not at URL browser_url="https://example.com/home" want="is at url https://example.com/user/dashboard" -``` - -Suggested actions: - -- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the expected page is displayed. -- Ensure the `DAST_AUTH_VERIFICATION_URL` is correct. - -#### Requirement unsatisfied, HTTP login request status code - -The HTTP response when loading the login form or submitting the form had a status code of 400 (client error) -or 500 (server error). - -```plaintext -2022-12-07T06:39:53.626 INF AUTH requirement is unsatisfied, HTTP login request returned status code 502 url="https://example.com/user/login" want="HTTP status code < 400" -``` - -- Verify that the username and password/authentication credentials used are correct. -- Generate the [authentication report](#configure-the-authentication-report) and verify the `Request` for the `Login submit` is correct. -- Verify the target application works as expected. - -#### Requirement unsatisfied, no authentication token - -DAST could not detect an [authentication token](#authentication-tokens) created during the authentication process. - -```plaintext -2022-12-07T11:25:29.010 INF AUTH authentication token cookies names=[] -2022-12-07T11:25:29.010 INF AUTH authentication token storage events keys=[] -2022-12-07T11:25:29.010 INF AUTH requirement is unsatisfied, no basic authentication, cookie or storage event authentication token detected want="has authentication token" -``` - -Suggestion actions: - -- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the login worked as expected. -- Using the browser's developer tools, investigate the cookies and local/session storage objects created while logging in. Ensure there is an authentication token created with sufficiently random value. -- If using cookies to store authentication tokens, set the names of the authentication token cookies using `DAST_AUTH_COOKIES`. +See [troubleshooting](authentication_troubleshooting.md) for more information. diff --git a/doc/user/application_security/dast/authentication_troubleshooting.md b/doc/user/application_security/dast/authentication_troubleshooting.md new file mode 100644 index 00000000000..62894d89ff6 --- /dev/null +++ b/doc/user/application_security/dast/authentication_troubleshooting.md @@ -0,0 +1,196 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting **(ULTIMATE ALL)** + +The [logs](#read-the-logs) provide insight into what DAST is doing and expecting during the authentication process. For more detailed +information, configure the [authentication report](#configure-the-authentication-report). + +For more information about particular error messages or situations see [known problems](#known-problems). + +The browser-based analyzer is used to authenticate the user. For advanced troubleshooting, see [browser-based troubleshooting](browser_based_troubleshooting.md). + +## Read the logs + +The console output of the DAST CI/CD job shows information about the authentication process using the `AUTH` log module. +For example, the following log shows failed authentication for a multi-step login form. +Authentication failed because a home page should be displayed after login. Instead, the login form was still present. + +```plaintext +2022-11-16T13:43:02.000 INF AUTH attempting to authenticate +2022-11-16T13:43:02.000 INF AUTH loading login page LoginURL=https://example.com/login +2022-11-16T13:43:10.000 INF AUTH multi-step authentication detected +2022-11-16T13:43:15.000 INF AUTH verifying if user submit was successful true_when="HTTP status code < 400" +2022-11-16T13:43:15.000 INF AUTH requirement is satisfied, no login HTTP message detected want="HTTP status code < 400" +2022-11-16T13:43:20.000 INF AUTH verifying if login attempt was successful true_when="HTTP status code < 400 and has authentication token and no login form found (no element found when searching using selector css:[id=email] or css:[id=password] or css:[id=submit])" +2022-11-24T14:43:20.000 INF AUTH requirement is satisfied, HTTP login request returned status code 200 url=https://example.com/user/login?error=invalid%20credentials want="HTTP status code < 400" +2022-11-16T13:43:21.000 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[id=email] or css:[id=password] or css:[id=submit])" +2022-11-16T13:43:21.000 INF AUTH login attempt failed error="authentication failed: failed to authenticate user" +``` + +## Configure the authentication report + +WARNING: +The authentication report can contain sensitive information such as the credentials used to perform the login. + +An authentication report can be saved as a CI/CD job artifact to assist with understanding the cause of an authentication failure. + +The report contains steps performed during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots. + + + +An example configuration where the authentication debug report is exported may look like the following: + +```yaml +dast: + variables: + DAST_WEBSITE: "https://example.com" + DAST_AUTH_REPORT: "true" + artifacts: + paths: [gl-dast-debug-auth-report.html] + when: always +``` + +## Known problems + +### Login form not found + +DAST failed to find a login form when loading the login page, often because the authentication URL could not be loaded. +The log reports a fatal error such as: + +```plaintext +2022-12-07T12:44:02.838 INF AUTH loading login page LoginURL=[authentication URL] +2022-12-07T12:44:11.119 FTL MAIN authentication failed: login form not found +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) to inspect HTTP response. +- Check the target application authentication is deployed and running. +- Check the `DAST_AUTH_URL` is correct. +- Check the GitLab Runner can access the `DAST_AUTH_URL`. +- Check the `DAST_BROWSER_PATH_TO_LOGIN_FORM` is valid if used. + +### Scan doesn't crawl authenticated pages + +If DAST captures the wrong [authentication tokens](authentication.md#authentication-tokens) during the authentication process then +the scan can't crawl authenticated pages. Names of cookies and storage authentication tokens are written to the log. For example: + +```plaintext +2022-11-24T14:42:31.492 INF AUTH authentication token cookies names=["sessionID"] +2022-11-24T14:42:31.492 INF AUTH authentication token storage events keys=["token"] +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the login worked as expected. +- Verify the logged authentication tokens are those used by your application. +- If using cookies to store authentication tokens, set the names of the authentication token cookies using `DAST_AUTH_COOKIES`. + +### Unable to find elements with selector + +DAST failed to find the username, password, first submit button, or submit button elements. The log reports a fatal error such as: + +```plaintext +2022-12-07T13:14:11.545 FTL MAIN authentication failed: unable to find elements with selector: css:#username +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) to use the screenshot from the `Login page` to verify that the page loaded correctly. +- Load the login page in a browser and verify the [selectors](authentication.md#finding-an-elements-selector) configured in `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, and `DAST_SUBMIT_FIELD` are correct. + +### Failed to authenticate user + +DAST failed to authenticate due to a failed login verification check. The log reports a fatal error such as: + +```plaintext +2022-12-07T06:39:49.483 INF AUTH verifying if login attempt was successful true_when="HTTP status code < 400 and has authentication token and no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" +2022-12-07T06:39:49.484 INF AUTH requirement is satisfied, HTTP login request returned status code 303 url=http://auth-manual:8090/login want="HTTP status code < 400" +2022-12-07T06:39:49.513 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" +2022-12-07T06:39:49.589 INF AUTH login attempt failed error="authentication failed: failed to authenticate user" +2022-12-07T06:39:53.626 FTL MAIN authentication failed: failed to authenticate user +``` + +Suggested actions: + +- Look in the log for the `requirement is unsatisfied`. Respond to the appropriate error. + +### Requirement unsatisfied, login form was found + +Applications typically display a dashboard when the user logs in and the login form with an error message when the +username or password is incorrect. + +This error occurs when DAST detects the login form on the page displayed after authenticating the user, +indicating that the login attempt failed. + +```plaintext +2022-12-07T06:39:49.513 INF AUTH requirement is unsatisfied, login form was found want="no login form found (no element found when searching using selector css:[name=username] or css:[name=password] or css:button[type=\"submit\"])" +``` + +Suggested actions: + +- Verify that the username and password/authentication credentials used are correct. +- Generate the [authentication report](#configure-the-authentication-report) and verify the `Request` for the `Login submit` is correct. +- It's possible that the authentication report `Login submit` request and response are empty. This occurs when there is no request that would result + in a full page reload, such as a request made when submitting a HTML form. This occurs when using websockets or AJAX to submit the login form. +- If the page displayed following user authentication genuinely has elements matching the login form selectors, configure `DAST_AUTH_VERIFICATION_URL` + or `DAST_AUTH_VERIFICATION_SELECTOR` to use an alternate method of verifying the login attempt. + +### Requirement unsatisfied, selector returned no results + +DAST cannot find an element matching the selector provided in `DAST_AUTH_VERIFICATION_SELECTOR` on the page displayed following user login. + +```plaintext +2022-12-07T06:39:33.239 INF AUTH requirement is unsatisfied, searching DOM using selector returned no results want="has element css:[name=welcome]" +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the expected page is displayed. +- Ensure the `DAST_AUTH_VERIFICATION_SELECTOR` [selector](authentication.md#finding-an-elements-selector) is correct. + +### Requirement unsatisfied, browser not at URL + +DAST detected that the page displayed following user login has a URL different to what was expected according to `DAST_AUTH_VERIFICATION_URL`. + +```plaintext +2022-12-07T11:28:00.241 INF AUTH requirement is unsatisfied, browser is not at URL browser_url="https://example.com/home" want="is at url https://example.com/user/dashboard" +``` + +Suggested actions: + +- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the expected page is displayed. +- Ensure the `DAST_AUTH_VERIFICATION_URL` is correct. + +### Requirement unsatisfied, HTTP login request status code + +The HTTP response when loading the login form or submitting the form had a status code of 400 (client error) +or 500 (server error). + +```plaintext +2022-12-07T06:39:53.626 INF AUTH requirement is unsatisfied, HTTP login request returned status code 502 url="https://example.com/user/login" want="HTTP status code < 400" +``` + +- Verify that the username and password/authentication credentials used are correct. +- Generate the [authentication report](#configure-the-authentication-report) and verify the `Request` for the `Login submit` is correct. +- Verify the target application works as expected. + +### Requirement unsatisfied, no authentication token + +DAST could not detect an [authentication token](authentication.md#authentication-tokens) created during the authentication process. + +```plaintext +2022-12-07T11:25:29.010 INF AUTH authentication token cookies names=[] +2022-12-07T11:25:29.010 INF AUTH authentication token storage events keys=[] +2022-12-07T11:25:29.010 INF AUTH requirement is unsatisfied, no basic authentication, cookie or storage event authentication token detected want="has authentication token" +``` + +Suggestion actions: + +- Generate the [authentication report](#configure-the-authentication-report) and look at the screenshot from the `Login submit` to verify that the login worked as expected. +- Using the browser's developer tools, investigate the cookies and local/session storage objects created while logging in. Ensure there is an authentication token created with sufficiently random value. +- If using cookies to store authentication tokens, set the names of the authentication token cookies using `DAST_AUTH_COOKIES`. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 207db52ed71..c0d71a95f91 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST browser-based analyzer **(ULTIMATE ALL)** @@ -90,7 +89,7 @@ A simplified timing attack works as follows: Active scans do not use a browser to send HTTP requests in an effort to minimize scan time. -Anti-CSRF tokens are not regenerated for attacks that submit forms. Please disable anti-CSRF tokens when running an active scan. +Anti-CSRF tokens are not regenerated for attacks that submit forms. Disable anti-CSRF tokens when running an active scan. ## Getting started diff --git a/doc/user/application_security/dast/browser_based_troubleshooting.md b/doc/user/application_security/dast/browser_based_troubleshooting.md index 446cd0aaa92..9572c472284 100644 --- a/doc/user/application_security/dast/browser_based_troubleshooting.md +++ b/doc/user/application_security/dast/browser_based_troubleshooting.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting DAST browser-based analyzer **(ULTIMATE ALL)** diff --git a/doc/user/application_security/dast/checks/1336.1.md b/doc/user/application_security/dast/checks/1336.1.md new file mode 100644 index 00000000000..d20a67d34d4 --- /dev/null +++ b/doc/user/application_security/dast/checks/1336.1.md @@ -0,0 +1,32 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Server-Side Template Injection + +## Description + +The application is vulnerable to Server-Side Template Injection (SSTI), which enables attackers to +manipulate templates on the server side. This vulnerability arises when untrusted user input is +directly used in server-side templates without adequate sanitization. Attackers can exploit this +weakness to inject and execute arbitrary code in templates, potentially compromising the +system's integrity and confidentiality. + +## Remediation + +User-controlled data should always have special elements neutralized when used as part of +constructing Expression Language statements. Consult the documentation for the template +system in use on how properly neutralize user-controlled data. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 1336.1 | false | 1336 | Active | high | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/1336.html) +- [Testing for Server-side Template Injection](https://owasp.org/www-project-web-security-testing-guide/stable/4-Web_Application_Security_Testing/07-Input_Validation_Testing/18-Testing_for_Server-side_Template_Injection) diff --git a/doc/user/application_security/dast/checks/16.11.md b/doc/user/application_security/dast/checks/16.11.md new file mode 100644 index 00000000000..cdc0bd4e271 --- /dev/null +++ b/doc/user/application_security/dast/checks/16.11.md @@ -0,0 +1,40 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# TRACE HTTP method enabled + +## Description + +The debug TRACE method was found to be enabled on the target web server. This +HTTP method reflects HTTP request data back to the user in a response. In some circumstances +this information may include sensitive data that is applied by intermediary proxies. + +## Remediation + +The TRACE HTTP method is for debugging only and should not be enabled on production +sites. + +For Apache based web servers, ensure the `TraceEnable` directive is either removed or set to +`off`. + +For Microsoft Servers, remove the registry parameter named "EnableTraceMethod" found in the below +registry key: + +- `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters` + +For all other server types, consult your product's documentation on how to disable the TRACE method. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.11 | false | 16 | Active | high | + +## Links + +- [RFC](https://datatracker.ietf.org/doc/html/rfc9110.html#section-9.3.8) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) +- [Apache TraceEnable](https://httpd.apache.org/docs/2.4/mod/core.html#traceenable) diff --git a/doc/user/application_security/dast/checks/16.2.md b/doc/user/application_security/dast/checks/16.2.md index 2051b118009..fe6a882e3c4 100644 --- a/doc/user/application_security/dast/checks/16.2.md +++ b/doc/user/application_security/dast/checks/16.2.md @@ -27,7 +27,7 @@ IIS: For IIS based websites version 10 and above you can use the `removeServerHeader` element to the `requestFiltering` section of the `Web.config` file. -For all other server types, please consult your product's documentation on how to redact the version information from +For all other server types, consult your product's documentation on how to redact the version information from the `Server` header. ## Details diff --git a/doc/user/application_security/dast/checks/16.3.md b/doc/user/application_security/dast/checks/16.3.md index d1799baa517..3179be7d691 100644 --- a/doc/user/application_security/dast/checks/16.3.md +++ b/doc/user/application_security/dast/checks/16.3.md @@ -20,7 +20,7 @@ We recommend that the version information be removed from the `X-Powered-By` hea PHP: For PHP based web sites, set the `expose_php` option to `off` in the `php.ini` configuration file. -For all other server types, please consult your product's documentation on how to redact the version +For all other server types, consult your product's documentation on how to redact the version information from the `X-Powered-By` header. ## Details diff --git a/doc/user/application_security/dast/checks/16.8.md b/doc/user/application_security/dast/checks/16.8.md index b8faef75de7..816bc8bd873 100644 --- a/doc/user/application_security/dast/checks/16.8.md +++ b/doc/user/application_security/dast/checks/16.8.md @@ -13,7 +13,7 @@ hardening a website against various client side attacks such as Cross-Site Scrip ## Remediation -If the target site is missing a CSP, please investigate the relevant URLs for enabling CSP. Otherwise, +If the target site is missing a CSP, investigate the relevant URLs for enabling CSP. Otherwise, follow the recommendations to determine if any actions are necessary. ## Details diff --git a/doc/user/application_security/dast/checks/548.1.md b/doc/user/application_security/dast/checks/548.1.md index 6cef8ccdb63..3bef3bdc744 100644 --- a/doc/user/application_security/dast/checks/548.1.md +++ b/doc/user/application_security/dast/checks/548.1.md @@ -28,7 +28,7 @@ IIS: For IIS based websites version 7.0 and above you can use the `<directoryBrowse enabled="false" />` element in the `applicationHost.config` or `Web.config` files. -For all other server types, please consult your product's documentation on how to disable directory +For all other server types, Consult your product's documentation on how to disable directory indexing. ## Details diff --git a/doc/user/application_security/dast/checks/74.1.md b/doc/user/application_security/dast/checks/74.1.md new file mode 100644 index 00000000000..f7f37f3f1c7 --- /dev/null +++ b/doc/user/application_security/dast/checks/74.1.md @@ -0,0 +1,31 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# XSLT Injection + +## Description + +It is possible to supply an XSL template to a server-side XSLT processor. XSLT processors can +be abused to read or write files, initiate outbound connections, and in some cases execute +arbitrary code. + +## Remediation + +Applications should never accept user-supplied style sheets. XSLT processors are not built to +handle potentially malicious stylesheet files. However, some processors do implement or offer +security features which may be available. Consult the documentation for the XSLT processor +used by the target application for security guidelines and hardening steps. It is recommended +that all XML parsers and processors at the very least disable external entity resolution. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 74.1 | false | 74 | Active | high | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/74.html) diff --git a/doc/user/application_security/dast/checks/78.1.md b/doc/user/application_security/dast/checks/78.1.md new file mode 100644 index 00000000000..bcb655f37ae --- /dev/null +++ b/doc/user/application_security/dast/checks/78.1.md @@ -0,0 +1,44 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# OS Command Injection + +## Description + +It is possible to execute arbitrary OS commands on the target application server. +OS Command Injection is a critical vulnerability that can lead to a full system +compromise. + +## Remediation + +User input should never be used in constructing commands or command arguments +to functions which execute OS commands. This includes filenames supplied by +user uploads or downloads. + +Ensure your application does not: + +- Use user-supplied information in the process name to execute. +- Use user-supplied information in an OS command execution function which does +not escape shell meta-characters. +- Use user-supplied information in arguments to OS commands. + +The application should have a hardcoded set of arguments that are to be passed +to OS commands. If file names are being passed to these functions, it is +recommended that a hash of the file name be used instead, or some other unique +identifier. It is strongly recommended that a native library that implements +the same functionality be used instead of using OS system commands due to the +risk of unknown attacks against third party commands. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 78.1 | false | 78 | Active | high | + +## Links + +- [OWASP](https://owasp.org/www-community/attacks/Command_Injection) +- [CWE](https://cwe.mitre.org/data/definitions/78.html) diff --git a/doc/user/application_security/dast/checks/89.1.md b/doc/user/application_security/dast/checks/89.1.md index ca7ff5e4593..688e2c49664 100644 --- a/doc/user/application_security/dast/checks/89.1.md +++ b/doc/user/application_security/dast/checks/89.1.md @@ -20,7 +20,7 @@ situations where dynamic queries must be created, never use direct user input, b instead use a map or dictionary of valid values and resolve them using a user-supplied key. For example, some database drivers do not allow parameterized queries for `>` or `<` comparison -operators. In these cases, do not use a user supplied `>` or `<` value, but rather have the user +operators. In these cases, do not use a user-supplied `>` or `<` value, but rather have the user supply a `gt` or `lt` value. The alphabetical values are then used to look up the `>` and `<` values to be used in the construction of the dynamic query. The same goes for other queries where column or table names are required but can not be parameterized. diff --git a/doc/user/application_security/dast/checks/917.1.md b/doc/user/application_security/dast/checks/917.1.md index 68b9665e393..853407afe30 100644 --- a/doc/user/application_security/dast/checks/917.1.md +++ b/doc/user/application_security/dast/checks/917.1.md @@ -17,7 +17,7 @@ intended EL statement prior to it being executed by an interpreter. ## Remediation User-controlled data should always have special elements neutralized when used as part of -constructing Expression Language statements. Please consult the documentation for the EL +constructing Expression Language statements. Consult the documentation for the EL interpreter in use on how properly neutralize user controlled data. ## Details diff --git a/doc/user/application_security/dast/checks/918.1.md b/doc/user/application_security/dast/checks/918.1.md new file mode 100644 index 00000000000..88a8a632547 --- /dev/null +++ b/doc/user/application_security/dast/checks/918.1.md @@ -0,0 +1,33 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Server-Side Request Forgery + +## Description + +The application is susceptible to Server-Side Request Forgery (SSRF), a high-risk vulnerability +that allows attackers to make unauthorized requests to internal and external resources. This +vulnerability arises when user-controlled input is not properly validated or sanitized before +being used in requests to resources, enabling attackers to manipulate these requests for +malicious purposes. + +## Remediation + +Avoid using user-supplied data for constructing requests. If there is a business need for this, +consider an allowlist approach and/or block requests to internal resources using firewall +rules or a robust request library with anti-SSRF support. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 918.1 | false | 918 | Active | high | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/918.html) +- [OWASP](https://owasp.org/www-community/attacks/Server_Side_Request_Forgery) +- [Server-Side Request Forgery Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html) diff --git a/doc/user/application_security/dast/checks/94.2.md b/doc/user/application_security/dast/checks/94.2.md index 666052807b5..d6e7c5f482f 100644 --- a/doc/user/application_security/dast/checks/94.2.md +++ b/doc/user/application_security/dast/checks/94.2.md @@ -15,10 +15,10 @@ stored secrets, injecting code to take over accounts, or executing OS commands. ## Remediation Never pass user input directly into functions which evaluate string data as code, such as `eval`, -`send`, `public_send`, `instance_eval` or `class_eval`. There is almost no benefit of passing string +`send`, `public_send`, `instance_eval` or `class_eval`. There is almost no benefit of passing string values to these methods, as such the best recommendation is to replace the current logic with more safe implementations of dynamically evaluating logic with user input. If using `send` or `public_send` ensure -the first argument is to a known, hardcoded method/symbol and does not come from user input. +the first argument is to a known, hardcoded method/symbol and does not come from user input. For `eval`, `instance_eval` and `class_eval`, user input should never be sent directly to these methods. One alternative is to store functions or methods in a Hash that can be looked up using a key. If the key diff --git a/doc/user/application_security/dast/checks/98.1.md b/doc/user/application_security/dast/checks/98.1.md new file mode 100644 index 00000000000..b30147f7969 --- /dev/null +++ b/doc/user/application_security/dast/checks/98.1.md @@ -0,0 +1,34 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# PHP Remote File Inclusion + +## Description + +The server is vulnerable to PHP Remote File Inclusion (RFI), which enables attackers to load +remote files and have them executed as PHP scripts on the server side. This vulnerability occurs +when untrusted user input is directly used in script inclusion without proper validation. Attackers +can leverage this vulnerability to include and execute arbitrary remote files, potentially +compromising the system's integrity and confidentiality. + +## Remediation + +Avoid using user-controlled data directly in `include` and `require` statements and instead consider +an allow-list approach for dynamically including scripts. + +If possible, also consider setting `allow_url_include=Off` in the server's PHP configuration to +ensure URLs cannot be used in `include` and `require` statements. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 98.1 | false | 98 | Active | high | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/98.html) +- [File inclusion Vulnerability - Wikipedia](https://en.wikipedia.org/wiki/File_inclusion_vulnerability) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index c239fdb5e74..0a4b16aaa1d 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -168,12 +168,18 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | ID | Check | Severity | Type | |:---|:------|:---------|:-----| | [113.1](113.1.md) | Improper Neutralization of CRLF Sequences in HTTP Headers | High | Active | +| [1336.1](1336.1.md) | Server-Side Template Injection | High | Active | +| [16.11](16.11.md) | TRACE HTTP method enabled | High | Active | | [22.1](22.1.md) | Improper limitation of a pathname to a restricted directory (Path traversal) | High | Active | | [611.1](611.1.md) | External XML Entity Injection (XXE) | High | Active | +| [74.1](74.1.md) | XSLT Injection | High | Active | +| [78.1](78.1.md) | OS Command Injection | High | Active | | [89.1](89.1.md) | SQL Injection | High | Active | | [917.1](917.1.md) | Expression Language Injection | High | Active | +| [918.1](918.1.md) | Server-Side Request Forgery | High | Active | | [94.1](94.1.md) | Server-side code injection (PHP) | High | Active | | [94.2](94.2.md) | Server-side code injection (Ruby) | High | Active | | [94.3](94.3.md) | Server-side code injection (Python) | High | Active | | [94.4](94.4.md) | Server-side code injection (NodeJS) | High | Active | | [943.1](943.1.md) | Improper neutralization of special elements in data query logic | High | Active | +| [98.1](98.1.md) | PHP Remote File Inclusion | High | Active | diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 08f819e020c..9df98176c9a 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting DAST proxy-based analyzer **(ULTIMATE ALL)** diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 4ec693593fb..45b879dc53f 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dynamic Application Security Testing (DAST) **(ULTIMATE ALL)** diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 9e59ecc64d9..6127866b0a9 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -1,12 +1,16 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST proxy-based analyzer **(ULTIMATE ALL)** +WARNING: +Proxy-based DAST is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/430966). +We plan to [remove support for Proxy-based DAST](../../../update/deprecations.md#proxy-based-dast-deprecated). Migrate to [Browser-based DAST](browser_based.md) +to continue analyzing your projects for security findings via dynamic analysis. + The DAST proxy-based analyzer can be added to your [GitLab CI/CD](../../../ci/index.md) pipeline. This helps you discover vulnerabilities in web applications that do not use JavaScript heavily. For applications that do, see the [DAST browser-based analyzer](browser_based.md). diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index 0101749be71..ac597c99b62 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run DAST in an offline environment **(ULTIMATE ALL)** @@ -16,7 +15,7 @@ successfully run. For more information, see [Offline environments](../offline_de To use DAST in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](index.md#prerequisites). -- Docker Container Registry with a locally available copy of the DAST +- Docker container registry with a locally available copy of the DAST [container image](https://gitlab.com/security-products/dast), found in the [DAST container registry](https://gitlab.com/security-products/dast/container_registry). diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index ffa2e063535..df8fbff720b 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST API analyzer **(ULTIMATE ALL)** @@ -2600,7 +2599,7 @@ ERROR: Job failed: failed to pull image "registry.example.com/my-target-app:late **Solution** -Authentication credentials are provided using the methods outlined in the [Access an image from a private Container Registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a 3rd party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. +Authentication credentials are provided using the methods outlined in the [Access an image from a private container registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry) documentation section. The method used is dictated by your container registry provider and its configuration. If your using a container registry provided by a 3rd party, such as a cloud provider (Azure, Google Could (GCP), AWS and so on), check the providers documentation for information on how to authenticate to their container registries. The following example uses the [statically defined credentials](../../../ci/docker/using_docker_images.md#use-statically-defined-credentials) authentication method. In this example the container registry is `registry.example.com` and image is `my-target-app:latest`. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 91145b10f81..7f4806a89f1 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency list **(ULTIMATE ALL)** @@ -38,7 +37,7 @@ To view your project's dependencies, ensure you meet the following requirements: To view the dependencies of a project or all projects in a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Secure > Dependency list**. Details of each dependency are listed, sorted by decreasing severity of vulnerabilities (if any). You can sort the list instead by component name or packager. @@ -62,14 +61,38 @@ Details of each dependency are listed, sorted by decreasing severity of vulnerab  -### Vulnerabilities +## Filter dependency list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/422356) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies_filtering`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `group_level_dependencies_filtering`. +On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. + +In the group-level dependency list you can filter by: + +- Project +- License + +To filter the dependency list: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Secure > Dependency list**. +1. Select the filter bar. +1. Select a filter, then from the dropdown list select one or more criteria. + To close the dropdown list, select outside of it. To add more filters, repeat this step. +1. To apply the selected filters, press <kbd>Enter</kbd>. + +The dependency list shows only dependencies that match your filters. + +## Vulnerabilities If a dependency has known vulnerabilities, view them by selecting the arrow next to the dependency's name or the badge that indicates how many known vulnerabilities exist. For each vulnerability, its severity and description appears below it. To view more details of a vulnerability, select the vulnerability's description. The [vulnerability's details](../vulnerabilities) page is opened. -### Dependency paths +## Dependency paths The dependency list shows the path between a dependency and a top-level dependency it's connected to, if any. Multiple paths may connect a transient dependency to top-level @@ -99,6 +122,6 @@ list shows only the results of the last successful pipeline that ran on the defa To download the dependency list: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Secure > Dependency list**. 1. Select **Export**. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md deleted file mode 100644 index 0d7d495ba49..00000000000 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-09-22' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-09-22>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
\ No newline at end of file diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 683ba6ad19b..9d898ec0266 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -1,9 +1,46 @@ --- stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- +<style> +table.ds-table tr:nth-child(even) { + background-color: transparent; +} + +table.ds-table td { + border-left: 1px solid #dbdbdb; + border-right: 1px solid #dbdbdb; + border-bottom: 1px solid #dbdbdb; +} + +table.ds-table tr td:first-child { + border-left: 0; +} + +table.ds-table tr td:last-child { + border-right: 0; +} + +table.ds-table ul { + font-size: 1em; + list-style-type: none; + padding-left: 0px; + margin-bottom: 0px; +} + +table.no-vertical-table-lines td { + border-left: none; + border-right: none; + border-bottom: 1px solid #f0f0f0; +} + +table.no-vertical-table-lines tr { + border-top: none; +} +</style> + # Dependency Scanning **(ULTIMATE ALL)** Dependency Scanning analyzes your application's dependencies for known vulnerabilities. All @@ -42,35 +79,8 @@ For other interactive reading and how-to demos, see [Get Started With GitLab App The following languages and dependency managers are supported: -<style> -table.supported-languages tr:nth-child(even) { - background-color: transparent; -} - -table.supported-languages td { - border-left: 1px solid #dbdbdb; - border-right: 1px solid #dbdbdb; - border-bottom: 1px solid #dbdbdb; -} - -table.supported-languages tr td:first-child { - border-left: 0; -} - -table.supported-languages tr td:last-child { - border-right: 0; -} - -table.supported-languages ul { - font-size: 1em; - list-style-type: none; - padding-left: 0px; - margin-bottom: 0px; -} -</style> - <!-- markdownlint-disable MD044 --> -<table class="supported-languages"> +<table class="ds-table"> <thead> <tr> <th>Language</th> @@ -322,19 +332,88 @@ GitLab analyzers obtain dependency information using one of the following two me The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: -| Package Manager | Supported File Format Versions | Tested Package Manager Versions | -| ------ | ------ | ------ | -| Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | -| Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | -| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | -| NuGet | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | -| npm | v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup> | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | -| pnpm | v5, v6 | [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1), [8.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1) | -| yarn | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup> | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2), [2.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock), [3.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock) | -| Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | - <!-- markdownlint-disable MD044 --> +<table class="ds-table no-vertical-table-lines"> + <thead> + <tr> + <th>Package Manager</th> + <th>Supported File Format Versions</th> + <th>Tested Package Manager Versions</th> + </tr> + </thead> + <tbody> + <tr> + <td>Bundler</td> + <td>Not applicable</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118">1.17.3</a>, + <a href="https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118">2.1.4</a> + </td> + </tr> + <tr> + <td>Composer</td> + <td>Not applicable</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock">1.x</a> + </td> + </tr> + <tr> + <td>Conan</td> + <td>0.4</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38">1.x</a> + </td> + </tr> + <tr> + <td>Go</td> + <td>Not applicable</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum">1.x</a><sup><b><a href="#notes-regarding-parsing-lockfiles-1">1</a></b></sup> + </td> + </tr> + <tr> + <td>NuGet</td> + <td>v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2">4.9</a> + </td> + </tr> + <tr> + <td>npm</td> + <td>v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</a></b></sup></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4">6.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4">7.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4">9.x</a> + </td> + </tr> + <tr> + <td>pnpm</td> + <td>v5, v6</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1">7.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1">8.x</a> + </td> + </tr> + <tr> + <td>yarn</td> + <td>v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2">1.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock">2.x</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock">3.x</a> + </td> + </tr> + <tr> + <td>Poetry</td> + <td>v1</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock">1.x</a> + </td> + </tr> + </tbody> +</table> + <ol> <li> <a id="notes-regarding-parsing-lockfiles-1"></a> @@ -385,22 +464,99 @@ To support the following package managers, the GitLab analyzers proceed in two s 1. Execute the package manager or a specific task, to export the dependency information. 1. Parse the exported dependency information. -| Package Manager | Pre-installed Versions | Tested Versions | -| ------ | ------ | ------ | -| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L445-449), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L451-455), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L457-461), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L463-467), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L469-473), [1.5.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L475-479), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L481-485) | -| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L95-97)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L314-319), [6.7](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L321-326), [6.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L328-333), [7.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-maven_image_spec.rb#L335-339) | -| setuptools | [58.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17) | [>= 65.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/spec/gemnasium-python_image_spec.rb#L249-271) | -| pip | [22.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L88-102) | -| Pipenv | [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/requirements.txt#L13) | [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L186-210)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [2022.1.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L161-183) | -| Go | [1.18](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91) | [1.18](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91)<sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> | - <!-- markdownlint-disable MD044 --> +<table class="ds-table no-vertical-table-lines"> + <thead> + <tr> + <th>Package Manager</th> + <th>Pre-installed Versions</th> + <th>Tested Versions</th> + </tr> + </thead> + <tbody> + <tr> + <td>sbt</td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L4">1.6.2</a></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L726-730">1.0.4</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L732-736">1.1.6</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L738-742">1.2.8</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L662-666">1.3.12</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L668-672">1.4.6</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L674-678">1.5.8</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L680-694">1.6.2</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L696-700">1.7.3</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L702-706">1.8.3</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L708-713">1.9.6</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/.gitlab/ci/gemnasium-maven.gitlab-ci.yml#L109-119">1.9.7</a> + </td> + </tr> + <tr> + <td>maven</td> + <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L3">3.6.3</a></td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L83-85">3.6.3</a><sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> + </td> + </tr> + <tr> + <td>Gradle</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L5">6.7.1</a><sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L5">7.3.3</a><sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L285-290">5.6.4</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L292-297">6.7</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L299-304">6.9</a>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L306-310">7.3</a> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/spec/gemnasium-maven_image_spec.rb#L312-316">8.4</a> + </td> + </tr> + <tr> + <td>setuptools</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17">58.1.0</a> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/spec/gemnasium-python_image_spec.rb#L249-271">>= 65.6.3</a> + </td> + </tr> + <tr> + <td>pip</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/debian/Dockerfile#L17">22.0.4</a> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L88-102">20.x</a> + </td> + </tr> + <tr> + <td>Pipenv</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-python/requirements.txt#L13">2022.1.8</a> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L186-210">2022.1.8</a><sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.0.2/spec/gemnasium-python_image_spec.rb#L161-183">2022.1.8</a> + </td> + </tr> + <tr> + <td>Go</td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91">1.18</a> + </td> + <td> + <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium/alpine/Dockerfile#L88-91">1.18</a><sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> + </td> + </tr> + </tbody> +</table> + <ol> <li> <a id="exported-dependency-information-notes-1"></a> <p> - This test uses the default version of <code>maven</code> specified by the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v3.10.6/build/gemnasium-maven/debian/config/.tool-versions#L3">`.tool-versions`</a> file. + This test uses the default version of <code>maven</code> specified by the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v4.9.0/build/gemnasium-maven/debian/config/.tool-versions#L3"><code>.tool-versions</code></a> file. </p> </li> <li> @@ -554,7 +710,7 @@ your GitLab CI/CD configuration file is complex. To enable dependency scanning: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipeline editor**. 1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file: @@ -961,7 +1117,7 @@ this information is removed from the resulting merged file. ## Versioning and release process -Check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). +Check the [Release Process documentation](../../../development/sec/analyzer_development_guide.md#versioning-and-release-process). ## Contributing to the vulnerability database @@ -979,7 +1135,7 @@ jobs to run successfully. For more information, see [Offline environments](../of Here are the requirements for using dependency scanning in an offline environment: - GitLab Runner with the `docker` or `kubernetes` executor. -- Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- Docker container registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - If you have a limited access environment you need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` CI/CD variable to the URL of this repository. For more information on configuration variables, see [Customizing analyzer behavior](#customizing-analyzer-behavior). @@ -1176,217 +1332,3 @@ environment variable due to a possible exploit documented by [CVE-2018-20225](ht intended to obtain a private package from a private index. This only affects use of the `PIP_EXTRA_INDEX_URL` option, and exploitation requires that the package does not already exist in the public index (and thus the attacker can put the package there with an arbitrary version number). - -## Troubleshooting - -### Debug-level logging - -Debug-level logging can help when troubleshooting. For details, see -[debug-level logging](../index.md#debug-level-logging). - -### Working around missing support for certain languages or package managers - -As noted in the ["Supported languages" section](#supported-languages-and-package-managers) -some dependency definition files are not yet supported. -However, Dependency Scanning can be achieved if -the language, a package manager, or a third-party tool -can convert the definition file -into a supported format. - -Generally, the approach is the following: - -1. Define a dedicated converter job in your `.gitlab-ci.yml` file. - Use a suitable Docker image, script, or both to facilitate the conversion. -1. Let that job upload the converted, supported file as an artifact. -1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/index.md#dependencies) - to your `dependency_scanning` job to make use of the converted definitions files. - -For example, Poetry projects that _only_ have a `pyproject.toml` -file can generate the `poetry.lock` file as follows. - -```yaml -include: - - template: Security/Dependency-Scanning.gitlab-ci.yml - -stages: - - test - -gemnasium-python-dependency_scanning: - # Work around https://gitlab.com/gitlab-org/gitlab/-/issues/32774 - before_script: - - pip install "poetry>=1,<2" # Or via another method: https://python-poetry.org/docs/#installation - - poetry update --lock # Generates the lock file to be analyzed. -``` - -### `Error response from daemon: error processing tar file: docker-tar: relocation error` - -This error occurs when the Docker version that runs the dependency scanning job is `19.03.0`. -Consider updating to Docker `19.03.1` or greater. Older versions are not -affected. Read more in -[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). - -### Getting warning message `gl-dependency-scanning-report.json: no matching files` - -For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). - -### Limitation when using rules:exists - -The [dependency scanning CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) -uses the [`rules:exists`](../../../ci/yaml/index.md#rulesexists) -syntax. This directive is limited to 10000 checks and always returns `true` after reaching this -number. Because of this, and depending on the number of files in your repository, a dependency -scanning job might be triggered even if the scanner doesn't support your project. - -### Error: `dependency_scanning is used for configuration only, and its script should not be executed` - -For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). - -### Import multiple certificates for Java-based projects - -The `gemnasium-maven` analyzer reads the contents of the `ADDITIONAL_CA_CERT_BUNDLE` variable using `keytool`, which imports either a single certificate or a certificate chain. Multiple unrelated certificates are ignored and only the first one is imported by `keytool`. - -To add multiple unrelated certificates to the analyzer, you can declare a `before_script` such as this in the definition of the `gemnasium-maven-dependency_scanning` job: - -```yaml -gemnasium-maven-dependency_scanning: - before_script: - - . $HOME/.bashrc # make the java tools available to the script - - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file - - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates - - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) - - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import -``` - -### Dependency Scanning job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` - -Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: - -- Disabled by default in GitLab 13.0 and later. -- Unsupported from GitLab 13.4 and later. - -To fix this error, disable Docker-in-Docker for dependency scanning. Individual -`<analyzer-name>-dependency_scanning` jobs are created for each analyzer that runs in your CI/CD -pipeline. - -```yaml -include: - - template: Dependency-Scanning.gitlab-ci.yml - -variables: - DS_DISABLE_DIND: "true" -``` - -### Message `<file> does not exist in <commit SHA>` - -When the `Location` of a dependency in a file is shown, the path in the link goes to a specific Git -SHA. - -If the lock file that our dependency scanning tools reviewed was cached, however, selecting that -link redirects you to the repository root, with the message: -`<file> does not exist in <commit SHA>`. - -The lock file is cached during the build phase and passed to the dependency scanning job before the -scan occurs. Because the cache is downloaded before the analyzer run occurs, the existence of a lock -file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. - -We recommend committing the lock files, which prevents this warning. - -### You no longer get the latest Docker image after setting `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` - -If you have manually set `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` for specific reasons, -and now must update your configuration to again get the latest patched versions of our -analyzers, edit your `.gitlab-ci.yml` file and either: - -- Set your `DS_MAJOR_VERSION` to match the latest version as seen in - [our current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml#L18). -- If you hardcoded the `DS_ANALYZER_IMAGE` variable directly, change it to match the latest - line as found in our [current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml). - The line number varies depending on which scanning job you edited. - - For example, currently the `gemnasium-maven-dependency_scanning` job pulls the latest - `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to - `"$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION"`. - -### Dependency Scanning of setuptools project fails with `use_2to3 is invalid` error - -Support for [2to3](https://docs.python.org/3/library/2to3.html) -was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) -in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` -version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on -`lib2to3` fails with this message: - -```plaintext -error in <dependency name> setup command: use_2to3 is invalid -``` - -To work around this error, downgrade the analyzer's version of `setuptools` (for example, `v57.5.0`): - -```yaml -gemnasium-python-dependency_scanning: - before_script: - - pip install setuptools==57.5.0 -``` - -### Dependency Scanning of projects using psycopg2 fails with `pg_config executable not found` error - -Scanning a Python project that depends on `psycopg2` can fail with this message: - -```plaintext -Error: pg_config executable not found. -``` - -[psycopg2](https://pypi.org/project/psycopg2/) depends on the `libpq-dev` Debian package, -which is not installed in the `gemnasium-python` Docker image. To work around this error, -install the `libpq-dev` package in a `before_script`: - -```yaml -gemnasium-python-dependency_scanning: - before_script: - - apt-get update && apt-get install -y libpq-dev -``` - -### `NoSuchOptionException` when using `poetry config http-basic` with `CI_JOB_TOKEN` - -This error can occur when the automatically generated `CI_JOB_TOKEN` starts with a hyphen (`-`). -To avoid this error, follow [Poetry's configuration advice](https://python-poetry.org/docs/repositories/#configuring-credentials). - -### Error: Project has `<number>` unresolved dependencies - -The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, consult the [Gradle dependency resolution docs](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. - -### Setting build constraints when scanning Go projects - -Dependency scanning runs within a `linux/amd64` container. As a result, the build list generated -for a Go project contains dependencies that are compatible with this environment. If your deployment environment is not -`linux/amd64`, the final list of dependencies might contain additional incompatible -modules. The dependency list might also omit modules that are only compatible with your deployment environment. To prevent -this issue, you can configure the build process to target the operating system and architecture of the deployment -environment by setting the `GOOS` and `GOARCH` [environment variables](https://go.dev/ref/mod#minimal-version-selection) -of your `.gitlab-ci.yml` file. - -For example: - -```yaml -variables: - GOOS: "darwin" - GOARCH: "arm64" -``` - -You can also supply build tag constraints by using the `GOFLAGS` variable: - -```yaml -variables: - GOFLAGS: "-tags=test_feature" -``` - -### Dependency Scanning of Go projects returns false positives - -The `go.sum` file contains an entry of every module that was considered while generating the project's [build list](https://go.dev/ref/mod#glos-build-list). -Multiple versions of a module are included in the `go.sum` file, but the [MVS](https://go.dev/ref/mod#minimal-version-selection) -algorithm used by `go build` only selects one. As a result, when dependency scanning uses `go.sum`, it might report false positives. - -To prevent false positives, Gemnasium only uses `go.sum` if it is unable to generate the build list for the Go project. If `go.sum` is selected, a warning occurs: - -```shell -[WARN] [Gemnasium] [2022-09-14T20:59:38Z] ▶ Selecting "go.sum" parser for "/test-projects/gitlab-shell/go.sum". False positives may occur. See https://gitlab.com/gitlab-org/gitlab/-/issues/321081. -``` diff --git a/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md b/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md new file mode 100644 index 00000000000..77579a04c7e --- /dev/null +++ b/doc/user/application_security/dependency_scanning/troubleshooting_dependency_scanning.md @@ -0,0 +1,232 @@ +--- +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting Dependency Scanning **(FREE ALL)** + +When working with dependency scanning, you might encounter the following issues. + +## Debug-level logging + +Debug-level logging can help when troubleshooting. For details, see +[debug-level logging](../index.md#debug-level-logging). + +### Working around missing support for certain languages or package managers + +As noted in the ["Supported languages" section](index.md#supported-languages-and-package-managers) +some dependency definition files are not yet supported. +However, Dependency Scanning can be achieved if +the language, a package manager, or a third-party tool +can convert the definition file +into a supported format. + +Generally, the approach is the following: + +1. Define a dedicated converter job in your `.gitlab-ci.yml` file. + Use a suitable Docker image, script, or both to facilitate the conversion. +1. Let that job upload the converted, supported file as an artifact. +1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/index.md#dependencies) + to your `dependency_scanning` job to make use of the converted definitions files. + +For example, Poetry projects that _only_ have a `pyproject.toml` +file can generate the `poetry.lock` file as follows. + +```yaml +include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + +stages: + - test + +gemnasium-python-dependency_scanning: + # Work around https://gitlab.com/gitlab-org/gitlab/-/issues/32774 + before_script: + - pip install "poetry>=1,<2" # Or via another method: https://python-poetry.org/docs/#installation + - poetry update --lock # Generates the lock file to be analyzed. +``` + +### `Error response from daemon: error processing tar file: docker-tar: relocation error` + +This error occurs when the Docker version that runs the dependency scanning job is `19.03.0`. +Consider updating to Docker `19.03.1` or greater. Older versions are not +affected. Read more in +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). + +### Getting warning message `gl-dependency-scanning-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). + +## `Error response from daemon: error processing tar file: docker-tar: relocation error` + +This error occurs when the Docker version that runs the dependency scanning job is `19.03.0`. +Consider updating to Docker `19.03.1` or greater. Older versions are not +affected. Read more in +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). + +## Getting warning message `gl-dependency-scanning-report.json: no matching files` + +For information, see the [general Application Security troubleshooting section](../../../ci/jobs/job_artifacts_troubleshooting.md#error-message-no-files-to-upload). + +## Limitation when using rules:exists + +The [dependency scanning CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) +uses the [`rules:exists`](../../../ci/yaml/index.md#rulesexists) +syntax. This directive is limited to 10000 checks and always returns `true` after reaching this +number. Because of this, and depending on the number of files in your repository, a dependency +scanning job might be triggered even if the scanner doesn't support your project. + +## Error: `dependency_scanning is used for configuration only, and its script should not be executed` + +For information, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + +## Import multiple certificates for Java-based projects + +The `gemnasium-maven` analyzer reads the contents of the `ADDITIONAL_CA_CERT_BUNDLE` variable using `keytool`, which imports either a single certificate or a certificate chain. Multiple unrelated certificates are ignored and only the first one is imported by `keytool`. + +To add multiple unrelated certificates to the analyzer, you can declare a `before_script` such as this in the definition of the `gemnasium-maven-dependency_scanning` job: + +```yaml +gemnasium-maven-dependency_scanning: + before_script: + - . $HOME/.bashrc # make the java tools available to the script + - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file + - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates + - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) + - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import +``` + +## Dependency Scanning job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` + +Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: + +- Disabled by default in GitLab 13.0 and later. +- Unsupported from GitLab 13.4 and later. + +To fix this error, disable Docker-in-Docker for dependency scanning. Individual +`<analyzer-name>-dependency_scanning` jobs are created for each analyzer that runs in your CI/CD +pipeline. + +```yaml +include: + - template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DISABLE_DIND: "true" +``` + +## Message `<file> does not exist in <commit SHA>` + +When the `Location` of a dependency in a file is shown, the path in the link goes to a specific Git +SHA. + +If the lock file that our dependency scanning tools reviewed was cached, however, selecting that +link redirects you to the repository root, with the message: +`<file> does not exist in <commit SHA>`. + +The lock file is cached during the build phase and passed to the dependency scanning job before the +scan occurs. Because the cache is downloaded before the analyzer run occurs, the existence of a lock +file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. + +To prevent this warning, lock files should be committed. + +## You no longer get the latest Docker image after setting `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` + +If you have manually set `DS_MAJOR_VERSION` or `DS_ANALYZER_IMAGE` for specific reasons, +and now must update your configuration to again get the latest patched versions of our +analyzers, edit your `.gitlab-ci.yml` file and either: + +- Set your `DS_MAJOR_VERSION` to match the latest version as seen in + [our current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml#L18). +- If you hardcoded the `DS_ANALYZER_IMAGE` variable directly, change it to match the latest + line as found in our [current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml). + The line number varies depending on which scanning job you edited. + + For example, the `gemnasium-maven-dependency_scanning` job pulls the latest + `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to + `"$SECURE_ANALYZERS_PREFIX/gemnasium-maven:$DS_MAJOR_VERSION"`. + +## Dependency Scanning of setuptools project fails with `use_2to3 is invalid` error + +Support for [2to3](https://docs.python.org/3/library/2to3.html) +was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) +in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` +version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on +`lib2to3` fails with this message: + +```plaintext +error in <dependency name> setup command: use_2to3 is invalid +``` + +To work around this error, downgrade the analyzer's version of `setuptools` (for example, `v57.5.0`): + +```yaml +gemnasium-python-dependency_scanning: + before_script: + - pip install setuptools==57.5.0 +``` + +## Dependency Scanning of projects using psycopg2 fails with `pg_config executable not found` error + +Scanning a Python project that depends on `psycopg2` can fail with this message: + +```plaintext +Error: pg_config executable not found. +``` + +[psycopg2](https://pypi.org/project/psycopg2/) depends on the `libpq-dev` Debian package, +which is not installed in the `gemnasium-python` Docker image. To work around this error, +install the `libpq-dev` package in a `before_script`: + +```yaml +gemnasium-python-dependency_scanning: + before_script: + - apt-get update && apt-get install -y libpq-dev +``` + +## `NoSuchOptionException` when using `poetry config http-basic` with `CI_JOB_TOKEN` + +This error can occur when the automatically generated `CI_JOB_TOKEN` starts with a hyphen (`-`). +To avoid this error, follow [Poetry's configuration advice](https://python-poetry.org/docs/repositories/#configuring-credentials). + +## Error: Project has `<number>` unresolved dependencies + +The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, consult the [Gradle dependency resolution documentation](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. + +## Setting build constraints when scanning Go projects + +Dependency scanning runs within a `linux/amd64` container. As a result, the build list generated +for a Go project contains dependencies that are compatible with this environment. If your deployment environment is not +`linux/amd64`, the final list of dependencies might contain additional incompatible +modules. The dependency list might also omit modules that are only compatible with your deployment environment. To prevent +this issue, you can configure the build process to target the operating system and architecture of the deployment +environment by setting the `GOOS` and `GOARCH` [environment variables](https://go.dev/ref/mod#minimal-version-selection) +of your `.gitlab-ci.yml` file. + +For example: + +```yaml +variables: + GOOS: "darwin" + GOARCH: "arm64" +``` + +You can also supply build tag constraints by using the `GOFLAGS` variable: + +```yaml +variables: + GOFLAGS: "-tags=test_feature" +``` + +## Dependency Scanning of Go projects returns false positives + +The `go.sum` file contains an entry of every module that was considered while generating the project's [build list](https://go.dev/ref/mod#glos-build-list). +Multiple versions of a module are included in the `go.sum` file, but the [MVS](https://go.dev/ref/mod#minimal-version-selection) +algorithm used by `go build` only selects one. As a result, when dependency scanning uses `go.sum`, it might report false positives. + +To prevent false positives, Gemnasium only uses `go.sum` if it is unable to generate the build list for the Go project. If `go.sum` is selected, a warning occurs: + +```shell +[WARN] [Gemnasium] [2022-09-14T20:59:38Z] ▶ Selecting "go.sum" parser for "/test-projects/gitlab-shell/go.sum". False positives may occur. See https://gitlab.com/gitlab-org/gitlab/-/issues/321081. +``` diff --git a/doc/user/application_security/generate_test_vulnerabilities/index.md b/doc/user/application_security/generate_test_vulnerabilities/index.md deleted file mode 100644 index f9f93b97baf..00000000000 --- a/doc/user/application_security/generate_test_vulnerabilities/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: '../../../development/sec/generate_test_vulnerabilities.md' -remove_date: '2023-11-01' ---- - -This document was moved to [another location](../../../development/sec/generate_test_vulnerabilities.md). diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index 6143dd59373..e84149b91e8 100644 --- a/doc/user/application_security/get-started-security.md +++ b/doc/user/application_security/get-started-security.md @@ -1,7 +1,7 @@ --- stage: DevSecOps group: Technical writing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Get started with GitLab application security **(ULTIMATE ALL)** diff --git a/doc/user/application_security/gitlab_advisory_database/index.md b/doc/user/application_security/gitlab_advisory_database/index.md index e59eaccf8f8..7e01cd7b2d5 100644 --- a/doc/user/application_security/gitlab_advisory_database/index.md +++ b/doc/user/application_security/gitlab_advisory_database/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Vulnerability Research -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Advisory Database diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index bca29420192..da4fee978d0 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure as Code scanning **(FREE ALL)** diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 25fa1f5cbaf..e31877d195a 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application security **(ULTIMATE ALL)** @@ -95,6 +95,12 @@ against this, infrastructure analysis occurs on every merge request. Checks are - Infrastructure as Code (IaC) configuration files that define your application's deployment environment - [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md). +## Data privacy + +Concerning data privacy in the domain of security scanners, GitLab processes the source code and performs analysis locally on the GitLab Runner. No data is transmitted outside GitLab infrastructure (server and runners). + +Our scanners access the internet only to download the latest sets of signatures, rules, and patches. If you prefer the scanners do not access the internet, consider using an [offline environment](offline_deployments/index.md). + ## Vulnerability scanner maintenance The following vulnerability scanners and their databases are regularly updated: @@ -270,7 +276,9 @@ In the Free tier, the reports above aren't parsed by GitLab. As a result, the wi A merge request contains a security widget which displays a summary of the _new_ results. New results are determined by comparing the findings of the merge request against the findings of the most recent completed pipeline (`success`, `failed`, `canceled` or `skipped`) for the commit when the feature branch was created from the target branch. -GitLab checks the last 10 pipelines for the commit when the feature was created from the target branch to find one with security reports to use in comparison logic. If security scans have not run for the last 10 completed pipelines in the target branch when the feature branch was created, there is no base for comparison. The vulnerabilities from the merge request findings are listed as new in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. +GitLab checks the last 10 pipelines for the commit when the feature branch was created from the target branch to find one with security reports to use in comparison logic. If security scans have not run for the last 10 completed pipelines in the target branch when the feature branch was created, there is no base for comparison. The vulnerabilities from the merge request findings are listed as _new_ in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. + +The MR security widget considers all supported pipeline sources (based on the [`CI_PIPELINE_SOURCE` variable](../../ci/variables/predefined_variables.md)) when comparing results from both the source and target branches when determining if a merge request requires approval. Pipeline sources `webide` and `parent_pipeline` are not supported. The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both new and existing findings. @@ -283,9 +291,11 @@ findings, select **View full report** to go directly to the **Security** tab in ### Pipeline security tab -A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch -and existing vulnerabilities already present when you created the branch. These results likely do not match the findings -displayed in the Merge Request security widget, as those do not include the existing vulnerabilities. Refer to [View vulnerabilities in a pipeline](vulnerability_report/pipeline.md) for more information. +A pipeline's security tab lists all findings in the current branch. It includes findings introduced +by this branch and vulnerabilities already present in the base branch. These results likely do not +match the findings displayed in the Merge Request security widget, as those do not include the +existing vulnerabilities. For more information see +[Vulnerabilities in a pipeline](vulnerability_report/pipeline.md). ### Security dashboard @@ -588,7 +598,7 @@ variables: This indicates to all GitLab analyzers that they are to output **all** messages. For more details, see [logging level](#logging-level). -<!-- NOTE: The below subsection(`### Secure job failing with exit code 1`) documentation URL is referred in the [/gitlab-org/security-products/analyzers/command](https://gitlab.com/gitlab-org/security-products/analyzers/command/-/blob/main/command.go#L19) repository. If this section/subsection changes, please ensure to update the corresponding URL in the mentioned repository. +<!-- NOTE: The below subsection(`### Secure job failing with exit code 1`) documentation URL is referred in the [/gitlab-org/security-products/analyzers/command](https://gitlab.com/gitlab-org/security-products/analyzers/command/-/blob/main/command.go#L19) repository. If this section/subsection changes, ensure to update the corresponding URL in the mentioned repository. --> ### Secure job failing with exit code 1 diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 1ab26229b50..46d2313b1fe 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Offline environments **(FREE SELF)** @@ -124,7 +123,7 @@ include: ``` The pipeline downloads the Docker images needed for the Security Scanners and saves them as -[job artifacts](../../../ci/jobs/job_artifacts.md) or pushes them to the [Container Registry](../../packages/container_registry/index.md) +[job artifacts](../../../ci/jobs/job_artifacts.md) or pushes them to the [container registry](../../packages/container_registry/index.md) of the project where the pipeline is executed. These archives can be transferred to another location and [loaded](https://docs.docker.com/engine/reference/commandline/load/) in a Docker daemon. This method requires a runner with access to both `gitlab.com` (including diff --git a/doc/user/application_security/policies/img/association_diagram.png b/doc/user/application_security/policies/img/association_diagram.png Binary files differdeleted file mode 100644 index 3a56aeba91b..00000000000 --- a/doc/user/application_security/policies/img/association_diagram.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png b/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png Binary files differnew file mode 100644 index 00000000000..d2f5466e383 --- /dev/null +++ b/doc/user/application_security/policies/img/scan_results_evaluation_white-bg.png diff --git a/doc/user/application_security/policies/img/security_policy_project_v14_6.png b/doc/user/application_security/policies/img/security_policy_project_v14_6.png Binary files differdeleted file mode 100644 index feea1b1b01c..00000000000 --- a/doc/user/application_security/policies/img/security_policy_project_v14_6.png +++ /dev/null diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index a86d9b63c63..bd40209320d 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -1,19 +1,23 @@ --- stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Policies **(ULTIMATE ALL)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in GitLab 13.10 with a flag named `security_orchestration_policies_configuration`. Disabled by default. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.3. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.4. +> [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.4. Feature flag `security_orchestration_policies_configuration` removed. -Policies in GitLab provide security teams a way to require scans of their choice to be run -whenever a project pipeline runs according to the configuration specified. Security teams can -therefore be confident that the scans they set up have not been changed, altered, or disabled. You -can access these by navigating to your project's **Secure > Policies** page. +Policies in GitLab provide security and compliance teams with a way to enforce controls globally in +their organization. Security teams can ensure: + +- Security scanners are enforced in development team pipelines with proper configuration. +- That all scan jobs execute without any changes or alterations. +- That proper approvals are provided on merge requests based on results from those findings. + +Compliance teams can centrally enforce multiple approvers on all merge requests and ensure various +settings are enabled on projects in scope of organizational requirements, such as enabling or +locking merge request and repository settings. GitLab supports the following security policies: @@ -22,65 +26,221 @@ GitLab supports the following security policies: ## Security policy project -All security policies are stored as YAML in a separate security policy project that gets linked to -the development project, group, or sub-group. This association can be a one-to-many relationship, allowing one security -policy project to apply to multiple development projects, groups, or sub-groups: +A security policy project (SPP) is a special type of project used only to contain policies. The +policies are stored in the `.gitlab/security-policies/policy.yml` YAML file. + +To enforce the policies contained in an SPP you link it to a project, subgroup, group, or multiples +of each. An SPP can contain multiple policies but they are enforced together. An +SPP enforced on a group or subgroup applies to everything below in the hierarchy, including all +subgroups and their projects. -- For self-managed GitLab instances, linked projects are not required to be in the same group - or the same subgroup as the development projects to which they are linked. -- For GitLab SaaS, the security policy project is required to be in the same top-level group - as the development project, although, it is not necessary for the project to be in the same subgroup. +Policy changes made in a merge request take effect as soon as the merge request is merged. Those +that do not go through a merge request, but instead are committed directly to the default branch, may +require up to 10 minutes before the policy changes take effect. - +## Policy design guidelines -Although it is possible to have one project linked to itself and to serve as both the development -project and the security policy project, this is not recommended. Keeping the security policy -project separate from the development project allows for complete separation of duties between -security/compliance teams and development teams. +When designing your policies, your goals should be: -All security policies are stored in the `.gitlab/security-policies/policy.yml` YAML file inside the -linked security policy project. The format for this YAML is specific to the type of policy that is -stored there. Examples and schema information are available for the following policy types: +- Designing policy enforcement for minimum overhead but maximum coverage +- Separation of duties -- [Scan execution policy](scan-execution-policies.md#example-security-policies-project) -- [Scan result policy](scan-result-policies.md#example-security-scan-result-policies-project) +### Policy enforcement design -Most policy changes take effect as soon as the merge request is merged. Any changes that -do not go through a merge request and are committed directly to the default branch may require up to 10 minutes -before the policy changes take effect. +To maximize policy coverage, link an SPP at the highest level that achieves your objectives: group +level, subgroup level, or project level. Enforcement at the highest level minimizes the number of +SPPs and therefore the management overhead. Policies cascade down from each level to a project, such that policies may be enforced from the group level, each subgroup above it, and then for any policies created at the project level itself. -### Managing the linked security policy project +Policy inheritance of policies not only ensures maximum coverage with the minimum +number of SPPs, but also helps when implementing policy changes. For example, to test a policy change +you could copy an existing policy and enforce the modified policy first to a project, then to a +subgroup, and, if applicable, to a group. NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select, edit, and unlink a security policy project. +GitLab SaaS users may enforce policies against their top-level group or across subgroups, but cannot enforce policies across GitLab SaaS top-level groups. GitLab self-managed users can enforce policies across multiple top-level groups in their instance. -As a project owner, take the following steps to create or edit an association between your current -project and a project that you would like to designate as the security policy project: +The following example illustrates two groups and their structure: + +- Alpha group contains two subgroups, each of which contains multiple projects. +- Security and Compliance group contains two policies. -1. On the left sidebar, select **Search or go to** and find your project. +**Alpha** group (contains code projects) + +- **Finance** (subgroup) + - Project A + - Accounts receiving (subgroup) + - Project B + - Project C +- **Engineering** (subgroup) + - Project K + - Project L + - Project M + +**Security and Compliance** group (contains SPPs) + +- Security Policy Management +- Security Policy Management - security policy project + - SAST policy + - Secret Detection policy + +Assuming no policies have already been enforced, consider the following examples: + +- If the "SAST" policy is enforced at group Alpha, it applies to its subgroups, Finance and + Engineering, and all their projects and subgroups. If the "Secret Detection" policy is enforced + also at subgroup "Accounts receiving", both policies apply to projects B and C. However, only the + "SAST" policy applies to project A. +- If the "SAST policy is enforced at subgroup "Accounts receiving", it applies only to projects B + and C. No policy applies to project A. +- If the "Secret Detection" is enforced at project K, it applies only to project K. No other + subgroups or projects have a policy apply to them. + +### Separation of duties + +Separation of duties is vital to successfully implementing policies. Security and compliance teams +should be responsible for defining policies and working with development teams. Development teams +should not be able to disable, modify, or circumvent the policies, in any way, or for any +exceptions. The policies should be implemented to achieve the necessary compliance and security +requirements, while allowing development teams to achieve their goals. + +The role required to enforce an SPP depends on the hierarchy level at which it's being linked: + +| Organization unit | Group owner | Subgroup owner | Project owner | +|-------------------|------------------------|------------------------|------------------------| +| Group | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| Subgroup | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| Project | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | + +## Policy implementation + +Implementation options for SPPs differ slightly between GitLab SaaS and GitLab self-managed. The +main difference is that on GitLab SaaS it's only possible to create subgroups. Ensuring separation +of duties requires more granular permission configuration. + +### Enforce policies across subgroups and projects **(ULTIMATE SAAS)** + +To enforce policies against subgroups and projects, create a subgroup to contain the SPPs, separate +to the subgroups containing the projects. Using separate subgroups allows for separation of duties, +with the SPP managed by the security team, and the projects' subgroups managed by the development +team. The security team can add or change policies without intervention from the subgroups' owners. +Subgroup and project owners cannot override policies. + +Prerequisites: + +- You must have the Owner role to link to the SPP. For details see + [Separation of duties](#separation-of-duties). + +The high-level workflow for enforcing policies across multiple subgroups: + +1. Create a subgroup to contain your policies and ensure separation of duties. + + By creating a separate standalone subgroup, you can minimize the number of users who inherit + permissions. +1. In the new group or subgroup, create a new project for managing your policies, such as "Security + Policy Management". + + This serves as the primary location of the policy editor, allowing you to create and manage + policies in the UI. +1. Create a test policy. (you can create a policy as disabled for testing.) + + Creating the policy automatically creates a new SPP under your group or subgroup. This project is + used to store your `policy.yml` or policy-as-code. +1. Check and set project permissions in the newly-created project so that only members of the security team have the Owner role. +1. If additional restrictions are needed to block inherited permissions or require additional review + or approval of policy changes, you can create an additional and separate set of policies to + enforce against the first. For example, you may define a single set of individual users + responsible for approving policy changes. +1. In the SPP just created, create the policies required. You can use the policy editor in the `Security Policy Management` project you created, under the Policies tab. Or you can directly update the policies in the `policy.yml` file stored in the newly-created security policy project `Security Policy Management - security policy project`. +1. Link up groups, subgroups, or projects to the SPP. As a subgroup owner, or project + owner, you can visit the Policies page and create a link to the SPP. Include the full + path and the project's name should end with "- security policy project". For details, see + [Link to a security policy project](#link-to-a-security-policy-project). + +### Enforce policies across groups, subgroups, and projects **(ULTIMATE SELF)** + +To enforce policies against multiple groups, create a group to contain the SPPs, separate to the +groups containing the projects. Using separate groups allows for separation of duties, with the SPP +managed by the security team, and the projects' groups managed by the development team. The security +team can add or change policies without intervention from the groups' owners. Subgroup and project +owners cannot override policies. + +Prerequisites: + +- You must have the Owner role to link to the SPP. For details see + [Separation of duties](#separation-of-duties). +- To support approval groups globally across your instance, enable `security_policy_global_group_approvers_enabled` in your [GitLab instance application settings](../../../api/settings.md). + +The high-level workflow for enforcing policies across multiple groups: + +1. Create a separate group to contain your policies and ensure separation of duties. + + By creating a separate standalone group, you can minimize the number of users who inherit + permissions. +1. In the new group, create a new project for managing your policies, such as "Security Policy + Management". + + This serves as the primary location of the policy editor, allowing you to + create and manage policies in the UI. +1. Create a test policy (you can create a policy as disabled for testing). + + Creating the policy automatically creates a new SPP under your group. This project is + used to store your `policy.yml` or policy-as-code. +1. Check and set permissions in the newly created project as desired. By default, Owners and + Maintainers are able to create, edit, and delete policies. +1. If additional restrictions are needed to block inherited permissions or require additional review + or approval of policy changes, you can create an additional and separate set of policies to + enforce against the first. For example, you may define a single set of individual users + responsible for approving policy changes. +1. Set the permissions of the SPP so that only members of the security team have the Owner role. +1. In the SPP just created, create the policies required. +1. Link up groups, subgroups, or projects to the SPP. As a group owner, subgroup owner, or project + owner, you can visit the Policies page and create a link to the SPP. Include the full path and + the project's name should end with "- security policy project". For details, see + [Link to a security policy project](#link-to-a-security-policy-project). + +### Enforce policies across multiple projects + +When linking a group or subgroup to your policies is not granular enough, it is possible to link up +to the SPP per project. This allows you to filter projects from enforcement that are not applicable. +To enforce an SPP policies at the project level, create a security policy project and link them. Use +project permissions to ensure only the security team has the Owner role in the security policy +project. + +To enforce policies against a project: + +1. Create a security policy project at the same level as the target project. +1. In the security policy project, create the policies required. +1. Link the target project to the security policy project. + +## Link to a security policy project + +To enforce the policies contained in an SPP against a project, subgroup, or group, you link them. + +Prerequisites: + +- You must have the Owner role to link to the SPP. For details, see + [Separation of duties](#separation-of-duties). + +To link a project, subgroup, or group to an SPP: + +1. On the left sidebar, select **Search or go to** and find your project, subgroup, or group. 1. Select **Secure > Policies**. -1. Select **Edit Policy Project**, and search for and select the - project you would like to link from the dropdown list. +1. Select **Edit Policy Project**, then search for and select the project you would like to link + from the dropdown list. 1. Select **Save**. To unlink a security policy project, follow the same steps but instead select the trash can icon in -the modal. - - +the dialog. ### Viewing the linked security policy project -All users who have access to the project policy page and are not project owners will instead view a -button linking out to the associated security policy project. If no security policy project has been -associated then the linking button does not appear. +All users who have access to the project policy page and are not project owners instead view a +button linking out to the associated security policy project. ## Policy management -The Policies page displays deployed -policies for all available environments. You can check a -policy's information (for example, description or enforcement -status), and create and edit deployed policies: +The Policies page displays deployed policies for all available environments. You can check a +policy's information (for example, description or enforcement status), and create and edit deployed +policies: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. @@ -141,16 +301,43 @@ The workaround is to amend your group or instance push rules to allow branches f ### Troubleshooting common issues configuring security policies -- Confirm that scanners are properly configured and producing results for the latest branch. Security Policies are designed to require approval when there are no results (no security report), as this ensures that no vulnerabilities are introduced. We cannot know if there are any vulnerabilities unless the scans enforced by the policy complete successfully and are evaluated. -- For scan result policies, we require artifacts for each scanner defined in the policy for both the source and target branch. To ensure scan result policies capture the necessary results, confirm your scan execution is properly implemented and enforced. If using scan execution policies, enforcing on `all branches` often address this need. -- When running scan execution policies based on a SAST action, ensure target repositories contain proper code files. SAST runs different analyzers [based on the types of files in the repository](../sast/index.md#supported-languages-and-frameworks), and if no supported files are found it will not run any jobs. See the [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) for more details. -- Check for any branch configuration conflicts. If your policy is configured to enforce rules on `main` but some projects within the scope are using `master` as their default branch, the policy is not applied for the latter. You can define policies to enforce rules generically on `default` branches regardless of the name used in the project or on `all protected branches` to address this issue. -- Scan result policies created at the group or sub-group level can take some time to apply to all the merge requests in the group. +- Confirm that scanners are properly configured and producing results for the latest branch. + Security Policies are designed to require approval when there are no results (no security report), + as this ensures that no vulnerabilities are introduced. We cannot know if there are any + vulnerabilities unless the scans enforced by the policy complete successfully and are evaluated. +- For scan result policies, we require artifacts for each scanner defined in the policy for both the + source and target branch. To ensure scan result policies capture the necessary results, confirm + your scan execution is properly implemented and enforced. If using scan execution policies, + enforcing on `all branches` often addresses this need. +- When running scan execution policies based on a SAST action, ensure target repositories contain + proper code files. SAST runs different analyzers + [based on the types of files in the repository](../sast/index.md#supported-languages-and-frameworks), + and if no supported files are found it does not run any jobs. See the + [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) + for more details. +- Check for any branch configuration conflicts. For example, if your policy is configured to enforce rules on + `main` but some projects in the scope are using `master` as their default branch, the policy + is not applied for the latter. You can define policies to enforce rules generically on `default` + branches regardless of the name used in the project or on `all protected branches` to address this + issue. +- Scan result policies created at the group or subgroup level can take some time to apply to all + the merge requests in the group. - Scheduled scan execution policies run with a minimum 15 minute cadence. Learn more [about the schedule rule type](../policies/scan-execution-policies.md#schedule-rule-type). -- When scheduling pipelines, keep in mind that CRON scheduling is based on UTC on GitLab SaaS and is based on your server time for self managed instances. When testing new policies, it may appear pipelines are not running properly when in fact they are scheduled in your server's timezone. -- When enforcing scan execution policies, security policies use a bot in the target project that will trigger scheduled pipelines to ensure enforcement. When the bot is missing, it will be automatically created, and the following scheduled scan will use it. -- You should not link a security policy project to a development project and to the group or sub-group the development project belongs to at the same time. Linking this way will result in approval rules from the Scan Result Policy not being applied to merge requests in the development project. -- When creating a Scan Result Policy, neither the array `severity_levels` nor the array `vulnerability_states` in the [`scan_finding` rule](../policies/scan-result-policies.md#scan_finding-rule-type) can be left empty; for a working rule, at least one entry must exist. -- When configuring pipeline and scan result policies, it's important to remember that security scans performed in manual jobs aren't verified to determine whether MR approval is required. When you run a manual job with security scans, it won't ensure approval even if vulnerabilities are introduced. +- When scheduling pipelines, keep in mind that CRON scheduling is based on UTC on GitLab SaaS and is + based on your server time for self managed instances. When testing new policies, it may appear + pipelines are not running properly when in fact they are scheduled in your server's time zone. +- When enforcing scan execution policies, security policies use a bot in the target project to + trigger scheduled pipelines to ensure enforcement. When the bot is missing, it is automatically + created, and the following scheduled scan uses it. +- You should not link a security policy project to a development project and to the group or + subgroup the development project belongs to at the same time. Linking this way results in approval + rules from the Scan Result Policy not being applied to merge requests in the development project. +- When creating a Scan Result Policy, neither the array `severity_levels` nor the array + `vulnerability_states` in the [`scan_finding` rule](../policies/scan-result-policies.md#scan_finding-rule-type) + can be left empty. For a working rule, at least one entry must exist. +- When configuring pipeline and scan result policies, it's important to remember that security scans + performed in manual jobs are not verified to determine whether MR approval is required. When you + run a manual job with security scans, it does not ensure approval even if vulnerabilities are + introduced. If you are still experiencing issues, you can [view recent reported bugs](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=popularity&state=opened&label_name%5B%5D=group%3A%3Asecurity%20policies&label_name%5B%5D=type%3A%3Abug&first_page_size=20) and raise new unreported issues. diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index f6ef8a2c49e..f299a38dff1 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -1,7 +1,7 @@ --- stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Scan execution policies **(ULTIMATE ALL)** @@ -201,16 +201,23 @@ The keys for a schedule rule are: ## `scan` action type +> - Scan Execution Policies variable precedence was [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/424028) in GitLab 16.7 [with a flag](../../../administration/feature_flags.md) named `security_policies_variables_precedence`. Enabled by default. +> - The `custom` scan action type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126457) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. On GitLab.com, this feature is not available. On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `compliance_pipeline_in_policies`. + This action executes the selected `scan` with additional parameters when conditions for at least one rule in the defined policy are met. | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| -| `scan` | `string` | `sast`, `sast_iac`, `dast`, `secret_detection`, `container_scanning`, `dependency_scanning` | The action's type. | +| `scan` | `string` | `sast`, `sast_iac`, `dast`, `secret_detection`, `container_scanning`, `dependency_scanning`, `custom` | The action's type. | | `site_profile` | `string` | Name of the selected [DAST site profile](../dast/proxy-based.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | | `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/proxy-based.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| | `variables` | `object` | | A set of CI variables, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the variable name, with its `value` provided as a string. This parameter supports any variable that the GitLab CI job supports for the specified scan. | | `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs are run by runner with the specified tags. | +| `ci_configuration` <sup>1</sup> | `string` | | GitLab CI YAML as formatted as string. | +| `ci_configuration_path` <sup>1</sup> | object | Object with project path and file name pointing to a CI configuration. | + +1. For `custom` scans, you must specify one of `ci_configuration` or `ci_configuration_path`. Note the following: @@ -224,13 +231,22 @@ Note the following: policy project's repository must have access to the scanner and site profiles. Otherwise, the scan is not scheduled successfully. - For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) - are not supported. -- A secret detection scan runs in `default` mode when executed as part of a pipeline, and in - [`historic`](../secret_detection/index.md#full-history-secret-detection) - mode when executed as part of a scheduled scan. + are not supported. Alternatively, you may configure a [remote configuration file](../secret_detection/index.md#specify-a-remote-configuration-file) and set the `SECRET_DETECTION_RULESET_GIT_REFERENCE` variable. +- By default, for `scheduled` scan execution policies, secret detection scans configured without any CI variables defined run first in `historic` mode (`SECRET_DETECTION_HISTORIC_SCAN` = `true`). All subsequent scheduled scans run in default mode with `SECRET_DETECTION_LOG_OPTIONS` set to the commit range between last run and current SHA. CI variables provided in the scan execution policy can override this behavior. Learn more about [historic mode](../secret_detection/index.md#full-history-secret-detection). +- For `triggered` scan execution policies, secret detection works just like regular scan [configured manually in the `.gitlab-ci.yml`](../secret_detection/index.md#edit-the-gitlab-ciyml-file-manually). - A container scanning scan that is configured for the `pipeline` rule type ignores the agent defined in the `agents` object. The `agents` object is only considered for `schedule` rule types. An agent with a name provided in the `agents` object must be created and configured for the project. - Variables defined in a Scan Execution Policy follow the standard [CI/CD variable precedence](../../../ci/variables/index.md#cicd-variable-precedence). +- `custom` scans are be executed for scheduled rules. +- Jobs variables and stages definitions from `custom` scans take precedence over the project's CI/CD configuration. + +### `ci_configuration_path` object + +| Field | Type | Description | +|-------|------|-------------| +| `project` | `string` | A project namespace path. | +| `file` | `string` | The filename of the CI/CD YAML file. | +| `ref` | `string` (optional) | The branch name, tag name, or commit SHA. | ## Example security policies project @@ -251,6 +267,12 @@ scan_execution_policy: - scan: dast scanner_profile: Scanner Profile A site_profile: Site Profile B + - scan: custom + ci_configuration: |- + test job: + stage: test + script: + - echo "Hello World" - name: Enforce DAST and secret detection scans every 10 minutes description: This policy enforces DAST and secret detection scans to run every 10 minutes enabled: true @@ -282,7 +304,9 @@ scan_execution_policy: In this example: - For every pipeline executed on branches that match the `release/*` wildcard (for example, branch - `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. + `release/v1.2.1`) + - DAST scans run with `Scanner Profile A` and `Site Profile B`. + - A `test job` is injected into the `test` stage of the pipeline, printing `Hello World`. - DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` and `Site Profile D`. - Secret detection, container scanning, and SAST scans run for every pipeline executed on the `main` diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index d0d3cb2ca03..0fadd761fe4 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -1,7 +1,7 @@ --- stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Scan result policies **(ULTIMATE ALL)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can use scan result policies to take action based on scan results. For example, one type of scan result policy is a security approval policy that allows approval to be required based on the -findings of one or more security scan jobs. Scan result policies are evaluated after a CI scanning job is fully executed. +findings of one or more security scan jobs. Scan result policies are evaluated after a CI scanning job is fully executed and both vulnerability and license type policies are evaluated based on the job artifact reports that are published in the completed pipeline. NOTE: Scan result policies are applicable only to [protected](../../project/protected_branches.md) target branches. @@ -34,6 +34,7 @@ The following video gives you an overview of GitLab scan result policies: - The maximum number of policies is five. - Each policy can have a maximum of five rules. - All configured scanners must be present in the merge request's latest pipeline. If not, approvals are required even if some vulnerability criteria have not been met. +- Scan result policies evaluate findings and determine approval requirements based on the job artifact reports published in a completed pipeline. However, scan result policies do not check the integrity or authenticity of the scan results generated in the artifact reports. ## Merge request with multiple pipelines @@ -84,24 +85,24 @@ If you're not familiar with how to read [JSON schemas](https://json-schema.org/) the following sections and tables provide an alternative. | Field | Type | Required | Possible values | Description | -|----------------------|-------------------------------|----------|-----------------|------------------------------------------| +|----------------------|-------------------------------|----------|-----------------|-------------------------------------------| | `scan_result_policy` | `array` of Scan Result Policy | true | | List of scan result policies (maximum 5). | ## Scan result policy schema -> The `approval_settings` fields was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. All are disabled by default. +> The `approval_settings` fields were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information. FLAG: -On self-managed GitLab, by default the `approval_settings` field is unavailable. To show the feature, an administrator can [enable the feature flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request`, or `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information. +On self-managed GitLab, by default the `approval_settings` field is available. To hide the feature, an administrator can [disable the feature flags](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`, `scan_result_any_merge_request` and `scan_result_policies_block_force_push`. See the `approval_settings` section below for more information. On GitLab.com, the `approval_settings` field is available. -| Field | Type | Required |Possible values | Description | -|--------|------|----------|----------------|-------------| -| `name` | `string` | true | | Name of the policy. Maximum of 255 characters.| -| `description` | `string` | false | | Description of the policy. | -| `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | -| `rules` | `array` of rules | true | | List of rules that the policy applies. | -| `actions` | `array` of actions | false | | List of actions that the policy enforces. | -| `approval_settings` | `object` | false | | Project settings that the policy overrides. | +| Field | Type | Required | Possible values | Description | +|---------------------|--------------------|----------|-----------------|----------------------------------------------------------| +| `name` | `string` | true | | Name of the policy. Maximum of 255 characters. | +| `description` | `string` | false | | Description of the policy. | +| `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | +| `rules` | `array` of rules | true | | List of rules that the policy applies. | +| `actions` | `array` of actions | false | | List of actions that the policy enforces. | +| `approval_settings` | `object` | false | | Project settings that the policy overrides. | ## `scan_finding` rule type @@ -115,7 +116,7 @@ This rule enforces the defined actions based on security scan findings. |-------|------|----------|-----------------|-------------| | `type` | `string` | true | `scan_finding` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of protected branches the given policy applies to. Cannot be used with the `branches` field. Default branches must also be `protected`. | | `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `scanners` | `array` of `string` | true | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. `sast` includes results from both SAST and SAST IaC scanners. | | `vulnerabilities_allowed` | `integer` | true | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | @@ -136,7 +137,7 @@ This rule enforces the defined actions based on license findings. |------------|------|----------|-----------------|-------------| | `type` | `string` | true | `license_finding` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of protected branches the given policy applies to. Cannot be used with the `branches` field. Default branches must also be `protected`. | | `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `match_on_inclusion` | `boolean` | true | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | | `license_types` | `array` of `string` | true | license types | [SPDX license names](https://spdx.org/licenses) to match on, for example `Affero General Public License v1.0` or `MIT License`. | @@ -145,10 +146,11 @@ This rule enforces the defined actions based on license findings. ## `any_merge_request` rule type > - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/133753) in GitLab 16.5. Feature flag removed. -> - The `any_merge_request` rule type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4. Disabled by default. +> - The `any_merge_request` rule type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4. Enabled by default. [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136298) in GitLab 16.6. FLAG: -On self-managed GitLab, by default the `any_merge_request` field is not available. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `any_merge_request`. +On self-managed GitLab, by default the `any_merge_request` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `any_merge_request`. +On GitLab.com, this feature is available. This rule enforces the defined actions for any merge request based on the commits signature. @@ -156,7 +158,7 @@ This rule enforces the defined actions for any merge request based on the commit |---------------|---------------------|--------------------------------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | `string` | true | `any_merge_request` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | -| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of protected branches the given policy applies to. Cannot be used with the `branches` field. Default branches must also be `protected`. | | `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `commits` | `string` | true | `any`, `unsigned` | Whether the rule matches for any commits, or only if unsigned commits are detected in the merge request. | @@ -179,24 +181,31 @@ the defined policy. > - The `block_unprotecting_branches` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423101) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policy_settings`. Disabled by default. > - The `scan_result_policy_settings` feature flag was replaced by the `scan_result_policies_block_unprotecting_branches` feature flag in 16.4. +> - The `block_unprotecting_branches` field was [replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137153) by `block_branch_modification` field in GitLab 16.7. +> - The above field was [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423901) in GitLab 16.7. +> - The above field was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423901) in GitLab 16.7. > - The `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. Disabled by default. -> - The `prevent_force_pushing` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420629) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. Disabled by default. +> - The above fields were [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.6. +> - The above fields were [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/423988) in GitLab 16.7. +> - The `prevent_pushing_and_force_pushing` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420629) in GitLab 16.4 [with flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. Disabled by default. +> - The above field was [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.6. +> - The above field was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/427260) in GitLab 16.7. FLAG: -On self-managed GitLab, by default the `block_unprotecting_branches` field is unavailable. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`. On GitLab.com, this feature is unavailable. -On self-managed GitLab, by default the `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields are unavailable. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. On GitLab.com, this feature is available. -On self-managed GitLab, by default the `prevent_force_pushing` field is unavailable. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. On GitLab.com, this feature is unavailable. +On self-managed GitLab, by default the `block_branch_modification` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_policies_block_unprotecting_branches`. On GitLab.com, this feature is available. +On self-managed GitLab, by default the `prevent_approval_by_author`, `prevent_approval_by_commit_author`, `remove_approvals_with_new_commit`, and `require_password_to_approve` fields are available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_any_merge_request`. On GitLab.com, this feature is available. +On self-managed GitLab, by default the `prevent_pushing_and_force_pushing` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `scan_result_policies_block_force_push`. On GitLab.com, this feature is available. The settings set in the policy overwrite settings in the project. -| Field | Type | Required | Possible values | Description | -|-------|------|----------|-----------------|-------------| -| `block_unprotecting_branches` | `boolean` | false | `true`, `false` | Prevent a user from removing a branch from the protected branches list, deleting a protected branch, or changing the default branch if that branch is included in the security policy. | -| `prevent_approval_by_author` | `boolean` | false | `true`, `false` | When enabled, two person approval is required on all MRs as merge request authors cannot approve their own MRs and merge them unilaterally. | -| `prevent_approval_by_commit_author` | `boolean` | false | `true`, `false` | When enabled, users who have contributed code to the MR are ineligible for approval, ensuring code committers cannot introduce vulnerabilities and approve code to merge. | -| `remove_approvals_with_new_commit` | `boolean` | false | `true`, `false` | If an MR receives all necessary approvals to merge, but then a new commit is added, new approvals are required. This ensures new commits that may include vulnerabilities cannot be introduced. | -| `require_password_to_approve` | `boolean` | false | `true`, `false` | Password confirmation on approvals provides an additional level of security. Enabling this enforces the setting on all projects targeted by this policy. | -| `prevent_force_pushing` | `boolean` | false | `true`, `false` | Prevent pushing and force pushing to a protected branch. | +| Field | Type | Required | Possible values | Applicable rule type | Description | +|-------------------------------------|-----------|----------|-----------------|----------------------|-------------| +| `block_branch_modification` | `boolean` | false | `true`, `false` | All | When enabled, prevents a user from removing a branch from the protected branches list, deleting a protected branch, or changing the default branch if that branch is included in the security policy. This ensures users cannot remove protection status from a branch to merge vulnerable code. | +| `prevent_approval_by_author` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, merge request authors cannot approve their own MRs. This ensures code authors cannot introduce vulnerabilities and approve code to merge. | +| `prevent_approval_by_commit_author` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, users who have contributed code to the MR are ineligible for approval. This ensures code committers cannot introduce vulnerabilities and approve code to merge. | +| `remove_approvals_with_new_commit` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, if an MR receives all necessary approvals to merge, but then a new commit is added, new approvals are required. This ensures new commits that may include vulnerabilities cannot be introduced. | +| `require_password_to_approve` | `boolean` | false | `true`, `false` | `Any merge request` | When enabled, there will be password confirmation on approvals. Password confirmation adds an extra layer of security. | +| `prevent_pushing_and_force_pushing` | `boolean` | false | `true`, `false` | All | When enabled, prevents users from pushing and force pushing to a protected branch if that branch is included in the security policy. This ensures users do not bypass the merge request process to add vulnerable code to a branch. | ## Example security scan result policies project @@ -325,6 +334,16 @@ There are several situations where the scan result policy requires an additional - A job in a merge request fails and is configured with `allow_failure: false`. As a result, the pipeline is in a blocked state. - A pipeline has a manual job that must run successfully for the entire pipeline to pass. +### Managing scan findings used to evaluate approval requirements + +Scan result policies evaluate the artifact reports generated by scanners in your pipelines after the pipeline has completed. Scan result policies focus on evaluating the results and determining approvals based on the scan result findings to identify potential risks, block merge requests, and require approval. + +Scan result policies do not extend beyond that scope to reach into artifact files or scanners. Instead, we trust the results from artifact reports. This gives teams flexibility in managing their scan execution and supply chain, and customizing scan results generated in artifact reports (for example, to filter out false positives) if needed. + +Lock file tampering, for example, is outside of the scope of security policy management, but may be mitigated through use of [Code owners](../../project/codeowners/index.md#codeowners-file) or [external status checks](../../project/merge_requests/status_checks.md). For more information, see [issue 433029](https://gitlab.com/gitlab-org/gitlab/-/issues/433029). + + + ### Known issues We have identified in [epic 11020](https://gitlab.com/groups/gitlab-org/-/epics/11020) common areas of confusion in scan result findings that need to be addressed. Below are a few of the known issues: @@ -364,3 +383,30 @@ end.each do |project, configuration_ids| Security::ScanResultPolicies::SyncProjectWorker.perform_async(project.id) end ``` + +### Debugging security approval policy approvals + +GitLab SaaS users may submit a [support ticket](https://about.gitlab.com/support/) titled "Scan result approval policy debugging". Provide the following details: + +- Group path, project path and optionally merge request ID +- Severity +- Current behavior +- Expected behavior + +Support teams will investigate [logs](https://log.gprd.gitlab.net/) (`pubsub-sidekiq-inf-gprd*`) to identify the failure `reason`. Below is an example response snippet from logs. You can use this query to find logs related to approvals: `json.event.keyword: "update_approvals"` and `json.project_path: "group-path/project-path"`. Optionally, you can further filter by the merge request identifier using `json.merge_request_iid`: + +```json +"json": { + "project_path": "group-path/project-path", + "merge_request_iid": 2, + "missing_scans": [ + "api_fuzzing" + ], + "reason": "Scanner removed by MR", + "event": "update_approvals", +} +``` + +Common failure reasons: + +- Scanner removed by MR: Scan result policy expect that the scanners defined in the policy are present and that they successfully produce an artifact for comparison. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index f896616d537..a813ac9888d 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAST analyzers **(FREE ALL)** diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index ed3b33fc35b..992e99f1cc7 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customize rulesets **(ULTIMATE ALL)** diff --git a/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png b/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png Binary files differnew file mode 100644 index 00000000000..c86f536afc4 --- /dev/null +++ b/doc/user/application_security/sast/img/sast_inline_indicator_v16_7.png diff --git a/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png b/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png Binary files differnew file mode 100644 index 00000000000..199f8b6d322 --- /dev/null +++ b/doc/user/application_security/sast/img/sast_mr_widget_v16_7.png diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 770e24d87ca..ab6d5212227 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Static Application Security Testing (SAST) **(FREE ALL)** @@ -17,7 +17,6 @@ any GitLab tier. The analyzers output JSON-formatted reports as job artifacts. With GitLab Ultimate, SAST results are also processed so you can: -- See them in merge requests. - Use them in approval workflows. - Review them in the security dashboard. @@ -208,7 +207,8 @@ include: A FIPS-compliant image is only available for the Semgrep-based analyzer. -To use SAST in a FIPS-compliant manner, you must [exclude other analyzers from running](analyzers.md#customize-analyzers). +WARNING: +To use SAST in a FIPS-compliant manner, you must [exclude other analyzers from running](analyzers.md#customize-analyzers). If you use a FIPS-enabled image to run Semgrep in [a runner with non-root user](https://docs.gitlab.com/runner/install/kubernetes.html#running-with-non-root-user), you must update the `run_as_user` attribute under `runners.kubernetes.pod_security_context` to use the ID of `gitlab` user [created by the image](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/a5d822401014f400b24450c92df93467d5bbc6fd/Dockerfile.fips#L58), which is `1000`. ## Summary of features per tier @@ -222,6 +222,7 @@ as shown in the following table: | [Customize SAST settings](#available-cicd-variables) | **{check-circle}** | **{check-circle}** | | Download [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | | See new findings in merge request widget | **{dotted-circle}** | **{check-circle}** | +| See new findings in merge request changes | **{dotted-circle}** | **{check-circle}** | | [Manage vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | | [Configure SAST by using the UI](#configure-sast-by-using-the-ui) | **{dotted-circle}** | **{check-circle}** | @@ -229,6 +230,35 @@ as shown in the following table: | [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | | [Track moved vulnerabilities](#advanced-vulnerability-tracking) | **{dotted-circle}** | **{check-circle}** | +## View SAST results + +SAST results are shown in the: + +- Merge request widget +- Merge request changes view +- Vulnerability Report + +### Merge request widget **(ULTIMATE ALL)** + +SAST results display in the merge request widget area if a report from the target +branch is available for comparison. The merge request widget displays SAST findings and resolutions that +were introduced by the changes made in the merge request. + + + +### Merge request changes view **(ULTIMATE ALL)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10959) in GitLab 16.6 with a [flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `sast_reports_in_inline_diff`. +On GitLab.com, this feature is available. + +SAST results display in the merge request **Changes** view. Lines containing SAST +issues are marked by a symbol beside the gutter. Select the symbol to see the list of issues, then select an issue to see its details. + + + ## Contribute your scanner The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab. @@ -642,7 +672,7 @@ run successfully. For more information, see [Offline environments](../offline_de To use SAST in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- A Docker container registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Configure certificate checking of packages (optional). GitLab Runner has a [default `pull_policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), diff --git a/doc/user/application_security/sast/rules.md b/doc/user/application_security/sast/rules.md index 3fb24bcd66b..187f8b940b2 100644 --- a/doc/user/application_security/sast/rules.md +++ b/doc/user/application_security/sast/rules.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAST rules **(FREE)** diff --git a/doc/user/application_security/sast/troubleshooting.md b/doc/user/application_security/sast/troubleshooting.md index 77a2f20c934..0ac94db4f47 100644 --- a/doc/user/application_security/sast/troubleshooting.md +++ b/doc/user/application_security/sast/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting SAST **(FREE ALL)** diff --git a/doc/user/application_security/secret_detection/automatic_response.md b/doc/user/application_security/secret_detection/automatic_response.md index 1a5ab913b29..762d42d7614 100644 --- a/doc/user/application_security/secret_detection/automatic_response.md +++ b/doc/user/application_security/secret_detection/automatic_response.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Automatic response to leaked secrets **(ULTIMATE ALL)** diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 4332b91c0f9..bf7375a58d7 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secret Detection **(FREE ALL)** diff --git a/doc/user/application_security/secret_detection/pre_receive.md b/doc/user/application_security/secret_detection/pre_receive.md new file mode 100644 index 00000000000..1e7ea4aaaeb --- /dev/null +++ b/doc/user/application_security/secret_detection/pre_receive.md @@ -0,0 +1,73 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Pre-receive secret detection **(EXPERIMENT)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11439) in GitLab 16.7 as an [Experiment](../../../policy/experiment-beta-support.md) for GitLab Dedicated customers. + +NOTE: +This feature is an [Experiment](../../../policy/experiment-beta-support.md), available only on GitLab Dedicated, and is subject to the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). + +Pre-receive secret detection scans the contents of committed files when they are pushed to a remote repository to prevent the accidental exposure of secrets like keys or API tokens to your repositories. If any secrets are detected, the push is blocked, ensuring that the secrets do not reach your instance. + +Pre-receive secret detection is an Experiment, and only available on GitLab Dedicated. To use secret detection in your instance, use [pipeline secret detection](../index.md) instead. + +## Enable pre-receive secret detection + +Prerequisites: + +- You must be an administrator for your GitLab Dedicated instance. + +1. Sign into your GitLab Dedicated instance as an administrator. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > Security and Compliance**. +1. Expand **Secret Detection**. +1. Select the **Enable pre-receive secret detection** checkbox. + +## Limitations + +This feature only scans non-binary blobs under 1 MiB in size. Binary blobs and blobs larger than 1 MiB are not scanned. + +## Resolve a blocked push + +If the blocked secret was added with the most recent commit on your branch: + +1. Remove the secrets from the files. +1. Stage the changes with `git add <file-name>`. +1. Modify the most recent commit to include the changed files with `git commit --amend`. +1. Push your changes with `git push`. + +If the blocked secret appears earlier in your Git history: + +1. Identify the commit SHA from the push error message. If there are multiple, find the earliest using `git log`. +1. Use `git rebase -i <commit-sha>~1` to start an interactive rebase. +1. Mark the offending commits for editing by changing the `pick` command to `edit` in the editor. +1. Remove the secrets from the files. +1. Stage the changes with `git add <file-name>`. +1. Commit the changed files with `git commit --amend`. +1. Continue the rebase with `git rebase --continue` until all secrets are removed. +1. Push your changes with `git push`. + +## Skip secret detection + +In some cases, it may be necessary to skip pre-receive secret detection. For example, a developer may need to commit a placeholder secret for testing, or a user may want to bypass secret detection due to a Git operation timeout. To skip secret detection for a particular secret, add `# gitleaks:allow` to the end of the line. To skip secret detection for all commits in a push, add `[skip secret detection]` to one of the commit messages. For example: + +```ruby +# This secret will be skipped due to gitleaks:allow. +FAKE_TOKEN = allowfaketoken123 # gitleaks:allow + +# This secret will be scanned, and the push will be rejected. +REAL_TOKEN = rejectrealtoken123 +``` + +```shell +# These commits are in the same push. Both will not be scanned. +Add real secret by accident +Add placeholder token to test file [skip secret detection] +``` + +NOTE: +[Pipeline secret detection](../index.md) still scans the bypassed secrets when using `[skip secret detection]` in one of your commit messages. diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md index f4fb8c49277..b35de7827e8 100644 --- a/doc/user/application_security/secure_your_application.md +++ b/doc/user/application_security/secure_your_application.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure your application **(FREE ALL)** diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png Binary files differindex 1d324b8207a..f2dcf22f5ab 100644 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png Binary files differindex 46fdebca9cd..6491c99e31c 100644 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 89c950f2473..405017ab023 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Security Dashboards and Security Center **(ULTIMATE ALL)** @@ -19,7 +18,7 @@ you with a collection of metrics, ratings, and charts for the vulnerabilities de The data provided by the Security Dashboards can be used supply to insight on what decisions can be made to improve your security posture. For example, using the 365 day trend view, you can see on which days a significant number of vulnerabilities were introduced. Then you can examine the code changes performed on those particular days in order perform a root-cause analysis to create better policies for preventing the introduction of vulnerabilities in the future. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Security Dashboard](https://www.youtube.com/watch?v=QHQHN4luNpc). +For an overview, see [Security Dashboard](https://www.youtube.com/watch?v=Uo-pDns1OpQ). ## Prerequisites diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index f09672685de..ba501baefb0 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -1,8 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure and Govern glossary **(FREE ALL)** diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 476b2411621..0fda401194d 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability Page **(ULTIMATE ALL)** @@ -77,6 +77,47 @@ The following data is shared with third-party AI APIs: record). - Filename. +## Vulnerability resolution **(ULTIMATE SAAS EXPERIMENT)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10779) in GitLab 16.7 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) on GitLab.com. + +Use GitLab Duo Vulnerability resolution to automatically create a merge request that +resolves the vulnerability. + +On GitLab.com this feature is available. By default, it is powered by Google's `code-bison-001` +model. + +We cannot guarantee that the large language model produces results that are correct. Use the +explanation with caution. + +Prerequisites: + +- You must have the GitLab Ultimate subscription tier. +- You must be a member of the project. +- The vulnerability must be a SAST finding. + +Learn more about [how to enable all GitLab Duo features](../../ai_features.md#enable-aiml-features). + +To resolve the vulnerability: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Security and Compliance > Vulnerability report**. +1. In the **Tool** dropdown list, select **SAST**. +1. Select the SAST vulnerability you want resolved. +1. At the top of the vulnerability's page, from the **Resolve with merge request** dropdown list, select **Resolve with AI**. + +A merge request containing the AI remediation suggestions is opened. Review the suggested changes, +then process the merge request according to your standard workflow. + +### Data shared with third-party AI APIs + +The following data is shared with third-party AI APIs: + +- Vulnerability title (which might contain the file name, depending on which scanner is used). +- Vulnerability identifiers. +- Code block. +- File name. + ## Vulnerability status values A vulnerability's status can be: @@ -126,17 +167,9 @@ To change a vulnerability's status from its Vulnerability Page: Details of the status change, including who made the change and when, are recorded in the vulnerability's action log. -## Creating an issue for a vulnerability +## Create a GitLab issue for a vulnerability -From a vulnerability's page you can create an issue to track all action taken to resolve or -mitigate it. - -You can create either: - -- [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default). -- [A Jira issue](#create-a-jira-issue-for-a-vulnerability). - -### Create a GitLab issue for a vulnerability +You can create a GitLab issue to track any action taken to resolve or mitigate a vulnerability. To create a GitLab issue for a vulnerability: @@ -145,42 +178,19 @@ To create a GitLab issue for a vulnerability: 1. Select the vulnerability's description. 1. Select **Create issue**. -An issue is created in the project, pre-populated with information from the vulnerability report. -The issue is then opened so you can take further action. +A GitLab issue is created in the project with information from the vulnerability report. -### Create a Jira issue for a vulnerability - -Prerequisites: - -- [Enable Jira integration](../../../integration/jira/configure.md). The - **Enable Jira issue creation from vulnerabilities** option must be selected as part - of the configuration. -- Each user must have a personal Jira user account with permission to create issues in the target - project. - -To create a Jira issue for a vulnerability: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Secure > Vulnerability report**. -1. Select the vulnerability's description. -1. Select **Create Jira issue**. -1. If you're not already logged in to Jira, sign in. - -The Jira issue is created and opened in a new browser tab. The **Summary** and **Description** -fields are pre-populated from the vulnerability's details. - -Unlike GitLab issues, the status of whether a Jira issue is open or closed does not display in the -GitLab user interface. +To create a Jira issue, see [Create a Jira issue for a vulnerability](../../../integration/jira/configure.md#create-a-jira-issue-for-a-vulnerability). ## Linking a vulnerability to GitLab and Jira issues You can link a vulnerability to one or more existing [GitLab](#create-a-gitlab-issue-for-a-vulnerability) -or [Jira](#create-a-jira-issue-for-a-vulnerability) issues. Only one linking feature is available at the same time. +or [Jira](../../../integration/jira/configure.md#create-a-jira-issue-for-a-vulnerability) issues. Only one linking feature is available at the same time. Adding a link helps track the issue that resolves or mitigates a vulnerability. ### Link a vulnerability to existing GitLab issues -Prerequisite: +Prerequisites: - [Jira issue integration](../../../integration/jira/configure.md) must not be enabled. @@ -209,7 +219,7 @@ Be aware of the following conditions between a vulnerability and a linked GitLab ### Link a vulnerability to existing Jira issues -Prerequisite: +Prerequisites: - [Jira issue integration](../../../integration/jira/configure.md) must be enabled, with option **Enable Jira issue creation from vulnerabilities** also enabled. @@ -282,7 +292,7 @@ To manually apply the patch that GitLab generated for a vulnerability: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. NOTE: -Security training is not accessible in an environment that is offline, meaning computers that are isolated from the public internet as a security measure. Some third-party training vendors may require you to sign up for a _free_ account. Sign up for an account by going to +Security training is not accessible in an environment that is offline, meaning computers that are isolated from the public internet as a security measure. Specifically, the GitLab server needs the ability to query the API endpoints for any training provider you choose to enable. Some third-party training vendors may require you to sign up for a _free_ account. Sign up for an account by going to any of [Secure Code Warrior](https://www.securecodewarrior.com/), [Kontra](https://application.security/), or [SecureFlag](https://www.secureflag.com/). GitLab does not send any user information to these third-party vendors; we do send the CWE or OWASP identifier and the language name of the file extension. diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index db6b4e0f4a8..0db848d6d11 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability severity levels **(ULTIMATE ALL)** diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index e71aab5839e..23454bf387a 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability Report **(ULTIMATE ALL)** @@ -12,7 +11,7 @@ cumulative results of all successful jobs, regardless of whether the pipeline wa pipeline are only ingested after all the jobs in the pipeline complete. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Vulnerability Management](https://www.youtube.com/watch?v=8SJHz6BCgXM). +For an overview, see [Vulnerability Management](https://www.youtube.com/watch?v=alMRIq5UPbw). At all levels, the Vulnerability Report contains: @@ -29,8 +28,8 @@ At the project level, the Vulnerability Report also contains: The **Activity** column contains icons to indicate the activity, if any, taken on the vulnerability in that row: -- Issues **{issues}**: Links to issues created for the vulnerability. For more details, read - [Create an issue for a vulnerability](../vulnerabilities/index.md#creating-an-issue-for-a-vulnerability). +- Issues **{issues}**: Links to issues created for the vulnerability. For more information, see + [Create a GitLab issue for a vulnerability](../vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability). - Wrench **{admin}**: The vulnerability has been remediated. - False positive **{false-positive}**: The scanner determined this vulnerability to be a false positive. @@ -81,6 +80,8 @@ Additionally, the [project filter](#project-filter) is available at the group le To filter the list of vulnerabilities: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Vulnerability report**. 1. Select a filter. 1. Select values from the dropdown list. 1. Repeat the above steps for each desired filter. @@ -92,13 +93,33 @@ After each filter is selected: ### Tool filter -The tool filter allows you to focus on vulnerabilities detected by selected tools. +> Project-level tool filter [introduced](https://gitlab.com/groups/gitlab-org/-/epics/11237) in GitLab 16.6. + +You can filter vulnerabilities by the tool that detected them. By default, the +vulnerability report lists vulnerabilities from all tools. When you select a heading, you select all the tools +under that heading. + +::Tabs + +:::TabTitle GitLab 16.6 and later + +The content of the tool filter for both projects and groups depends on the following: + +- If you've integrated and enabled third-party analyzers, the tool filter is grouped by + scanning category (for example, container scanning, DAST, and dependency scanning). Scanner + entries are only shown if the scanner detected vulnerabilities. +- If you have not integrated any third-party analyzers, see GitLab 16.5 and + earlier. -When using the tool filter, you can choose: +:::TabTitle GitLab 16.5 and earlier -- **All tools** (default). -- Individual GitLab-provided tools. -- Any integrated third-party tool. +The content of the tool filter at all levels is categorized first by the analyzer's vendor, then by +scanning category. If you've only enabled GitLab analyzers, only those analyzers are listed in the +tool filter. + +::EndTabs + +To filter vulnerabilities that were added manually, use the **Manually added** filter. For details of each of the available tools, see [Security scanning tools](../index.md#application-coverage). @@ -113,7 +134,7 @@ The content of the Project filter depends on the current level: ### Activity filter The activity filter behaves differently from the other filters. You can select only one value in -each category. +each category. To remove a filter, from the activity filter dropdown list select the filter you want to remove. Selection behavior when using the activity filter: @@ -146,12 +167,19 @@ To view the relevant file, select the filename in the vulnerability's details. > Providing a comment and dismissal reason [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408366) in GitLab 16.0. -From the Vulnerability Report you can change the status of one or more vulnerabilities. +As you triage vulnerabilities you can change their status, including dismissing vulnerabilities. + +When a vulnerability is dismissed, the audit log includes a note of who dismissed it, when it was +dismissed, and the reason it was dismissed. You cannot delete vulnerability records, so a permanent +record always remains. -To change the status of vulnerabilities in the table: +To change the status of vulnerabilities: -1. Select the checkbox beside each vulnerability you want to update the status of. To select all, - select the checkbox in the table header. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Vulnerability report**. +1. To select: + - One or more vulnerabilities, select the checkbox beside each vulnerability. + - All vulnerabilities on the page, select the checkbox in the table header. 1. In the **Set status** dropdown list, select the desired status. 1. If the **Dismissed** status is chosen, select the desired reason in the **Set dismissal reason** dropdown list. 1. In the **Add a comment** input, you can provide a comment. For the **Dismissed** status, a comment is required. @@ -173,11 +201,11 @@ apply to the export. Fields included are: +- Status (See the following table for details of how the status value is exported.) - Group name - Project name - Tool - Scanner name -- Status - Vulnerability - Basic details - Additional information @@ -198,6 +226,16 @@ Full details are available through our Use one of the `gl-*-report.json` report filenames in place of `*artifact_path` to obtain, for example, the path of files in which vulnerabilities were detected. +The Status field's values shown in the vulnerability report are different to those contained +in the vulnerability export. Use the following reference table to match them. + +| Vulnerability report | Vulnerability export | +|:---------------------|:---------------------| +| Needs triage | detected | +| Dismissed | dismissed | +| Resolved | resolved | +| Confirmed | confirmed | + ### Export details in CSV format To export details of all vulnerabilities listed in the Vulnerability Report, select **Export**. @@ -209,57 +247,41 @@ NOTE: It may take several minutes for the download to start if your project contains thousands of vulnerabilities. Do not close the page until the download finishes. -## Dismiss a vulnerability - -When you evaluate a vulnerability and decide it requires no more action, -you can mark it as **Dismissed**. -Dismissed vulnerabilities do not appear in the merge request security widget -when detected in future scans. - -When a vulnerability is dismissed in a project or group, a record is made of: - -- Who dismissed it. -- Date and time when it was dismissed. -- Optionally, a reason why it was dismissed. - -Vulnerability records cannot be deleted, so a permanent record always remains. - -You can dismiss a vulnerability in projects and groups: - -1. Select the vulnerability in the Security Dashboard. -1. In the upper-right corner, from the **Status** dropdown list, select **Dismissed**. -1. Optional. Add a reason for the dismissal and select **Save comment**. - -To undo this action, select a different status from the same menu. - -## Manually add a vulnerability finding +## Manually add a vulnerability > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353796) in GitLab 14.10. > - [Feature flag `new_vulnerability_form`](https://gitlab.com/gitlab-org/gitlab/-/issues/359049) removed in GitLab 15.0. -To add a new vulnerability finding from your project level Vulnerability Report page: +Add a vulnerability manually when it is not available in the GitLab vulnerabilities database. You +can add a vulnerability only in a project's vulnerability report. + +To add a vulnerability manually: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select **Submit vulnerability**. 1. Complete the fields and submit the form. -You are brought to the newly created vulnerability's detail page. Manually created records appear in the -Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. +The newly-created vulnerability's detail page is opened. ## Group vulnerabilities -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/420055) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `vulnerability_report_grouping`. Disabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10164) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `vulnerability_report_grouping`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/422509) in GitLab 16.6. Feature flag `vulnerability_report_grouping` removed. -To group the Vulnerability Report: +In the project-level vulnerability report you can group vulnerabilities, enabling more efficient +triaging. -1. Below the **Vulnerability Report** filters, select the **Group By** dropdown list. -1. Select the attribute you want to group by: status or severity. +To group vulnerabilities in the vulnerability report: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Secure > Vulnerability report**. +1. From the **Group By** dropdown list, select an attribute. -To see what is included in a group, select a category to expand the report and see related -vulnerabilities. +Vulnerabilities are grouped according to the attribute you selected. Each group is collapsed, with +totals per group displayed beside their name. To see the vulnerabilities in each group, select the group's +name. ## Operational vulnerabilities diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index ef66925b9c9..e60ac7d4c21 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -1,54 +1,45 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# View vulnerabilities in a pipeline +# Vulnerabilities in a pipeline -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. +All enabled security analyzers run in the pipeline and output their results as artifacts. These +artifacts are processed, including [deduplication](#deduplication-process), and the results are +listed on the pipeline **Security** tab. By identifying vulnerability +[findings](../terminology/index.md#finding) in a pipeline, you can address the risks +proactively. + +The following criteria apply to the pipeline security tab: + +- The results of only successful security scan jobs are shown. For example, if a pipeline contains + SAST and DAST jobs, but the DAST job fails, only the SAST results are shown. +- If the pipeline has a [blocking manual job](../../../ci/jobs/job_control.md#types-of-manual-jobs), + the pipeline waits for the manual job, and the vulnerabilities cannot be displayed if the blocking + manual job did not run. +- Findings have an expiry period. Expired findings are not shown on the pipeline security tab. For + details, see [Retention period for findings](#retention-period-for-findings). + +## View vulnerabilities in a pipeline To view vulnerabilities in a pipeline: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipelines**. -1. From the list, select the pipeline you want to check for vulnerabilities. +1. Select the pipeline. 1. Select the **Security** tab. -A pipeline consists of multiple jobs, which may include security scans. When a job declares and produces security scan -reports using [`artifacts:reports`](../../../ci/yaml/artifacts_reports.md), GitLab parses and ingests the contents of -these reports to create vulnerabilities associated with the project the pipeline belongs to. - -If a job fails to finish, the pipeline vulnerability report doesn't show vulnerability findings detected by this job. -For example, if a pipeline contains DAST and SAST jobs, but the DAST job fails by returning a non-zero -[exit code](../../../development/integrations/secure.md#exit-code), the report doesn't show DAST results. - -The pipeline vulnerability report only shows results contained in the security report artifacts. This report differs from -the [vulnerability report](index.md), which contains cumulative results of all successful jobs, and from the merge request -[security widget](../index.md#merge-request), which contains new vulnerability findings that don't already exist on the default branch. - -NOTE: -If a new advisory is added to our advisory database and the last pipeline for the default branch is stale, the resulting vulnerability may appear in the MR widget as "New" when it is already in the default branch. This will be resolved by [Continuous Vulnerability Scans](https://gitlab.com/groups/gitlab-org/-/epics/7886). - -The pipeline vulnerability report only displays after the pipeline is complete. If the pipeline has a [blocking manual job](../../../ci/jobs/job_control.md#types-of-manual-jobs), the pipeline waits for the manual job and the vulnerabilities cannot be displayed if the blocking manual job did not run. - -Before GitLab displays results, the vulnerability findings in all pipeline reports are [deduplicated](#deduplication-process). - ## Scan details -**Scan details** shows a summary of vulnerability findings in the pipeline and the source reports. - -GitLab displays one row of information for each [scan type](../terminology/index.md#scan-type-report-type) artifact present in -the pipeline. +The **Scan details** section shows a summary of vulnerability findings in the pipeline and the +source reports. -Each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings -in the report doesn't match the number in **Scan details**, ensure that **Hide dismissed** is disabled. +GitLab displays one row of information for each [scan type](../terminology/index.md#scan-type-report-type) +artifact present in the pipeline. -### Download security scan outputs - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/333660) in GitLab 14.2. +## Downloading security scan results Depending on the type of security scanner, you can download: @@ -57,22 +48,32 @@ Depending on the type of security scanner, you can download: To download a security scan output: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Build > Pipelines**. +1. Select the pipeline. +1. Select the **Security** tab. 1. In **Scan details**, select **Download results**: - - To download a JSON file, select the JSON artifact. - - To download a CSV file, select **Download scanned resources**. + - To download a JSON file, select the JSON artifact. + - To download a CSV file, select **Download scanned resources**. ## Scan results -This shows a list of the combined results for all security report artifacts. The filters work like the -[Vulnerability Report filters](index.md#vulnerability-report-filters), but they are limited to **Severity** and **Tool**, with -the addition of a **Hide dismissed** toggle. +Findings present in the source branch are listed in descending order of severity. You can filter the +list of findings by severity and tool. You can also download the results of the security scans, for +analysis outside GitLab. + +Findings that are dismissed are hidden by default. To see these findings, turn off the +**Hide dismissed** toggle. + +For each finding you can: -When you review the vulnerability findings reported in the pipeline, you can select one or more entries for dismissal, -similar to [Dismissing a vulnerability](index.md#dismiss-a-vulnerability) in the Vulnerability Report. +- Get more information about the finding. +- Create an issue for the finding. +- Dismiss the finding. -When you merge the branch corresponding to the pipeline into the default branch, all reported findings are combined into -the [Vulnerability Report](index.md). Scan results in pipelines executed on the default branch are -incorporated once the pipeline finishes. +When you merge the merge request's branch into the target branch, all reported findings are +in the [vulnerability report](index.md). Scan results in pipelines executed on the +default branch are incorporated after the pipeline finishes, according to the following table: | Existing vulnerability status | Dismissed in pipeline? | New vulnerability status | |:------------------------------|:-----------------------|:-------------------------| @@ -81,18 +82,18 @@ incorporated once the pipeline finishes. | Confirmed | No | Confirmed | | Needs triage (Detected) | No | Needs triage (Detected) | | Resolved | No | Needs triage (Detected) | -| N/A (That is: new vulnerability) | No | Needs triage (Detected) | +| N/A (New vulnerability) | No | Needs triage (Detected) | -## Retention period for vulnerabilities +## Retention period for findings > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351524) in GitLab 15.5. -GitLab has the following retention policies for vulnerabilities on non-default branches. Vulnerabilities are no longer available: +Findings are no longer available: - When the related CI job artifact expires. - 90 days after the pipeline is created, even if the related CI job artifacts are locked. -To view vulnerabilities, either: +To view findings, either: - Run a new pipeline. - Download the related CI job artifacts if they are available. @@ -104,7 +105,7 @@ This does not apply for the vulnerabilities existing on the default branch. When a pipeline contains jobs that produce multiple security reports of the same type, it is possible that the same vulnerability finding is present in multiple reports. This duplication is common when different scanners are used to -increase coverage, but can also exist within a single report. The deduplication process allows you to maximize the vulnerability scanning coverage while reducing +increase coverage, but can also exist in a single report. The deduplication process allows you to maximize the vulnerability scanning coverage while reducing the number of findings you need to manage. A finding is considered a duplicate of another finding when their [scan type](../terminology/index.md#scan-type-report-type), diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index b481c0458aa..ea62384b35e 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # AsciiDoc **(FREE ALL)** diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index a1281d3d75c..9ff3837653e 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitLab CI/CD with a Kubernetes cluster **(FREE ALL)** @@ -114,7 +114,7 @@ Choose the context to run `kubectl` commands from your CI/CD scripts. In the project where you want to run Kubernetes commands, edit your project's `.gitlab-ci.yml` file. In the first command under the `script` keyword, set your agent's context. -Use the format `path/to/agent/repository:agent-name`. For example: +Use the format `<path/to/agent/project>:<agent-name>`. For example: ```yaml deploy: @@ -123,7 +123,7 @@ deploy: entrypoint: [''] script: - kubectl config get-contexts - - kubectl config use-context path/to/agent/repository:agent-name + - kubectl config use-context path/to/agent/project:agent-name - kubectl get pods ``` @@ -138,7 +138,7 @@ Set the value of `KUBE_CONTEXT` to the context of the agent you want Auto DevOps ```yaml deploy: variables: - KUBE_CONTEXT: <path_to_agent_config_repository>:<agent_name> + KUBE_CONTEXT: path/to/agent/project:agent-name ``` You can assign different agents to separate Auto DevOps jobs. For instance, @@ -162,7 +162,7 @@ When you deploy to an environment that has both a - The certificate-based cluster's context is called `gitlab-deploy`. This context is always selected by default. - In GitLab 14.9 and later, agent contexts are included in `$KUBECONFIG`. - You can select them by using `kubectl config use-context path/to/agent/repository:agent-name`. + You can select them by using `kubectl config use-context <path/to/agent/project>:<agent-name>`. - In GitLab 14.8 and earlier, you can still use agent connections, but for environments that already have a certificate-based cluster, the agent connections are not included in `$KUBECONFIG`. diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index d79d32a1234..df63d8ce7be 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitOps with a Kubernetes cluster **(FREE ALL)** diff --git a/doc/user/clusters/agent/gitops/agent.md b/doc/user/clusters/agent/gitops/agent.md index a4e83916acb..2eba00f0c78 100644 --- a/doc/user/clusters/agent/gitops/agent.md +++ b/doc/user/clusters/agent/gitops/agent.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitOps with the agent for Kubernetes (deprecated) **(FREE ALL)** diff --git a/doc/user/clusters/agent/gitops/flux.md b/doc/user/clusters/agent/gitops/flux.md deleted file mode 100644 index 13fcfeb28e9..00000000000 --- a/doc/user/clusters/agent/gitops/flux.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../gitops.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../gitops.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md index 2c4796adf2b..e1832de51af 100644 --- a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md @@ -8,7 +8,7 @@ info: A tutorial for deploying an OCI artifact using Flux This tutorial teaches you how to package your Kubernetes manifests into an [OCI](https://opencontainers.org/) artifact and deploy them to your cluster using Flux. You'll set up a sample manifest project, configure it to -store manifests as an artifact in the project's Container Registry, and configure Flux to sync the artifact. With this +store manifests as an artifact in the project's container registry, and configure Flux to sync the artifact. With this setup, you can run additional steps in GitLab pipelines before Flux picks up the changes from the OCI image. @@ -63,7 +63,7 @@ First, create a repository for your Kubernetes manifests: ## Configure the manifest repository to create an OCI artifact Next, configure [GitLab CI/CD](../../../../ci/index.md) to package your manifests into an OCI artifact, -and push the artifact to the [GitLab Container Registry](../../../packages/container_registry/index.md): +and push the artifact to the [GitLab container registry](../../../packages/container_registry/index.md): 1. In the root of `web-app-manifests`, create and push a [`.gitlab-ci.yml`](../../../../ci/index.md#the-gitlab-ciyml-file) file with the following contents: @@ -92,9 +92,9 @@ and push the artifact to the [GitLab Container Registry](../../../packages/conta - Uses `kustomization.yaml` to render your final Kubernetes manifests. - Packages your manifests into an OCI artifact. - - Pushes the OCI artifact to the Container Registry. + - Pushes the OCI artifact to the container registry. - After the pipeline has completed, you can check your OCI artifact with the Container Registry UI. + After the pipeline has completed, you can check your OCI artifact with the container registry UI. ## Configure Flux to sync your artifact diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md deleted file mode 100644 index 22587cd0e5d..00000000000 --- a/doc/user/clusters/agent/gitops/helm.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../gitops.md' -remove_date: '2023-10-22' ---- - -This document was moved to [another location](../gitops.md). - -<!-- This redirect file can be deleted after 2023-10-22. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/clusters/agent/gitops/secrets_management.md b/doc/user/clusters/agent/gitops/secrets_management.md index a9590f34183..52aa046a01a 100644 --- a/doc/user/clusters/agent/gitops/secrets_management.md +++ b/doc/user/clusters/agent/gitops/secrets_management.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing Kubernetes secrets in a GitOps workflow (deprecated) @@ -13,7 +13,7 @@ To manage cluster resources with GitOps, you should use the [Flux integration](. You should never store Kubernetes secrets in unencrypted form in a `git` repository. If you use a GitOps workflow, you can follow these steps to securely manage your secrets. 1. Set up the Sealed Secrets controller to manage secrets. -1. Deploy Docker credentials so the cluster can pull images from the GitLab Container Registry. +1. Deploy Docker credentials so the cluster can pull images from the GitLab container registry. ## Prerequisites @@ -49,7 +49,7 @@ For more details on how the Sealed Secrets controller works, view [the usage ins ## Deploy Docker credentials -To deploy containers from the GitLab Container Registry, you must configure the cluster with the proper Docker registry credentials. You can achieve this by deploying a `docker-registry` type secret. +To deploy containers from the GitLab container registry, you must configure the cluster with the proper Docker registry credentials. You can achieve this by deploying a `docker-registry` type secret. 1. Generate a GitLab token with at least `read-registry` rights. The token can be either a Personal or a Project Access Token. 1. Create a Kubernetes secret manifest YAML file. Update the values as needed: diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 140ac060dc7..66e67f56172 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connecting a Kubernetes cluster with GitLab @@ -63,13 +63,20 @@ GitLab in a Kubernetes cluster, you might need a different version of Kubernetes You can upgrade your Kubernetes version to a supported version at any time: -- 1.27 (support ends on July 22, 2024 or when 1.30 becomes supported) -- 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported) +- 1.27 (support ends on July 18, 2024 or when 1.30 becomes supported) +- 1.26 (support ends on March 21, 2024 or when 1.29 becomes supported) - 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported) GitLab aims to support a new minor Kubernetes version three months after its initial release. GitLab supports at least three production-ready Kubernetes minor versions at any given time. +When a new version of Kubernetes is released, we will: + +- Update this page with the results of our early smoke tests within approximately + four weeks. +- If we expect a delay in releasing new version support, we will update this page + with the expected GitLab support version within approximately eight weeks. + When installing the agent, use a Helm version compatible with your Kubernetes version. Other versions of Helm might not work. For a list of compatible versions, see the [Helm version support policy](https://helm.sh/docs/topics/version_skew/). Support for deprecated APIs can be removed from the GitLab codebase when we drop support for the Kubernetes version that only supports the deprecated API. diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 588be3a1223..5b07dbd56d9 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Installing the agent for Kubernetes **(FREE ALL)** diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index c01b1337aca..f9c3ab93906 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting the GitLab agent for Kubernetes diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md index b3735770a97..80ee7303dfc 100644 --- a/doc/user/clusters/agent/user_access.md +++ b/doc/user/clusters/agent/user_access.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Grant users Kubernetes access **(FREE ALL BETA)** @@ -147,7 +147,7 @@ subjects: You can configure an agent to allow GitLab users to access a cluster with the Kubernetes API. -Prerequisite: +Prerequisites: - You have an agent configured with the `user_access` entry. diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index e57551fc8c1..18f46878eb4 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -1,7 +1,7 @@ --- stage: Secure group: Composition analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Operational Container Scanning **(ULTIMATE ALL)** diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 70abbebaaad..e1f84197405 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing the agent for Kubernetes instances **(FREE ALL)** @@ -12,7 +12,7 @@ Use the following tasks when you work with the agent for Kubernetes. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, the installed `agentk` version is displayed on the **Agent** tab. -Prerequisite: +Prerequisites: - You must have at least the Developer role. diff --git a/doc/user/clusters/create/index.md b/doc/user/clusters/create/index.md index 8dfeafeb48e..d6a07d26c09 100644 --- a/doc/user/clusters/create/index.md +++ b/doc/user/clusters/create/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create Kubernetes clusters diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 4a6fa8d4862..96281f2fa50 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cluster Environments (deprecated) **(PREMIUM ALL)** diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f2f9aceda69..178f1bd7705 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cluster management project (deprecated) **(FREE ALL)** @@ -62,8 +62,7 @@ To associate a cluster management project with your cluster: - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. - [Instance-level cluster](../instance/clusters/index.md): - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Kubernetes**. 1. Expand **Advanced settings**. 1. From the **Cluster management project** dropdown list, select the cluster management project diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index a40fc5a262e..2b5ccd92566 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage cluster applications **(FREE ALL)** diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index 4bd42abb9e8..e9c32eaad43 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated) **(FREE ALL)** diff --git a/doc/user/compliance/compliance_center/index.md b/doc/user/compliance/compliance_center/index.md index 4a42a70a7e7..63b4560a498 100644 --- a/doc/user/compliance/compliance_center/index.md +++ b/doc/user/compliance/compliance_center/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance center **(ULTIMATE ALL)** @@ -16,14 +15,14 @@ See report and manage standards adherence, violations, and compliance frameworks > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125875) GraphQL APIs in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `compliance_adherence_report`. Disabled by default. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125444) standards adherence dashboard in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `adherence_report_ui`. Disabled by default. > - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/414495) in GitLab 16.5. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can -[disable the feature flags](../../../administration/feature_flags.md) named `compliance_adherence_report` and `adherence_report_ui`. On GitLab.com, -this feature is available. +> - [Feature flag `compliance_adherence_report` and `adherence_report_ui`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137398) removed in GitLab 16.7. +> - Standards adherence filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/413734) in GitLab 16.7. Standards adherence dashboard lists the adherence status of projects complying to GitLab standard. +When a project is added or an associated project or group setting is changed, an adherence scan is run on that project to update the standards adherence for that project. The date in the +**Last Scanned** column reflects any changes. + ### View the standards adherence dashboard Prerequisites: @@ -33,7 +32,13 @@ Prerequisites: To view the standards adherence dashboard for a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. + +You can filter the standards adherence dashboard on: + +- The project that the check was performed on. +- The type of check that was performed on a project. +- The standard that the check belongs to. ### GitLab standard @@ -101,7 +106,7 @@ Prerequisites: To view the compliance violations report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. You can sort the compliance report on: @@ -188,9 +193,9 @@ Prerequisites: To export a report of merge request compliance violations for projects in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. -1. On the page, select the **Violations** tab. -1. On the Violations tab, select the **Export full report as CSV** action in the top right corner +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export violations report**. A report is compiled and delivered to your email inbox as an attachment. @@ -235,8 +240,9 @@ If the commit has a related merge commit, then the following are also included: To generate the Chain of Custody report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. -1. Select **List of all merge commits**. +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export chain of custody report**. Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. @@ -251,10 +257,10 @@ details for the provided commit SHA. To generate a commit-specific Chain of Custody report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. -1. At the top of the compliance report, to the right of **List of all commits**, select the down arrow - (**{chevron-lg-down}**). -1. Enter the commit SHA, and then select **Export commit custody report**. +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export custody report of a specific commit**. +1. Enter the commit SHA, and then select **Export custody report**. Depending on your version of GitLab, the Chain of Custody report is either sent through email or available for download. @@ -283,7 +289,7 @@ Prerequisites: To view the compliance projects report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. ### Apply a compliance framework to projects in a group @@ -300,7 +306,7 @@ Prerequisites: To apply a compliance framework to one project in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. Next to the project you want to add the compliance framework to, select **{plus}** **Add framework**. 1. Select an existing compliance framework or create a new one. @@ -308,7 +314,7 @@ To apply a compliance framework to one project in a group: To apply a compliance framework to multiple projects in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. Select multiple projects. 1. From the **Choose one bulk action** dropdown list, select **Apply framework to selected projects**. @@ -329,14 +335,14 @@ Prerequisites: To remove a compliance framework from one project in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. Next to the compliance framework to remove from the project, select **{close}** on the framework label. To remove a compliance framework from multiple projects in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. Select multiple projects. 1. From the **Choose one bulk action** dropdown list, select **Remove framework from selected projects**. @@ -358,9 +364,9 @@ Prerequisites: To export a report of compliance frameworks on projects in a group: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. -1. On the page, select the **Projects** tab. -1. On the Frameworks tab, select the **Export as CSV** action in the top right corner +1. Select **Secure > Compliance center**. +1. In the top-right corner, select **Export**. +1. Select **Export list of project frameworks**. A report is compiled and delivered to your email inbox as an attachment. @@ -371,13 +377,13 @@ A report is compiled and delivered to your email inbox as an attachment. To filter the list of compliance frameworks: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Projects** tab. 1. In the search field: 1. Select the attribute you want to filter by. 1. Select an operator. 1. Select from the list of options or enter text for the search. -1. Select **Search** (**{search}**). +1. Select **Search**. Repeat this process to filter by multiple attributes. @@ -406,5 +412,5 @@ Prerequisites: To view the compliance projects report: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Secure > Compliance center**. +1. Select **Secure > Compliance center**. 1. On the page, select the **Frameworks** tab. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md deleted file mode 100644 index 998e9c81d18..00000000000 --- a/doc/user/compliance/compliance_report/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../compliance_center/index.md' -remove_date: '2023-09-20' ---- - -This document was moved to [another location](../compliance_center/index.md). - -<!-- This redirect file can be deleted after <2023-09-20>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index 51053c03d8c..167eeddc00d 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance **(ULTIMATE ALL)** diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md index cf5f340c0f6..9ec48e74aa9 100644 --- a/doc/user/compliance/license_approval_policies.md +++ b/doc/user/compliance/license_approval_policies.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Security Policies -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # License approval policies **(ULTIMATE ALL)** @@ -40,7 +39,7 @@ Create a license approval policy to enforce license compliance. To create a license approval policy: -1. [Link a security policy project](../application_security/policies/index.md#managing-the-linked-security-policy-project) to your development group, subgroup, or project (the Owner role is required). +1. [Link a security policy project](../application_security/policies/index.md#policy-implementation) to your development group, subgroup, or project (the Owner role is required). 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. 1. Create a new [Scan Result Policy](../application_security/policies/scan-result-policies.md). diff --git a/doc/user/compliance/license_list.md b/doc/user/compliance/license_list.md index 7ad19775509..43d76845ffa 100644 --- a/doc/user/compliance/license_list.md +++ b/doc/user/compliance/license_list.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Threat Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # License list **(ULTIMATE ALL)** diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md index 5d7a689e610..120d0ebcc31 100644 --- a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # License scanning of CycloneDX files **(ULTIMATE ALL)** @@ -11,14 +10,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385176) in GitLab 16.4. Feature flags `license_scanning_sbom_scanner` and `package_metadata_synchronization` removed. NOTE: -The legacy License Compliance analyzer was deprecated in GitLab 15.9 and removed in GitLab 16.3. To continue using GitLab for License Compliance, remove the License Compliance template from your CI/CD pipeline and add the [Dependency Scanning template](../../application_security/dependency_scanning/index.md#configuration). The Dependency Scanning template is now capable of gathering the required license information so it is no longer necessary to run a separate License Compliance job. The License Compliance CI/CD template should not be removed prior to verifying that the instance has been upgraded to a version that supports the new method of license scanning. To begin using the Dependency Scanner quickly at scale, you may set up a [scan execution policy](../../application_security/policies/scan-execution-policies.md) at the group level to enforce the SBOM-based license scan for all projects in the group. Then, you may remove the inclusion of the `Jobs/License-Scanning.gitlab-ci.yml` template from your CI/CD configuration. If you wish to continue using the legacy License Compliance feature, you can do so by setting the `LICENSE_MANAGEMENT_VERSION CI` variable to `4`. This variable can be set at the [project](../../../ci/variables/index.md#for-a-project), [group](../../../ci/variables/index.md#for-a-group) or [instance](../../../ci/variables/index.md#for-an-instance) level. This configuration change will allow you to continue using the existing version of License Compliance to generate [license scanning report](../../../ci/yaml/artifacts_reports.md#artifactsreportslicense_scanning) artifacts in your pipelines. However, since legacy license scanning support is being removed from our codebase, switching back to this legacy analyzer prevents other License Compliance features from working as expected, so this approach is not recommended. In addition to this, **bugs and vulnerabilities in this legacy analyzer will no longer be fixed.** +The legacy License Compliance analyzer was deprecated in GitLab 15.9 and removed in GitLab 16.3. +To continue using GitLab for License Compliance, remove the License Compliance template from your +CI/CD pipeline and add the [Dependency Scanning template](../../application_security/dependency_scanning/index.md#configuration). +The Dependency Scanning template is now capable of gathering the required license information so it +is no longer necessary to run a separate License Compliance job. The License Compliance CI/CD +template should not be removed prior to verifying that the instance has been upgraded to a version +that supports the new method of license scanning. To begin using the Dependency Scanner quickly at +scale, you may set up a [scan execution policy](../../application_security/policies/scan-execution-policies.md) +at the group level to enforce the SBOM-based license scan for all projects in the group. +Then, you may remove the inclusion of the `Jobs/License-Scanning.gitlab-ci.yml` template from your +CI/CD configuration. If you wish to continue using the legacy License Compliance feature, you can do +so by setting the `LICENSE_MANAGEMENT_VERSION CI` variable to `4`. This variable can be set at the +[project](../../../ci/variables/index.md#for-a-project), [group](../../../ci/variables/index.md#for-a-group) +or [instance](../../../ci/variables/index.md#for-an-instance) level. To detect the licenses in use, License Compliance relies on running the [Dependency Scanning CI Jobs](../../application_security/dependency_scanning/index.md), and analyzing the [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) generated by those jobs. -Other 3rd party scanners may also be used as long as they produce a CycloneDX file with a list of dependencies for [one of our supported languages](#supported-languages-and-package-managers). -This method of scanning is also capable of parsing and identifying over 500 different types of licenses, as defined in [the SPDX list](https://spdx.org/licenses/). -Licenses not in the SPDX list are reported as "Unknown". License information can also be extracted from packages that are dual-licensed, or have multiple different licenses that apply. +This method of scanning is capable of parsing and identifying over 500 different types of licenses, as defined in [the SPDX list](https://spdx.org/licenses/). +Third-party scanners may be used to generate the list of dependencies, as long as they produce a CycloneDX report artifact for [one of our supported languages](#supported-languages-and-package-managers) and follow the [GitLab CycloneDX property taxonomy](../../../development/sec/cyclonedx_property_taxonomy.md). Note that it is not yet possible to use a CI report artifact as a source of data for license information, and licenses that are not in the SPDX list are reported as "Unknown". +The ability to provide other licenses is tracked in [epic 10861](https://gitlab.com/groups/gitlab-org/-/epics/10861). + +NOTE: +The License Scanning feature relies on publicly available package metadata collected in an +external database and synced with the GitLab instance automatically. This database is a multi-region Google Cloud Storage bucket hosted in the United States. +The scan is executed exclusively within the GitLab instance. +No contextual information (for example, a list of project dependencies) is sent to the external service. ## Configuration @@ -26,7 +44,7 @@ To enable License scanning of CycloneDX files: - Enable [Dependency Scanning](../../application_security/dependency_scanning/index.md#enabling-the-analyzer) and ensure that its prerequisites are met. -- On GitLab self-managed only, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then please refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance. +- On GitLab self-managed only, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance. ## Supported languages and package managers @@ -110,12 +128,8 @@ The supported files and versions are the ones supported by ## License expressions -GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). -License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, -if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](../license_approval_policies.md), -GitLab evaluates the composite license as _denied_, as this is the safer option. -The ability to support other license expression operators (like `OR`, `WITH`) is tracked -in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). +The License Scanning of CycloneDX files does not support [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). +Adding this capability is tracked in issue [336878](https://gitlab.com/gitlab-org/gitlab/-/issues/336878). ## Blocking merge requests based on detected licenses diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 46e395af5bc..4f1eeb3578c 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customer relations management (CRM) **(FREE ALL)** diff --git a/doc/user/custom_roles.md b/doc/user/custom_roles.md index bbb48724078..1f3628efa39 100644 --- a/doc/user/custom_roles.md +++ b/doc/user/custom_roles.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom roles **(ULTIMATE ALL)** @@ -15,7 +15,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Ability to create and remove a custom role with the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393235) in GitLab 16.4. > - Ability to manage group members [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17364) in GitLab 16.5. > - Ability to manage project access tokens [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421778) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `manage_project_access_tokens`. -> - Ability to archive projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) in GitLab 16.6 in [with a flag](../administration/feature_flags.md) named `archive_project`. Disabled by default. +> - Ability to archive projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/425957) in GitLab 16.7. +> - Ability to use the UI to add a user to your group with a custom role, change a user's custom role, or remove a custom role from a group member [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/393239) in GitLab 16.7. Custom roles allow group Owners or instance administrators to create roles specific to the needs of their organization. @@ -50,7 +51,7 @@ with the ability to: ### GitLab SaaS -Prerequisite: +Prerequisites: - You must have the Owner role in the group you are creating the custom role in. @@ -59,25 +60,40 @@ Prerequisite: 1. Select **Add new role**. 1. In **Base role to use as template**, select an existing non-custom role. 1. In **Role name**, enter the custom role's title. +1. Optional. In **Description**, enter a description for the custom role. 1. Select the **Permissions** for the new custom role. 1. Select **Create new role**. +In **Settings > Roles and Permissions**, the list of all custom roles displays the: + +- Custom role name. +- Role ID. +- Base role that the custom role uses as a template. +- Permissions. + ### Self Managed GitLab Instances -Prerequisite: +Prerequisites: - You must be an administrator for the self-managed instance you are creating the custom role in. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Roles and Permissions**. 1. From the top dropdown list, select the group you want to create a custom role in. 1. Select **Add new role**. 1. In **Base role to use as template**, select an existing non-custom role. 1. In **Role name**, enter the custom role's title. +1. Optional. In **Description**, enter a description for the custom role. 1. Select the **Permissions** for the new custom role. 1. Select **Create new role**. +In **Settings > Roles and Permissions**, the list of all custom roles displays the: + +- Custom role name. +- Role ID. +- Base role that the custom role uses as a template. +- Permissions. + To create a custom role, you can also [use the API](../api/member_roles.md#add-a-member-role-to-a-group). ### Available permissions @@ -95,10 +111,10 @@ These requirements are documented in the `Required permission` column in the fol | `read_vulnerability` | GitLab 16.1 and later | Not applicable | View [vulnerability reports](application_security/vulnerability_report/index.md). | | `admin_vulnerability` | GitLab 16.1 and later | `read_vulnerability` | Change the [status of vulnerabilities](application_security/vulnerabilities/index.md#vulnerability-status-values). | | `read_dependency` | GitLab 16.3 and later | Not applicable | View [project dependencies](application_security/dependency_list/index.md). | -| `admin_merge_request` | GitLab 16.4 and later | Not applicable | View and approve [merge requests](project/merge_requests/index.md), and view the associated merge request code. <br> Does not allow users to view or change merge request approval rules. | +| `admin_merge_request` | GitLab 16.4 and later | Not applicable | View and approve [merge requests](project/merge_requests/index.md), revoke merge request approval, and view the associated merge request code. <br> Does not allow users to view or change merge request approval rules. | | `manage_project_access_tokens` | GitLab 16.5 and later | Not applicable | Create, delete, and list [project access tokens](project/settings/project_access_tokens.md). | | `admin_group_member` | GitLab 16.5 and later | Not applicable | Add or remove [group members](group/manage.md). | -| `archive_project` | GitLab 16.6 and later | Not applicable | Archive and unarchive [projects](project/settings/index.md#archive-a-project). | +| `archive_project` | GitLab 16.6 and later | Not applicable | Archive and unarchive [projects](project/settings/migrate_projects.md#archive-a-project). | ## Billing and seat usage @@ -112,7 +128,50 @@ This does not apply when the user's custom role only has the `read_code` permiss enabled. Guest users with that specific permission only are not considered billable users and do not use a seat. -## Associate a custom role with an existing group member +## Add a user to your group with a custom role + +Prerequisites: + +- You must be an administrator, or have the Owner role in the group you are creating the custom role in. + +To add a user to your group with a custom role: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select **Invite members**. +1. In **Username or email address**, if the user: + - Has a GitLab account, enter their username. + - Does not have a GitLab account, enter their email address. +1. In **Select a role**, select a static or custom role. +1. Optional. In **Access expiration date (optional)**, enter or select a date. + From that date onward, the user can no longer access the group. +1. Select **Invite**. If you invite the user by their: + - GitLab username, the user is added to the member list. + - Email address, the user receives an email invitation and is prompted to create an account. + If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. + Unaccepted invites are automatically deleted after 90 days. + +The new member with custom role and custom permissions appears on the [group's members list](group/index.md#view-group-members). + +NOTE: +Most custom roles are considered [billable users that use a seat](#billing-and-seat-usage). When you add a user to your group with a custom role, a warning is displayed if you are about to incur additional charges for having more seats than are included in your subscription. + +### Change a member's custom role + +To change a group member's custom role: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select the **Max role** dropdown list for the member you want to select a custom role for. +1. On the **Change role** dialog, select a different custom role. + +### Associate a custom role with an existing group member + +You can use the API to associate a custom role with an existing group member. + +Prerequisites: + +- You must have the Owner role for the group. To associate a custom role with an existing group member, a group member with the Owner role: @@ -143,9 +202,9 @@ the Owner role: ## Remove a custom role -Prerequisite: +Prerequisites: -- You must be an administrator or have the Owner role in the group you are removing the custom role from. +- You must be an administrator, or have the Owner role in the group you are removing the custom role from. You can remove a custom role from a group only if no group members have that role. @@ -153,7 +212,14 @@ To do this, you can either remove the custom role from all group members with th ### Remove a custom role from a group member -To remove a custom role from a group member, use the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) +To remove a custom role from a group member: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Manage > Members**. +1. Select the **Max role** dropdown list for the member you want to remove a custom role from. +1. On the **Change role** dialog, select a static role. + +You can update or remove a custom role from a group member also with the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project). and pass an empty `member_role_id` value: ```shell @@ -178,8 +244,7 @@ curl --request PUT --header "Content-Type: application/json" --header "Authoriza After you have made sure no group members have that custom role, delete the custom role. -1. On the left sidebar, select **Search or go to**. -1. GitLab.com only. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Roles and Permissions**. 1. Select **Custom Roles**. 1. In the **Actions** column, select **Delete role** (**{remove}**) and confirm. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index a3ed888ed53..034e2e45127 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Comments and threads **(FREE ALL)** @@ -78,13 +77,17 @@ Notifications and mentions can be disabled in When you mention a group in a comment, every member of the group gets a to-do item added to their To-do list. -1. Open the MR or issue. +1. On the left sidebar, select **Search or go to** and find your project. +1. For merge requests, select **Code > Merge requests**, and find your merge request. +1. For issues, select **Plan > Issues**, and find your issue. 1. In a comment, type `@` followed by the user, group, or subgroup namespace. For example, `@alex`, `@alex-team`, or `@alex-team/marketing`. 1. Select **Comment**. A to-do item is created for all the group and subgroup members. +For more information on mentioning subgroups see [Mention subgroups](../group/subgroups/index.md#mention-subgroups). + ## Add a comment to a merge request diff You can add comments to a merge request diff. These comments @@ -95,8 +98,9 @@ persist, even when you: To add a commit diff comment: -1. To select a specific commit, on the merge request, select the **Commits** tab, select the commit - message. To view the latest commit, select the **Changes** tab. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests**, and find your merge request. +1. Select the **Commits** tab, then select the commit message. 1. By the line you want to comment on, hover over the line number and select **Comment** (**{comment}**). You can select multiple lines by dragging the **Comment** (**{comment}**) icon. 1. Enter your comment and select **Start a review** or **Add comment now**. @@ -149,17 +153,19 @@ If you edit an existing comment to add a user mention that wasn't there before, You can prevent public comments in an issue or merge request. When you do, only project members can add and edit comments. -Prerequisite: +Prerequisites: - In merge requests, you must have at least the Developer role. - In issues, you must have at least the Reporter role. To lock an issue or merge request: -1. On the right sidebar, next to **Lock discussion**, select **Edit**. -1. On the confirmation dialog, select **Lock**. +1. On the left sidebar, select **Search or go to** and find your project. +1. For merge requests, select **Code > Merge requests**, and find your merge request. +1. For issues, select **Plan > Issues**, and find your issue. +1. On the top right, select **Merge request actions** or **Issue actions** (**{ellipsis_v}**), then select **Lock discussion**. -Notes are added to the page details. +A system note is added to the page details. If an issue or merge request is closed with a locked discussion, then you cannot reopen it until the discussion is unlocked. @@ -188,7 +194,7 @@ Prerequisites: To add an internal note: -1. Start adding a new comment. +1. On the issue or epic, in the **Comment** text box, type a comment. 1. Below the comment, select the **Make this an internal note** checkbox. 1. Select **Add internal note**. @@ -203,7 +209,7 @@ changes ([system notes](../project/system_notes.md)). System notes include chang objects, or changes to labels, assignees, and the milestone. GitLab saves your preference, and applies it to every issue, merge request, or epic you view. -1. Open the **Overview** tab in a merge request, issue, or epic. +1. On a merge request, issue, or epic, select the **Overview** tab. 1. On the right side of the page, from the **Sort or filter** dropdown list, select a filter: - **Show all activity**: Display all user comments and system notes. - **Show comments only**: Display only user comments. @@ -280,12 +286,7 @@ A threaded comment is created. > - Resolvable threads for issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.3 [with a flag](../../administration/feature_flags.md) named `resolvable_issue_threads`. Disabled by default. > - Resolvable threads for issues [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.4. - -FLAG: -On self-managed GitLab, resolvable threads _for issues_ are available by default. -To hide the feature, an administrator can -[disable the feature flag](../../administration/feature_flags.md) named `resolvable_issue_threads`. -On GitLab.com, this feature is available. +> - Resolvable threads for issues [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/31114) in GitLab 16.7. Feature flag `resolvable_issue_threads` removed. You can resolve a thread when you want to finish a conversation. diff --git a/doc/user/emoji_reactions.md b/doc/user/emoji_reactions.md index 1b2c1bcd2e5..10385da7cdc 100644 --- a/doc/user/emoji_reactions.md +++ b/doc/user/emoji_reactions.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Emoji reactions **(FREE ALL)** @@ -48,8 +48,15 @@ To remove an emoji reaction, select the emoji again. > - [Introduced for GraphQL API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 [with a flag](../administration/feature_flags.md) named `custom_emoji`. Disabled by default. > - Enabled on GitLab.com in GitLab 14.0. > - UI to add emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333095) in GitLab 16.2. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/138969) in GitLab 16.7. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `custom_emoji`. +On GitLab.com, this feature is available. +This feature is ready for production use. Custom emoji show in the emoji picker everywhere you can react with emoji. + To add an emoji reaction to a comment or description: 1. Select **Add reaction** (**{slight-smile}**). @@ -66,3 +73,23 @@ For more information, see [Use custom emoji with GraphQL](../api/graphql/custom_ For a list of custom emoji available for GitLab.com, see [the `custom_emoji` project](https://gitlab.com/custom_emoji/custom_emoji/-/tree/main/img). + +### Upload custom emoji to a group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128355) in GitLab 16.5. + +Upload your custom emoji to a group to use them in all its subgroups and projects. + +Prerequisites: + +- You must at least have the developer role for the group. + +To upload custom emoji: + +1. On a description or a comment, select **Add reaction** (**{slight-smile}**). +1. At the bottom of the emoji picker, select **Create new emoji**. +1. Enter a name and URL for the custom emoji. +1. Select **Save**. + +You can also upload custom emoji to a GitLab instance with the GraphQL API. +For more information, see [Use custom emoji with GraphQL](../api/graphql/custom_emoji.md). diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md index 2909c06046e..cc7e0e3b499 100644 --- a/doc/user/enterprise_user/index.md +++ b/doc/user/enterprise_user/index.md @@ -1,14 +1,13 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Enterprise users **(PREMIUM SAAS)** Enterprise users have user accounts that are administered by an organization that -has purchased a [GitLab subscription](../../subscriptions/index.md). +has [verified their email domain](../project/pages/custom_domains_ssl_tls_certification/index.md) and purchased a [GitLab subscription](../../subscriptions/index.md). Enterprise users are identified by the **Enterprise** badge next to their names on the [Members list](../group/index.md#filter-and-sort-members-in-a-group). @@ -55,11 +54,6 @@ Only GitLab administrators can change enterprise users' primary email address to Providing the ability to group Owners to change their enterprise users' primary email to an email with a non-verified domain is proposed in [issue 412966](https://gitlab.com/gitlab-org/gitlab/-/issues/412966). -## Dissociation of the user from their enterprise group - -Changing an enterprise user's primary email to an email with a non-verified domain automatically disassociates them from their enterprise group. -However, there are [primary email change restrictions](#primary-email-change). - ## Verified domains for groups The following automated processes use [verified domains](../project/pages/custom_domains_ssl_tls_certification/index.md) to run: @@ -193,14 +187,14 @@ To disable 2FA: 1. Find a user with the **Enterprise** and **2FA** badges. 1. Select **More actions** (**{ellipsis_v}**) and select **Disable two-factor authentication**. -### Prevent users from creating groups and projects outside the corporate group +### Prevent enterprise users from creating groups and projects outside the corporate group A SAML identity administrator can configure the SAML response to set: -- Whether users can create groups. -- The maximum number of personal projects users can create. +- Whether enterprise users can create groups. +- The maximum number of personal projects enterprise users can create. -For more information, see the [supported user attributes for SAML responses](../group/saml_sso/index.md#supported-user-attributes). +For more information, see how to [configure enterprise user settings from the SAML response](../group/saml_sso/index.md#configure-enterprise-user-settings-from-saml-response). ### Bypass email confirmation for provisioned users @@ -208,8 +202,15 @@ A top-level group Owner can [set up verified domains to bypass confirmation emai ### Get users' email addresses through the API -A top-level group Owner can use the [group and project members API](../../api/members.md) -to access users' information, including email addresses. +A top-level group Owner can use the [group and project members API](../../api/members.md) to access +users' information. For users provisioned by the group with [SCIM](../group/saml_sso/scim_setup.md), +this information includes users' email addresses. + +[Issue 391453](https://gitlab.com/gitlab-org/gitlab/-/issues/391453) proposes to change the criteria for access to email addresses from provisioned users to enterprise users. + +### Remove enterprise management features from an account + +Changing an enterprise user's primary email to any email with a non-verified domain automatically removes the enterprise badge from the account. This does not alter any account roles or permissions for the user, but does limit the group Owner's ability to manage this account. ## Troubleshooting diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index 88928ab6d47..83e2926e8e3 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "View a list of all the flags available in the GitLab application." layout: 'feature_flags' --- diff --git a/doc/user/free_push_limit.md b/doc/user/free_push_limit.md index c1be8287eb1..53088cd4445 100644 --- a/doc/user/free_push_limit.md +++ b/doc/user/free_push_limit.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Free push limit **(FREE SAAS)** @@ -39,7 +39,7 @@ Git LFS is designed to work with Git to track large files. ## Feedback -If you have any feedback to share about this limit, please do so in +If you have any feedback to share about this limit, do so in [issue 428188](https://gitlab.com/gitlab-org/gitlab/-/issues/428188). ## Related topics diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index c978105c13b..330f041b430 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Free user limit **(FREE SAAS)** @@ -15,24 +15,18 @@ namespaces cannot write new data to repositories, Git Large File Storage (LFS), packages, or registries. For the full list of restricted actions, see [Read-only namespaces](read_only_namespaces.md). -## Manage members in your namespace +In the Free tier of GitLab SaaS, user limits do not apply to users in: -To help manage your free user limit, -you can view and manage the total number of members across all projects and groups -in your namespace. - -Prerequisite: +- Public top-level groups +- Paid tiers +- Self-managed Free tier +- [Community programs](https://about.gitlab.com/community/): + - GitLab for Open Source + - GitLab for Education + - GitLab for Startups users -- You must have the Owner role for the group. - -1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > Usage Quotas**. -1. To view all members, select the **Seats** tab. -1. To remove a member, select **Remove user**. - -If you need more time to manage your members, or to try GitLab features -with a team of more than five members, you can [start a trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com&glm_content=free-user-limit). -A trial lasts for 30 days and includes an unlimited number of members. +NOTE: +Personal namespaces are public by default and are excluded from the user limit. ## Determining namespace user counts @@ -62,6 +56,78 @@ The group `example-2` has: The namespace `example-2` has six unique members: `A`, `B`, `C`, `D`, `E`, and `F`. Because `example-2` has six unique users, it is impacted by the five-user limit. -## Related topics +## Manage members in your group namespace + +To help manage your Free user limit, +you can view and manage the total number of members across all projects and groups +in your namespace. + +Prerequisite: + +- You must have the Owner role for the group. + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > Usage Quotas**. +1. To view all members, select the **Seats** tab. +1. To remove a member, select **Remove user**. + +If you need more time to manage your members, or to try GitLab features +with a team of more than five members, you can [start a trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com?&glm_content=free-user-limit-faq/ee/user/free_user_limit.html). +A trial lasts for 30 days and includes an unlimited number of members. + +## Include a group in an organization's subscription + +If there are multiple groups in your organization, they might have a +combination of Paid and Free subscriptions. When a group +with a Free subscription exceeds the user limit, their namespace becomes [read-only](../user/read_only_namespaces.md). + +To avoid user limits on groups with Free subscriptions, you can +include them in your organization's subscription. To check if a group is included in the subscription, +[view the group's subscription details](../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription). +If the group is on the Free tier, it is not included in your organization's subscription. + +To include the group in your Paid subscription, [transfer the group](../user/group/manage.md#transfer-a-group) to your organization's +top-level namespace. + +NOTE: +If you previously purchased a subscription and the 5-user limit was applied to a group, +ensure that [your subscription is linked](../subscriptions/gitlab_com/index.md#change-the-linked-namespace) +to the correct top-level namespace, or that it has been +linked to your Customers Portal account. + +### Impact on seat count by transferred groups + +When you transfer a group, there might be an increase in your seat count, +which could incur additional costs for your subscription. + +For example, a company has Group A and Group B: + +- Group A is on a Paid tier and has five users. +- Group B is on the Free tier and has eight users, four of which are members of Group A. +- Group B is placed in a read-only state when it exceeds the user limit. +- Group B is transferred to the company's subscription to remove the read-only state. +- The company incurs an additional cost of four seats for the + four members of Group B that are not members of Group A. + +Users that are not part of the top-level namespace require additional seats to remain active. For more information, see [Add seats to your subscription](../subscriptions/gitlab_com/index.md#add-seats-to-your-subscription). + +## Increase the five-user limit + +On the Free tier on GitLab SaaS, you cannot increase the limit of five users on top-level groups with private visibility. + +For larger teams, you should upgrade to the Premium or Ultimate tier, which +has no user limits and offers more features to increase team productivity. To experience the +value of Paid features and unlimited users, you should start a [free trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com/ee/user/free_user_limit.html) for GitLab Ultimate. + +## Manage members in personal projects outside a group namespace + +Personal projects are not located in top-level group namespaces. You can manage the users in each of your +personal projects, but you cannot have more than five users in all of your personal projects. + +You should [move your personal project to a group](../tutorials/move_personal_project_to_group/index.md) so that +you can: -- [GitLab SaaS Free tier frequently asked questions](https://about.gitlab.com/pricing/faq-efficient-free-tier/) +- Increase the amount of users to more than five. +- Purchase a paid tier subscription, additional compute minutes, or storage. +- Use GitLab features in the group. +- Start a trial. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 6f809ae867a..70ac1f737e6 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab.com settings **(FREE SAAS)** @@ -191,7 +191,7 @@ the related documentation. ## Package registry limits The [maximum file size](../../administration/instance_limits.md#file-size-limits) -for a package uploaded to the [GitLab Package Registry](../../user/packages/package_registry/index.md) +for a package uploaded to the [GitLab package registry](../../user/packages/package_registry/index.md) varies by format: | Package type | GitLab.com | @@ -214,6 +214,7 @@ the default value [is the same as for self-managed instances](../../administrati |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------| | [Repository size including LFS](../../administration/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | | [Maximum import size](../project/settings/import_export.md#import-a-project-and-its-data) | 5 GiB | +| [Maximum export size](../project/settings/import_export.md#export-a-project-and-its-data) | 40 GiB | | [Maximum remote file size for imports from external object storages](../../administration/settings/import_and_export_settings.md#maximum-remote-file-size-for-imports) | 10 GiB | | [Maximum download file size when importing from source GitLab instances by direct transfer](../../administration/settings/import_and_export_settings.md#maximum-download-file-size-for-imports-by-direct-transfer) | 5 GiB | | Maximum attachment size | 100 MiB | @@ -390,7 +391,7 @@ user confirmation, user sign in, and password reset. [User and IP rate limits](../../administration/settings/user_and_ip_rate_limits.md#response-headers) includes a list of the headers responded to blocked requests. -See [Protected Paths](../admin_area/settings/protected_paths.md) for more details. +See [Protected Paths](../../administration/settings/protected_paths.md) for more details. ### IP blocks @@ -422,6 +423,11 @@ This limit: No response headers are provided. +`git` requests over `https` always send an unauthenticated request first, which for private repositories results in a `401` error. +`git` then attempts an authenticated request with a username, password, or access token (if available). +These requests might lead to a temporary IP block if too many requests are sent simultaneously. +To resolve this issue, use [SSH keys to communicate with GitLab](../ssh.md). + ### Pagination response headers For performance reasons, if a query returns more than 10,000 records, [GitLab excludes some headers](../../api/rest/index.md#pagination-response-headers). @@ -463,7 +469,7 @@ used on GitLab.com. Per-repository Gitaly RPC concurrency and queuing limits are configured for different types of Git operations such as `git clone`. When these limits are exceeded, a `fatal: remote error: GitLab is currently unable to handle this request due to load` message is returned to the client. -For administrator documentation, see [limit RPC concurrency](../../administration/gitaly/configure_gitaly.md#limit-rpc-concurrency). +For administrator documentation, see [limit RPC concurrency](../../administration/gitaly/concurrency_limiting.md#limit-rpc-concurrency). ## GitLab.com logging diff --git a/doc/user/gitlab_duo_chat.md b/doc/user/gitlab_duo_chat.md index ba6cd9b8f21..ebcb4c69e64 100644 --- a/doc/user/gitlab_duo_chat.md +++ b/doc/user/gitlab_duo_chat.md @@ -1,48 +1,70 @@ --- stage: AI-powered group: Duo Chat -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Answer questions with GitLab Duo Chat **(ULTIMATE SAAS EXPERIMENT)** +# Answer questions with GitLab Duo Chat **(ULTIMATE SAAS BETA)** -> Introduced in GitLab 16.0 as an [Experiment](../policy/experiment-beta-support.md#experiment). +> Introduced in GitLab 16.6 as a [Beta](../policy/experiment-beta-support.md#beta). -You can get AI generated support from GitLab Duo Chat about the following topics: +You can get AI-generated support from GitLab Duo Chat about: - How to use GitLab. -- Questions about an issue. -- Question about an epic. -- Questions about a code file. -- Follow-up questions to answers from the chat. +- The contents of an issue or issue. +- The contents of a code or CI/CD configuration file. -Example questions you might ask: +You can also use GitLab Duo Chat to create code and CI/CD files. + +When you get an answer, you can ask follow-up questions to learn more. + +This is a Beta feature. We're continuously extending the capabilities and reliability of the responses. + +## Ask about GitLab + +You can ask questions about how GitLab works. Things like: - `Explain the concept of a 'fork' in a concise manner.` - `Provide step-by-step instructions on how to reset a user's password.` + +## Ask about your work + +You can ask about GitLab issues and epics. For example: + - `Generate a summary for the issue identified via this link: <link to your issue>` -- `Generate a concise summary of the description of the current issue.` +- `Generate a concise summary of the current issue.` -The examples above all use data from either the issue or the GitLab documentation. However, you can also ask to generate code, CI/CD configurations, or to explain code. For example: +## Ask about code + +You can also ask GitLab Duo Chat to generate code: - `Write a Ruby function that prints 'Hello, World!' when called.` - `Develop a JavaScript program that simulates a two-player Tic-Tac-Toe game. Provide both game logic and user interface, if applicable.` -- `Create a .gitlab-ci.yml configuration file for testing and building a Ruby on Rails application in a GitLab CI/CD pipeline.` + +And you can ask GitLab Duo Chat to explain code: + - `Provide a clear explanation of the given Ruby code: def sum(a, b) a + b end. Describe what this code does and how it works.` -In addition to the provided prompts, feel free to ask follow-up questions to delve deeper into the topic or task at hand. This helps you get more detailed and precise responses tailored to your specific needs, whether it's for further clarification, elaboration, or additional assistance. +## Ask about CI/CD -- A follow-up to the question `Write a Ruby function that prints 'Hello, World!' when called.` could be: - - `Could you also explain how I can call and execute this Ruby function in a typical Ruby environment, such as the command line?` +You can ask GitLab Duo Chat to create a CI/CD configuration: -This is an experimental feature and we're continuously extending the capabilities and reliability of the chat. +- `Create a .gitlab-ci.yml configuration file for testing and building a Ruby on Rails application in a GitLab CI/CD pipeline.` -## Enable GitLab Duo Chat +## Ask follow up questions + +You can ask follow-up questions to delve deeper into the topic or task at hand. +This helps you get more detailed and precise responses tailored to your specific needs, +whether it's for further clarification, elaboration, or additional assistance. -To use this feature, at least one group you're a member of must: +A follow-up to the question `Write a Ruby function that prints 'Hello, World!' when called` could be: -- Have the [experiment and beta features setting](group/manage.md#enable-experiment-and-beta-features) enabled. +- `Can you also explain how I can call and execute this Ruby function in a typical Ruby environment, such as the command line?` + +## Enable GitLab Duo Chat + +To use this feature, at least one group you're a member of must +have the [experiment and beta features setting](group/manage.md#enable-experiment-and-beta-features) enabled. ## Use GitLab Duo Chat @@ -56,12 +78,65 @@ To use this feature, at least one group you're a member of must: NOTE: Only the last 50 messages are retained in the chat history. The chat history expires 3 days after last use. -## Give Feedback +### Delete all conversations + +To delete all previous conversations: + +1. In the text box, type `/clean` and select **Send**. + +## Use GitLab Duo Chat in the Web IDE and VS Code **(ULTIMATE SAAS EXPERIMENT)** + +> Introduced in GitLab 16.6 as an [EXPERIMENT](../policy/experiment-beta-support.md#experiment). + +### Web IDE + +To use GitLab Duo Chat in the Web IDE on GitLab.com: + +1. Open the Web IDE: + 1. On the left sidebar, select **Search or go to** and find your project. + 1. Select a file. Then in the upper right, select **Edit > Open in Web IDE**. +1. Then open Chat by using one of the following methods: + - On the left sidebar, select **GitLab Duo Chat**. + - In the file that you have open in the editor, select some code. + 1. Right-click and select **GitLab Duo Chat**. + 1. Select **Explain selected code** or **Generate Tests**. + + - Use the keyboard shortcut: <kbd>ALT</kbd>+<kbd>d</kbd> (on Windows and Linux) or <kbd>Option</kbd>+<kbd>d</kbd> (on Mac) + +1. In the message box, enter your question and press **Enter** or select **Send**. + +If you have selected code in the editor, this selection is sent along with your question to the AI. This way you can ask questions about this code selection. For instance, `Could you simplify this?`. + +### GitLab Workflow extension for VS Code + +To use GitLab Duo Chat in VS Code: + +1. Install and set up the Workflow extension for VS Code: + 1. In VS Code, download and Install the [GitLab Workflow extension for VS Code](../editor_extensions/visual_studio_code/index.md#download-the-extension). + 1. Configure the [GitLab Workflow extension](../editor_extensions/visual_studio_code/index.md#configure-the-extension). +1. In VS Code, open a file. The file does not need to be a file in a Git repository. +1. Open Chat by using one of the following methods: + - On the left sidebar, select **GitLab Duo Chat**. + - In the file that you have open in the editor, select some code. + 1. Right-click and select **GitLab Duo Chat**. + 1. Select **Explain selected code** or **Generate Tests**. + - Use the keyboard shortcut: <kbd>ALT</kbd>+<kbd>d</kbd> (on Windows and Linux) or <kbd>Option</kbd>+<kbd>d</kbd> (on Mac) +1. In the message box, enter your question and press **Enter** or select **Send**. + +If you have selected code in the editor, this selection is sent along with your question to the AI. This way you can ask questions about this code selection. For instance, `Could you simplify this?`. + +### Disable Chat in Web IDE and VS Code + +To disable GitLab Duo Chat in the Web IDE and VS Code: + +1. Go to **Settings > Extensions > GitLab Workflow (GitLab VSCode Extension)**. +1. Clear the **Enable GitLab Duo Chat assistant** checkbox. + +## Give feedback Your feedback is important to us as we continually enhance your GitLab Duo Chat experience: - **Enhance Your Experience**: Leaving feedback helps us customize the Chat for your needs and improve its performance for everyone. -- **Privacy Assurance**: Rest assured, we don't collect your prompts. Your privacy is respected, and your interactions remain private. To give feedback about a specific response, use the feedback buttons in the response message. -Or, you can add a comment in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/415591). +Or, you can add a comment in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/430124). diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 53a62a60157..e08cfea7095 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group access and permissions @@ -303,7 +303,7 @@ To create group links via filter: LDAP user permissions can be manually overridden by an administrator. To override a user's permissions: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Manage > Members**. If LDAP synchronization +1. Select **Manage > Members**. If LDAP synchronization has granted a user a role with: - More permissions than the parent group membership, that user is displayed as having [direct membership](../project/members/index.md#display-direct-members) of the group. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 5c0844dff92..ded99f7c936 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group-level Kubernetes clusters (certificate-based) (deprecated) **(FREE ALL)** diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 7258791a983..4a03db33a86 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance frameworks **(PREMIUM ALL)** @@ -25,7 +25,7 @@ or deleted at the subgroup or project level. Project owners can choose a framewo ## Add a compliance framework to a project -Prerequisite: +Prerequisites: - The group to which the project belongs must have a compliance framework. @@ -336,7 +336,7 @@ cannot change them: non-modifiable and are always run. - Explicitly set any [variables](../../ci/yaml/index.md#variables) the job references. This: - Ensures that project-level pipeline configurations do not set them and alter their - behavior. + behavior. For example, see `before_script` and `after_script` configuration in the [example configuration](#example-configuration). - Includes any jobs that drive the logic of your job. - Explicitly set the [container image](../../ci/yaml/index.md#image) to run the job in. This ensures that your script steps execute in the correct environment. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 96cc9ce974c..6d8d209986c 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Contribution analytics **(PREMIUM ALL)** diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 967ba4e05d0..07158a0c06f 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom group-level project templates **(PREMIUM ALL)** @@ -21,7 +21,7 @@ You can also configure [custom templates for the instance](../../administration/ ## Set up group-level project templates -Prerequisite: +Prerequisites: - You must have the Owner role for the group. @@ -40,7 +40,7 @@ Projects in nested subgroups are not included in the template list. ## Which projects are available as templates - Public and internal projects can be selected by any authenticated user as a template for a new project, - if all [project features](../project/settings/index.md#configure-project-features-and-permissions) + if all [project features](../project/settings/project_features_permissions.md#configure-project-features-and-permissions) except for **GitLab Pages** and **Security and Compliance** are set to **Everyone With Access**. - Private projects can be selected only by users who are members of the projects. diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 5359d7b52a0..cdb11bb0548 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group DevOps Adoption **(ULTIMATE ALL)** @@ -30,7 +30,7 @@ how to use those features. ## View DevOps Adoption -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the group. diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 69b64861bd5..0547f947419 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epic boards **(PREMIUM ALL)** @@ -17,10 +17,10 @@ labels. On the top of each list, you can see the number of epics in the list (**{epic}**) and the total weight of all its epics (**{weight}**). <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=I1bFIAQBHB8">Epics and Issue Boards - Project Management</a>. + See the video: <a href="https://www.youtube.com/watch?v=eQUnHwbKEkY">Epics and Issue Boards - Project Management</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/I1bFIAQBHB8" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/eQUnHwbKEkY" frameborder="0" allowfullscreen> </iframe> </figure> To view an epic board: diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 83d38dbc70b..c524490eb0b 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epics **(PREMIUM ALL)** @@ -20,10 +20,10 @@ Use epics: - To discuss and collaborate on feature ideas and scope at a high level. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=kdE-yb6Puuo">GitLab Epics - Setting up your Organization with GitLab</a>. + See the video: <a href="https://www.youtube.com/watch?v=c0EwYYUZppw">GitLab Epics - Setting up your Organization with GitLab</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/kdE-yb6Puuo" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/c0EwYYUZppw" frameborder="0" allowfullscreen> </iframe> </figure> ## Relationships between epics and issues diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 8b57c1b4d1f..fb63e851a69 100644 --- a/doc/user/group/epics/linked_epics.md +++ b/doc/user/group/epics/linked_epics.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked epics **(ULTIMATE ALL)** diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index a5cc3ad9070..9cdebdd7d9d 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -1,8 +1,7 @@ --- -type: howto stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage epics **(PREMIUM ALL)** diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 24d5ca5b214..28878855098 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating GitLab groups **(FREE ALL)** @@ -76,7 +76,7 @@ Estimating the duration of migration by direct transfer is difficult. The follow very different amounts of time to migrate if one of the projects has a lot more attachments, comments, and other items on the merge requests. Therefore, the number of merge requests on a project is a poor predictor of how long a project will take to migrate. -There’s no exact formula to reliably estimate a migration. However, the average durations of each pipeline worker importing a project relation can help you to get an idea of how long importing your projects might take: +There's no exact formula to reliably estimate a migration. However, the average durations of each pipeline worker importing a project relation can help you to get an idea of how long importing your projects might take: | Project resource type | Average time (in seconds) to import a record | |:----------------------------|:---------------------------------------------| @@ -113,6 +113,8 @@ If you are migrating large projects and encounter problems with timeouts or dura ### Limits +> Eight hour time limit on migrations [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/429867) in GitLab 16.7. + Hardcoded limits apply on migration by direct transfer. | Limit | Description | @@ -121,7 +123,6 @@ Hardcoded limits apply on migration by direct transfer. | 210 seconds | Maximum number of seconds to wait for decompressing an archive file. | | 50 MB | Maximum length an NDJSON row can have. | | 5 minutes | Maximum number of seconds until an empty export status on source instance is raised. | -| 8 hours | Time until migration times out. | [Configurable limits](../../../administration/settings/account_and_limit_settings.md) are also available. @@ -173,9 +174,12 @@ To migrate groups by direct transfer: - For GitLab 15.0 and earlier source instances, the personal access token must have both the `api` and `read_repository` scopes. - You must have the Owner role on the source group to migrate from. -- Your must have a role on the destination namespace the enables you to +- You must have a role in the destination namespace that enables you to [create a subgroup](../../group/subgroups/index.md#create-a-subgroup) in that namespace. +- To import items stored in object storage, you must either: + - [Configure `proxy_download`](../../../administration/object_storage.md#configure-the-common-parameters). + - Ensure that the destination GitLab instance has access to the object storage of the source GitLab instance. ### Prepare user accounts @@ -201,7 +205,7 @@ Create the group you want to import to and connect the source GitLab instance: - A new subgroup. On existing group's page, either: - Select **New subgroup**. - On the left sidebar, at the top, select **Create new** (**{plus}**) and **New subgroup**. Then select the **import an existing group** link. -1. Enter the URL of a GitLab instance running GitLab 14.0 or later. +1. Enter the base URL of a GitLab instance running GitLab 14.0 or later. 1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your source GitLab instance. 1. Select **Connect instance**. @@ -226,6 +230,8 @@ ready for production use. ### Group import history +> **Partially completed** status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394727) in GitLab 16.7. + You can view all groups migrated by you by direct transfer listed on the group import history page. This list includes: - Paths of source groups. @@ -249,7 +255,7 @@ To view group import history: To review the results of an import: 1. Go to the [Group import history page](#group-import-history). -1. To see the details of a failed import, select the **See failures** link on any import with a **Failed** status. +1. To see the details of a failed import, select the **See failures** link on any import with a **Failed** or **Partially completed** status. ### Migrated group items @@ -433,7 +439,7 @@ Some project items are excluded from migration because they either: - Environments - Feature flags - Infrastructure Registry - - Package Registry + - Package registry - Pages domains - Remote mirrors @@ -613,15 +619,14 @@ sure these users exist before importing the desired groups. ### Enable export for a group -Prerequisite: +Prerequisites: - You must have the Owner role for the group. To enable import and export for a group: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. In the **Import sources** section, select the checkboxes for the sources you want. @@ -662,7 +667,7 @@ NOTE: The maximum import file size can be set by the administrator, default is `0` (unlimited). As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the -[Admin Area](../../admin_area/settings/account_and_limit_settings.md). +[Admin Area](../../../administration/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to 0 in GitLab 13.8. ### Rate limits diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 1a4fa9df305..f4b4f9f2d39 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Groups **(FREE ALL)** @@ -32,7 +32,7 @@ A single top-level group provides insights in your entire organization via a com ## Group visibility -Like projects, a group can be configured to limit the visibility of it to: +Like projects, a group can be configured to be visible to: - Anonymous users. - All authenticated users. @@ -42,30 +42,30 @@ The restriction for [visibility levels](../../administration/settings/visibility on the application setting level also applies to groups. If set to internal, the explore page is empty for anonymous users. The group page has a visibility level icon. -Administrator users cannot create a subgroup or project with a higher visibility level than that of +Users cannot create a subgroup or project with a higher visibility level than that of the immediate parent group. ## View groups -To explore all public groups: +To explore all public groups you are a member of: 1. On the left sidebar, select **Search or go to**. 1. Select **View all my groups**. -1. At the top right, select **Explore groups**. +1. In the upper right, select **Explore groups**. -To view groups where you have a direct or indirect membership: +To view groups where you have direct or indirect membership: 1. On the left sidebar, select **Search or go to**. 1. Select **View all my groups**. -This page shows groups that you are a member of: +This page shows groups that you are a member of through: -- Through membership of a subgroup's parent group. -- Through direct or inherited membership of a project in the group or subgroup. +- Membership of a subgroup's parent group. +- Direct or inherited membership of a project in the group or subgroup. ## View group activity -To view the activity of a project: +To view the activity of a group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Activity**. @@ -75,7 +75,6 @@ To view the activity of a project: - **Push events**: Push events in the group's projects. - **Merge events**: Accepted merge requests in the group's projects. - **Issue events**: Issues opened and closed in the group's projects. - - **Epic events**: Epics opened and closed in the group. - **Comments**: Comments posted by group members in the group's projects. - **Wiki**: Updates to wiki pages in the group. - **Designs**: Designs added, updated, and removed in the group's projects. @@ -87,19 +86,52 @@ To create a group: 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**. 1. Select **Create group**. -1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see +1. In the **Group name** text box, enter the name of the group. For a list of words that cannot be used as group names, see [reserved names](../reserved_names.md). -1. Enter a path for the group in **Group URL**, which is used for the [namespace](../namespace/index.md). -1. Choose the [visibility level](../public_access.md). -1. Personalize your GitLab experience by answering the following questions: - - What is your role? - - Who is using this group? - - What are you using this group for? -1. Invite GitLab members or other users to join the group. +1. In the **Group URL** text box, enter the path for the group used for the [namespace](../namespace/index.md). +1. Select the [**Visibility level**](../public_access.md) of the group. +1. Optional. To personalize your GitLab experience: + - From the **Role** dropdown list, select your role. + - For **Who will be using this group?**, select an option. + - From the **What will you use this group for?** dropdown list, select an option. +1. Optional. To invite members to the group, in the **Email 1** text box, enter the email address of the user you want to invite. To invite more users, select **Invite another member** and enter the user's email address. +1. Select **Create group**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For details about groups, watch [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A). +## Edit group name and description + +You can edit your group details from the group general settings. + +Prerequisites: + +- You must have the Owner role for the group. + +To edit group details: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. In the **Group name** text box, enter your group name. See the [limitations on group names](../../user/reserved_names.md). +1. Optional. In the **Group description (optional)** text box, enter your group description. + The description is limited to 500 characters. +1. Select **Save changes**. + +## Leave a group + +> The button to leave a group [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7. + +When you leave a group: + +- You are no longer a member of the group, its subgroups, and projects, and cannot contribute. +- All the issues and merge requests that were assigned to you are unassigned. + +To leave a group: + +1. On the left sidebar, select **Search or go to** and find your group. +1. On the group overview page, in the upper-right corner, select **Actions** (**{ellipsis_v})**. +1. Select **Leave group**, then **Leave group** again. + ## Remove a group > Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. @@ -107,23 +139,19 @@ For details about groups, watch [GitLab Namespaces (users, groups and subgroups) To remove a group and its contents: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. In the **Remove group** section, select **Remove group**. -1. Type the group name. -1. Select **Confirm**. +1. On the confirmation dialog, type the group name and select **Confirm**. -A group can also be removed from the groups dashboard: +You can also remove a group from the groups dashboard: 1. On the left sidebar, select **Search or go to**. 1. Select **View all my groups**. 1. Select (**{ellipsis_v}**) for the group you want to delete. 1. Select **Delete**. -1. In the Remove group section, select **Remove group**. -1. Type the group name. -1. Select **Confirm**. - -This action removes the group. It also adds a background job to delete all projects in the group. +1. In the **Remove group** section, select **Remove group**. +1. On the confirmation dialog, type the group name and select **Confirm**. In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on GitLab [Premium](https://about.gitlab.com/pricing/premium/) and [Ultimate](https://about.gitlab.com/pricing/ultimate/), this action adds a background job to mark a group for deletion. By default, the job schedules the deletion seven days in the future. You can modify this retention period through the [instance settings](../../administration/settings/visibility_and_access_controls.md#deletion-protection). @@ -146,11 +174,10 @@ To immediately remove a group marked for deletion: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Advanced**. -1. In the "Permanently remove group" section, select **Remove group**. +1. In the **Permanently remove group** section, select **Remove group**. 1. Confirm the action when asked to. -Your group, its subgroups, projects, and all related resources, including issues and merge requests, -are deleted. +This action deletes the group, its subgroups, projects, and all related resources, including issues and merge requests. ## Restore a group **(PREMIUM ALL)** @@ -161,7 +188,7 @@ To restore a group that is marked for deletion: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Advanced** section. -1. In the Restore group section, select **Restore group**. +1. In the **Restore group** section, select **Restore group**. ## Request access to a group @@ -169,12 +196,12 @@ As a user, you can request to be a member of a group, if an administrator allows 1. On the left sidebar, select **Search or go to**. 1. Select **View all my groups**. -1. At the top right side, select **Explore groups**. -1. Search for the group by name. +1. In the upper right, select **Explore groups**. +1. In the **Search by name** text box, enter the name of the group you want to join. 1. In the search results, select the name of the group. 1. On the group page, under the group name, select **Request Access**. -As many as ten of the most-recently-active group owners receive an email with your request. +Up to ten of the most recently active group owners receive an email with your request. Any group owner can approve or decline the request. If you change your mind before your request is approved, select @@ -189,16 +216,16 @@ To view a group's members: A table displays the member's: -- **Account** name and username +- **Account** name and username. - **Source** of their [membership](../project/members/index.md#membership-types). For transparency, GitLab displays all membership sources of group members. Members who have multiple membership sources are displayed and counted as separate members. For example, if a member has been added to the group both directly and through inheritance, the member is displayed twice in the **Members** table, with different sources, and is counted as two individual members of the group. -- [**Max role**](../project/members/index.md#which-roles-you-can-assign) in the group -- **Expiration** date of their group membership -- **Activity** related to their account +- [**Max role**](../project/members/index.md#which-roles-you-can-assign) in the group. +- **Expiration** date of their group membership. +- **Activity** related to their account. NOTE: The display of group members' **Source** might be inconsistent. @@ -223,11 +250,11 @@ In lists of group members, entries can display the following badges: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. -1. Above the list of members, in the **Filter members** box, enter filter criteria. - - To view members in the group only, select **Membership = Direct**. - - To view members of the group and its subgroups, select **Membership = Inherited**. - - To view members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **Disabled**. - - To view members of the top-level group who are [enterprise users](../enterprise_user/index.md), select **Enterprise = true**. +1. Above the list of members, in the **Filter members** text box, enter your search criteria. To view: + - Direct members of the group, select **Membership = Direct**. + - Members of the group and its subgroups, select **Membership = Inherited**. + - Members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **2FA = Disabled**. + - Members of the top-level group who are [enterprise users](../enterprise_user/index.md), select **Enterprise = true**. ### Search a group @@ -255,27 +282,43 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last You can give a user access to all projects in a group. -Prerequisite: +Prerequisites: -- You must have the Owner role. +- You must have the Owner role for the group. 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. 1. Select **Invite members**. -1. Fill in the fields. - - The role applies to all projects in the group. For more information, see [permissions](../permissions.md). - - Optional. Select an **Access expiration date**. From that date onward, the - user can no longer access the project. +1. If the user: + + - Has a GitLab account, enter the user's username. + - Doesn't have a GitLab account, enter the user's email address. + +1. Select a [role](../permissions.md). +1. Optional. For **Access expiration date**, enter or select a date. + From that date onward, the user can no longer access the project. + + If you enter an access expiration date, the group member gets an email notification + seven days before their access expires. + + WARNING: + If you give a member the Maintainer role and enter an expiration date, that member + has full permissions as long as they are in the role. These permissions include the member's ability + to extend their own time in the Maintainer role. + 1. Select **Invite**. + If you invite the user by their: -If you selected an access expiration date, the group member gets an email notification -seven days before their access expires. + - GitLab username, the user is added to the member list. + - Email address, the user receives an email invitation and is prompted to create an account. + If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. + Unaccepted invites are automatically deleted after 90 days. Members that are not automatically added are displayed on the **Invited** tab. -Users can be on this tab because they: +This tab includes users who: - Have not yet accepted the invitation. -- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). +- Are waiting for [approval from an administrator](../../administration/moderate_users.md). - [Exceed the group user cap](manage.md#user-cap-for-groups). ## Remove a member from the group @@ -293,21 +336,16 @@ To remove a member from a group: 1. Select **Manage > Members**. 1. Next to the member you want to remove, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Remove member**. -1. Optional. On the **Remove member** confirmation box: - - To remove direct user membership from subgroups and projects, select the **Also remove direct user membership from subgroups and projects** checkbox. - - To unassign the user from linked issues and merge requests, select the **Also unassign this user from linked issues and merge requests** checkbox. +1. Optional. On the **Remove member** confirmation dialog, select one or both checkboxes: + - **Also remove direct user membership from subgroups and projects** + - **Also unassign this user from linked issues and merge requests** 1. Select **Remove member**. -## Ensure removed users cannot invite themselves back - -Malicious users with the Maintainer or Owner role could exploit a race condition that allows -them to invite themselves back to a group or project that a GitLab administrator has removed them from. - -To avoid this problem, GitLab administrators can [ensure removed users cannot invite themselves back](../project/members/index.md#ensure-removed-users-cannot-invite-themselves-back). +GitLab administrators can also [ensure removed users cannot invite themselves back](../project/members/index.md#ensure-removed-users-cannot-invite-themselves-back). ## Add projects to a group -There are two different ways to add a new project to a group: +You can add a new project to a group in two ways: - Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md). - While you are creating a project, select a group from the dropdown list. @@ -316,13 +354,10 @@ There are two different ways to add a new project to a group: ### Specify who can add projects to a group -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10. - -By default, users with: +By default, users with at least the: -- At least the Developer role can create projects under a group. This default can be changed. -- At least the Maintainer role can fork projects into a group. This default prevents users with the Developer role from forking projects that +- Developer role can create projects under a group. This default can be changed. +- Maintainer role can fork projects into a group. This default prevents users with the Developer role from forking projects that contain protected branches and cannot be changed. To change the role that can create projects under a group: @@ -330,7 +365,19 @@ To change the role that can create projects under a group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand the **Permissions and group features** section. -1. Select the desired option in the **Roles allowed to create projects** dropdown list. +1. From **Roles allowed to create projects**, select an option. 1. Select **Save changes**. To change this setting globally, see [Default project creation protection](../../administration/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). + +## Get the group ID + +> Group ID [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7. + +You might need the group ID if you want to interact with it using the [GitLab API](../../api/index.md). + +To copy the group ID: + +1. On the left sidebar, select **Search or go to** and find your group. +1. On the group overview page, in the upper-right corner, select **Actions** (**{ellipsis_v})**. +1. Select **Copy group ID**. diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 2ded1b08de2..6ca37cb9a2c 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Insights for groups **(ULTIMATE ALL)** @@ -56,6 +56,16 @@ By default, insights display all available dimensions on the chart. To exclude a dimension, from the legend below the chart, select the name of the dimension. +### Drill down on charts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372215/) in GitLab 16.7. + +You can drill down into the data of the **Bugs created per month by priority** and **Bugs created per month by severity** charts from the [default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). + +To view a drill-down report of the data for a specific priority or severity in a month: + +- On the chart, select the bar stack you want to drill down on. + ## Configure group insights GitLab reads insights from the diff --git a/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png b/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png Binary files differnew file mode 100644 index 00000000000..519e56acaa5 --- /dev/null +++ b/doc/user/group/issues_analytics/img/enhanced_issue_analytics_v16_7.png diff --git a/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png b/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png Binary files differdeleted file mode 100644 index 5e1fe4eaa8c..00000000000 --- a/doc/user/group/issues_analytics/img/issues_closed_analytics_v16_4.png +++ /dev/null diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 4f1c7b4be7a..28f4026b3e3 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue analytics for groups **(PREMIUM ALL)** @@ -16,7 +15,7 @@ prior. To access the chart: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Analyze > Issue analytics**. +1. Select **Analyze > Issue analytics**. You can also access the chart from the [Value Streams Dashboard](../../analytics/value_streams_dashboard.md) through the **New issues** drill-down report. @@ -50,7 +49,7 @@ available. This feature is not ready for production use. Enhanced issue analytics display the additional metric "Issues closed", which represents the total number of resolved issues in your group over a selected period. You can use this metric to improve the overall turn-around time and value delivered to your customers. - + ## Drill into the information diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 8c0838cf33c..bfbba8cc0da 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Iterations **(PREMIUM ALL)** @@ -78,7 +77,7 @@ From there you can create a new iteration or select an iteration to get a more d NOTE: If a project has issue tracking -[turned off](../../project/settings/index.md#configure-project-features-and-permissions), +[turned off](../../project/settings/project_features_permissions.md#configure-project-features-and-permissions), to view the iterations list, enter its URL. To do so, add: `/-/cadences` to your project or group URL. For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/cadences`. This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). @@ -179,7 +178,7 @@ Prerequisites: To create an iteration: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Plan > Iterations** and select an iteration cadence. +1. Select **Plan > Iterations** and select an iteration cadence. 1. Select **New iteration**. 1. Enter the title, a description (optional), a start date, and a due date. 1. Select **Create iteration**. The iteration details page opens. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index 48f86ee4f0e..877db58b716 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage groups @@ -23,7 +23,7 @@ A single top-level group provides insights in your entire organization via a com As a group owner or member, you can use a README to provide more information about your team, and invite users to contribute to your projects. The README is displayed on the group overview page, and can be changed in the group settings. All group members can edit the README. -Prerequisite: +Prerequisites: - To create the README from the group settings, you must have the Owner role for the group. @@ -53,20 +53,15 @@ member with the Owner role. ## Change a group's path -Changing a group's path (group URL) can have unintended side effects. Read -[how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes) +Changing a group's path (group URL) can have unintended side effects. Read how redirects behave +[on the project-level](../project/repository/index.md#what-happens-when-a-repository-path-changes) +and [in the API](../../api/rest/index.md#redirects) before you proceed. If you are changing the path so it can be claimed by another group or user, you must rename the group too. Both names and paths must be unique. -After you change the group path, the new group path is a new namespace and you must update the existing project URL in the following resources: - -- [Include statements](../../ci/yaml/includes.md#include-a-single-configuration-file). -- Docker image references in CI files. -- Variables that specify a project or namespace. - To retain ownership of the original namespace and protect the URL redirects, create a new group and transfer projects to it instead. @@ -83,6 +78,11 @@ It is not possible to rename a namespace if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. +WARNING: +To ensure that groups with thousands of subgroups get processed correctly, you should test the path change in a test environment. +Consider increasing the [Puma worker timeout](../../administration/operations/puma.md#change-the-worker-timeout) temporarily. +For more information about our solution to mitigate this timeout risk, see [issue 432065](https://gitlab.com/gitlab-org/gitlab/-/issues/432065). + ## Change the default branch protection of a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. @@ -231,7 +231,7 @@ To disable group mentions: You can export a list of members in a group or subgroup as a CSV. 1. On the left sidebar, select **Search or go to** and find your group or subgroup. -1. On the left sidebar, **Manage > Members**. +1. Select **Manage > Members**. 1. Select **Export as CSV**. 1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. @@ -254,7 +254,7 @@ disabled for the group and its subgroups. ### Specify a user cap for a group -Prerequisite: +Prerequisites: - You must be assigned the Owner role for the group. @@ -276,7 +276,7 @@ Increasing the user cap does not approve pending members. You can remove the user cap, so there is no limit on the number of members you can add to a group. -Prerequisite: +Prerequisites: - You must be assigned the Owner role for the group. @@ -297,14 +297,14 @@ and must be approved. Pending members do not count as billable. Members count as billable only after they have been approved and are no longer in a pending state. -Prerequisite: +Prerequisites: -- You must be assigned the Owner role) for the group. +- You must be assigned the Owner role for the group. To approve members that are pending because they've exceeded the user cap: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select **Settings > Usage Quotas**. 1. On the **Seats** tab, under the alert, select **View pending approvals**. 1. For each member you want to approve, select **Approve**. @@ -322,7 +322,7 @@ User cap doesn’t consider whether users are billable or not (e.g., Free Guest Use group file templates to share a set of templates for common file types with every project in a group. It is analogous to the -[instance template repository](../admin_area/settings/instance_template_repository.md). +[instance template repository](../../administration/settings/instance_template_repository.md). The selected project should follow the same naming conventions as are documented on that page. @@ -390,7 +390,7 @@ You can configure [skipped pipelines](../../ci/pipelines/index.md#skip-a-pipelin See also [the project-level setting](../project/merge_requests/merge_when_pipeline_succeeds.md#allow-merge-after-skipped-pipelines). -Prerequisite: +Prerequisites: - You must be the owner of the group. @@ -409,7 +409,7 @@ To change this behavior: You can prevent merge requests from being merged until all threads are resolved. When this setting is enabled, for all child projects in your group, the **Unresolved threads** count in a merge request is shown in orange when at least one thread remains unresolved. -Prerequisite: +Prerequisites: - You must be the owner of the group. @@ -443,7 +443,7 @@ Approval settings should not be confused with [approval rules](../project/merge_ for the ability to set merge request approval rules for groups is tracked in [epic 4367](https://gitlab.com/groups/gitlab-org/-/epics/4367). -## Enable Code Suggestions **(FREE SAAS)** +## Enable Code Suggestions for a group **(FREE SAAS)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/405126) in GitLab 15.11. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. @@ -454,12 +454,9 @@ This feature is in [Beta](../../policy/experiment-beta-support.md#beta). Beta users should read about the [known limitations](../project/repository/code_suggestions/index.md#known-limitations). We look forward to hearing your [feedback](../project/repository/code_suggestions/index.md#feedback). -You can give all users in a group and its subgroups access to [Code Suggestions](../project/repository/code_suggestions/index.md). - -- This setting - [cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) in the group. -- Each user can - [enable Code Suggestions](../../user/profile/preferences.md#enable-code-suggestions). +You can give all users in a group and its subgroups access to +[Code Suggestions](../project/repository/code_suggestions/index.md). This setting +[cascades to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) in the group. Code Suggestions are enabled by default at the group level. @@ -471,6 +468,9 @@ To update this setting: 1. Under **Code Suggestions**, select the **Projects in this group can use Code Suggestions** checkbox. 1. Select **Save changes**. +Individual users can disable Code Suggestions by disabling the feature in their +[installed IDE editor extension](../project/repository/code_suggestions/index.md#supported-editor-extensions). + ## Enable Experiment and Beta features **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118222) in GitLab 16.0. @@ -509,7 +509,7 @@ Changes to [group wikis](../project/wiki/group.md) do not appear in group activi You can view the most recent actions taken in a group, either in your browser or in an RSS feed: 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Manage > Activity**. +1. Select **Manage > Activity**. To view the activity feed in Atom format, select the **RSS** (**{rss}**) icon. diff --git a/doc/user/group/moderate_users.md b/doc/user/group/moderate_users.md index 6859125b323..38d83c6b5f7 100644 --- a/doc/user/group/moderate_users.md +++ b/doc/user/group/moderate_users.md @@ -1,16 +1,23 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Moderate users **(FREE ALL)** +# Moderate users **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8. This is the group-level documentation. For self-managed instances, see the [administration documentation](../../administration/moderate_users.md). A group Owner can moderate user access by banning and unbanning users. +You should ban a user when you want to block them from the group. + +A banned user: + +- Cannot access the group or any of repositories. +- Cannot use [slash commands](../project/integrations/gitlab_slack_application.md#slash-commands). +- Does not occupy a [seat](../free_user_limit.md). ## Unban a user diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md index 17552ceaf88..3cfcba066c7 100644 --- a/doc/user/group/planning_hierarchy/index.md +++ b/doc/user/group/planning_hierarchy/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Planning hierarchies **(PREMIUM ALL)** diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index d32524b8f5f..e00602aeacd 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git abuse rate limit **(ULTIMATE ALL)** @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w FLAG: On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `limit_unique_project_downloads_per_namespace_user`. On GitLab.com, this feature is available. -This is the group-level documentation. For self-managed instances, see the [administration documentation](../../admin_area/reporting/git_abuse_rate_limit.md). +This is the group-level documentation. For self-managed instances, see the [administration documentation](../../../administration/reporting/git_abuse_rate_limit.md). Git abuse rate limiting is a feature to automatically ban users who download, clone, pull, fetch, or fork more than a specified number of repositories of a group in a given time frame. Banned users cannot access the top-level group or any of its non-public subgroups via HTTP or SSH. The rate limit also applies to users who authenticate with [personal](../../../user/profile/personal_access_tokens.md) or [group access tokens](../../../user/group/settings/group_access_tokens.md), as well as [CI/CD job tokens](../../../ci/jobs/ci_job_token.md). Access to unrelated groups is unaffected. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 6f02b27a214..baeab5b0bbc 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Execution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repositories analytics for groups **(PREMIUM ALL)** diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 89d461127e7..6af2a234447 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Roadmap **(PREMIUM ALL)** diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index 86ad2ba32d1..46666abe366 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Example group SAML and SCIM configurations **(PREMIUM SAAS)** @@ -41,9 +40,6 @@ This section has screenshots for the elements of Azure Active Directory configur  -NOTE: -Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are not supported. - ### SCIM mapping Provisioning: diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 7b10da016b9..144d927f7e5 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAML Group Sync **(PREMIUM ALL)** @@ -77,11 +76,26 @@ example configurations for [Azure AD](../../../user/group/saml_sso/example_saml_ ## Configure SAML Group Links -When SAML is enabled, users with the Maintainer or Owner role -see a new menu item in group **Settings > SAML Group Links**. You can configure one or more **SAML Group Links** to map -a SAML identity provider group name to a GitLab role. This can be done for a top-level group or any subgroup. +When SAML is enabled, users with the Maintainer or Owner role see a new menu +item in group **Settings > SAML Group Links**. -SAML Group Sync only manages a group if that group has one or more SAML group links. If a SAML group link is created then removed, the user remains in the group until they are removed from the group in the identity provider. +- You can configure one or more **SAML Group Links** to map a SAML identity + provider group name to a GitLab role. +- Members of the SAML identity provider group are added as members of the GitLab + group on their next SAML sign-in. +- Group membership is evaluated each time a user signs in using SAML. +- SAML Group Links can be configured for a top-level group or any subgroup. +- SAML Group Sync only manages a group if that group has one or more SAML group + links. If a SAML group link is created then removed, and there are: + - Other SAML group links configured, users that were in the removed group + link are automatically removed from the group during sync. + - No other SAML group links configured, users remain in the group during sync. + Those users must be manually removed from the group. + +Prerequisites: + +- Self-managed GitLab instances must have configured SAML Group Sync. GitLab.com + instances are already configured for SAML Group Sync, and require no extra configuration. To link the SAML groups: @@ -104,8 +118,6 @@ Users granted: - A lower or the same role with Group Sync are displayed as having [inherited membership](../../project/members/index.md#display-inherited-members) of the group. -SAML group membership is evaluated each time a user signs in. - ### Use the API > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. @@ -171,8 +183,7 @@ To configure for a GitLab.com group: To configure for self-managed: 1. Configure [SAML SSO for the instance](../../../integration/saml.md). -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. In the **Microsoft Azure integration** section, select the **Enable Microsoft Azure integration for this group** checkbox. 1. Enter the **Tenant ID**, **Client ID**, and **Client secret** obtained earlier when configuring Azure Active Directory in the Azure Portal. @@ -202,11 +213,10 @@ When global group memberships lock is enabled: To enable global group memberships lock: 1. [Configure SAML](../../../integration/saml.md) for your self-managed GitLab instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand the **Visibility and access controls** section. -1. Ensure the **Lock memberships to SAML synchronization** checkbox is selected. +1. Ensure that **Lock memberships to SAML Group Links synchronization** is selected. ## Automatic member removal diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 70af800b180..6f1ab305782 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAML SSO for GitLab.com groups **(PREMIUM SAAS)** @@ -179,6 +179,9 @@ To set up OneLogin as your identity provider: ### Configure assertions +NOTE: +The attributes are case-sensitive. + At minimum, you must configure the following assertions: 1. [NameID](#manage-user-saml-identity). @@ -192,9 +195,6 @@ Optionally, you can pass user information to GitLab as attributes in the SAML as For more information, see the [attributes available for self-managed GitLab instances](../../../integration/saml.md#configure-assertions). -NOTE: -Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are not supported. For more information on configuring required attribute names in the SAML identity provider's settings, see [example group SAML and SCIM configurations](../../../user/group/saml_sso/example_saml_config.md). - ### Use metadata To configure some identity providers, you need a GitLab metadata URL. @@ -236,6 +236,8 @@ If the **NameID** is configured with the email address, [change the **NameID** f ## Configure GitLab +> Ability to set a custom role as the default membership role [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417285) in GitLab 16.7. + After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: 1. On the left sidebar, select **Search or go to** and find your group. @@ -244,9 +246,12 @@ After you set up your identity provider to work with GitLab, you must configure - In the **Identity provider single sign-on URL** field, enter the SSO URL from your identity provider. - In the **Certificate fingerprint** field, enter the fingerprint for the SAML token signing certificate. 1. In the **Default membership role** field, select the role to assign to new users. - The default role is **Guest**. In [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523) - and later, group owners can set a default membership role other than **Guest**. - That role becomes the starting role of all users added to the group. + The default role is **Guest**. That role becomes the starting role of all users + added to the group: + - In [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523) and + later, group Owners can set a default membership role other than **Guest**. + - In GitLab 16.7 and later, group Owners can set a [custom role](../../custom_roles.md) + as the default membership role. 1. Select the **Enable SAML authentication for this group** checkbox. 1. Optional. Select: - **Enforce SSO-only authentication for web activity for this group**. @@ -349,25 +354,22 @@ breaks the configuration and could lock users out of the GitLab group. For more information on the recommended value and format for specific identity providers, see [set up your identity provider](#set-up-your-identity-provider). -### Configure user settings from SAML response +### Configure enterprise user settings from SAML response -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/412898) to configure only enterprise user settings in GitLab 16.7. GitLab allows setting certain user attributes based on values from the SAML response. An existing user's attributes are updated from the SAML response values if that -user was originally provisioned by the group. Users are provisioned by the group -when the account was created either: - -- Through [SCIM](scim_setup.md). -- By first sign-in with SAML SSO for GitLab.com groups. +user is an [enterprise user](../../enterprise_user/index.md) of the group. #### Supported user attributes -- **can_create_group** - `true` or `false` to indicate whether the user can create +- **can_create_group** - `true` or `false` to indicate whether an enterprise user can create new top-level groups. Default is `true`. -- **projects_limit** - The total number of personal projects a user can create. +- **projects_limit** - The total number of personal projects an enterprise user can create. A value of `0` means the user cannot create new projects in their personal - namespace. Default is `10000`. + namespace. Default is `100000`. #### Example SAML response diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index e29b33469ab..3c5c53cbdf6 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure SCIM for GitLab.com groups **(PREMIUM SAAS)** @@ -19,6 +19,8 @@ When SCIM is enabled for a GitLab group, membership of that group is synchronize The [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). Identity providers can use the [internal GitLab group SCIM API](../../../development/internal_api/index.md#group-scim-api) to develop a SCIM app. +To set up SCIM on GitLab self-managed, see [Configure SCIM for self-managed GitLab instances](../../../administration/settings/scim_setup.md). + ## Configure GitLab Prerequisites: diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index 527d710058a..a2576f37ac9 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting SAML **(FREE ALL)** @@ -222,7 +221,7 @@ to [reset their password](https://gitlab.com/users/password/new) if both: Users might get an error that states "SAML Name ID and email address do not match your user account. Contact an administrator." This means: -- The NameID value sent by SAML does not match the existing SAML identity `extern_uid` value. Both the NameID and the `extern_uid` are case sensitive. For more information, see [manage user SAML identity](index.md#manage-user-saml-identity). +- The NameID value sent by SAML does not match the existing SAML identity `extern_uid` value. Both the NameID and the `extern_uid` are case sensitive. For more information, see [manage user SAML identity](index.md#manage-user-saml-identity). - Either the SAML response did not include an email address or the email address did not match the user's GitLab email address. The workaround is that a GitLab group Owner uses the [SAML API](../../../api/saml.md) to update the user's SAML `extern_uid`. @@ -290,7 +289,7 @@ If a subset of users are receiving a `404` after signing in to the IdP, first ve Example request: ```plaintext - curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <SCIM_TOKEN>" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }' + curl --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <SCIM_TOKEN>" --header "Content-Type: application/scim+json" --data '{ "Operations": [{"op":"Replace","path":"active","value":"true"}] }' ``` ### 500 error after login **(FREE SELF)** @@ -323,8 +322,7 @@ This message might indicate that you must add or remove a domain from your domai To implement this workaround: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings** > **General**. 1. Expand **Sign-up restrictions**. 1. Add or remove a domain as appropriate to **Allowed domains for sign-ups** and **Denied domains for sign-ups**. @@ -359,18 +357,21 @@ Additionally, see [troubleshooting users receiving a 404 after sign in](#users-r ## Message: The SAML response did not contain an email address. Either the SAML identity provider is not configured to send the attribute, or the identity provider directory does not have an email address value for your user -This error appears when the SAML response does not contain the user's email address in an **email** or **mail** attribute as shown in the following example: +This error appears when the SAML response does not contain the user's email address in an **email** or **mail** attribute. +Ensure the SAML identity provider is configured to send a [supported mail attribute](../../../integration/saml.md). + +Examples: ```xml <Attribute Name="email"> - <AttributeValue>user@domain.com‹/AttributeValue> + <AttributeValue>user@example.com‹/AttributeValue> </Attribute> ``` -Attribute names starting with phrases such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/` like in the following example are not supported. Remove this type of attribute name from the SAML response on the IDP side. +Attribute names starting with phrases such as `http://schemas.xmlsoap.org/ws/2005/05/identity/claims` and `http://schemas.microsoft.com/ws/2008/06/identity/claims/` are supported by default beginning in GitLab 16.7. ```xml -<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/email"> - <AttributeValue>user@domain.com‹/AttributeValue> +<Attribute Name="http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress"> + <AttributeValue>user@example.com‹/AttributeValue> </Attribute> ``` diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md index b31c2eed9df..3dcb2d93096 100644 --- a/doc/user/group/saml_sso/troubleshooting_scim.md +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting SCIM **(FREE ALL)** @@ -18,20 +18,17 @@ When the user is added back to the SCIM app, GitLab does not create a new user b From August 11, 2023, the `skip_saml_identity_destroy_during_scim_deprovision` feature flag is enabled. For a user de-provisioned by SCIM from that date, their SAML identity is not removed. - When that user is added back to the SCIM app: - Their SCIM identity `active` attribute is set to `true`. - They can sign in using SSO. For users de-provisioned by SCIM before that date, their SAML identity is destroyed. +To solve this problem, the user must [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account). -To solve this problem: - -1. Have the user sign in directly to GitLab. -1. [Manually link](scim_setup.md#link-scim-and-saml-identities) their account. +### Self-managed GitLab -Alternatively, self-managed administrators can [add a user identity](../../../administration/admin_area.md#user-identities). +For a self-managed GitLab instance, administrators of that instance can instead [add the user identity themselves](../../../administration/admin_area.md#user-identities). This might save time if administrators need to re-add multiple identities. ## User cannot sign in @@ -130,6 +127,47 @@ For example, use these values as a definitive source on why an account was provi details. This information can help where an account was SCIM provisioned with details that do not match the SCIM app configuration. +## Member's email address is not linked error in SCIM log + +When you attempt to provision a SCIM user on GitLab.com, GitLab checks to see if +a user with that email address already exists. You might see the following error +when the: + +- User exists, but does not have a SAML identity linked. +- User exists, has a SAML identity, **and** has a SCIM identity that is set to `active: false`. + +```plaintext +The member's email address is not linked to a SAML account or has an inactive +SCIM identity. +``` + +This error message is returned with the status `412`. + +This might prevent the affected end user from accessing their account correctly. + +The first workaround is: + +1. Have the end user [link SAML to their existing GitLab.com account](index.md#link-saml-to-your-existing-gitlabcom-account). +1. After the user has done this, initiate a SCIM sync from your identity provider. +If the SCIM sync completes without the same error, GitLab has +successfully linked the SCIM identity to the existing user account, and the user +should now be able to sign in using SAML SSO. + +If the error persists, the user most likely already exists, has both a SAML and +SCIM identity, and a SCIM identity that is set to `active: false`. To resolve +this: + +1. Optional. If you did not save your SCIM token when you first configured SCIM, [generate a new token](scim_setup.md#configure-gitlab). If you generate a new SCIM token, you **must** update the token in your identity provider's SCIM configuration, or SCIM will stop working. +1. Locate your SCIM token. +1. Use the API to [get a single SCIM provisioned user](/ee/development/internal_api/index.md#get-a-single-scim-provisioned-user). +1. Check the returned information to make sure that: + - The user's identifier (`id`) and email match what your identity provider is sending. + - `active` is set to `false`. + If any of this information does not match, [contact GitLab Support](https://support.gitlab.com/). +1. Use the API to [update the SCIM provisioned user's `active` value to `true`](/ee/development/internal_api/index.md#update-a-single-scim-provisioned-user). +1. If the update returns a status code `204`, have the user attempt to sign in +using SAML SSO. + ## Azure Active Directory The following troubleshooting information is specifically for SCIM provisioned through Azure Active Directory. diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index cd3efcc6562..5b3f962061e 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Group access tokens **(FREE)** @@ -59,6 +58,7 @@ To create a group access token: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Access Tokens**. +1. Select **Add new token**. 1. Enter a name. The token name is visible to any user with permissions to view the group. 1. Enter an expiry date for the token: - The token expires on that date at midnight UTC. @@ -121,7 +121,7 @@ To revoke a group access token: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > Access Tokens**. -1. Next to the group access token to revoke, select **Revoke**. +1. Next to the group access token to revoke, select **Revoke** (**{remove}**). ## Revoke a group access token using Rails console @@ -143,17 +143,17 @@ token.revoke! The scope determines the actions you can perform when you authenticate with a group access token. -| Scope | Description | -|:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `api` | Grants complete read and write access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_api` | Grants read access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_registry` | Grants read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if any project within a group is private and authorization is required. | -| `write_registry` | Grants write access (push) to the [Container Registry](../../packages/container_registry/index.md). | -| `read_repository` | Grants read access (pull) to all repositories within a group. | -| `write_repository` | Grants read and write access (pull and push) to all repositories within a group. | -| `create_runner` | Grants permission to create runners in a group. | -| `ai_features` | Grants permission to perform API actions for GitLab Duo. | -| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in a group. | +| Scope | Description | +|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped group and related project API, including the [container registry](../../packages/container_registry/index.md), the [dependency proxy](../../packages/dependency_proxy/index.md), and the [package registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped group and related project API, including the [package registry](../../packages/package_registry/index.md). | +| `read_registry` | Grants read access (pull) to the [container registry](../../packages/container_registry/index.md) images if any project within a group is private and authorization is required. | +| `write_registry` | Grants write access (push) to the [container registry](../../packages/container_registry/index.md). | +| `read_repository` | Grants read access (pull) to all repositories within a group. | +| `write_repository` | Grants read and write access (pull and push) to all repositories within a group. | +| `create_runner` | Grants permission to create runners in a group. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in a group. | ## Enable or disable group access token creation @@ -163,6 +163,7 @@ To enable or disable group access token creation for all subgroups in a top-leve 1. Select **Settings > General**. 1. Expand **Permissions and group features**. 1. Under **Permissions**, turn on or off **Users can create project access tokens and group access tokens in this group**. +1. Select **Save changes**. Even when creation is disabled, you can still use and revoke existing group access tokens. diff --git a/doc/user/group/ssh_certificates.md b/doc/user/group/ssh_certificates.md new file mode 100644 index 00000000000..25c5f4b1be8 --- /dev/null +++ b/doc/user/group/ssh_certificates.md @@ -0,0 +1,83 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Manage group's SSH certificates **(PREMIUM SAAS)** + +Manage Git access to the projects by sharing public Certified Authority (`CA`) files in your organization's top-level group. + +Git access control options on GitLab SaaS (SSH, HTTPS) rely on credentials (such as access tokens and SSH keys) +setup in the user profile and are out of control of the organization. +To temporarily grant Git access to your projects, you can use SSH certificates. + +## Add a CA certificate to a top-level group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.4 [with a flag](../feature_flags.md) named `ssh_certificates_rest_endpoints`. Disabled by default. + +FLAG: +On GitLab.com, this feature is not available. +Prerequisites: + +- You must have the Owner role for the group. +- The group must be a top-level group, not a subgroup. + +To add a CA certificate to a group: + +1. Generate an SSH key pair to be used as a Certified Authority file: + + ```plaintext + ssh-keygen -f CA + ``` + +1. Add the public key to the top-level group using [Group SSH certificates API](../../api/group_ssh_certificates.md#create-ssh-certificate) + to grant access to the projects of the group and its subgroups. + +## Issue CA certificates for users + +Prerequisites: + +- You must have the Owner role for the group. +- The user certificates can only be used to access the projects within the top-level group and its subgroups. +- A user's username or primary email (`user` or `user@example.com`) must be specified to associate a + GitLab user with the user certificate. +- The user must be an [Enterprise User](../enterprise_user/index.md). + +To issue user certificates, use the private key from the pair you [created earlier](#add-a-ca-certificate-to-a-top-level-group): + +```shell +ssh-keygen -s CA -I user@example.com -V +1d user-key.pub +``` + +The (`user-key.pub`) key is the public key from an SSH key pair that is used by a user for SSH authentication. +The SSH key pair is either generated by a user or provisioned by the group owner infrastructure along with the SSH certificate. + +The expiration date (`+1d`) identifies how long the SSH certificate can be used to access the group projects. + +The user certificates can only be used to access the projects within the top-level group. + +## Enforce SSH certificates + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/421915) in GitLab 16.7 [with a flag](../feature_flags.md) named `enforce_ssh_certificates_via_settings`. Disabled by default. + +FLAG: +On GitLab.com, this feature is not available. + +You can enforce usage of SSH certificates and forbid users from authenticating using SSH +keys and access tokens. + +When SSH certificates are enforced, only individual user accounts are affected. +It does not apply to service accounts, deploy keys, and other types of internal accounts. + +Prerequisites: + +- You must have the Owner role for the group. + +To enforce using SSH certificates: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Select the **Enforce SSH Certificates** checkbox. +1. Select **Save changes**. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index e9064ff72a6..a63d4a98fa2 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Subgroups **(FREE ALL)** @@ -49,7 +49,7 @@ graph TD ## View subgroups of a group -Prerequisite: +Prerequisites: - To view private nested subgroups, you must be a direct or inherited member of the private subgroup. @@ -58,23 +58,25 @@ To view the subgroups of a group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select the **Subgroups and projects** tab. -1. To view a nested subgroup, expand a subgroup in the hierarchy list. +1. Select the subgroup you want to view. + To view nested subgroups, expand (**{chevron-down}**) a subgroup. ### Private subgroups in public parent groups -In the hierarchy list, public groups with a private subgroup have an expand option (**{chevron-down}**) -for all users that indicate there is a subgroup. When users who are not direct or inherited members of -the private subgroup select expand (**{chevron-down}**), the nested subgroup does not display. +In the hierarchy list, public groups with private subgroups have an expand option (**{chevron-down}**), +which indicates the group has nested subgroups. The expand option (**{chevron-down}**) is visible +to all users, but the private group is displayed only to users who are direct or inherited members +of the private subgroup. -If you prefer to keep information about the presence of nested subgroups private, we advise that you -add private subgroups only to private parent groups. +If you prefer to keep information about the presence of nested subgroups private, +you should add private subgroups only to private parent groups. ## Create a subgroup Prerequisites: - You must have either: - - At least the Maintainer role for a group to create subgroups for it. + - At least the Maintainer role for a group. - The [role determined by a setting](#change-who-can-create-subgroups). These users can create subgroups even if group creation is [disabled by an Administrator](../../../administration/admin_area.md#prevent-a-user-from-creating-top-level-groups) in the user's settings. @@ -84,15 +86,14 @@ You cannot host a GitLab Pages subgroup website with a top-level domain name. Fo To create a subgroup: -1. On the left sidebar, select **Search or go to** and find a parent group for the subgroup. +1. On the left sidebar, select **Search or go to** and find the group you want to create the subgroup in. 1. On the parent group's overview page, in the upper-right corner, select **New subgroup**. -1. Select **Create group**. 1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. -1. Select **Create group**. +1. Select **Create subgroup**. ### Change who can create subgroups -Prerequisite: +Prerequisites: - You must have at least the Maintainer role on the group, depending on the group's setting. @@ -102,25 +103,21 @@ To change who can create subgroups on a group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. - 1. Select a role from **Roles allowed to create subgroups**. + 1. From **Roles allowed to create subgroups**, select an option. 1. Select **Save changes**. - As an administrator: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. - 1. On the left sidebar, select **Overview > Groups**. - 1. In the group's row select **Edit**. - 1. Select a role from **Allowed to create subgroups**. + 1. On the left sidebar, at the bottom, select **Admin Area**. + 1. On the left sidebar, select **Overview > Groups** and find your group. + 1. In the group's row, select **Edit**. + 1. From the **Allowed to create subgroups** dropdown list, select an option. 1. Select **Save changes**. For more information, view the [permissions table](../../permissions.md#group-members-permissions). ## Subgroup membership -NOTE: -There is a bug that causes some pages in the parent group to be accessible by subgroup members. For more details, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340421). - -When you add a member to a group, that member is also added to all subgroups. The user's permissions are inherited from -the group's parent. +When you add a member to a group, that member is also added to all subgroups of that group. +The member's permissions are inherited from the group's parent. Subgroup members can be: @@ -163,6 +160,7 @@ To see if a member has inherited the permissions from a parent group: 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Manage > Members**. + The member's inheritance is displayed in the **Source** column. Members list for an example subgroup _Four_: @@ -189,22 +187,23 @@ Members can be [filtered by inherited or direct membership](../index.md#filter-a ### Override ancestor group membership -Users with the Owner role on a subgroup can add members to it. +Users with the Owner role in a subgroup can add members to it. -You can't give a user a role on a subgroup that's lower than the roles they have on ancestor groups. To override a user's -role on an ancestor group, add the user to the subgroup again with a higher role. For example: +You can't give a user a role in a subgroup that is lower than the roles the user has in ancestor groups. +To override a user's role in an ancestor group, add the user to the subgroup again with a higher role. +For example: -- If User 1 is added to group _Two_ with the Developer role, they inherit that role in every subgroup of group _Two_. -- To give User 1 the Maintainer role on group _Four_ (under _One / Two / Three_), add them again to group _Four_ with +- If User 1 is added to group _Two_ with the Developer role, User 1 inherits that role in every subgroup of group _Two_. +- To give User 1 the Maintainer role in group _Four_ (under _One / Two / Three_), add User 1 again to group _Four_ with the Maintainer role. -- If User 1 is removed from group _Four_, their role falls back to their role on group _Two_. They have the Developer - role on group _Four_ again. +- If User 1 is removed from group _Four_, the user's role falls back to their role in group _Two_. User 1 has the Developer + role in group _Four_ again. ## Mention subgroups Mentioning subgroups ([`@<subgroup_name>`](../../discussions/index.md#mentions)) in issues, commits, and merge requests -notifies all direct members of that group. Inherited members of a subgroup are not notified by mentions. Mentioning works the same as for projects and groups, and you can choose the group -of people to be notified. +notifies all direct members of that group. Inherited members of a subgroup are not notified by mentions. +Mentioning works the same as for projects and groups, and you can choose the group of members to be notified. <!-- ## Troubleshooting diff --git a/doc/user/group/troubleshooting.md b/doc/user/group/troubleshooting.md index 08343f604f1..d7086e9271e 100644 --- a/doc/user/group/troubleshooting.md +++ b/doc/user/group/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting groups diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 2ed01a0ec05..0fdd572ed7c 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Value stream analytics **(FREE ALL)** @@ -208,9 +207,10 @@ You can change the name of a project environment in your GitLab CI/CD configurat > - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 > - Horizontal stage path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in 13.0 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in 13.12 > - Predefined date ranges dropdown list [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408656/) in GitLab 16.5 [with a flag](../../../administration/feature_flags.md) named `vsa_predefined_date_ranges`. Disabled by default. +> - Predefined date ranges dropdown list [enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/433149) in GitLab 16.7. FLAG: -On self-managed GitLab, by default the predefined date ranges dropdown list feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `vsa_predefined_date_ranges`. On GitLab.com, this feature is not available. The feature is not ready for production use. +On self-managed GitLab, by default the predefined date ranges dropdown list feature is available. To hide the feature per user, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `vsa_predefined_date_ranges`. On GitLab.com, this feature is available. Prerequisites: @@ -302,7 +302,7 @@ In GitLab 13.8 and earlier, deployment frequency metrics are calculated based on ## View lifecycle and DORA metrics -Prerequisite: +Prerequisites: - To view deployment metrics, you must have a [production environment configured](#how-value-stream-analytics-identifies-the-production-environment). diff --git a/doc/user/img/enable_AI_ML_features.png b/doc/user/img/enable_AI_ML_features.png Binary files differdeleted file mode 100644 index 97d06c877e4..00000000000 --- a/doc/user/img/enable_AI_ML_features.png +++ /dev/null diff --git a/doc/user/img/objective_two_column_view_v16_2.png b/doc/user/img/objective_two_column_view_v16_2.png Binary files differdeleted file mode 100644 index d3f4f733e7e..00000000000 --- a/doc/user/img/objective_two_column_view_v16_2.png +++ /dev/null diff --git a/doc/user/img/objective_two_column_view_v16_7.png b/doc/user/img/objective_two_column_view_v16_7.png Binary files differnew file mode 100644 index 00000000000..70001108203 --- /dev/null +++ b/doc/user/img/objective_two_column_view_v16_7.png diff --git a/doc/user/img/snippet_sample_v16_6.png b/doc/user/img/snippet_sample_v16_6.png Binary files differindex 035947a2b82..d2dd08be88d 100644 --- a/doc/user/img/snippet_sample_v16_6.png +++ b/doc/user/img/snippet_sample_v16_6.png diff --git a/doc/user/img/task_two_column_view_v16_2.png b/doc/user/img/task_two_column_view_v16_2.png Binary files differdeleted file mode 100644 index 8ca87f55f8a..00000000000 --- a/doc/user/img/task_two_column_view_v16_2.png +++ /dev/null diff --git a/doc/user/img/task_two_column_view_v16_7.png b/doc/user/img/task_two_column_view_v16_7.png Binary files differnew file mode 100644 index 00000000000..b3cd205c60e --- /dev/null +++ b/doc/user/img/task_two_column_view_v16_7.png diff --git a/doc/user/index.md b/doc/user/index.md index 490a946a077..80f480d9e26 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitLab **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 961914aac9c..4a8ec3d85f7 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect a cluster to GitLab **(FREE ALL)** @@ -44,9 +44,8 @@ your cluster's level. **Instance-level clusters:** -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Kubernetes**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Kubernetes**. ## Security implications for clusters connected with certificates diff --git a/doc/user/infrastructure/clusters/connect/new_aks_cluster.md b/doc/user/infrastructure/clusters/connect/new_aks_cluster.md index 24933875d48..0c5f67069d5 100644 --- a/doc/user/infrastructure/clusters/connect/new_aks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_aks_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create an Azure AKS cluster @@ -63,9 +63,9 @@ Use CI/CD environment variables to configure your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Variables**. -1. Set the variable `AZURE_CLIENT_ID` to your Azure client ID. -1. Set the variable `AZURE_CLIENT_SECRET` to your Azure client secret. -1. Set the variable `AZURE_TENANT_ID` to your service principal. +1. Set the variable `ARM_CLIENT_ID` to your Azure client ID. +1. Set the variable `ARM_CLIENT_SECRET` to your Azure client secret. +1. Set the variable `ARM_TENANT_ID` to your service principal. 1. Set the variable `TF_VAR_agent_token` to the agent token displayed in the previous task. 1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task. diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index de35b21c8b6..37310040f28 100644 --- a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a Civo Kubernetes cluster diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 4ec28a7c3c6..c0499339812 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create an Amazon EKS cluster diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 5412ced3e6d..3b20125ff03 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a Google GKE cluster @@ -64,7 +64,7 @@ To create a GitLab agent for Kubernetes: 1. On the left sidebar, select **Operate > Kubernetes clusters**. 1. Select **Connect a cluster (agent)**. -1. From the **Select an agent** dropdown list, select `gke-agent` and select **Register an agent**. +1. From the **Select an agent or enter a name to create new** dropdown list, choose your agent's name and select **Register**. 1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. 1. GitLab provides an address for the agent server (KAS), which you will also need later. diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index cd81f6a1f86..bd074d42efb 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tracking cluster resources managed by GitLab (deprecated) **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index cace9c66fcf..79f350b1084 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Kubernetes clusters **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index 2408e16160b..22a77ac0b5a 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install cert-manager with a cluster management project **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md index ee9b2f848fe..c6bad5a9cb4 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/ingress.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install Ingress with a cluster management project **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index cbc23402915..cd8a261544b 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -1,7 +1,7 @@ --- stage: Verify group: Runner -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install GitLab Runner with a cluster management project **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md index ac61c0c11b4..c58db7cd9b4 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/vault.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install Vault with a cluster management project **(FREE ALL)** diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index 1e1372bb035..530376c1923 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate to the GitLab agent for Kubernetes **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md index 2161c2ba191..e86f2c71d3b 100644 --- a/doc/user/infrastructure/iac/gitlab_terraform_helpers.md +++ b/doc/user/infrastructure/iac/gitlab_terraform_helpers.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Terraform helpers **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 65ec84652ef..d76f5dd736a 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure as Code with Terraform and GitLab **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index 8fe639bb453..beef4c4d2aa 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform integration in merge requests **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 876300a7794..e8b8d840453 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab-managed Terraform state **(FREE ALL)** diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index 404e48d61bf..3036a297b0e 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform template recipes **(FREE ALL)** @@ -177,7 +177,7 @@ To define a custom container image: ``` 1. In a new job, define a `prepare` stage that builds the image whenever the `Dockerfile` changes. - - The built image is pushed to the [GitLab Container Registry](../../packages/container_registry). A tag is applied to indicate whether the image was built from a merge request or from the default branch. + - The built image is pushed to the [GitLab container registry](../../packages/container_registry). A tag is applied to indicate whether the image was built from a merge request or from the default branch. 1. Use your image in your Terraform jobs, such as `build` and `deploy`. - You can combine your image with specialized `before_script` configurations to perform setup commands, like to generate inputs for Terraform. diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index d770c0111d0..5b0420d476e 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting the Terraform integration with GitLab diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 54f062884ee..04d6caff0ba 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure management **(FREE ALL)** diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 5787051a2c2..dfd38f7daf1 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance-level Kubernetes clusters (certificate-based) (deprecated) **(FREE SELF)** @@ -21,8 +21,7 @@ projects. To view the instance level Kubernetes clusters: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Kubernetes**. ## Cluster precedence diff --git a/doc/user/markdown.md b/doc/user/markdown.md index a06e26c3e82..01bd7ce0ba6 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Flavored Markdown (GLFM) **(FREE ALL)** @@ -78,6 +78,29 @@ Features [extended from standard Markdown](#features-extended-from-standard-mark | [line breaks](#line-breaks) | [more line break control](#newlines) | | [links](#links) | [automatically linking URLs](#url-auto-linking) | +## Markdown and accessibility + +When you use GitLab Flavored Markdown, you are creating digital content. +This content should be as accessible as possible to your audience. +The following list is not exhaustive, but it provides guidance for some of the GLFM styles to pay +particular attention to: + +### Headings + +Use heading formatting to create a logical heading structure. +The structure of headings on a page should make sense, like a good table of contents. +Ensure that there is only one `h1` element on a page, that heading levels are not skipped, and that they are nested correctly. + +### Tables + +To keep tables accessible and scannable, tables should not have any empty cells. +If there is no otherwise meaningful value for a cell, consider entering **N/A** for "not applicable" or **None**. + +### Images and videos + +Describe the image or video in the `[alt text]`. Make the description accurate, succinct, and unique. +Don't use `image of` or `video of` in the description. For more information, see [WebAim Alternative Text](https://webaim.org/techniques/alttext/). + ## Features not found in standard Markdown The following features are not found in standard Markdown. @@ -459,10 +482,21 @@ To create a task list, follow the format of an ordered or unordered list: ### Table of contents +<!-- +The following paragraphs use HTML to work around a Markdown bug. +Do not change it back to a Markdown backticks. +For more information, see https://gitlab.com/gitlab-org/gitlab/-/issues/359077. +--> +<!-- vale gitlab.Uppercase = NO --> A table of contents is an unordered list that links to subheadings in the document. You can add a table of contents to issues and merge requests, but you can't add one -to notes or comments. Add either the `[[_TOC_]]` or `[TOC]` tag on its own line +to notes or comments. Add either the `[[_TOC_]]` or <code>[TOC]</code> tag on its own line to the **Description** field of any of the supported content types: +<!-- vale gitlab.Uppercase = YES --> + +NOTE: +A table of contents renders also when you use <code>`[TOC]`</code>, regardless of being on its own line or not. +This behavior is unintended. For more information, see [issue 359077](https://gitlab.com/gitlab-org/gitlab/-/issues/359077). - Markdown files. - Wiki pages. diff --git a/doc/user/namespace/index.md b/doc/user/namespace/index.md index 00eb63da3ff..f4acde64dce 100644 --- a/doc/user/namespace/index.md +++ b/doc/user/namespace/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Namespaces diff --git a/doc/user/okrs.md b/doc/user/okrs.md index ca5882da22a..14e887fe297 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -54,14 +54,10 @@ To learn how to create better OKRs and how we use them at GitLab, see the ## Create an objective -Prerequisites: - -- You must have at least the Guest role for the project. - To create an objective: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Plan > Issues**. +1. Select **Plan > Issues**. 1. In the upper-right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. 1. Select **New objective** again. 1. Enter the objective title. @@ -71,28 +67,20 @@ To create a key result, [add it as a child](#add-a-child-key-result) to an exist ## View an objective -Prerequisites: - -- You must have at least the Guest role for the project. - To view an objective: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Plan > Issues**. +1. Select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = objective`. 1. Select the title of an objective from the list. ## View a key result -Prerequisites: - -- You must have at least the Guest role for the project. - To view a key result: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Plan > Issues**. +1. Select **Plan > Issues**. 1. [Filter the list of issues](project/issues/managing_issues.md#filter-the-list-of-issues) for `Type = key_result`. 1. Select the title of a key result from the list. @@ -126,12 +114,12 @@ Prerequisites: - You must have at least the Reporter role for the project. -You can view all the system notes related to the task. By default they are sorted by **Oldest first**. +You can view all the [system notes](project/system_notes.md) related to the OKR. By default they are sorted by **Oldest first**. You can always change the sorting order to **Newest first**, which is remembered across sessions. ## Comments and threads -You can add [comments](discussions/index.md) and reply to threads in tasks. +You can add [comments](discussions/index.md) and reply to threads in OKRs. ## Assign users @@ -403,7 +391,7 @@ To turn off a check-in reminder, enter: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 16.6. -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the project. - The parent objective and child OKR must belong to the same project. @@ -431,6 +419,15 @@ leaking out. By default, OKRs are public. You can make an OKR confidential when you create or edit it. +#### In a new OKR + +When you create a new objective, a checkbox right below the text area is available to mark the +OKR as confidential. + +Select that checkbox and then select **Create objective** or **Create key result** to create the OKR. + +#### In an existing OKR + Prerequisites: - You must have at least the Reporter role for the project. @@ -443,20 +440,11 @@ Prerequisites: - To add child objectives or key results to a confidential objective, you must first make them confidential. -#### In a new OKR - -When you create a new objective, a checkbox right below the text area is available to mark the -OKR as confidential. - -Check that box and select **Create objective** or **Create key result** to create the OKR. - -#### In an existing OKR - To change the confidentiality of an existing OKR: 1. [Open the objective](#view-an-objective) or [key result](#view-a-key-result). 1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**). -1. Select **Turn on confidentiality**. +1. Select **Turn on confidentiality** or **Turn off confidentiality**. ### Who can see confidential OKRs @@ -504,16 +492,16 @@ When enabled, OKRs use a two-column layout, similar to issues. The description and threads are on the left, and attributes, such as labels or assignees, on the right. - + ## Linked items in OKRs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Enabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `linked_work_items`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `linked_work_items`. +On GitLab.com, this feature is available. Linked items are a bi-directional relationship and appear in a block below the Child objectives and key results. You can link an objective, key result, or a task in the same project with each other. @@ -522,18 +510,18 @@ The relationship only shows up in the UI if the user can see both items. ### Add a linked item -Prerequisite: +Prerequisites: - You must have at least the Guest role for the project. To link an item to an objective or key result: 1. In the **Linked items** section of an objective or key result, - select the **Add** button. + select **Add**. 1. Select the relationship between the two items. Either: - - **relates to** - - **blocks** - - **is blocked by** + - **Relates to** + - **Blocks** + - **Is blocked by** 1. Enter the search text of the item. 1. When you have added all the items to be linked, select **Add** below the search box. @@ -544,7 +532,7 @@ them categorized so their relationships can be better understood visually. ### Remove a linked item -Prerequisite: +Prerequisites: - You must have at least the Guest role for the project. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 3364d927a9b..3b53195ff2b 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Operations Dashboard **(PREMIUM ALL)** diff --git a/doc/user/organization/index.md b/doc/user/organization/index.md index 5a08307cc11..c4fff4178f1 100644 --- a/doc/user/organization/index.md +++ b/doc/user/organization/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Organization @@ -30,20 +30,9 @@ everything you do as a GitLab administrator, including: - Defining and applying settings to all of your groups, subgroups, and projects. - Aggregating data from all your groups, subgroups, and projects. -Our goal is to reach feature parity between SaaS and self-managed installations, with all -[Admin Area settings](../../administration/settings/index.md) moving to either: - -- Groups. Available in the Organization, and subgroups. -- Hardware Controls. For functionality that does not apply to groups, Hardware Controls are only - applicable to self-managed installations. There is one Hardware Controls section per installation. - For more information about the state of organization development, see [epic 9265](https://gitlab.com/groups/gitlab-org/-/epics/9265). -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a video introduction to the new hierarchy concept for groups and projects for epics, see -[Consolidating groups and projects update (August 2021)](https://www.youtube.com/watch?v=fE74lsG_8yM). - ## View organizations To view the organizations you have access to: @@ -53,17 +42,25 @@ To view the organizations you have access to: ## Create an organization 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New organization**. -1. In the **Organization name** field, enter a name for the organization. -1. In the **Organization URL** field, enter a path for the organization. +1. In the **Organization name** text box, enter a name for the organization. +1. In the **Organization URL** text box, enter a path for the organization. 1. Select **Create organization**. ## Edit an organization's name 1. On the left sidebar, select **Organizations** (**{organization}**) and find the organization you want to edit. 1. Select **Settings > General**. -1. Update the **Organization name** field. +1. In the **Organization name** text box, edit the name. 1. Select **Save changes**. +## Change an organization's URL + +1. On the left sidebar, select **Organizations** (**{organization}**) and find organization whose URL you want to change. +1. Select **Settings > General**. +1. Expand the **Advanced** section. +1. In the **Organization URL** text box, edit the URL. +1. Select **Change organization URL**. + ## Manage groups and projects 1. On the left sidebar, select **Organizations** (**{organization}**) and find the organization you want to manage. @@ -78,3 +75,4 @@ To view the organizations you have access to: ## Related topics - [Organization developer documentation](../../development/organization/index.md) +- [Organization blueprint](../../architecture/blueprints/organization/index.md) diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 6eac299e71f..db3d31d3c18 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Composer packages in the Package Registry **(FREE ALL BETA)** +# Composer packages in the package registry **(FREE ALL BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab 13.2. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -16,7 +16,7 @@ The Composer package registry for GitLab is under development and isn't ready fo limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6817) details the remaining work and timelines to make it production ready. -Publish [Composer](https://getcomposer.org/) packages in your project's Package Registry. +Publish [Composer](https://getcomposer.org/) packages in your project's package registry. Then, install the packages whenever you need to use them as a dependency. For documentation of the specific API endpoints that the Composer @@ -29,7 +29,7 @@ Learn how to [build a Composer package](../workflows/build_packages.md#composer) ## Publish a Composer package by using the API -Publish a Composer package to the Package Registry, +Publish a Composer package to the package registry, so that anyone who can access the project can use the package as a dependency. Prerequisites: @@ -81,7 +81,7 @@ selecting the **Composer** tab. ## Publish a Composer package by using CI/CD -You can publish a Composer package to the Package Registry as part of your CI/CD process. +You can publish a Composer package to the package registry as part of your CI/CD process. 1. Specify a `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file: @@ -123,11 +123,11 @@ When you publish: > Authorization to [download a package archive](../../../api/packages/composer.md#download-a-package-archive) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331601) in GitLab 14.10. -Install a package from the Package Registry so you can use it as a dependency. +Install a package from the package registry so you can use it as a dependency. Prerequisites: -- A package in the Package Registry. +- A package in the package registry. - The group ID, which is on the group's home page. - One of the following token types: - A [personal access token](../../../user/profile/personal_access_tokens.md) @@ -138,9 +138,9 @@ Prerequisites: To install a package: -1. Add the Package Registry URL to your project's `composer.json` file, along with the package name and version you want to install: +1. Add the package registry URL to your project's `composer.json` file, along with the package name and version you want to install: - - Connect to the Package Registry for your group: + - Connect to the package registry for your group: ```shell composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 74152515198..56ea4fe74b4 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Conan packages in the Package Registry **(FREE ALL EXPERIMENT)** +# Conan packages in the package registry **(FREE ALL EXPERIMENT)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab 12.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. @@ -17,25 +17,25 @@ work and timelines to make it production ready. NOTE: The Conan registry is not FIPS compliant and is disabled when [FIPS mode](../../../development/fips_compliance.md) is enabled. -Publish Conan packages in your project's Package Registry. Then install the +Publish Conan packages in your project's package registry. Then install the packages whenever you need to use them as a dependency. -To publish Conan packages to the Package Registry, add the Package Registry as a +To publish Conan packages to the package registry, add the package registry as a remote and authenticate with it. Then you can run `conan` commands and publish your package to the -Package Registry. +package registry. For documentation of the specific API endpoints that the Conan package manager client uses, see the [Conan API documentation](../../../api/packages/conan.md). Learn how to [build a Conan package](../workflows/build_packages.md#conan). -## Add the Package Registry as a Conan remote +## Add the package registry as a Conan remote -To run `conan` commands, you must add the Package Registry as a Conan remote for +To run `conan` commands, you must add the package registry as a Conan remote for your project or instance. Then you can publish packages to -and install packages from the Package Registry. +and install packages from the package registry. ### Add a remote for your project @@ -105,13 +105,13 @@ Example recipe names: [Project remotes](#add-a-remote-for-your-project) have a more flexible naming convention. -## Authenticate to the Package Registry +## Authenticate to the package registry GitLab requires authentication to upload packages, and to install packages from private and internal projects. (You can, however, install packages from public projects without authentication.) -To authenticate to the Package Registry, you need one of the following: +To authenticate to the package registry, you need one of the following: - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. @@ -151,8 +151,8 @@ occasionally need to re-enter your personal access token. ### Set a default remote for your project (optional) -If you want to interact with the GitLab Package Registry without having to -specify a remote, you can tell Conan to always use the Package Registry for your +If you want to interact with the GitLab package registry without having to +specify a remote, you can tell Conan to always use the package registry for your packages. In a terminal, run this command: @@ -174,14 +174,14 @@ remote in your commands: ## Publish a Conan package -Publish a Conan package to the Package Registry, so that anyone who can access +Publish a Conan package to the package registry, so that anyone who can access the project can use the package as a dependency. Prerequisites: - The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). - [Authentication](#authenticate-to-the-package-registry) with the - Package Registry must be configured. + package registry must be configured. - A local [Conan package](https://docs.conan.io/en/latest/creating_packages/getting_started.html) must exist. - For an instance remote, the package must meet the [naming convention](#package-recipe-naming-convention-for-instance-remotes). @@ -229,7 +229,7 @@ only the most recently-published package is returned. ## Install a Conan package -Install a Conan package from the Package Registry so you can use it as a +Install a Conan package from the package registry so you can use it as a dependency. You can install a package from the scope of your instance or your project. If multiple packages have the same recipe, when you install a package, the most recently-published package is retrieved. @@ -242,7 +242,7 @@ Prerequisites: - The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). - For private and internal projects, you must configure [Authentication](#authenticate-to-the-package-registry) - with the Package Registry. + with the package registry. 1. In the project where you want to install the package as a dependency, open `conanfile.txt`. Or, in the root of your project, create a file called @@ -278,7 +278,7 @@ Delete `~/.conan/data` to clean up the packages stored in the cache. ## Remove a Conan package -There are two ways to remove a Conan package from the GitLab Package Registry. +There are two ways to remove a Conan package from the GitLab package registry. - From the command line, using the Conan client: @@ -291,14 +291,14 @@ There are two ways to remove a Conan package from the GitLab Package Registry. NOTE: This command removes all recipe and binary package files from the - Package Registry. + package registry. - From the GitLab user interface: Go to your project's **Deploy > Package Registry**. Remove the package by selecting **Remove repository** (**{remove}**). -## Search for Conan packages in the Package Registry +## Search for Conan packages in the package registry To search by full or partial package name, or by exact recipe, run the `conan search` command. @@ -327,7 +327,7 @@ packages in the target project, as long as you have permission to access it. NOTE: The limit of the search results is 500 packages, and the results are sorted by the most recently published packages. -## Fetch Conan package information from the Package Registry +## Fetch Conan package information from the package registry The `conan info` command returns information about a package: @@ -339,13 +339,13 @@ conan info Hello/0.1@mycompany/beta The GitLab Conan repository supports the following Conan CLI commands: -- `conan upload`: Upload your recipe and package files to the Package Registry. -- `conan install`: Install a Conan package from the Package Registry, which +- `conan upload`: Upload your recipe and package files to the package registry. +- `conan install`: Install a Conan package from the package registry, which includes using the `conanfile.txt` file. -- `conan search`: Search the Package Registry for public packages, and private +- `conan search`: Search the package registry for public packages, and private packages you have permission to view. -- `conan info`: View the information on a given package from the Package Registry. -- `conan remove`: Delete the package from the Package Registry. +- `conan info`: View the information on a given package from the package registry. +- `conan remove`: Delete the package from the package registry. ## Troubleshooting diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md index 2aab69877ff..ae19a891fc9 100644 --- a/doc/user/packages/container_registry/authenticate_with_container_registry.md +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -1,17 +1,12 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Authenticate with the Container Registry **(FREE ALL)** +# Authenticate with the container registry **(FREE ALL)** -<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> -WARNING: -In GitLab 16.0 and later, [external authorization](../../admin_area/settings/external_authorization.md) prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. -<!--- end_remove --> - -To authenticate with the Container Registry, you can use a: +To authenticate with the container registry, you can use a: - [Personal access token](../../profile/personal_access_tokens.md). - [Deploy token](../../project/deploy_tokens/index.md). @@ -31,11 +26,11 @@ To authenticate, run the `docker login` command. For example: ## Use GitLab CI/CD to authenticate -To use CI/CD to authenticate with the Container Registry, you can use: +To use CI/CD to authenticate with the container registry, you can use: - The `CI_REGISTRY_USER` CI/CD variable. - This variable has read-write access to the Container Registry and is valid for + This variable has read-write access to the container registry and is valid for one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. ```shell diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md index 93140e34493..680aab42544 100644 --- a/doc/user/packages/container_registry/build_and_push_images.md +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -1,18 +1,18 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Build and push container images to the Container Registry **(FREE ALL)** +# Build and push container images to the container registry **(FREE ALL)** -Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the Container Registry. +Before you can build and push container images, you must [authenticate](authenticate_with_container_registry.md) with the container registry. ## Use Docker commands -You can use Docker commands to build and push container images to your Container Registry: +You can use Docker commands to build and push container images to your container registry: -1. [Authenticate](authenticate_with_container_registry.md) with the Container Registry. +1. [Authenticate](authenticate_with_container_registry.md) with the container registry. 1. Run the Docker command to build or push. For example: - To build: @@ -29,7 +29,7 @@ You can use Docker commands to build and push container images to your Container ## Configure your `.gitlab-ci.yml` file -You can configure your `.gitlab-ci.yml` file to build and push container images to the Container Registry. +You can configure your `.gitlab-ci.yml` file to build and push container images to the container registry. - If multiple jobs require authentication, put the authentication command in the `before_script`. - Before building, use `docker build --pull` to fetch changes to base images. It takes slightly @@ -50,7 +50,7 @@ You can use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push containe Container Registry. You can use CI/CD to test, build, and deploy your project from the container image you created. -### Use a Docker-in-Docker container image from your Container Registry +### Use a Docker-in-Docker container image from your container registry You can use your own container images for Docker-in-Docker. @@ -108,7 +108,7 @@ and an error like the following is shown: error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker on 192.168.0.1:53: no such host ``` -## Container Registry examples with GitLab CI/CD +## Container registry examples with GitLab CI/CD If you're using Docker-in-Docker on your runners, your `.gitlab-ci.yml` file should look similar to this: diff --git a/doc/user/packages/container_registry/delete_container_registry_images.md b/doc/user/packages/container_registry/delete_container_registry_images.md index 0b91a9453a7..852c20a80f5 100644 --- a/doc/user/packages/container_registry/delete_container_registry_images.md +++ b/doc/user/packages/container_registry/delete_container_registry_images.md @@ -1,12 +1,12 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Delete container images from the Container Registry **(FREE ALL)** +# Delete container images from the container registry **(FREE ALL)** -You can delete container images from your Container Registry. +You can delete container images from your container registry. WARNING: Deleting container images is a destructive action and can't be undone. To restore @@ -18,9 +18,9 @@ Deleting a container image on self-managed instances doesn't free up storage spa as eligible for deletion. To actually delete unreferenced container images and recover storage space, administrators must run [garbage collection](../../../administration/packages/container_registry.md#container-registry-garbage-collection). -On GitLab.com, the latest version of the Container Registry includes an automatic online garbage +On GitLab.com, the latest version of the container registry includes an automatic online garbage collector. For more information, see [this blog post](https://about.gitlab.com/blog/2021/10/25/gitlab-com-container-registry-update/). -In this new version of the Container Registry, the following are automatically scheduled +In this new version of the container registry, the following are automatically scheduled for deletion in 24 hours if left unreferenced: - Layers that aren't referenced by any image manifest. @@ -117,4 +117,4 @@ the code example by changing the `REG_SHA256` and `REG_VERSION` variables define ## Use a cleanup policy You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and -images are regularly removed from the Container Registry. +images are regularly removed from the container registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 786fd0ca658..13bdd9ad4e5 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -1,25 +1,25 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Container Registry **(FREE ALL)** +# GitLab container registry **(FREE ALL)** > Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. -You can use the integrated Container Registry to store container images for each GitLab project +You can use the integrated container registry to store container images for each GitLab project -To enable the Container Registry for your GitLab instance, see the [administrator documentation](../../../administration/packages/container_registry.md). +To enable the container registry for your GitLab instance, see the [administrator documentation](../../../administration/packages/container_registry.md). NOTE: If you pull Docker container images from Docker Hub, you can use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) to avoid rate limits and speed up your pipelines. For more information about the Docker Registry, see <https://docs.docker.com/registry/introduction/>. -## View the Container Registry +## View the container registry -You can view the Container Registry for a project or group. +You can view the container registry for a project or group. 1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: @@ -29,14 +29,14 @@ You can view the Container Registry for a project or group. You can search, sort, filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) your container images. You can share a filtered view by copying the URL from your browser. -Only members of the project or group can access the Container Registry for a private project. +Only members of the project or group can access the container registry for a private project. Container images downloaded from a private registry may be [available to other users in a shared runner](https://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). -If a project is public, the Container Registry is also public. +If a project is public, the container registry is also public. -### View the tags of a specific container image in the Container Registry +### View the tags of a specific container image in the container registry -You can use the Container Registry **Tag Details** page to view a list of tags associated with a given container image: +You can use the container registry **Tag Details** page to view a list of tags associated with a given container image: 1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: @@ -50,9 +50,9 @@ and the manifest and configuration digests. You can search, sort (by tag name), filter, and [delete](delete_container_registry_images.md#use-the-gitlab-ui) tags on this page. You can share a filtered view by copying the URL from your browser. -## Use container images from the Container Registry +## Use container images from the container registry -To download and run a container image hosted in the Container Registry: +To download and run a container image hosted in the container registry: 1. On the left sidebar, select **Search or go to** and find your project or group. 1. For: @@ -101,19 +101,19 @@ registry.example.com/mynamespace/myproject/image:latest registry.example.com/mynamespace/myproject/my/image:rc1 ``` -## Move or rename Container Registry repositories +## Move or rename container registry repositories -Moving or renaming existing Container Registry repositories is not supported after you have pushed +Moving or renaming existing container registry repositories is not supported after you have pushed container images. The container images are stored in a path that matches the repository path. To move -or rename a repository with a Container Registry, you must delete all existing container images. +or rename a repository with a container registry, you must delete all existing container images. Community suggestions to work around this known issue are shared in [issue 18383](https://gitlab.com/gitlab-org/gitlab/-/issues/18383#possible-workaround). -## Disable the Container Registry for a project +## Disable the container registry for a project -The Container Registry is enabled by default. +The container registry is enabled by default. -You can, however, remove the Container Registry for a project: +You can, however, remove the container registry for a project: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. @@ -123,51 +123,55 @@ You can, however, remove the Container Registry for a project: The **Deploy > Container Registry** entry is removed from the project's sidebar. -## Change visibility of the Container Registry +## Change visibility of the container registry > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18792) in GitLab 14.2. -By default, the Container Registry is visible to everyone with access to the project. -You can, however, change the visibility of the Container Registry for a project. +By default, the container registry is visible to everyone with access to the project. +You can, however, change the visibility of the container registry for a project. For more information about the permissions that this setting grants to users, -see [Container Registry visibility permissions](#container-registry-visibility-permissions). +see [Container registry visibility permissions](#container-registry-visibility-permissions). 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. 1. Expand the section **Visibility, project features, permissions**. 1. Under **Container Registry**, select an option from the dropdown list: - - **Everyone With Access** (Default): The Container Registry is visible to everyone with access - to the project. If the project is public, the Container Registry is also public. If the project - is internal or private, the Container Registry is also internal or private. + - **Everyone With Access** (Default): The container registry is visible to everyone with access + to the project. If the project is public, the container registry is also public. If the project + is internal or private, the container registry is also internal or private. - - **Only Project Members**: The Container Registry is visible only to project members with + - **Only Project Members**: The container registry is visible only to project members with at least the Reporter role. This visibility is similar to the behavior of a private project with Container Registry visibility set to **Everyone With Access**. 1. Select **Save changes**. -## Container Registry visibility permissions +## Container registry visibility permissions -The ability to view the Container Registry and pull container images is controlled by the Container Registry's +The ability to view the container registry and pull container images is controlled by the container registry's visibility permissions. You can change the visibility through the [visibility setting on the UI](#change-visibility-of-the-container-registry) or the [API](../../../api/container_registry.md#change-the-visibility-of-the-container-registry). -[Other permissions](../../permissions.md) such as updating the Container Registry and pushing or deleting container images are not affected by -this setting. However, disabling the Container Registry disables all Container Registry operations. +[Other permissions](../../permissions.md) such as updating the container registry and pushing or deleting container images are not affected by +this setting. However, disabling the container registry disables all Container Registry operations. | | | Anonymous<br/>(Everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | |-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|--------------------------------------|-------|----------------------------------------| -| Public project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | Yes | Yes | Yes | -| Public project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Internal project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | Yes | Yes | -| Internal project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | -| Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | +| Public project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | Yes | Yes | Yes | +| Public project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes | +| Internal project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | No | Yes | Yes | +| Internal project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes | +| Private project with container registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View container registry <br/> and pull images | No | No | Yes | +| Private project with container registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View container registry <br/> and pull images | No | No | Yes | +| Any project with container registry `disabled` | All operations on container registry | No | No | No | ## Supported image types -The Container Registry supports [Docker V2](https://docs.docker.com/registry/spec/manifest-v2-2/) and [Open Container Initiative (OCI)](https://github.com/opencontainers/image-spec/blob/main/spec.md) image formats. +> OCI conformance [introduced](https://gitlab.com/groups/gitlab-org/-/epics/10345) in GitLab 16.6. + +The container registry supports the [Docker V2](https://docs.docker.com/registry/spec/manifest-v2-2/) +and [Open Container Initiative (OCI)](https://github.com/opencontainers/image-spec/blob/main/spec.md) +image formats. Additionally, the container registry [conforms to the OCI distribution specification](https://conformance.opencontainers.org/#gitlab-container-registry). OCI support means that you can host OCI-based image formats in the registry, such as [Helm 3+ chart packages](https://helm.sh/docs/topics/registries/). There is no distinction between image formats in the GitLab [API](../../../api/container_registry.md) and the UI. [Issue 38047](https://gitlab.com/gitlab-org/gitlab/-/issues/38047) addresses this distinction, starting with Helm. diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md index 9ac00445b95..c2a48d1e91a 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md +++ b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md @@ -1,14 +1,14 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Reduce Container Registry data transfers **(FREE ALL)** +# Reduce container registry data transfers **(FREE ALL)** -Depending on the frequency with which images or tags are downloaded from the Container Registry, +Depending on the frequency with which images or tags are downloaded from the container registry, data transfers can exceed the GitLab.com limit. This page offers several recommendations and tips for -reducing the amount of data you transfer with the Container Registry. +reducing the amount of data you transfer with the container registry. ## Check data transfer use diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index 8c4f25af2e1..614639c705f 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -1,10 +1,10 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Reduce Container Registry storage **(FREE ALL)** +# Reduce container registry storage **(FREE ALL)** Container registries can grow in size over time if you don't manage your registry usage. For example, if you add a large number of images or tags: @@ -15,16 +15,21 @@ if you add a large number of images or tags: You should delete unnecessary images and tags and set up a [cleanup policy](#cleanup-policy) to automatically manage your container registry usage. -## Check Container Registry storage use **(FREE SAAS)** +## View container registry usage **(FREE SAAS)** -The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. -Measuring usage is only possible on the new version of the GitLab Container Registry backed by a -metadata database, which is [available on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/5523) since GitLab 15.7. -For information on the planned availability for self-managed instances, see [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5523) in GitLab 15.7 + +To view the storage usage for the container registry: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > Usage Quotas**. + +You cannot view container registry usage for self-managed instances, but this is +proposed in [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). ## How container registry usage is calculated -Image layers stored in the Container Registry are deduplicated at the root namespace level. +Image layers stored in the container registry are deduplicated at the root namespace level. An image is only counted once if: @@ -75,7 +80,7 @@ the size value only changes when: > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2. > - [Required permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) changed from developer to maintainer in GitLab 15.0. -The cleanup policy is a scheduled job you can use to remove tags from the Container Registry. +The cleanup policy is a scheduled job you can use to remove tags from the container registry. For the project where it's defined, tags matching the regex pattern are removed. The underlying layers and images remain. @@ -106,7 +111,7 @@ GitLab.com that don't have a container image. ### How the cleanup policy works -The cleanup policy collects all tags in the Container Registry and excludes tags until the only +The cleanup policy collects all tags in the container registry and excludes tags until the only tags you want to delete remain. The cleanup policy searches for images based on the tag name. Support for full path matching is tracked in issue [281071](https://gitlab.com/gitlab-org/gitlab/-/issues/281071). @@ -121,11 +126,11 @@ The cleanup policy: 1. Orders the remaining tags by `created_date`. 1. Excludes the N tags based on the `keep_n` value (Number of tags to retain). 1. Excludes the tags more recent than the `older_than` value (Expiration interval). -1. Deletes the remaining tags in the list from the Container Registry. +1. Deletes the remaining tags in the list from the container registry. WARNING: On GitLab.com, the execution time for the cleanup policy is limited. Some tags may remain in -the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included. +the container registry after the policy runs. The next time the policy runs, the remaining tags are included. It may take multiple runs to delete all tags. WARNING: @@ -274,11 +279,10 @@ For self-managed instances, those settings can be updated in the [Rails console] ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) ``` -They are also available in the [administrator area](../../admin_area/index.md): +They are also available in the [administrator area](../../../administration/admin_area.md): -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > CI/CD** +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > CI/CD** 1. Expand **Container Registry**. ### Use the cleanup policy API @@ -331,9 +335,9 @@ the GitLab background jobs may get backed up or fail completely. For projects created before GitLab 12.8, you should enable container cleanup policies only if the number of tags being cleaned up is minimal. -## More Container Registry storage reduction options +## More container registry storage reduction options -Here are some other options you can use to reduce the Container Registry storage used by your project: +Here are some other options you can use to reduce the container registry storage used by your project: - Use the [GitLab UI](delete_container_registry_images.md#use-the-gitlab-ui) to delete individual image tags or the entire repository containing all the tags. @@ -371,7 +375,7 @@ There can be different reasons behind this: - If you are on GitLab 13.9 or later, you can [set limits for the cleanup policy](reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). This limits the cleanup execution in time, and avoids the expired token error. - - Extend the expiration delay of the Container Registry authentication tokens. This defaults to 5 + - Extend the expiration delay of the container registry authentication tokens. This defaults to 5 minutes. You can set a custom value by running `ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)` in the Rails console, where `<integer>` is the desired number of minutes. For reference, the expiration delay diff --git a/doc/user/packages/container_registry/troubleshoot_container_registry.md b/doc/user/packages/container_registry/troubleshoot_container_registry.md index 3fb2754eb9c..b923be94bfe 100644 --- a/doc/user/packages/container_registry/troubleshoot_container_registry.md +++ b/doc/user/packages/container_registry/troubleshoot_container_registry.md @@ -1,20 +1,20 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Troubleshooting the GitLab Container Registry +# Troubleshooting the GitLab container registry -You must sign in to GitLab with administrator rights to troubleshoot most issues with the GitLab Container Registry. +You must sign in to GitLab with administrator rights to troubleshoot most issues with the GitLab container registry. -You can find [additional troubleshooting information](../../../administration/packages/container_registry.md#troubleshooting) in the GitLab Container Registry administration documentation. +You can find [additional troubleshooting information](../../../administration/packages/container_registry.md#troubleshooting) in the GitLab container registry administration documentation. -## Migrating OCI container images to GitLab Container Registry +## Migrating OCI container images to GitLab container registry Migrating container images to the GitLab registry is not supported, but [epic](https://gitlab.com/groups/gitlab-org/-/epics/5210) proposes to change this behavior. -You can use third-party tools to migrate container images. For example, [skopeo](https://github.com/containers/skopeo), can [copy container images](https://github.com/containers/skopeo#copying-images) between various storage mechanisms. You can use skopeo to copy from container registries, container storage backends, local directories, and local OCI-layout directories to the GitLab Container Registry. +You can use third-party tools to migrate container images. For example, [skopeo](https://github.com/containers/skopeo), can [copy container images](https://github.com/containers/skopeo#copying-images) between various storage mechanisms. You can use skopeo to copy from container registries, container storage backends, local directories, and local OCI-layout directories to the GitLab container registry. ## Docker connection error @@ -25,19 +25,19 @@ project, or branch name. Special characters include: - A trailing hyphen or dash. To resolve this error, you can change the [group path](../../group/manage.md#change-a-groups-path), -the [project path](../../project/settings/index.md#rename-a-repository) or the branch name. +the [project path](../../project/working_with_projects.md#rename-a-repository) or the branch name. You may get a `404 Not Found` or `Unknown Manifest` error message if you use Docker Engine 17.11 or earlier. Current versions of Docker Engine use the [v2 API](https://docs.docker.com/registry/spec/manifest-v2-2/). -The images in your GitLab Container Registry must use the Docker v2 API. +The images in your GitLab container registry must use the Docker v2 API. For information on how to update version 1 images to version 2, see the [Docker documentation](https://docs.docker.com/registry/spec/deprecated-schema-v1). ## `Blob unknown to registry` error when pushing a manifest list When [pushing a Docker manifest list](https://docs.docker.com/engine/reference/commandline/manifest/#create-and-push-a-manifest-list) -to the GitLab Container Registry, you may receive the error +to the GitLab container registry, you may receive the error `manifest blob unknown: blob unknown to registry`. This error is likely caused by having multiple images with different architectures spread out over several repositories instead of the same repository. @@ -61,7 +61,7 @@ you may receive one of the following errors: - Project cannot be transferred because tags are present in its container registry. - Namespace cannot be moved because at least one project has tags in the container registry. -This error occurs when the project has images in the Container Registry. +This error occurs when the project has images in the container registry. You must delete or move these images before you change the path or transfer the project. @@ -122,7 +122,7 @@ unauthorized: authentication required ``` This error happens when your authentication token expires before the image push is complete. By default, tokens for -the Container Registry on self-managed GitLab instances expire every five minutes. On GitLab.com, the token expiration +the container registry on self-managed GitLab instances expire every five minutes. On GitLab.com, the token expiration time is set to 15 minutes. If you are using self-managed GitLab, an administrator can diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 45ebfb2ef73..86d85b5e0ca 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Debian packages in the Package Registry **(FREE SELF EXPERIMENT)** +# Debian packages in the package registry **(FREE SELF EXPERIMENT)** > - Debian API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42670) in GitLab 13.5. > - Debian group API [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66188) in GitLab 14.2. @@ -14,7 +14,7 @@ WARNING: The Debian package registry for GitLab is under development and isn't ready for production use. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6057) details the remaining work and timelines to make it production ready. Support for [Debian packages is an experiment](../package_registry/supported_package_managers.md), and has known security vulnerabilities. -Publish Debian packages in your project's Package Registry. Then install the +Publish Debian packages in your project's package registry. Then install the packages whenever you need to use them as a dependency. Project and Group packages are supported. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 02810bcb922..9037abde1cf 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Proxy **(FREE ALL)** @@ -86,9 +86,9 @@ docker login gitlab.example.com --username my_username --password my_password You can authenticate using: - Your GitLab username and password. -- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. +- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`, or to `api`. - A [group deploy token](../../../user/project/deploy_tokens/index.md) with the scope set to `read_registry` and `write_registry`. -- A [group access token](../../../user/group/settings/group_access_tokens.md) for the group, with the scope set to `read_registry` and `write_registry`. +- A [group access token](../../../user/group/settings/group_access_tokens.md) for the group, with the scope set to `read_registry` and `write_registry`, or to `api`. Users accessing the Dependency Proxy with a personal access token or username and password must have at least the Guest role for the group they pull images from. @@ -170,7 +170,7 @@ build: before_script: - docker login -u $CI_DEPENDENCY_PROXY_USER -p $CI_DEPENDENCY_PROXY_PASSWORD $CI_DEPENDENCY_PROXY_SERVER script: - - docker build -t test . + - docker build -t test . ``` You can also use [custom CI/CD variables](../../../ci/variables/index.md#for-a-project) to store and access your personal access token or deploy token. diff --git a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md index e24a3d3fa84..3b565f3a3ad 100644 --- a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md +++ b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce Dependency Proxy Storage **(FREE ALL)** diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 1416dcde14f..188b634af0a 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Generic Packages Repository **(FREE ALL)** @@ -9,11 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4209) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `generic_packages`. Enabled by default. > - [Feature flag `generic_packages`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80886) removed in GitLab 14.8. -Publish generic files, like release binaries, in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. +Publish generic files, like release binaries, in your project's package registry. Then, install the packages whenever you need to use them as a dependency. -## Authenticate to the Package Registry +## Authenticate to the package registry -To authenticate to the Package Registry, you need either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), +To authenticate to the package registry, you need either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), [CI/CD job token](../../../ci/jobs/ci_job_token.md), or [deploy token](../../project/deploy_tokens/index.md). In addition to the standard API authentication mechanisms, the generic package @@ -142,8 +142,8 @@ If multiple packages have the same name, version, and filename, then the most re Prerequisites: -- You need to [authenticate with the API](../../../api/rest/index.md#authentication). - - If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. +- You need to [authenticate with the API](../../../api/rest/index.md#authentication). + - If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. - Project access tokens require the `read_api` scope and at least the `Reporter` role. ```plaintext diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 6dffd7371b6..590a3d1e949 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Go proxy for GitLab **(FREE ALL EXPERIMENT)** @@ -53,7 +53,7 @@ Feature.disable(:go_proxy, Project.find(2)) ``` NOTE: -Even if it's enabled, GitLab doesn't display Go modules in the **Package Registry**. +Even if it's enabled, GitLab doesn't display Go modules in the **package registry**. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for details. diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index d45b6ea7026..85e1f1b5fd1 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Container Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Harbor Registry **(FREE ALL)** diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index b7888fe2d18..891dc59bb80 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Helm charts in the Package Registry **(FREE ALL BETA)** +# Helm charts in the package registry **(FREE ALL BETA)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18997) in GitLab 14.1. @@ -13,7 +13,7 @@ The Helm chart registry for GitLab is under development and isn't ready for prod limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6366) details the remaining work and timelines to make it production ready. -Publish Helm packages in your project's Package Registry. Then install the +Publish Helm packages in your project's package registry. Then install the packages whenever you need to use them as a dependency. For documentation of the specific API endpoints that Helm package manager @@ -127,7 +127,7 @@ See [Using Helm](https://helm.sh/docs/intro/using_helm/) for more information. ## Troubleshooting -### The chart is not visible in the Package Registry after uploading +### The chart is not visible in the package registry after uploading Check the [Sidekiq log](../../../administration/logs/index.md#sidekiqlog) for any related errors. If you see `Validation failed: Version is invalid`, it means that the diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 8173a0407f0..3abdbfd83b3 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -1,16 +1,16 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Packages and Registries **(FREE ALL)** -The GitLab [Package Registry](package_registry/index.md) acts as a private or public registry +The GitLab [package registry](package_registry/index.md) acts as a private or public registry for a variety of common package managers. You can publish and share packages, which can be easily consumed as a dependency in downstream projects. -## Container Registry +## Container registry The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index c8730c42022..8f702183adc 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -1,12 +1,12 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Maven packages in the Package Registry **(FREE ALL)** +# Maven packages in the package registry **(FREE ALL)** -Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. +Publish [Maven](https://maven.apache.org) artifacts in your project's package registry. Then, install the packages whenever you need to use them as a dependency. For documentation of the specific API endpoints that the Maven package manager @@ -20,9 +20,9 @@ Supported clients: - `sbt` can only be used to [pull dependencies](#install-a-package). See this [issue 408479](https://gitlab.com/gitlab-org/gitlab/-/issues/408479) for more details. -## Publish to the GitLab Package Registry +## Publish to the GitLab package registry -### Authenticate to the Package Registry +### Authenticate to the package registry You need a token to publish a package. There are different tokens available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../package_registry/index.md#authenticate-with-the-registry). @@ -135,7 +135,7 @@ file: ##### Basic HTTP Authentication -You can also use basic HTTP authentication to authenticate to the Maven Package Registry. +You can also use basic HTTP authentication to authenticate to the Maven package registry. ::Tabs @@ -237,7 +237,7 @@ You must to provide a name and a password. NOTE: The name field must be named to match the token you chose. -To install a package from the Maven GitLab Package Registry by using `sbt`, you must configure +To install a package from the Maven GitLab package registry by using `sbt`, you must configure a [Maven resolver](https://www.scala-sbt.org/1.x/docs/Resolvers.html#Maven+resolvers). If you're accessing a private or an internal project or group, you need to set up [credentials](https://www.scala-sbt.org/1.x/docs/Publishing.html#Credentials). @@ -458,7 +458,7 @@ Go to your project's **Packages and registries** page and view the published pac ## Install a package -To install a package from the GitLab Package Registry, you must configure +To install a package from the GitLab package registry, you must configure the [remote and authenticate](#authenticate-to-the-package-registry). When this is completed, you can install a package from a project, group, or namespace. @@ -466,6 +466,9 @@ group, or namespace. If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. +In case there are not enough permissions to read the most recently-published +package than `403 Forbidden` is returning. + ::Tabs :::TabTitle `mvn` @@ -489,7 +492,7 @@ To install a package by using `mvn install`: mvn install ``` -The message should show that the package is downloading from the Package Registry: +The message should show that the package is downloading from the package registry: ```shell Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom @@ -509,7 +512,7 @@ You can also install packages by using the Maven [`dependency:get` command](http NOTE: The repository IDs in the command(`gitlab-maven`) and the `settings.xml` file must match. -The message should show that the package is downloading from the Package Registry: +The message should show that the package is downloading from the package registry: ```shell Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom @@ -592,11 +595,11 @@ FLAG: By default this feature is not available for self-managed. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. This feature is not available for SaaS users. -When a Maven package is not found in the Package Registry, the request is forwarded +When a Maven package is not found in the package registry, the request is forwarded to [Maven Central](https://search.maven.org/). When the feature flag is enabled, administrators can disable this behavior in the -[Continuous Integration settings](../../admin_area/settings/continuous_integration.md). +[Continuous Integration settings](../../../administration/settings/continuous_integration.md). Maven forwarding is restricted to only the project level and group level [endpoints](#naming-convention). The instance level endpoint @@ -789,13 +792,13 @@ The GitLab Maven repository supports the following CLI commands: :::TabTitle `mvn` -- `mvn deploy`: Publish your package to the Package Registry. +- `mvn deploy`: Publish your package to the package registry. - `mvn install`: Install packages specified in your Maven project. - `mvn dependency:get`: Install a specific package. :::TabTitle `gradle` -- `gradle publish`: Publish your package to the Package Registry. +- `gradle publish`: Publish your package to the package registry. - `gradle install`: Install packages specified in your Gradle project. ::EndTabs diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 43defb29fd5..7a94db939cc 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -1,20 +1,20 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# npm packages in the Package Registry **(FREE ALL)** +# npm packages in the package registry **(FREE ALL)** For documentation of the specific API endpoints that the npm package manager client uses, see the [npm API documentation](../../../api/packages/npm.md). Learn how to build an [npm](../workflows/build_packages.md#npm) or [yarn](../workflows/build_packages.md#yarn) package. -Watch a [video demo](https://youtu.be/yvLxtkvsFDA) of how to publish npm packages to the GitLab Package Registry. +Watch a [video demo](https://youtu.be/yvLxtkvsFDA) of how to publish npm packages to the GitLab package registry. -## Publish to GitLab Package Registry +## Publish to GitLab package registry -### Authentication to the Package Registry +### Authentication to the package registry You need an token to publish a package. There are different tokens available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../../../user/packages/package_registry/index.md#authenticate-with-the-registry). @@ -43,7 +43,7 @@ If you plan to install a package through the [instance level](#install-from-the- of the project with the source code of the package itself. The scope should be lowercase. - The package name can be anything you want -| Project URL | Package Registry in | Scope | Full package name | +| Project URL | Package registry in | Scope | Full package name | | ------------------------------------------------------- | ------------------- | --------- | ---------------------- | | `https://gitlab.com/my-org/engineering-group/analytics` | Analytics | `@my-org` | `@my-org/package-name` | @@ -81,11 +81,11 @@ Associate your [token](#authentication-to-the-package-registry) with the `"${NPM NPM_TOKEN=your_token npm publish ``` -Your package should now publish to the Package Registry. +Your package should now publish to the package registry. ## Publishing a package by using a CI/CD pipeline -When publishing by using a CI/CD pipeline, you can use the [predefined variables](../../../ci/variables/predefined_variables.md) `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}` to authenticate with your project's Package Registry. We use these variables to create a `.npmrc` file [for authentication](#authenticating-via-the-npmrc) during execution of your CI/CD job. +When publishing by using a CI/CD pipeline, you can use the [predefined variables](../../../ci/variables/predefined_variables.md) `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}` to authenticate with your project's package registry. We use these variables to create a `.npmrc` file [for authentication](#authenticating-via-the-npmrc) during execution of your CI/CD job. WARNING: When generating the `.npmrc` file, do not specify the port after `${CI_SERVER_HOST}` if it is a default port, @@ -109,7 +109,7 @@ publish-npm: - Replace `@scope` with the [scope](https://docs.npmjs.com/cli/v10/using-npm/scope) of the package that is being published. -Your package is published to the Package Registry when the `publish-npm` job in your pipeline runs. +Your package is published to the package registry when the `publish-npm` job in your pipeline runs. ## Install a package @@ -121,9 +121,9 @@ You can install a package from a GitLab project, group, or instance: - **Group-level**: Use when you have many npm packages in different projects in the same GitLab group. - **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -### Authenticate to the Package Registry +### Authenticate to the package registry -You must authenticate to the Package Registry to install a package from a private project or a private group. +You must authenticate to the package registry to install a package from a private project or a private group. No authentication is needed if the project or the group is public. To authenticate with `npm`: @@ -171,7 +171,7 @@ are not supported. WARNING: To install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). -1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). +1. [Authenticate to the package registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -194,7 +194,7 @@ To install a package from the instance level, the package must have been publish > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) in GitLab 16.0 [with a flag](../../../administration/feature_flags.md) named `npm_group_level_endpoints`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121837) in GitLab 16.1. Feature flag `npm_group_level_endpoints` removed. -1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). +1. [Authenticate to the package registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -214,7 +214,7 @@ To install a package from the instance level, the package must have been publish ### Install from the project level -1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). +1. [Authenticate to the package registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -232,6 +232,18 @@ To install a package from the instance level, the package must have been publish npm install @scope/my-package ``` +### Package forwarding to npmjs.com + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in GitLab 12.9. + +When an npm package is not found in the package registry, GitLab responds with an HTTP redirect so the requesting client can resend the request to [npmjs.com](https://www.npmjs.com/). + +Administrators can disable this behavior in the [Continuous Integration settings](../../../administration/settings/continuous_integration.md). + +Group owners can disable this behavior in the group **Packages and registries** settings. + +Improvements are tracked in [epic 3608](https://gitlab.com/groups/gitlab-org/-/epics/3608). + ## Deprecate a package > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396763) in GitLab 16.0. @@ -267,14 +279,6 @@ npm deprecate @scope/package "" ## Helpful hints -### Package forwarding to npmjs.com - -When an npm package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). The forward is performed by sending an HTTP redirect back to the requesting client. - -Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). - -Group owners can disable this behavior in the group Packages and Registries settings. - ### Install npm packages from other organizations You can route package requests to organizations and users outside of GitLab. @@ -289,7 +293,7 @@ and use your organization's URL. The name is case-sensitive and must match the n ### npm metadata -The GitLab Package Registry exposes the following attributes to the npm client. +The GitLab package registry exposes the following attributes to the npm client. These are similar to the [abbreviated metadata format](https://github.com/npm/registry/blob/9e368cf6aaca608da5b2c378c0d53f475298b916/docs/responses/package-metadata.md#abbreviated-metadata-format): - `name` @@ -407,7 +411,7 @@ And the `.npmrc` file should look like: If you get this error, ensure that: -- The Package Registry is enabled in your project settings. Although the Package Registry is enabled by default, it's possible to [disable it](../package_registry/index.md#disable-the-package-registry). +- The package registry is enabled in your project settings. Although the package registry is enabled by default, it's possible to [disable it](../package_registry/index.md#disable-the-package-registry). - Your token is not expired and has appropriate permissions. - A package with the same name or version doesn't already exist within the given scope. - The scoped packages URL includes a trailing slash: diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 8db79dc6c5f..76a97834a73 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -1,19 +1,19 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# NuGet packages in the Package Registry **(FREE ALL)** +# NuGet packages in the package registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab 12.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. > - Symbol package support [added](https://gitlab.com/gitlab-org/gitlab/-/issues/262081) in GitLab 14.1. -Publish NuGet packages in your project's Package Registry. Then, install the +Publish NuGet packages in your project's package registry. Then, install the packages whenever you need to use them as a dependency. -The Package Registry works with: +The package registry works with: - [NuGet CLI](https://learn.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference) - [.NET Core CLI](https://learn.microsoft.com/en-us/dotnet/core/tools/) @@ -37,18 +37,18 @@ To use the GitLab endpoint for NuGet Packages, choose an option: Some features such as [publishing](#publish-a-nuget-package) a package are only available on the project-level endpoint. -When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 most recent versions. +When asking for versions of a given NuGet package name, the GitLab package registry returns a maximum of 300 most recent versions. Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. WARNING: -Because of how NuGet handles credentials, the Package Registry rejects anonymous requests on the group-level endpoint. +Because of how NuGet handles credentials, the package registry rejects anonymous requests on the group-level endpoint. To work around this limitation, set up [authentication](#add-the-package-registry-as-a-source-for-nuget-packages). -## Add the Package Registry as a source for NuGet packages +## Add the package registry as a source for NuGet packages -To publish and install packages to the Package Registry, you must add the -Package Registry as a source for your packages. +To publish and install packages to the package registry, you must add the +package registry as a source for your packages. Prerequisites: @@ -76,10 +76,10 @@ You can now add a new source to NuGet with: #### Project-level endpoint -A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is required to publish NuGet packages to the package registry. A project-level endpoint is also required to install NuGet packages from a project. -To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the package registry as a source with `nuget`: ```shell nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> @@ -97,7 +97,7 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/proje To install a NuGet package from a group, use a group-level endpoint. -To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the package registry as a source with `nuget`: ```shell nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> @@ -115,10 +115,10 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/group #### Project-level endpoint -A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is required to publish NuGet packages to the package registry. A project-level endpoint is also required to install NuGet packages from a project. -To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio: +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the package registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). 1. In Windows, select **Tools > Options**. On macOS, select **Visual Studio > Preferences**. @@ -146,7 +146,7 @@ If you get a warning, ensure that the **Source**, **Username**, and To install a package from a group, use a group-level endpoint. -To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio: +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the package registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). 1. In Windows, select **Tools > Options**. On macOS, select **Visual Studio > Preferences**. @@ -174,11 +174,11 @@ If you get a warning, ensure that the **Source**, **Username**, and #### Project-level endpoint -A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is required to publish NuGet packages to the package registry. A project-level endpoint is also required to install NuGet packages from a project. To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) -NuGet endpoint, add the Package Registry as a source with `nuget`: +NuGet endpoint, add the package registry as a source with `nuget`: ```shell dotnet nuget add source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" --name <source_name> --username <gitlab_username or deploy_token_username> --password <gitlab_personal_access_token or deploy_token> @@ -198,7 +198,7 @@ dotnet nuget add source "https://gitlab.example.com/api/v4/projects/10/packages/ To install a NuGet package from a group, use a group-level endpoint. To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) -NuGet endpoint, add the Package Registry as a source with `nuget`: +NuGet endpoint, add the package registry as a source with `nuget`: ```shell dotnet nuget add source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" --name <source_name> --username <gitlab_username or deploy_token_username> --password <gitlab_personal_access_token or deploy_token> @@ -219,10 +219,10 @@ dotnet nuget add source "https://gitlab.example.com/api/v4/groups/23/-/packages/ A project-level endpoint is required to: -- Publish NuGet packages to the Package Registry. +- Publish NuGet packages to the package registry. - Install NuGet packages from a project. -To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) package registry as a source for .NET: 1. In the root of your project, create a file named `nuget.config`. 1. Add this content: @@ -254,7 +254,7 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package To install a package from a group, use a group-level endpoint. -To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: +To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) package registry as a source for .NET: 1. In the root of your project, create a file named `nuget.config`. 1. Add this content: @@ -288,11 +288,11 @@ You can add a source feed with the Chocolatey CLI. If you use Chocolatey CLI v1. #### Configure a project-level endpoint -You need a project-level endpoint to publish NuGet packages to the Package Registry. +You need a project-level endpoint to publish NuGet packages to the package registry. -To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for Chocolatey: +To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) package registry as a source for Chocolatey: -- Add the Package Registry as a source with `choco`: +- Add the package registry as a source with `choco`: ```shell choco source add -n=gitlab -s "'https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/v2'" -u=<gitlab_username or deploy_token_username> -p=<gitlab_personal_access_token or deploy_token> @@ -300,13 +300,13 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package ## Publish a NuGet package -Prerequisite: +Prerequisites: - Set up the [source](#add-the-package-registry-as-a-source-for-nuget-packages) with a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). When publishing packages: -- The Package Registry on GitLab.com can store up to 5 GB of content. +- The package registry on GitLab.com can store up to 5 GB of content. This limit is [configurable for self-managed GitLab instances](../../../administration/instance_limits.md#package-registry-limits). - If you publish the same package with the same version multiple times, each consecutive upload is saved as a separate file. When installing a package, @@ -362,7 +362,7 @@ dotnet nuget push <package_file> --source <source_url> --api-key <gitlab_persona ``` - `<package_file>` is your package filename, ending in `.nupkg`. -- `<source_url>` is the URL of the NuGet Package Registry. +- `<source_url>` is the URL of the NuGet package registry. For example: @@ -406,9 +406,9 @@ updated: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416404) in GitLab 16.2. -Prerequisite: +Prerequisites: -- The project-level Package Registry is a source for Chocolatey. +- The project-level package registry is a source for Chocolatey. To publish a package with the Chocolatey CLI: @@ -419,7 +419,7 @@ choco push <package_file> --source <source_url> --api-key <gitlab_personal_acces In this command: - `<package_file>` is your package filename and ends with `.nupkg`. -- `<source_url>` is the URL of the NuGet v2 feed Package Registry. +- `<source_url>` is the URL of the NuGet v2 feed package registry. For example: @@ -457,14 +457,14 @@ not be recognized as a duplicate. If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. -To install a NuGet package from the Package Registry, you must first +To install a NuGet package from the package registry, you must first [add a project-level or group-level endpoint](#add-the-package-registry-as-a-source-for-nuget-packages). ### Install a package with the NuGet CLI WARNING: By default, `nuget` checks the official source at `nuget.org` first. If you have -a NuGet package in the Package Registry with the same name as a package at +a NuGet package in the package registry with the same name as a package at `nuget.org`, you must specify the source name to install the correct package. Install the latest version of a package by running this command: @@ -483,7 +483,7 @@ nuget install <package_id> -OutputDirectory <output_directory> \ ### Install a package with the .NET CLI WARNING: -If you have a package in the Package Registry with the same name as a package at +If you have a package in the package registry with the same name as a package at a different source, verify the order in which `dotnet` checks sources during install. This is defined in the `nuget.config` file. @@ -503,7 +503,7 @@ dotnet add package <package_id> \ Prerequisites: -- The project-level Package Registry is a [v2 feed source](#add-a-source-with-chocolatey-cli) for Chocolatey. +- The project-level package registry is a [v2 feed source](#add-a-source-with-chocolatey-cli) for Chocolatey. - A version must be provided when installing or upgrading a package using NuGet v2 feed. To install a package with the Chocolatey CLI: @@ -515,7 +515,7 @@ choco install <package_id> -Source <source_url> -Version <package_version> In this command: - `<package_id>` is the package ID. -- `<source_url>` is the URL or name of the NuGet v2 feed Package Registry. +- `<source_url>` is the URL or name of the NuGet v2 feed package registry. - `<package_version>` is the package version. For example: @@ -537,7 +537,7 @@ choco upgrade <package_id> -Source <source_url> -Version <package_version> In this command: - `<package_id>` is the package ID. -- `<source_url>` is the URL or name of the NuGet v2 feed Package Registry. +- `<source_url>` is the URL or name of the NuGet v2 feed package registry. - `<package_version>` is the package version. For example: @@ -587,12 +587,51 @@ can also push them manually: nuget push My.Package.snupkg -Source <source_name> ``` -Consuming symbol packages is not yet guaranteed using clients such as Visual Studio or -dotnet-symbol. The `.snupkg` files are available for download through the UI or the -[API](../../../api/packages/nuget.md#download-a-package-file). +### Use the package registry as a symbol server + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416178) in GitLab 16.7. + +GitLab can consume symbol files from the NuGet package registry, +so you can use the package registry as a symbol server. + +To use the symbol server: + +1. Enable the `nuget_symbol_server_enabled` namespace setting with the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings). +1. Configure your debugger to use the symbol server. + For example, to configure Visual Studio: + + 1. Open **Tools > Preferences**. + 1. Select **Debugger > Symbol sources**. + 1. Select **Add**. + 1. Fill in the required fields. The URL for the symbol server is: + + ```shell + https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/symbolfiles + -- or -- + https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/symbolfiles + ``` + + 1. Select **Add Source**. + +After you configure the debugger, you can debug your application as usual. +The debugger automatically downloads the symbol PDB files from the package registry as long as they're available. + +#### Consuming symbol packages + +When the debugger is configured to consume symbol packages, the debugger sends the following +in a request: + +- `Symbolchecksum` header: The SHA-256 checksum of the symbol file. +- `file_name` request parameter: The name of the symbol file. For example, `mypackage.pdb`. +- `signature` request parameter: The GUID and age of the PDB file. + +The GitLab server matches this information to a symbol file and returns it. + +Note that: -Follow the [NuGet symbol package issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262081) -for further updates. +- Only portable PDB files are supported. +- Because debuggers can't provide authentication tokens, the symbol server endpoint doesn't support the usual authentication methods. + The GitLab server requires the `signature` and `Symbolchecksum` to return the correct symbol file. ## Supported CLI commands diff --git a/doc/user/packages/package_registry/dependency_proxy/index.md b/doc/user/packages/package_registry/dependency_proxy/index.md new file mode 100644 index 00000000000..7b5e7a4c624 --- /dev/null +++ b/doc/user/packages/package_registry/dependency_proxy/index.md @@ -0,0 +1,293 @@ +--- +stage: Package +group: Package Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Dependency proxy for packages **(PREMIUM ALL BETA)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3610) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `packages_dependency_proxy_maven`. Disabled by default. +> - This feature is in [Beta](../../../../policy/experiment-beta-support.md). + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `packages_dependency_proxy_maven`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +The GitLab dependency proxy for packages is a local proxy for frequently pulled packages. +It is implemented as a pull-through cache that works at the project level. + +Packages are pulled from the upstream package registry and automatically published to the +project's package registry. Subsequent identical requests are fulfilled with the project's +package registry. You can use the dependency proxy for packages to reduce unnecessary traffic +to the upstream registry. + +## Enable the dependency proxy + +To use the dependency proxy for packages, ensure your project is configured properly, +and that users who pull from the cache have the necessary authentication: + +1. In the global configuration, if the following features are disabled, enable them: + - The [`package` feature](../../../../administration/packages/index.md#enable-or-disable-the-package-registry). Enabled by default. + - The [`dependency_proxy` feature](../../../../administration/packages/dependency_proxy.md#turn-on-the-dependency-proxy). Enabled by default. +1. In the project settings, if the [`package` feature](../../package_registry/index.md#disable-the-package-registry) + is disabled, enable it. It is enabled by default. +1. [Add an authentication method](#configure-a-client). The dependency proxy supports the same [authentication methods](../index.md#authenticate-with-the-registry) as the package registry: + - [Personal access token](../../../profile/personal_access_tokens.md) + - [Project deploy token](../../../project/deploy_tokens/index.md) + - [Group deploy token](../../../project/deploy_tokens/index.md) + - [Job token](../../../../ci/jobs/ci_job_token.md) + +## Advanced caching + +When possible, the dependency proxy for packages uses advanced caching to store packages in the project's package registry. + +Advanced caching verifies the coherence between the project's package registry +and the upstream package registry. If the upstream registry has updated files, +the dependency proxy uses them to update the cached files. + +When advanced caching is not supported, the dependency proxy falls back to the default behavior: + +- If the requested file is found in the project's package registry, it is returned. +- If the file is not found, it is fetched from the upstream package registry. + +Advanced caching support depends on how the upstream package registry +responds to dependency proxy requests, and on +which package format you use. + +::Tabs + +:::TabTitle Maven + +| Package registry | Advanced caching supported? | +|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| +| [GitLab](../../maven_repository/index.md) | **{check-circle}** Yes | +| [Maven Central](https://mvnrepository.com/repos/central) | **{check-circle}** Yes | +| [Artifactory](https://jfrog.com/integration/maven-repository/) | **{check-circle}** Yes | +| [Sonatype Nexus](https://help.sonatype.com/repomanager3/nexus-repository-administration/formats/maven-repositories) | **{check-circle}** Yes | +| [GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) | **{dotted-circle}** No | + +::EndTabs + +### Permissions + +When the dependency proxy pulls a file, the following occurs: + +1. The dependency proxy searches for a file in the project's package registry. + This is a read operation. +1. The dependency proxy might publish a package file to the project's package registry. + This is a write operation. + +Whether both steps are executed depends on user permissions. +The dependency proxy uses the [same permissions as the package registry](../index.md#package-registry-visibility-permissions). + +| Project visibility | Minimum [role](../../../../user/permissions.md#roles) | Can read package files? | Can write package files? | Behavior | +|--------------------|-------------------------------------------------------|-------------------------|--------------------------|----------| +| Public | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected. | +| Public | Guest | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. | +| Public | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. | +| Internal | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected | +| Internal | Guest | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. | +| Internal | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. | +| Private | Anonymous | **{dotted-circle}** No | **{dotted-circle}** No | Request rejected | +| Private | Reporter | **{check-circle}** Yes | **{dotted-circle}** No | Package file returned from either the cache or the remote registry. | +| Internal | Developer | **{check-circle}** Yes | **{check-circle}** Yes | Package file returned from either the cache or the remote registry. The file is published to the cache. | + +At a minimum, any user who can use the dependency proxy can also use the project's package registry. + +To ensure the cache is properly filled over time, you should make sure a user with at least the Developer role pulls packages with the dependency proxy. + +## Configure a client + +Configuring a client for the dependency proxy is similar to configuring a client for the [package registry](../supported_functionality.md#pulling-packages). + +### For Maven packages + +For Maven packages, [all clients supported by the package registry](../../maven_repository/index.md) are supported by the dependency proxy: + +- `mvn` +- `gradle` +- `sbt` + +For authentication, the Maven dependency proxy access all authentication methods accepted by the [Maven package registry](../../maven_repository/index.md#edit-the-client-configuration). +You should use the [Basic HTTP authentication](../../maven_repository/index.md#basic-http-authentication) method as it is less complex. + +To configure the client: + +1. Follow the instructions in [Basic HTTP authentication](../../maven_repository/index.md#basic-http-authentication). + + Make sure you use the endpoint URL `https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven`. + +1. Complete the configuration for your client: + +::Tabs + +:::TabTitle mvn + +In the `pom.xml` file add a `repository` element: + +```xml +<repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven</url> + </repository> +</repositories> +``` + +Where: + +- `<project_id>` is the ID of the project to be used as a dependency proxy. +- `<id>` contains the name of the `<server>` used in the [authentication configuration](../../maven_repository/index.md#basic-http-authentication). + +By default, Maven Central is checked first through the [Super POM](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Super_POM). +However, you might want to force `mvn` to check the GitLab endpoint first. To do this, follow the instructions from the [request forward](../../maven_repository/index.md#additional-configuration-for-mvn). + +:::TabTitle gradle + +Add a `repositories` section to your [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) file. + +- In Groovy DSL: + + ```groovy + repositories { + maven { + url "https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven" + name "GitLab" + credentials(PasswordCredentials) { + username = 'REPLACE_WITH_NAME' + password = gitLabPrivateToken + } + authentication { + basic(BasicAuthentication) + } + } + } + ``` + +- In Kotlin DSL: + + ```kotlin + repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven") + name = "GitLab" + credentials(BasicAuthentication::class) { + username = "REPLACE_WITH_NAME" + password = findProperty("gitLabPrivateToken") as String? + } + authentication { + create("basic", BasicAuthentication::class) + } + } + } + ``` + +In this example: + +- `<project_id>` is the ID of the project to be used as a dependency proxy. +- `REPLACE_WITH_NAME` is explained in the [Basic HTTP authentication](../../maven_repository/index.md#basic-http-authentication) section. + +:::TabTitle sbt + +In your [`build.sbt`](https://www.scala-sbt.org/1.x/docs/Directories.html#sbt+build+definition+files), add the following lines: + +```scala +resolvers += ("gitlab" at "https://gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven") + +credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>") +``` + +In this example: + +- `<project_id>` is the ID of the project to be used as a dependency proxy. +- `<host>` is the host present in the `<endpoint url>` without the protocol scheme or the port. Example: `gitlab.example.com`. +- `<name>` and `<token>` are explained in the [Basic HTTP authentication](../../maven_repository/index.md#basic-http-authentication) section. + +::EndTabs + +## Configure the remote registry + +The dependency proxy must be configured with: + +- The URL of the remote package registry. +- Optional. The required credentials. + +To set those parameters: + +1. Use the related [GraphQL mutation](../../../../api/graphql/reference/index.md#mutationupdatedependencyproxypackagessettings). + + A frontend to display and manage these settings is proposed by [issue 410726](https://gitlab.com/gitlab-org/gitlab/-/issues/410726). + +1. Complete the configuration for your package format: + +::Tabs + +:::TabTitle Maven + +Any Maven package registry can be connected to the dependency proxy. You can +authorize the connection with the Maven package registry username and password. + +To set or update the remote Maven package registry, update the following fields on the settings object: + +- `mavenExternalRegistryUrl` - The URL of the remote registry. +- `mavenExternalRegistryUsername` - Optional. The username to use with the remote registry. +- `mavenExternalRegistryPassword` - Optional. The password to use with the remote registry. + +Example of the GraphQL mutation: + +```graphql +mutation { + updateDependencyProxyPackagesSettings(input: { projectPath : <project full path>, enabled: true, mavenExternalRegistryUrl: <remote registry url>, mavenExternalRegistryUsername: <username>, mavenExternalRegistryPassword: <password> }) { + dependencyProxyPackagesSetting { + enabled + mavenExternalRegistryUrl + mavenExternalRegistryUsername + } + errors + } +} +``` + +::EndTabs + +## Troubleshooting + +### Manual file pull errors + +You can pull files manually with cURL. +However, you might encounter one of the following responses: + +- `404 Not Found` - The dependency proxy setting object was not found because it doesn't exist, or because the [requirements](#enable-the-dependency-proxy) were not fulfilled. +- `401 Unauthorized` - The user was properly authenticated but did not have the proper permissions to access the dependency proxy object. +- `403 Forbidden` - There was an issue with the [GitLab license level](#enable-the-dependency-proxy). +- `502 Bad Gateway` - The remote package registry could not fulfill the file request. Verify the [dependency proxy settings](#configure-the-remote-registry). +- `504 Gateway Timeout` - The remote package registry timed out. Verify the [dependency proxy settings](#configure-the-remote-registry). + +::Tabs + +:::TabTitle Maven + +```shell +curl --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/<group id and artifact id>/<version>/<file_name>" +``` + +- `<username>` and `<personal access token>` are the credentials to access the dependency proxy of the GitLab instance. +- `<project_id>` is the project ID. +- `<group id and artifact id>` are the [Maven package group ID and artifact ID](https://maven.apache.org/pom.html#Maven_Coordinates) joined with a forward slash. +- `<version>` is the package version. +- `file_name` is the exact name of the file. + +For example, given a package with: + +- group ID: `com.my_company`. +- artifact ID: `my_package`. +- version: `1.2.3`. + +The request to manually pull a package is: + +```shell +curl --verbose "https://<username>:<personal access token>@gitlab.example.com/api/v4/projects/<project_id>/dependency_proxy/packages/maven/com/my_company/my_package/1.2.3/my_package-1.2.3.pom" +``` + +::EndTabs diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index e9c019deefa..6a4e7c0d6a5 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -1,20 +1,20 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Package Registry **(FREE ALL)** +# Package registry **(FREE ALL)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. -With the GitLab Package Registry, you can use GitLab as a private or public registry for a variety +With the GitLab package registry, you can use GitLab as a private or public registry for a variety of [supported package managers](supported_package_managers.md). You can publish and share packages, which can be consumed as a dependency in downstream projects. ## Package workflows -Learn how to use the GitLab Package Registry to build your own custom package workflow: +Learn how to use the GitLab package registry to build your own custom package workflow: - [Use a project as a package registry](../workflows/project_registry.md) to publish all of your packages to one project. @@ -43,11 +43,6 @@ For information on how to create and upload a package, view the GitLab documenta ## Authenticate with the registry -<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> -WARNING: -In GitLab 16.0 and later, [external authorization](../../admin_area/settings/external_authorization.md) prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. -<!--- end_remove --> - Authentication depends on the package manager being used. For more information, see the docs on the specific package format you want to use. @@ -83,7 +78,7 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -For more information about using the GitLab Package Registry with CI/CD, see: +For more information about using the GitLab package registry with CI/CD, see: - [Composer](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) - [Conan](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) @@ -110,18 +105,18 @@ For a list of supported packages, see [Importing packages from other repositorie ## Reduce storage usage -For information on reducing your storage use for the Package Registry, see -[Reduce Package Registry storage use](reduce_package_registry_storage.md). +For information on reducing your storage use for the package registry, see +[Reduce package registry storage use](reduce_package_registry_storage.md). -## Disable the Package Registry +## Disable the package registry -The Package Registry is automatically enabled. +The package registry is automatically enabled. If you are using a self-managed instance of GitLab, your administrator can remove the menu item, **Packages and registries**, from the GitLab sidebar. For more information, see the [administration documentation](../../../administration/packages/index.md). -You can also remove the Package Registry for your project specifically: +You can also remove the package registry for your project specifically: 1. In your project, go to **Settings > General**. 1. Expand the **Visibility, project features, permissions** section and disable the @@ -130,45 +125,45 @@ You can also remove the Package Registry for your project specifically: The **Deploy > Package Registry** entry is removed from the sidebar. -## Package Registry visibility permissions +## Package registry visibility permissions [Project-level permissions](../../permissions.md) determine actions such as downloading, pushing, or deleting packages. -The visibility of the Package Registry is independent of the repository and can be controlled from +The visibility of the package registry is independent of the repository and can be controlled from your project's settings. For example, if you have a public project and set the repository visibility -to **Only Project Members**, the Package Registry is then public. Disabling the Package -Registry disables all Package Registry operations. +to **Only Project Members**, the package registry is then public. Disabling the Package +Registry disables all package registry operations. | Project visibility | Action | Minimum [role](../../permissions.md#roles) required | |--------------------|-----------------------|---------------------------------------------------------| -| Public | View Package Registry | `n/a`, everyone on the internet can perform this action | +| Public | View package registry | `n/a`, everyone on the internet can perform this action | | Public | Publish a package | Developer | | Public | Pull a package | `n/a`, everyone on the internet can perform this action | -| Internal | View Package Registry | Guest | +| Internal | View package registry | Guest | | Internal | Publish a package | Developer | | Internal | Pull a package | Guest (1) | -| Private | View Package Registry | Reporter | +| Private | View package registry | Reporter | | Private | Publish a package | Developer | | Private | Pull a package | Reporter (1) | -### Allow anyone to pull from Package Registry +### Allow anyone to pull from package registry > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385994) in GitLab 15.7. -To allow anyone to pull from the Package Registry, regardless of project visibility: +To allow anyone to pull from the package registry, regardless of project visibility: 1. On the left sidebar, select **Search or go to** and find your private or internal project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Turn on the **Allow anyone to pull from Package Registry** toggle. 1. Select **Save changes**. -Anyone on the internet can access the Package Registry for the project. +Anyone on the internet can access the package registry for the project. #### Disable allowing anyone to pull -Prerequisite: +Prerequisites: - You must be an administrator. @@ -178,7 +173,7 @@ To hide the **Allow anyone to pull from Package Registry** toggle globally: Anonymous downloads are disabled, even for projects that turned on the **Allow anyone to pull from Package Registry** toggle. -Several known issues exist when you allow anyone to pull from the Package Registry: +Several known issues exist when you allow anyone to pull from the package registry: - Project-level endpoints are supported. Group-level and instance-level endpoints are not supported. Support for group-level endpoints is proposed in [issue 383537](https://gitlab.com/gitlab-org/gitlab/-/issues/383537). - It does not work with the [Composer](../composer_repository/index.md#install-a-composer-package), because Composer only has a group endpoint. diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index e6251034cb2..c1d3d7d0937 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Reduce Package Registry Storage **(FREE ALL)** +# Reduce package registry storage **(FREE ALL)** Without cleanup, package registries become large over time. When a large number of packages and their assets are added: @@ -14,13 +14,13 @@ their assets are added: We recommend deleting unnecessary packages and assets. This page offers examples of how to do so. -## Check Package Registry Storage Use +## Check package registry storage use The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. ## Delete a package -You cannot edit a package after you publish it in the Package Registry. Instead, you +You cannot edit a package after you publish it in the package registry. Instead, you must delete and recreate it. To delete a package, you must have suitable [permissions](../../permissions.md). diff --git a/doc/user/packages/package_registry/supported_functionality.md b/doc/user/packages/package_registry/supported_functionality.md index eb6b415ee06..4b10e703127 100644 --- a/doc/user/packages/package_registry/supported_functionality.md +++ b/doc/user/packages/package_registry/supported_functionality.md @@ -1,12 +1,12 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported package functionality -The GitLab Package Registry supports different functionalities for each package type. This support includes publishing +The GitLab package registry supports different functionalities for each package type. This support includes publishing and pulling packages, request forwarding, managing duplicates, and authentication. ## Publishing packages **(FREE ALL)** @@ -133,7 +133,7 @@ By default, the GitLab package registry either allows or prevents duplicates bas ## Authentication tokens **(FREE ALL)** -GitLab tokens are used to authenticate with the GitLab Package Registry. +GitLab tokens are used to authenticate with the GitLab package registry. The following tokens are supported: @@ -181,7 +181,7 @@ The following authentication protocols are supported: Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the [API](../../../api/packages.md). -The Package Registry supports the following hash types: +The package registry supports the following hash types: | Package type | Supported hashes | |-------------------------------------------------------|----------------------------------| diff --git a/doc/user/packages/package_registry/supported_package_managers.md b/doc/user/packages/package_registry/supported_package_managers.md index 8d31399a36b..aa56bed78aa 100644 --- a/doc/user/packages/package_registry/supported_package_managers.md +++ b/doc/user/packages/package_registry/supported_package_managers.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported package managers **(FREE ALL)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Not all package manager formats are ready for production use. -The Package Registry supports the following package manager types: +The package registry supports the following package manager types: | Package type | GitLab version | Status | | ------------------------------------------------ | -------------- | --------------------------------------------------------------- | @@ -27,4 +27,4 @@ The Package Registry supports the following package manager types: [View what each status means](../../../policy/experiment-beta-support.md). -You can also use the [API](../../../api/packages.md) to administer the Package Registry. +You can also use the [API](../../../api/packages.md) to administer the package registry. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index c196e414461..ccd47527855 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -1,18 +1,18 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# PyPI packages in the Package Registry **(FREE ALL)** +# PyPI packages in the package registry **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. -Publish PyPI packages in your project's Package Registry. Then install the +Publish PyPI packages in your project's package registry. Then install the packages whenever you need to use them as a dependency. -The Package Registry works with: +The package registry works with: - [pip](https://pypi.org/project/pip/) - [twine](https://pypi.org/project/twine/) @@ -22,9 +22,9 @@ clients use, see the [PyPI API documentation](../../../api/packages/pypi.md). Learn how to [build a PyPI package](../workflows/build_packages.md#pypi). -## Authenticate with the Package Registry +## Authenticate with the package registry -Before you can publish to the Package Registry, you must authenticate. +Before you can publish to the package registry, you must authenticate. To do this, you can use: @@ -119,9 +119,10 @@ https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi Prerequisites: -- You must [authenticate with the Package Registry](#authenticate-with-the-package-registry). +- You must [authenticate with the package registry](#authenticate-with-the-package-registry). - Your [version string must be valid](#ensure-your-version-string-is-valid). - The maximum allowed package size is 5 GB. +- The maximum length of the `description` field is 4000 characters. Longer `description` strings are truncated. - You can't upload the same version of a package multiple times. If you try, you receive the error `400 Bad Request`. - PyPI packages are published using your projectID. @@ -202,9 +203,9 @@ more than once, a `400 Bad Request` error occurs. ## Install a PyPI package In [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/233413), -when a PyPI package is not found in the Package Registry, the request is forwarded to [pypi.org](https://pypi.org/). +when a PyPI package is not found in the package registry, the request is forwarded to [pypi.org](https://pypi.org/). -Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). +Administrators can disable this behavior in the [Continuous Integration settings](../../../administration/settings/continuous_integration.md). WARNING: When you use the `--index-url` option, do not specify the port if it is a default diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 361114e6f9e..f9017d9b5a7 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -1,10 +1,10 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Ruby gems in the Package Registry **(FREE ALL EXPERIMENT)** +# Ruby gems in the package registry **(FREE ALL EXPERIMENT)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/803) in GitLab 13.10. @@ -13,9 +13,9 @@ The Ruby gems package registry for GitLab is under development and isn't ready f limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/3200) details the remaining work and timelines to make it production ready. -You can publish Ruby gems in your project's Package Registry, then install the packages when you +You can publish Ruby gems in your project's package registry, then install the packages when you need to use them as a dependency. Although you can push gems to the registry, you cannot install -them from the registry. However, you can download `gem` files directly from the Package Registry's +them from the registry. However, you can download `gem` files directly from the package registry's UI, or by using the [API](../../../api/packages/rubygems.md#download-a-gem-file). For documentation of the specific API endpoints that the Ruby gems and Bundler package manager @@ -49,9 +49,9 @@ Feature.disable(:rubygem_packages, Project.find(2)) If you need help creating a Ruby gem, see the [RubyGems documentation](https://guides.rubygems.org/make-your-own-gem/). -## Authenticate to the Package Registry +## Authenticate to the package registry -Before you can push to the Package Registry, you must authenticate. +Before you can push to the package registry, you must authenticate. To do this, you can use: @@ -108,7 +108,7 @@ https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/rubygem Prerequisites: -- You must [authenticate to the Package Registry](#authenticate-to-the-package-registry). +- You must [authenticate to the package registry](#authenticate-to-the-package-registry). - The maximum allowed gem size is 3 GB. To push your gem, run a command like this one: diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 5c4105f8e00..2c9576bf9f7 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform Module Registry **(FREE ALL)** @@ -34,6 +34,7 @@ To authenticate to the Terraform Module Registry, you need either: - A [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). +- A [deploy token](../../project/deploy_tokens/index.md) with the `read_package_registry` or `write_package_registry` scope, or both. Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. diff --git a/doc/user/packages/workflows/build_packages.md b/doc/user/packages/workflows/build_packages.md index a0757e968bc..59508b3e9e2 100644 --- a/doc/user/packages/workflows/build_packages.md +++ b/doc/user/packages/workflows/build_packages.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Build packages @@ -51,7 +51,7 @@ Learn how to install and build packages different package formats. ### Install Conan -Prerequisite: +Prerequisites: - You must install Conan version 1.x. Support for Conan version 2 is proposed in [epic 8258](https://gitlab.com/groups/gitlab-org/-/epics/8258). @@ -92,7 +92,7 @@ The CMake version is printed in the output. ### Create a project -To test the Package Registry, you need a C++ project. If you don't already have +To test the package registry, you need a C++ project. If you don't already have one, you can clone the Conan [hello world starter project](https://github.com/conan-io/hello). ### Build a Conan package @@ -505,4 +505,4 @@ The output should appear similar to the following: mypypipackage-0.0.1-py3-none-any.whl mypypipackage-0.0.1.tar.gz ``` -The package is now ready to be published to the Package Registry. +The package is now ready to be published to the package registry. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 4db77348bd4..d85988a0bd7 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -1,12 +1,12 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Store all of your packages in one GitLab project **(FREE ALL)** -You can store all of your packages in one project's Package Registry. Rather than using +You can store all of your packages in one project's package registry. Rather than using a GitLab repository to store code, you can use the repository to store all your packages. Then you can configure your remote repositories to point to the project in GitLab. @@ -36,7 +36,7 @@ Let's take a look at how you might create one project to host all of your packag 1. Create a new project in GitLab. The project doesn't require any code or content. 1. On the left sidebar, select **Project overview**, and note the project ID. -1. Create an access token for authentication. All package types in the Package Registry can be published by using: +1. Create an access token for authentication. All package types in the package registry can be published by using: - A [personal access token](../../profile/personal_access_tokens.md). - A [CI/CD job token](../../../ci/jobs/ci_job_token.md) (`CI_JOB_TOKEN`) in a CI/CD job. @@ -56,7 +56,7 @@ If you're using npm, create an `.npmrc` file. Add the appropriate URL for publis packages to your project. Finally, add a section to your `package.json` file. Follow the instructions in the -[GitLab Package Registry npm documentation](../npm_registry/index.md#authentication-to-the-package-registry). After +[GitLab package registry npm documentation](../npm_registry/index.md#authentication-to-the-package-registry). After you do this, you can publish your npm package to your project using `npm publish`, as described in the [publishing packages](../npm_registry/index.md#publish-to-gitlab-package-registry) section. diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md index 1383cd6df27..11c8eab2513 100644 --- a/doc/user/packages/workflows/working_with_monorepos.md +++ b/doc/user/packages/workflows/working_with_monorepos.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monorepo package management workflows **(FREE ALL)** diff --git a/doc/user/packages/yarn_repository/index.md b/doc/user/packages/yarn_repository/index.md index 942e62ae3e7..99f456bc1cb 100644 --- a/doc/user/packages/yarn_repository/index.md +++ b/doc/user/packages/yarn_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Publish packages with Yarn @@ -17,11 +17,11 @@ You can use the Yarn documentation to get started with [Yarn Classic](https://classic.yarnpkg.com/en/docs/getting-started) and [Yarn 2+](https://yarnpkg.com/getting-started/). -## Publish to GitLab Package Registry +## Publish to GitLab package registry -You can use Yarn to publish to the GitLab Package Registry. +You can use Yarn to publish to the GitLab package registry. -### Authentication to the Package Registry +### Authentication to the package registry You need a token to publish a package. Different tokens are available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../../../user/packages/package_registry/index.md#authenticate-with-the-registry). @@ -54,7 +54,7 @@ In this configuration: Scoped registry does not work in Yarn Classic in `package.json` file, based on this [issue](https://github.com/yarnpkg/yarn/pull/7829). Therefore, under `publishConfig` there should be `registry` and not `@scope:registry` for Yarn Classic. -You can publish using your command line or a CI/CD pipeline to the GitLab Package Registry. +You can publish using your command line or a CI/CD pipeline to the GitLab package registry. ### Publishing via the command line - Manual Publish @@ -66,7 +66,7 @@ yarn publish yarn npm publish ``` -Your package should now publish to the Package Registry. +Your package should now publish to the package registry. ### Publishing via a CI/CD pipeline - Automated Publish @@ -163,7 +163,7 @@ deploy: - yarn npm publish ``` -Your package should now publish to the Package Registry when the pipeline runs. +Your package should now publish to the package registry when the pipeline runs. ## Install a package @@ -191,7 +191,7 @@ You can use one of two API endpoints to install packages: If you plan to install a package through the [project level](#install-from-the-project-level), you do not have to adhere to the naming convention. -| Project URL | Package Registry | Organization Scope | Full package name | +| Project URL | Package registry | Organization Scope | Full package name | |-------------------------------------------------------------------|----------------------|--------------------|-----------------------------| | `https://gitlab.com/<my-org>/<group-name>/<package-name-example>` | Package Name Example | `@my-org` | `@my-org/package-name` | | `https://gitlab.com/<example-org>/<group-name>/<project-name>` | Project Name | `@example-org` | `@example-org/project-name` | @@ -301,7 +301,7 @@ Then you can use `yarn add` to install your packages. ## Troubleshooting -### Error running Yarn with the Package Registry for the npm registry +### Error running Yarn with the package registry for the npm registry If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get an error message like: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index ab26e490f51..8c15d696760 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Permissions and roles **(FREE ALL)** @@ -74,9 +74,9 @@ The following table lists project permissions available for each role: | [GitLab Agent for Kubernetes](clusters/agent/index.md):<br>View agents | | | ✓ | ✓ | ✓ | | [GitLab Agent for Kubernetes](clusters/agent/index.md):<br>Manage agents | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/delete_container_registry_images.md#use-a-cleanup-policy) | | | | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (19) | ✓ (19) | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| [Container registry](packages/container_registry/index.md):<br>Push an image to the container registry | | | ✓ | ✓ | ✓ | +| [Container registry](packages/container_registry/index.md):<br>Pull an image from the container registry | ✓ (19) | ✓ (19) | ✓ | ✓ | ✓ | +| [Container registry](packages/container_registry/index.md):<br>Remove a container registry image | | | ✓ | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/pages_access_control.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | @@ -121,8 +121,9 @@ The following table lists project permissions available for each role: | [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View License Compliance reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [License Scanning](compliance/license_scanning_of_cyclonedx_files/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | | [License approval policies](../user/compliance/license_approval_policies.md):<br>Manage license policy | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>View a merge request | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>View list | (25) | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Approve (8) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | @@ -133,6 +134,12 @@ The following table lists project permissions available for each role: | [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](project/merge_requests/index.md#resolve-a-thread) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage [merge approval rules](project/merge_requests/approvals/settings.md) (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | +| [Objectives and key results](okrs.md):<br>Add a child OKR | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>Add a linked item | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>View | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>Change confidentiality | | ✓ | ✓ | ✓ | ✓ | +| [Objectives and key results](okrs.md):<br>Edit | | ✓ | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Pull a package | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | @@ -208,6 +215,7 @@ The following table lists project permissions available for each role: | [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | +| [Tasks](tasks.md):<br>Add a linked item | ✓ | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Create (17) | | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Edit | | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Remove from issue | | ✓ | ✓ | ✓ | ✓ | @@ -244,12 +252,13 @@ The following table lists project permissions available for each role: 16. In projects that accept contributions from external members, users can create, edit, and close their own merge requests. 17. Authors and assignees can modify the title and description even if they don't have the Reporter role. 18. Authors and assignees can close and reopen issues even if they don't have the Reporter role. -19. The ability to view the Container Registry and pull images is controlled by the [Container Registry's visibility permissions](packages/container_registry/index.md#container-registry-visibility-permissions). +19. The ability to view the container registry and pull images is controlled by the [container registry's visibility permissions](packages/container_registry/index.md#container-registry-visibility-permissions). 20. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests. 21. Authors of tasks can delete them even if they don't have the Owner role, but they have to have at least the Guest role for the project. 22. You must have permission to [view the epic](group/epics/manage_epics.md#who-can-view-an-epic). -23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on self-managed) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a [custom role](custom_roles.md) through the API and assign that role to the users. +23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator (on self-managed or GitLab Dedicated) or group owner (on GitLab.com) gives those users permission. The administrator or group owner can create a [custom role](custom_roles.md) through the API or UI and assign that role to the users. 24. In GitLab 16.4 the ability for `Developers` to change the status of a vulnerability (`admin_vulnerability`) was [deprecated](../update/deprecations.md#deprecate-change-vulnerability-status-from-the-developer-role). The `admin_vulnerability` permission will be removed, by default, from all `Developer` roles in GitLab 17.0. +25. Members with the Guest role can view the list of MRs in public projects. Private projects restrict Guests from viewing MR lists. <!-- markdownlint-enable MD029 --> @@ -268,26 +277,27 @@ More details about the permissions for some project-level features follow. | Action | Non-member | Guest | Reporter | Developer | Maintainer | Owner | |---------------------------------------------------------------------------------------------------------------------------|------------|---------|----------|-----------|------------|-------| -| See that artifacts exist | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | -| View a list of jobs | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | -| View and download artifacts | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | -| View [environments](../ci/environments/index.md) | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | -| View job logs and job details page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | -| View pipelines and pipeline details pages | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | -| View pipelines tab in MR | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | -| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| See that artifacts exist | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| View a list of jobs | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View and download artifacts | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View [environments](../ci/environments/index.md) | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| View job logs and job details page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipelines and pipeline details pages | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipelines tab in MR | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (2) | ✓ | ✓ | ✓ | ✓ | | View and download project-level [Secure Files](../api/secure_files.md) | | | | ✓ | ✓ | ✓ | -| Cancel and retry jobs | | | | ✓ | ✓ | ✓ | +| Retry jobs | | | | ✓ | ✓ | ✓ | +| Cancel jobs | | | | ✓ (7) | ✓ (7) | ✓ (7) | | Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| Delete job logs or job artifacts | | | | ✓ (4) | ✓ | ✓ | +| Delete job logs or job artifacts | | | | ✓ (4) | ✓ | ✓ | | Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | -| Run CI/CD pipeline for a protected branch | | | | ✓ (5) | ✓ (5) | ✓ | +| Run CI/CD pipeline for a protected branch | | | | ✓ (5) | ✓ (5) | ✓ | | Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| Run deployment job for a protected environment | | | ✓ (5) | ✓ (6) | ✓ (6) | ✓ | +| Run deployment job for a protected environment | | | ✓ (5) | ✓ (6) | ✓ (6) | ✓ | | View a job with [debug logging](../ci/variables/index.md#enable-debug-logging) | | | | ✓ | ✓ | ✓ | | Use pipeline editor | | | | ✓ | ✓ | ✓ | | Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | -| Add project runners to project | | | | | ✓ | ✓ | +| Add project runners to project | | | | | ✓ | ✓ | | Clear runner caches manually | | | | | ✓ | ✓ | | Enable shared runners in project | | | | | ✓ | ✓ | | Manage CI/CD settings | | | | | ✓ | ✓ | @@ -308,6 +318,7 @@ More details about the permissions for some project-level features follow. run for a non-protected branch. 5. If the user is [allowed to merge or push to the protected branch](../ci/pipelines/index.md#pipeline-security-on-protected-branches). 6. If the user if [part of a group with at least the Reporter role](../ci/environments/protected_environments.md#deployment-only-access-to-protected-environments) +7. Cancellation permissions can be [customized via the pipeline settings](../ci/pipelines/settings.md#restrict-roles-that-can-cancel-pipelines-or-jobs) <!-- markdownlint-enable MD029 --> @@ -363,8 +374,8 @@ The following table lists group permissions available for each role: | Delete [packages](packages/index.md) | | | | ✓ | ✓ | | Create/edit/delete [Maven and generic package duplicate settings](packages/generic_packages/index.md#do-not-allow-duplicate-generic-packages) | | | | ✓ | ✓ | | Enable/disable package request forwarding | | | | ✓ | ✓ | -| Pull a Container Registry image | ✓ (6) | ✓ | ✓ | ✓ | ✓ | -| Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| Pull a container registry image | ✓ (6) | ✓ | ✓ | ✓ | ✓ | +| Remove a container registry image | | | ✓ | ✓ | ✓ | | View [Group DevOps Adoption](group/devops_adoption/index.md) | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | View [Productivity analytics](analytics/productivity_analytics.md) | | ✓ | ✓ | ✓ | ✓ | @@ -404,6 +415,7 @@ The following table lists group permissions available for each role: | Manage group runners | | | | | ✓ | | [Migrate groups](group/import/index.md) | | | | | ✓ | | Manage [subscriptions, and purchase storage and compute minutes](../subscriptions/gitlab_com/index.md) | | | | | ✓ | +| Manage group-level custom roles | | | | | ✓ | <!-- markdownlint-disable MD029 --> @@ -436,8 +448,8 @@ For more information, see Users with the Minimal Access role do not: -- Count as licensed seats on self-managed Ultimate subscriptions or any GitLab.com subscriptions. - Automatically have access to projects and subgroups in that root group. +- Count as licensed seats on self-managed Ultimate subscriptions or any GitLab.com subscriptions, provided the user has no other role anywhere in the instance or in the GitLab SaaS namespace. Owners must explicitly add these users to the specific subgroups and projects. @@ -465,6 +477,6 @@ To work around the issue, give these users the Guest role or higher to any proje - [Project aliases](../user/project/import/index.md#project-aliases) - [Auditor users](../administration/auditor_users.md) - [Confidential issues](project/issues/confidential_issues.md) -- [Container Registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) +- [Container registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) - [Release permissions](project/releases/index.md#release-permissions) - [Read-only namespaces](../user/read_only_namespaces.md) diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 94217f985cf..75e44471f92 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Product Analytics -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Product analytics **(ULTIMATE ALL EXPERIMENT)** @@ -19,12 +19,11 @@ On GitLab.com, this feature is not available. This feature is not ready for production use. This page is a work in progress, and we're updating the information as we add more features. -For more information, see the [group direction page](https://about.gitlab.com/direction/analytics/product-analytics/). +For more information, see the [group direction page](https://about.gitlab.com/direction/monitor/product-analytics/). To leave feedback about Product Analytics bugs or functionality: - Comment on [issue 391970](https://gitlab.com/gitlab-org/gitlab/-/issues/391970). - Create an issue with the `group::product analytics` label. -- [Schedule a call](https://calendly.com/jheimbuck/30-minute-call) with the team. ## How product analytics works @@ -32,7 +31,7 @@ Product analytics uses several tools: - [**Snowplow**](https://docs.snowplow.io/docs) - A developer-first engine for collecting behavioral data, and passing it through to ClickHouse. - [**ClickHouse**](https://clickhouse.com/docs) - A database suited to store, query, and retrieve analytical data. -- [**Cube**](https://cube.dev/docs/) - An analytical graphing library that provides an API to run queries against the data stored in ClickHouse. +- [**Cube**](https://cube.dev/docs/) - A universal semantic layer that provides an API to run queries against the data stored in ClickHouse. The following diagram illustrates the product analytics flow: @@ -74,12 +73,11 @@ This feature is not ready for production use. To track events in your project applications on a self-managed instance, you must enable and configure product analytics. -Prerequisite: +Prerequisites: - You must be an administrator of a self-managed GitLab instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand the **Analytics** tab and find the **Product analytics** section. 1. Select **Enable product analytics** and enter the configuration values. @@ -224,7 +222,7 @@ You can [query the funnel data with the REST API](../../api/product_analytics.md To do this, you can use the example query body below, where you need to replace `FUNNEL_NAME` with your funnel's name. NOTE: -The `afterDate` filter is not supported. Please use `beforeDate` or `inDateRange`. +The `afterDate` filter is not supported. Use `beforeDate` or `inDateRange`. ```json { @@ -299,12 +297,8 @@ If the request is successful, the returned JSON includes an array of rows of res ## View product analytics usage quota -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424153) in GitLab 16.6 with a [flag](../../administration/feature_flags.md) named `product_analytics_usage_quota`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_usage_quota`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/424153) in GitLab 16.6 with a [flag](../../administration/feature_flags.md) named `product_analytics_usage_quota`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/427838) in GitLab 16.7. Feature flag `product_analytics_usage_quota` removed. Product analytics usage quota is calculated from the number of events received from instrumented applications. The tab displays the monthly totals for the group, and a breakdown of usage per project. Current month shows events counted to date. diff --git a/doc/user/product_analytics/instrumentation/browser_sdk.md b/doc/user/product_analytics/instrumentation/browser_sdk.md index f2beafab8e0..6bc9a9ef234 100644 --- a/doc/user/product_analytics/instrumentation/browser_sdk.md +++ b/doc/user/product_analytics/instrumentation/browser_sdk.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Browser SDK @@ -83,7 +83,7 @@ interface GitLabClientSDKOptions { | :---------------------------- | :---------- | | `appId` | The ID provided by the GitLab Project Analytics setup guide. This ID ensures your data is sent to your analytics instance. | | `host` | The GitLab Project Analytics instance provided by the setup guide. | -| `hasCookieConsent` | Whether to use cookies to identify unique users and record their full IP address. Set to `false` by default. When `false`, users are considered anonymous users. No cookies or other storage mechanisms are used to identify users. | +| `hasCookieConsent` | Whether to use cookies to identify unique users. Set to `false` by default. When `false`, users are considered anonymous users. No cookies or other storage mechanisms are used to identify users. | | `respectGlobalPrivacyControl` | Whether to respect the user's [GPC](https://globalprivacycontrol.org/) configuration to permit or refuse tracking. Set to `true` by default. When `false`, events are emitted regardless of user configuration. | | `trackerId` | Used to differentiate between multiple trackers running on the same page or application, because each tracker instance can be configured differently to capture different sets of data. This identifier helps ensure that the data sent to the collector is correctly associated with the correct tracker configuration. Default value is `gitlab`. | | `pagePingTracking` | Option to track user engagement on your website or application by sending periodic events while a user is actively browsing a page. Page pings provide valuable insight into how users interact with your content, such as how long they spend on a page, which sections they are viewing, and whether they are scrolling. `pagePingTracking` can be boolean or an object. As a boolean, set to `true` it enables page ping with default options, and set to `false` it disables page ping tracking. As an object, it has two options: `minimumVisitLength` (the minimum time that must have elapsed before the first heartbeat) and `heartbeatDelay` (the interval at which the callback is fired). | diff --git a/doc/user/product_analytics/instrumentation/index.md b/doc/user/product_analytics/instrumentation/index.md index f909a01ff59..da30563eede 100644 --- a/doc/user/product_analytics/instrumentation/index.md +++ b/doc/user/product_analytics/instrumentation/index.md @@ -1,7 +1,7 @@ --- -stage: Analyze +stage: Monitor group: Analytics Instrumentation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instrumentation diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 2166b40b575..6c78152fa70 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -1,8 +1,7 @@ --- -type: reference stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Creating users **(FREE SELF)** @@ -16,9 +15,9 @@ You can create users: ## Create users on sign-in page -Prerequisite: +Prerequisites: -- [Sign-up must be enabled](../../admin_area/settings/sign_up_restrictions.md). +- [Sign-up must be enabled](../../../administration/settings/sign_up_restrictions.md). Users can create their own accounts by either: @@ -27,14 +26,13 @@ Users can create their own accounts by either: ## Create users in Admin Area -Prerequisite: +Prerequisites: - You must have administrator access to the instance. To create a user manually: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select **New user**. 1. Complete the required fields, such as name, username, and email. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 70c12cbcf00..a3df0aa5460 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,8 +1,7 @@ --- -type: howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deleting a user account **(FREE ALL)** @@ -36,8 +35,7 @@ On GitLab.com, there is a seven day delay between a user deleting their own acco As an administrator, to delete a user account: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Overview > Users**. 1. Select a user. 1. Under the **Account** tab, select: diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index d26f2193124..376fde66cf0 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Two-factor authentication **(FREE ALL)** @@ -521,7 +521,7 @@ Instead you can authenticate: - Using a [personal access token](../personal_access_tokens.md) (PAT): - For Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required. - - For [GitLab Container Registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT + - For [GitLab container registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT with `read_registry` or `write_registry` scope is required. - For [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with `read_registry` and `write_registry` scopes is required. diff --git a/doc/user/profile/achievements.md b/doc/user/profile/achievements.md index c208bd554bf..0f03868de95 100644 --- a/doc/user/profile/achievements.md +++ b/doc/user/profile/achievements.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Achievements **(FREE ALL EXPERIMENT)** diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 5e8eb80a1aa..658134be9ad 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Active sessions **(FREE ALL)** diff --git a/doc/user/profile/comment_templates.md b/doc/user/profile/comment_templates.md index 98fabdb0a35..126f0e1dc8c 100644 --- a/doc/user/profile/comment_templates.md +++ b/doc/user/profile/comment_templates.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Comment templates **(FREE ALL)** diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index 37b2c1a26e6..ec1bb3f7771 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Contributions calendar **(FREE ALL)** diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 64fa5d7b448..81e2f3d7a55 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -1,8 +1,7 @@ --- -type: index, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User account **(FREE ALL)** @@ -127,14 +126,15 @@ GitLab displays the contents of your README below your contribution graph. ### From an existing project To add the README from an existing project to your profile, -[update the path](../project/settings/index.md#rename-a-repository) of the project +[update the path](../project/working_with_projects.md#rename-a-repository) of the project to match your username. ## Add external accounts to your user profile page -> Mastodon user account [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132892) in 16.6 [with a flag](../feature_flags.md) named `mastodon_social_ui`. Disabled by default. This feature is in [Beta](../../policy/experiment-beta-support.md#beta). +> - Mastodon user account [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/132892) in GitLab 16.6 [with a flag](../feature_flags.md) named `mastodon_social_ui`. Disabled by default. +> - Mastodon user account [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/428163) in GitLab 16.7. Feature flag `mastodon_social_ui` removed. -You can add links to certain other external accounts you might have, like Skype and Twitter. +You can add links to certain other external accounts you might have, like Skype and X (formerly Twitter). They can help other users connect with you on other platforms. To add links to other accounts: @@ -146,7 +146,7 @@ To add links to other accounts: - LinkedIn profile name. - Mastodon username. - Skype username. - - Twitter @username. + - X (formerly Twitter) @username. Your user ID or username must be 500 characters or less. 1. Select **Update profile settings**. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 8d34055d42c..c7b2de3ce7f 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Notification emails **(FREE ALL)** @@ -101,7 +101,7 @@ To select a notification level for a group, use either of these methods: 1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. -1. Locate the project in the **Groups** section. +1. Locate the group in the **Groups** section. 1. Select the desired [notification level](#notification-levels). Or: @@ -120,7 +120,7 @@ You can use group notifications, for example, if you work freelance, and want to 1. On the left sidebar, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. -1. Locate the project in the **Groups** section. +1. Locate the group in the **Groups** section. 1. Select the desired email address. ### Change level of project notifications diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index a953a878cc9..9d54381ef87 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -1,8 +1,7 @@ --- -type: concepts, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Personal access tokens **(FREE ALL)** @@ -69,7 +68,7 @@ list of scopes. To do this, you can append a `name` parameter and a list of comm to the URL. For example: ```plaintext -https://gitlab.example.com/-/profile/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry +https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry ``` WARNING: @@ -83,7 +82,8 @@ At any time, you can revoke a personal access token. 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. -1. In the **Active personal access tokens** area, next to the key, select **Revoke**. +1. In the **Active personal access tokens** area, select **Revoke** for the relevant token. +1. On the confirmation dialog, select **Revoke**. ## View the last time a token was used @@ -100,7 +100,8 @@ To view the last time a token was used: 1. On the left sidebar, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. -1. In the **Active personal access tokens** area, next to the key, view the **Last Used** date. +1. In the **Active personal access tokens** area, view the **Last Used** date for + the relevant token. ## Personal access token scopes @@ -110,23 +111,23 @@ To view the last time a token was used: A personal access token can perform actions based on the assigned scopes. -| Scope | Access | -|--------------------|--------| -| `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | -| `read_user` | Grants read-only access to the authenticated user's profile through the `/user` API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under [`/users`](../../api/users.md). | -| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) in GitLab 12.10.) | -| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | -| `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | -| `read_registry` | Grants read-only (pull) access to a [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. | -| `write_registry` | Grants read-write (push) access to a [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the Container Registry is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | -| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator. | -| `admin_mode` | Grants permission to perform API actions as an administrator, when Admin Mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107875) in GitLab 15.8.) | -| `create_runner` | Grants permission to create runners. | -| `ai_features` | Grants permission to perform API actions for GitLab Duo. | -| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes. | +| Scope | Access | +|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry. | +| `read_user` | Grants read-only access to the authenticated user's profile through the `/user` API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under [`/users`](../../api/users.md). | +| `read_api` | Grants read access to the API, including all groups and projects, the container registry, and the package registry. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) in GitLab 12.10.) | +| `read_repository` | Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. | +| `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | +| `read_registry` | Grants read-only (pull) access to [container registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the container registry is enabled. | +| `write_registry` | Grants read-write (push) access to [container registry](../packages/container_registry/index.md) images if a project is private and authorization is required. Available only when the container registry is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | +| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator. | +| `admin_mode` | Grants permission to perform API actions as an administrator, when Admin Mode is enabled. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/107875) in GitLab 15.8.) | +| `create_runner` | Grants permission to create runners. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes. | WARNING: -If you enabled [external authorization](../admin_area/settings/external_authorization.md), personal access tokens cannot access container or package registries. If you use personal access tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use personal access tokens with container or package registries. +If you enabled [external authorization](../../administration/settings/external_authorization.md), personal access tokens cannot access container or package registries. If you use personal access tokens to access these registries, this measure breaks this use of these tokens. Disable external authorization to use personal access tokens with container or package registries. ## When personal access tokens expire @@ -141,33 +142,32 @@ Personal access tokens expire on the date you define, at midnight, 00:00 AM UTC. [maximum allowed lifetime for the token](../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens). If the maximum allowed lifetime is not set, the default expiry date is 365 days from the date of creation. -### Service Accounts +### Create a service account personal access token with no expiry date -You can [create a personal access token for a service account](../../api/groups.md#create-personal-access-token-for-service-account-user) with no expiry date. +You can [create a personal access token for a service account](../../api/groups.md#create-personal-access-token-for-service-account-user) with no expiry date. These personal access tokens never expire, unlike non-service account personal access tokens. NOTE: Allowing personal access tokens for service accounts to be created with no expiry date only affects tokens created after you change this setting. It does not affect existing tokens. #### GitLab.com -Prerequisite: +Prerequisites: - You must have the Owner role in the top-level group. 1. On the left sidebar, select **Search or go to** and find your group. -1. Select **Settings > Permissions and group features**. +1. Select **Settings > General > Permissions and group features**. 1. Clear the **Service account token expiration** checkbox. You can now create personal access tokens for a service account user with no expiry date. #### Self-managed GitLab -Prerequisite: +Prerequisites: - You must be an administrator for your self-managed instance. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Account and limit**. 1. Clear the **Service account token expiration** checkbox. @@ -179,7 +179,7 @@ You can now create personal access tokens for a service account user with no exp You can create a predetermined personal access token as part of your tests or automation. -Prerequisite: +Prerequisites: - You need sufficient access to run a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) @@ -219,7 +219,7 @@ sudo gitlab-rails runner "token = User.find_by_username('automation-bot').person You can programmatically revoke a personal access token as part of your tests or automation. -Prerequisite: +Prerequisites: - You need sufficient access to run a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) for your GitLab instance. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 34f083e0b48..6cc5f7c5039 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Profile preferences **(FREE ALL)** @@ -272,16 +271,20 @@ To use exact times on the GitLab UI: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15206) in GitLab 16.6. -You can customize the format used to display times of activities on your group and project overview pages and user profiles. You can display times as: +You can customize the format used to display times of activities on your group and project overview pages and user +profiles. You can display times as: - 12 hour format. For example: `2:34 PM`. - 24 hour format. For example: `14:34`. +You can also follow your system's setting. + To customize the time format: 1. On the left sidebar, select your avatar. -1. Select **Preferences** > **Time preferences**. -1. In **Time format**, select either the **12-hour** or **24-hour** option. +1. Select **Preferences**. +1. Go to the **Time preferences** section. +1. Under **Time format**, select either the **System**, **12-hour**, or **24-hour** option. 1. Select **Save changes**. ## User identities in CI job JSON web tokens @@ -315,13 +318,15 @@ To access your **Followers** and **Following** tabs: - On the left sidebar, select your avatar > select your name or username. - Select **Followers** or **Following**. -## Enable Code Suggestions +## Enable Code Suggestions **(FREE SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../policy/experiment-beta-support.md#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../policy/experiment-beta-support.md#beta). +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. -Code Suggestions are disabled by default at the user account level. +A percentage of users can use Code Suggestions without any additional configuration. -To update this setting: +If the following options are available to you, it means you are **not** part of the percentage of users +and you must manually enable Code Suggestions for your account: 1. On the left sidebar, select your avatar. 1. Select **Preferences**. @@ -329,7 +334,7 @@ To update this setting: 1. Select **Save changes**. NOTE: -If Code Suggestions are disabled [for any groups that you belong to](../../user/group/manage.md#enable-code-suggestions), then you cannot enable them for yourself. (Your setting has no effect.) +If Code Suggestions are disabled [for any groups that you belong to](../../user/group/manage.md#enable-code-suggestions-for-a-group), then you cannot enable them for yourself. (Your setting has no effect.) ## Integrate your GitLab instance with third-party services diff --git a/doc/user/profile/service_accounts.md b/doc/user/profile/service_accounts.md index 8fa0067f150..3833d844d46 100644 --- a/doc/user/profile/service_accounts.md +++ b/doc/user/profile/service_accounts.md @@ -1,8 +1,7 @@ --- -type: index, howto stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service accounts **(PREMIUM ALL)** @@ -40,7 +39,7 @@ How you create an account differs depending on whether you are on GitLab.com or ### GitLab.com -Prerequisite: +Prerequisites: - You must have the Owner role in a top-level group. @@ -62,7 +61,7 @@ Prerequisite: ### Self-managed GitLab -Prerequisite: +Prerequisites: - You must be an administrator for your self-managed instance. diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md index 1b4fbd5fa53..97fd1081e05 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User passwords **(FREE ALL)** diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 0bec72d64e8..c341d2cef3e 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" description: "Autocomplete characters in Markdown fields." --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 39c1d228d63..4848217c468 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Badges **(FREE ALL)** @@ -126,26 +126,6 @@ If you set an out of range value, GitLab automatically adjusts it to the default Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. If you find that you have to add the same badges to several projects, you may want to add them at the [group level](#group-badges). -### Add a badge to a project - -To add a new badge to a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Badges**. -1. Select **Add badge**. -1. Under **Link**, enter the URL that the badges should point to. -1. Under **Badge image URL**, enter the URL of the image that should be displayed. -1. Select **Add badge**. - -After adding a badge to a project, you can see the badge in the list below the form. - -### Edit or delete a project badge - -To edit a badge, select **Edit** (**{pencil}**). - -To delete a badge, select **Delete** (**{remove}**). - ### Example project badge: Pipeline Status A common project badge presents the GitLab CI pipeline status. @@ -177,26 +157,26 @@ If you need individual badges for each project, either: - Add the badge at the [project level](#project-badges). - Use [placeholders](#placeholders). -### Add a badge to a group +## View badges -To add a new badge to a group: +To view badges available in a project or group: -1. On the left sidebar, select **Search or go to** and find your group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > General**. 1. Expand **Badges**. -1. Under "Link", enter the URL that the badges should point to and under - "Badge image URL" the URL of the image that should be displayed. -1. Select **Add badge**. - -After adding a badge to a group, you can see it in the list below the form. -### Edit or delete a group badge +## Add a badge -To edit a badge, select **Edit** (**{pencil}**). +To add a new badge to a project or group: -To delete a badge, select **Delete** (**{remove}**). - -Badges associated with a group can be edited or deleted only at the [group level](#group-badges). +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Settings > General**. +1. Expand **Badges**. +1. Select **Add badge**. +1. In the **Name** text box, enter the name of your badge. +1. In the **Link** text box, enter the URL that the badges should point to. +1. In the **Badge image URL** text box, enter the URL of the image you want to display for the badge. +1. Select **Add badge**. ## View the URL of pipeline badges @@ -283,6 +263,31 @@ To add a new badge with a custom image to a group or project: To learn how to use custom images generated through a pipeline, see the documentation on [accessing the latest job artifacts by URL](../../ci/jobs/job_artifacts.md#from-a-url). +## Edit a badge + +To edit a badge in a project or group: + +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Settings > General**. +1. Expand **Badges**. +1. Next to the badge you want to edit, select **Edit** (**{pencil}**). +1. Edit the **Name**, **Link**, or **Badge image URL**. +1. Select **Save changes**. + +## Delete a badge + +To delete a badge in a project or group: + +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Settings > General**. +1. Expand **Badges**. +1. Next to the badge you want to delete, select **Delete** (**{remove}**). +1. On the confirmation dialog, select **Delete badge**. +1. Select **Save changes**. + +NOTE: +Badges associated with a group can be edited or deleted only at the [group level](#group-badges). + ## Placeholders Both the URL a badge points to and the image URL can contain placeholders, @@ -302,9 +307,3 @@ Placeholders allow badges to expose otherwise-private information, such as the default branch or commit SHA when the project is configured to have a private repository. This behavior is intentional, as badges are intended to be used publicly. Avoid using these placeholders if the information is sensitive. - -## Configure badges through the API - -You can also configure badges via the GitLab API. As in the settings, there is -a distinction between endpoints for badges at the -[project level](../../api/project_badges.md) and [group level](../../api/group_badges.md). diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index efa1fad92b8..fe425d7420e 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Canary deployments **(FREE ALL)** diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md index 1f251565d3f..a15bd39f1b7 100644 --- a/doc/user/project/changelogs.md +++ b/doc/user/project/changelogs.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, api +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Changelogs **(FREE ALL)** @@ -72,7 +71,7 @@ in the API documentation. Prerequisites: -- You have installed and configured the [GitLab CLI](../../integration/glab/index.md), +- You have installed and configured the [GitLab CLI](../../editor_extensions/gitlab_cli/index.md), version 1.30.0 or later. - Your repository's tag naming schema matches [the expected tag naming format](#customize-the-tag-format-when-extracting-versions). diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index d8b1b6fd413..831e37dcf3c 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect EKS clusters through cluster certificates (deprecated) **(FREE ALL)** @@ -248,8 +248,7 @@ For example, the following policy document allows assuming a role whose name sta To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and follow these steps: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Amazon EKS**. 1. Check **Enable Amazon EKS integration**. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 7e2c429c6bb..161a698a48c 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect existing clusters through cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index a087460d89e..96eff58c638 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect GKE clusters through cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index a3263109bb1..940561d70d0 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Add a cluster using cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 2b57fa964c0..74f3cb689ff 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Access controls with cluster certificates (RBAC or ABAC) (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 70c96280e48..e287a3b94bb 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to a Kubernetes cluster with cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 1126e5a7241..cb053c8ede8 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab-managed clusters (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 1a69b45b651..1b6fab8fa34 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project-level Kubernetes clusters (certificate-based) (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 7763cb13cd7..4fb6ecb1336 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple clusters per project with cluster certificates (deprecated) **(FREE ALL)** diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 7f0fd954d97..7af3068c691 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Runbooks **(FREE ALL)** diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 0df0ef977c0..a7f1aff9b02 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Code Intelligence **(FREE ALL)** @@ -41,7 +40,7 @@ code_navigation: lsif: dump.lsif ``` -The generated LSIF file size may be limited by +The generated LSIF file size might be limited by the [artifact application limits (`ci_max_artifact_size_lsif`)](../../administration/instance_limits.md#maximum-file-size-per-type-of-artifact), default to 100 MB (configurable by an instance administrator). diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md index 0fa9983e93b..292be3848c1 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Owners **(PREMIUM ALL)** @@ -420,6 +420,8 @@ A Code Owner approval rule is optional if any of these conditions are true: Code Owners [cannot inherit members from parent groups](https://gitlab.com/gitlab-org/gitlab/-/issues/288851/). - [Code Owner approval on a protected branch](../protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. - The section is [marked as optional](#make-a-code-owners-section-optional). +- No eligible code owners are available to approve the merge request due to conflicts + with other [merge request approval settings](../merge_requests/approvals/settings.md#approval-settings). ### Approvals do not show diff --git a/doc/user/project/codeowners/reference.md b/doc/user/project/codeowners/reference.md index c2fbbe88b6f..558ee8c3a7e 100644 --- a/doc/user/project/codeowners/reference.md +++ b/doc/user/project/codeowners/reference.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Owners syntax and error handling **(PREMIUM ALL)** diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 91a3d71642d..e1f6bcbf5cc 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,8 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: howto, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy boards (deprecated) **(FREE ALL)** diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 73d3d97be4a..6c2d4763526 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy keys **(FREE ALL)** @@ -17,7 +17,7 @@ Depending on your needs, you might want to use a [deploy token](../deploy_tokens | Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. | | Accessible resources | Git repository over SSH | Git repository over HTTP, package registry, and container registry. | -Deploy keys can't be used for Git operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. +Deploy keys can't be used for Git operations if [external authorization](../../../administration/settings/external_authorization.md) is enabled. ## Scope @@ -65,7 +65,7 @@ As with all sensitive information, you should ensure only those who need access For human interactions, use credentials tied to users such as Personal Access Tokens. To help detect a potential secret leak, you can use the -[Audit Event](../../../administration/audit_event_streaming/examples.md#example-payloads-for-ssh-events-with-deploy-key) feature. +[Audit Event](../../../administration/audit_event_streaming/examples.md#example-payloads-for-git-over-ssh-events-with-deploy-key) feature. ## View deploy keys @@ -111,8 +111,7 @@ Prerequisites: To create a public deploy key: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Deploy Keys**. 1. Select **New deploy key**. 1. Complete the fields. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 351762228fb..c53b557a9e0 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy tokens **(FREE ALL)** @@ -25,7 +25,7 @@ A deploy token is a pair of values: You can use a deploy token for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) to the following endpoints: -- GitLab Package Registry public API. +- GitLab package registry public API. - [Git commands](https://git-scm.com/docs/gitcredentials#_description). You can create deploy tokens at either the project or group level: @@ -37,8 +37,8 @@ By default, a deploy token does not expire. You can optionally set an expiry dat it. Expiry occurs at midnight UTC on that date. WARNING: -You cannot use new or existing deploy tokens for Git operations and Package Registry operations if -[external authorization](../../admin_area/settings/external_authorization.md) is enabled. +You cannot use new or existing deploy tokens for Git operations and package registry operations if +[external authorization](../../../administration/settings/external_authorization.md) is enabled. ## Scope @@ -79,7 +79,7 @@ name and token of the group deploy token. ### GitLab public API Deploy tokens can't be used with the GitLab public API. However, you can use deploy tokens with some -endpoints, such as those from the Package Registry. For more information, see +endpoints, such as those from the package registry. For more information, see [Authenticate with the registry](../../packages/package_registry/index.md#authenticate-with-the-registry). ## Create a deploy token diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 97b350c8692..db98688497a 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Description templates **(FREE ALL)** @@ -107,10 +107,10 @@ your merge request template with their values: ### Set instance-level description templates **(PREMIUM SELF)** You can set a description template at the **instance level** for issues -and merge requests by using an [instance template repository](../admin_area/settings/instance_template_repository.md). +and merge requests by using an [instance template repository](../../administration/settings/instance_template_repository.md). You can also use the instance template repository for file templates. -You might also be interested in [project templates](../admin_area/custom_project_templates.md) +You might also be interested in [project templates](../../administration/custom_project_templates.md) that you can use when creating a new project in the instance. ### Set group-level description templates **(PREMIUM ALL)** diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 783f5f3ee7c..48a09d99c21 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File Locking **(FREE ALL)** diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 5e67706708d..61e73fcce81 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Git attributes **(FREE ALL)** @@ -52,3 +51,72 @@ For more information, see [working-tree-encoding](https://git-scm.com/docs/gitat The `.gitattributes` file can be used to define which language to use when syntax highlighting files and diffs. For more information, see [Syntax highlighting](highlighting.md). + +## Custom merge drivers **(FREE SELF)** + +> Ability to configure custom merge drivers through GitLab introduced in GitLab 15.10. + +GitLab self-managed instance administrators can define [custom merge drivers](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver) +in a GitLab configuration file, then use the custom merge drivers in a Git `.gitattributes` file. Custom merge drivers are not supported on GitLab.com. + +You might configure a custom merge driver, for example, if there are certain +files that should be ignored during a merge such as build files and configuration files. + +### Configure a custom merge driver + +The following example illustrates how to define and use a custom merge driver in +GitLab. + +How to configure a custom merge driver depends on the type of installation. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. Edit `/etc/gitlab/gitlab.rb`. +1. Add configuration similar to the following: + + ```ruby + gitaly['configuration'] = { + # ... + git: { + # ... + config: [ + # ... + { key: "merge.foo.driver", value: "true" }, + ], + }, + } + ``` + +:::TabTitle Self-compiled (source) + +1. Edit `gitaly.toml`. +1. Add configuration similar to the following: + + ```toml + [[git.config]] + key = "merge.foo.driver" + value = "true" + ``` + +::EndTabs + +In this example, during a merge, Git uses the `driver` value as the command to execute. In +this case, because we are using [`true`](https://man7.org/linux/man-pages/man1/true.1.html) +with no arguments, it always returns a non-zero return code. This means that for +the files specified in `.gitattributes`, merges do nothing. + +To use your own merge driver, replace the value in `driver` to point to an +executable. For more details on how this command is invoked, see the Git +documentation on [custom merge drivers](https://git-scm.com/docs/gitattributes#_defining_a_custom_merge_driver). + +### Use `.gitattributes` to set files custom merge driver applies to + +In a `.gitattributes` file, you can set the paths of files you want to use with the custom merge driver. For example: + +```plaintext +config/* merge=foo +``` + +In this case, every file under the `config/` folder uses the custom merge driver called `foo` defined in the GitLab configuration. diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index ba7d7d39e84..54f529302ae 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Syntax Highlighting **(FREE ALL)** diff --git a/doc/user/project/img/global_time_report_v16_5.png b/doc/user/project/img/global_time_report_v16_5.png Binary files differnew file mode 100644 index 00000000000..36feb9591ae --- /dev/null +++ b/doc/user/project/img/global_time_report_v16_5.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index bafcbbb9cbd..92c14347a15 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -1,17 +1,16 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Import your project from Bitbucket Cloud to GitLab **(FREE ALL)** +# Import your project from Bitbucket Cloud **(FREE ALL)** -NOTE: -The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket -Server (aka Stash). If you are trying to import projects from Bitbucket Server, use -[the Bitbucket Server importer](bitbucket_server.md). +> - Parallel imports from Bitbucket Cloud [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/412614) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `bitbucket_parallel_importer`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/423530) in GitLab 16.6. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/423530) in GitLab 16.7. Feature flag `bitbucket_parallel_importer` removed. -Import your projects from Bitbucket Cloud to GitLab with minimal effort. +Import your projects from Bitbucket Cloud to GitLab. The Bitbucket importer can import: @@ -23,6 +22,9 @@ The Bitbucket importer can import: - Pull request comments - Milestones - Wiki +- Labels +- Milestones +- LFS objects When importing: @@ -30,29 +32,46 @@ When importing: - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. -## Prerequisites - -> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. - -- [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator - to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. -- [Bitbucket Cloud import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your - GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. -- At least the Maintainer role on the destination group to import to. - -## How it works +NOTE: +The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket +Server (aka Stash). If you are trying to import projects from Bitbucket Server, use +[the Bitbucket Server importer](bitbucket_server.md). -When issues/pull requests are being imported, the Bitbucket importer uses the Bitbucket nickname of +When issues, pull requests, and comments are imported, the Bitbucket importer uses the Bitbucket nickname of the author/assignee and tries to find the same Bitbucket identity in GitLab. If they don't match or the user is not found in the GitLab database, the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket author is kept. +For pull requests: + +- If the source SHA does not exist in the repository, the importer attempts to set the source commit to the merge commit SHA. +- The merge request assignee is set to the author. Reviewers are set with usernames matching Bitbucket identities in GitLab. +- Approvals are not imported. +- Merge requests in GitLab can be either can be either `opened`, `closed` or `merged`. + +For issues: + +- A label is added corresponding to the type of issue on Bitbucket. Either `bug`, `enhancement`, `proposal` or `task`. +- If the issue on Bitbucket was one of `resolved`, `invalid`, `duplicate`, `wontfix`, or `closed`, the issue is closed on GitLab. + The importer creates any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository is imported under the user's namespace that started the import process. -## Requirements for user-mapped contributions +## Prerequisites + +> Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. + +- [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be enabled. If that integration is not enabled, ask your GitLab administrator + to enable it. The Bitbucket Cloud integration is enabled by default on GitLab.com. +- [Bitbucket Cloud import source](../../../administration/settings/import_and_export_settings.md#configure-allowed-import-sources) must be enabled. If not enabled, ask your + GitLab administrator to enable it. The Bitbucket Cloud import source is enabled by default on GitLab.com. +- At least the Maintainer role on the destination group to import to. +- Pull requests in Bitbucket must have the same source and destination project and not be from a fork of a project. + Otherwise, the pull requests are imported as empty merge requests. + +### Requirements for user-mapped contributions For user contributions to be mapped, each user must complete the following before the project import: @@ -117,5 +136,5 @@ current Bitbucket public name, and reconnect if there's a mismatch: 1. Following reconnection, the user should use the API again to verify that their `extern_uid` in the GitLab database now matches their current Bitbucket public name. -The importer must then [delete the imported project](../../project/settings/index.md#delete-a-project) +The importer must then [delete the imported project](../../project/working_with_projects.md#delete-a-project) and import again. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 4afe23a29fa..41076bfbc67 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -1,34 +1,21 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from Bitbucket Server **(FREE ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. - -NOTE: -This process is different than [importing from Bitbucket Cloud](bitbucket.md). - -From Bitbucket Server, you can import: - -- Repository description -- Git repository data -- Pull requests -- Pull request comments - -When importing, repository public access is retained. If a repository is private in Bitbucket, it's -created as private in GitLab as well. - -## Import your Bitbucket repositories - > - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. > - Ability to import reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416611) in GitLab 16.3. +> - Support for pull request approval imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/135256) in GitLab 16.7. + +Import your projects from Bitbucket Server to GitLab. -You can import Bitbucket repositories to GitLab. +NOTE: +This process is different than [importing from Bitbucket Cloud](bitbucket.md). -### Prerequisites +## Prerequisites > Requirement for Maintainer role instead of Developer role introduced in GitLab 16.0 and backported to GitLab 15.11.1 and GitLab 15.10.5. @@ -36,8 +23,9 @@ You can import Bitbucket repositories to GitLab. must be enabled. If not enabled, ask your GitLab administrator to enable it. The Bitbucket Server import source is enabled by default on GitLab.com. - At least the Maintainer role on the destination group to import to. +- Bitbucket Server authentication token with administrator access. -### Import repositories +## Import repositories To import your Bitbucket repositories: @@ -52,16 +40,34 @@ To import your Bitbucket repositories: - For the first time: Select **Import**. - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. -### Items that are not imported +## Items that are imported + +- Repository description +- Git repository data +- Pull requests +- Pull request comments, reviewers, approvals, and merge events +- LFS objects + +When importing, repository public access is retained. If a repository is private in Bitbucket, it's +created as private in GitLab as well. + +When closed or merged pull requests are imported, commit SHAs that do not exist in the repository are fetched from the Bitbucket server +to make sure pull requests have commits tied to them: + +- Source commit SHAs are saved with references in the format `refs/merge-requests/<iid>/head`. +- Target commit SHAs are saved with references in the format `refs/keep-around/<SHA>`. + +If the source commit does not exist in the repository, a commit containing the SHA in the commit message is used instead. + +## Items that are not imported The following items aren't imported: -- Pull request approvals - Attachments in Markdown - Task lists - Emoji reactions -### Items that are imported but changed +## Items that are imported but changed The following items are changed when they are imported: @@ -69,15 +75,12 @@ The following items are changed when they are imported: inserted as comments in the merge request. - Multiple threading levels are collapsed into one thread and quotes are added as part of the original comment. -- Declined pull requests have unreachable commits. These pull requests show up as empty changes. - Project filtering doesn't support fuzzy search. Only **starts with** or **full match** strings are supported. ## User assignment -Prerequisite: - -- Authentication token with administrator access. +> Importing approvals by email address or username [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23586) in GitLab 16.7. When issues and pull requests are importing, the importer tries to find the author's email address with a confirmed email address in the GitLab user database. If no such user is available, the @@ -87,8 +90,10 @@ original creator. The importer creates any new namespaces (groups) if they don't exist. If the namespace is taken, the repository imports under the namespace of the user who started the import process. -The importer attempts to find reviewers by their email address in the GitLab user database. If they don't exist in GitLab, they cannot be added as reviewers to a -merge request. +The importer attempts to find: + +- Reviewers by their email address in the GitLab user database. If they don't exist in GitLab, they are not added as reviewers to a merge request. +- Approvers by username or email. If they don't exist in GitLab, the approval is not added to a merge request. ### User assignment by username @@ -129,16 +134,6 @@ If the project import completes but LFS objects can't be downloaded or cloned, y password or personal access token containing special characters. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337769). -### Pull requests are missing - -Importing large projects spawns a process that can consume a lot of memory. Sometimes you can see messages such as `Sidekiq worker RSS out of range` in the -[Sidekiq logs](../../../administration/logs/index.md#sidekiq-logs). This can mean that MemoryKiller is interrupting the `RepositoryImportWorker` because it's using -too much memory. - -To resolve this problem, temporarily increase the `SIDEKIQ_MEMORY_KILLER_MAX_RSS` environment variable using -[custom environment variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html) from the default `2000000` value to a larger value like `3000000`. -Consider memory constraints on the system before deciding to increase `SIDEKIQ_MEMORY_KILLER_MAX_RSS`. - ## Related topics - [Automate group and project import](index.md#automate-group-and-project-import) diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 30a85a108c9..13d068a8262 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from ClearCase **(FREE ALL)** diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 90ed6cfdb2c..b7f2c0229dc 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from CVS **(FREE ALL)** diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 2bce6708556..1e1b86224d5 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from FogBugz to GitLab **(FREE ALL)** diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 9629ec03443..b67f2c1bdc0 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from Gitea to GitLab **(FREE ALL)** diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index f9b94774809..87467cbc56c 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from GitHub to GitLab **(FREE ALL)** @@ -14,8 +14,7 @@ You can import your GitHub projects from either GitHub.com or GitHub Enterprise. migrate or import any types of groups or organizations from GitHub to GitLab. The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or -`gitlab.com/customer-success`. You can use bulk actions in the rails console to move projects to -different namespaces. +`gitlab.com/customer-success`. If you are importing from GitHub Enterprise to GitLab.com, use the [GitLab Import API](../../../api/import.md#import-repository-from-github) GitHub endpoint instead. The API allows you to @@ -79,61 +78,46 @@ If you are importing from GitHub.com to a self-managed GitLab instance: - GitHub pull request comments (known as diff notes in GitLab) created before 2017 are imported in separate threads. This occurs because of a limitation of the GitHub API that doesn't include `in_reply_to_id` for comments before 2017. -- Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/383047), if you are using GitHub as an - OmniAuth provider, ensure that the URL perimeter is specified in the - [OmniAuth configuration](../../../integration/github.md#enable-github-oauth-in-gitlab). - Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/424400), Markdown attachments from repositories on GitHub Enterprise Server instances aren't imported. +- Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/418800), when importing projects that used + [GitHub auto-merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request), the imported project in GitLab can have merge commits labeled "unverified" if the commit was signed with GitHub's internal GPG key. ## Import your GitHub repository into GitLab -### Use the GitHub integration - -Before you begin, ensure that any GitHub user you want to map to a GitLab user has a GitLab email address that matches their -[publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) on GitHub. - -If you are importing to GitLab.com, you can alternatively import GitHub repositories using a [personal access token](#use-a-github-token). +Before you begin, ensure that any GitHub user you want to map to a GitLab user +has a GitLab email address that matches their +[publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) +on GitHub. -If a GitHub user's public email address doesn't match any GitLab user email address, the user's activity is associated with the user account that is +If a GitHub user's public email address doesn't match any GitLab user email +address, the user's activity is associated with the user account that is performing the import. -NOTE: -If you are using a self-managed GitLab instance or if you are importing from GitHub Enterprise, this process requires that you have configured -[GitHub integration](../../../integration/github.md). +### Use the GitHub integration 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Import project** and then **GitHub**. 1. Now you can either: - - Add a personal access token and select **Authenticate**. - - If GitHub is [configured](../../../integration/github.md) for the instance, select **Authorize with GitHub**. -1. Select **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. + - If GitHub OAuth is [configured](../../../integration/github.md) for the instance, select **Authorize with GitHub**. + - Use a GitHub personal access token: + 1. Go to <https://github.com/settings/tokens/new>. + 1. In the **Note** field, enter a token description. + 1. Select the `repo` scope. + 1. Optional. To [import collaborators](#select-additional-items-to-import), select the `read:org` scope. + 1. Select **Generate token**. + 1. On the GitLab import page, in the **Personal Access Token** field, paste the GitHub personal access token. + 1. Select **Authenticate**. 1. Continue on to [selecting which repositories to import](#select-which-repositories-to-import). -### Use a GitHub token - -Prerequisite: +To use a different token to perform an imports after previously performing +these steps, sign out of your GitLab account and sign in again, or revoke the +older token in GitHub. -- Authentication token with administrator access. +### Use the REST API -If you are a GitLab.com user, you can use a personal access token to import your project from GitHub. -If you are an administrator of a self-managed GitLab instance or if you are importing from -GitHub Enterprise, you cannot use a personal access token. -The [GitHub integration method (above)](#use-the-github-integration) is recommended for all users. - -If you are not using the GitHub integration, you can still perform an authorization with GitHub to grant GitLab access your repositories: - -1. Go to `https://github.com/settings/tokens/new`. -1. Enter a token description. -1. Select the `repo` scope. -1. Optional. To [import collaborators](#select-additional-items-to-import), select the `read:org` scope. -1. Select **Generate token**. -1. Copy the token hash. -1. Go back to GitLab and provide the token to the GitHub importer. -1. Select **List Your GitHub Repositories** and wait while GitLab reads your repositories' information. - When done, you are taken to the importer page to select the repositories to import. - -To use a newer personal access token in imports after previously performing these steps, sign out of -your GitLab account and sign in again, or revoke the older personal access token in GitHub. +You can also import a repository from GitHub using the +[GitLab REST API](../../../api/import.md#import-repository-from-github). ### Filter repositories list @@ -165,7 +149,7 @@ To make imports as fast as possible, the following items aren't imported from Gi You can choose to import these items, but this could significantly increase import time. To import these items, select the appropriate fields in the UI: - **Import issue and pull request events**. -- **Use alternative comments import method**. If importing GitHub projects with more than approximately 30,000 comments, you should enable this method because of a +- **Use alternative comments import method**. If importing GitHub projects with more than approximately 30,000 comments across all issues and pull requests, you should enable this method because of a [limitation of the GitHub API](#missing-comments). - **Import Markdown attachments**. - **Import collaborators** (selected by default). Leaving it selected might result in new users using a seat in the group or namespace, @@ -226,7 +210,9 @@ Mirroring does not sync any new or updated pull requests from your GitHub projec ## Improve the speed of imports on self-managed instances -Administrator access on the GitLab server is required for this process. +Administrator access on the GitLab server is required for these steps. + +### Increase the number of Sidekiq workers For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: @@ -242,6 +228,33 @@ Reducing the time spent in cloning a repository can be done by increasing networ performance (by using high performance SSDs, for example) of the disks that store the Git repositories (for your GitLab instance). Increasing the number of Sidekiq workers does *not* reduce the time spent cloning repositories. +### Enable GitHub OAuth using a GitHub Enterprise Cloud OAuth App + +You can use a personal access token to make API requests. Additionally, you can +authorize a GitHub App or OAuth app, which can then make API requests on your +behalf. + +API requests to GitHub are [subject to rate limits](https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-authenticated-users). + +For GitHub repositories with tens of thousands of issues, pull requests, and +comments on those issues and pull requests, a higher rate limit results in a +faster overall import time because the GitLab importer must pause when a +GitHub rate limit is reached. To enable a higher rate limit for your +self-managed or dedicated GitLab instance: + +- Ensure that you have access to a + [GitHub Enterprise Cloud organization](https://docs.github.com/en/enterprise-cloud@latest/get-started/onboarding/getting-started-with-github-enterprise-cloud) +- [Create an OAuth app in GitHub](../../../integration/github.md#create-an-oauth-app-in-github). +- Ensure that the OAuth app is owned by the Enterprise Cloud Organization, not + your personal GitHub account. +- [Configure GitHub OAuth in GitLab](../../../integration/github.md#enable-github-oauth-in-gitlab). +- Perform the project import using the [GitHub integration](#use-the-github-integration) and select **Authorize with GitHub** to use the OAuth authorization method. +- Optional. By default, sign-in is enabled for all configured OAuth providers. + If you want to enable GitHub OAuth for imports but you want to + prevent the ability for users to sign in to your GitLab instance with GitHub, + you can + [disable sign-in with GitHub](../../../integration/omniauth.md#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). + ## Imported data The following items of a project are imported: diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 26054317441..e604d9d871b 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import a project from GitLab.com to your self-managed GitLab instance (removed) **(FREE ALL)** diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index e47e9715980..681174400a2 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import and migrate projects **(FREE ALL)** @@ -41,8 +41,7 @@ with a malicious `.gitlab-ci.yml` file could allow an attacker to exfiltrate gro GitLab self-managed administrators can reduce their attack surface by disabling import sources they don't need: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 921669e4b70..17ba5e5fb91 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your Jira project issues to GitLab **(FREE ALL)** diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index aaf19439c24..07328c7a672 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import multiple repositories by uploading a manifest file **(FREE ALL)** diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 10e61139d50..1646c2c5578 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from Perforce Helix **(FREE ALL)** diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 375cb718538..5d67d10582d 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import project from repository by URL **(FREE ALL)** @@ -19,10 +19,8 @@ You can import your existing repositories by providing the Git URL. ## Import project by URL -1. On the left sidebar, select **Search or go to**. -1. Select **View all my projects**. -1. On the right of the page, select **New project**. -1. Select the **Import project** tab. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. +1. Select **Import project**. 1. Select **Repository by URL**. 1. Enter a **Git repository URL**. 1. Complete the remaining fields. diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index b66e8431f9b..7617dfae525 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate from TFVC to Git **(FREE ALL)** diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 9ee1e33ecdd..7a70d5dde63 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Create a project **(FREE ALL)** @@ -15,7 +15,7 @@ To create a blank project: 1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. 1. Select **Create blank project**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. + - In the **Project name** field, enter the name of your project. See the [limitations on project names](../../user/reserved_names.md). - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -52,7 +52,7 @@ To create a project from a built-in template: - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. - - In the **Project description (optional)** field, enter the description of your project's dashboard. + - In the **Project description (optional)** field, enter the description of your project's dashboard. The description is limited to 500 characters. - To modify the project's [viewing and access rights](../public_access.md) for users, change the **Visibility Level**. 1. Select **Create project**. @@ -82,7 +82,7 @@ Custom project templates are available at: - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. - - The description of your project's dashboard in the **Project description (optional)** field. + - The description of your project's dashboard in the **Project description (optional)** field. The description is limited to 500 characters. - To modify the project's [viewing and access rights](../public_access.md) for users, change the **Visibility Level**. 1. Select **Create project**. @@ -107,7 +107,7 @@ To create a project from the HIPAA Audit Protocol template: - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. - - In the **Project description (optional)** field, enter the description of your project's dashboard. + - In the **Project description (optional)** field, enter the description of your project's dashboard. The description is limited to 500 characters. - To modify the project's [viewing and access rights](../public_access.md) for users, change the **Visibility Level**. 1. Select **Create project**. @@ -122,7 +122,7 @@ GitLab creates your project in your chosen namespace. You cannot use `git push` to create projects with project paths that: - Have previously been used. -- Have been [renamed](settings/index.md#rename-a-repository). +- Have been [renamed](working_with_projects.md#rename-a-repository). Previously used project paths have a redirect. The redirect causes push attempts to redirect requests to the renamed project location, instead of creating a new project. To create a new project for a previously diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index d8ad7f9a29c..8a91a0c4621 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Insights for projects **(ULTIMATE ALL)** diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 763f478eb99..3031ae42e4d 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -1,10 +1,10 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Apple App Store **(FREE ALL)** +# Apple App Store Connect **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/385335) in GitLab 15.10. Feature flag `apple_app_store_integration` removed. @@ -16,9 +16,9 @@ The feature is still in development, but you can: - [Report a bug](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=report_bug). - [Share feedback](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=general_feedback). -With the Apple App Store integration, you can configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. +With the Apple App Store Connect integration, you can configure your CI/CD pipelines to connect to [App Store Connect](https://appstoreconnect.apple.com) to build and release apps for iOS, iPadOS, macOS, tvOS, and watchOS. -The Apple App Store integration works out of the box with [fastlane](https://fastlane.tools/). You can also use this integration with other build tools. +The Apple App Store Connect integration works out of the box with [fastlane](https://fastlane.tools/). You can also use this integration with other build tools. ## Prerequisites @@ -26,7 +26,7 @@ An Apple ID enrolled in the [Apple Developer Program](https://developer.apple.co ## Configure GitLab -GitLab supports enabling the Apple App Store integration at the project level. Complete these steps in GitLab: +GitLab supports enabling the Apple App Store Connect integration at the project level. Complete these steps in GitLab: 1. In the Apple App Store Connect portal, generate a new private key for your project by following [these instructions](https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api). 1. On the left sidebar, select **Search or go to** and find your project. @@ -36,15 +36,15 @@ GitLab supports enabling the Apple App Store integration at the project level. C 1. Provide the Apple App Store Connect configuration information: - **Issuer ID**: The Apple App Store Connect issuer ID. - **Key ID**: The key ID of the generated private key. - - **Private Key**: The generated private key. You can download this key only once. - - **Protected branches and tags only**: Enable to only set variables on protected branches and tags. + - **Private key**: The generated private key. You can download this key only once. + - **Protected branches and tags only**: Enable to set variables on protected branches and tags only. 1. Select **Save changes**. -After the Apple App Store integration is activated: +After you enable the integration: - The global variables `$APP_STORE_CONNECT_API_KEY_ISSUER_ID`, `$APP_STORE_CONNECT_API_KEY_KEY_ID`, `$APP_STORE_CONNECT_API_KEY_KEY`, and `$APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64` are created for CI/CD use. -- `$APP_STORE_CONNECT_API_KEY_KEY` contains the Base64 encoded Private Key. +- `$APP_STORE_CONNECT_API_KEY_KEY` contains the Base64-encoded private key. - `$APP_STORE_CONNECT_API_KEY_IS_KEY_CONTENT_BASE64` is always `true`. ## Security considerations @@ -52,7 +52,7 @@ After the Apple App Store integration is activated: ### CI/CD variable security Malicious code pushed to your `.gitlab-ci.yml` file could compromise your variables, including -`$APP_STORE_CONNECT_API_KEY_KEY`, and send them to a third-party server. For more details, see +`$APP_STORE_CONNECT_API_KEY_KEY`, and send them to a third-party server. For more information, see [CI/CD variable security](../../../ci/variables/index.md#cicd-variable-security). ## Enable the integration in fastlane diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 442b8695136..1ce01973b2f 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Asana **(FREE ALL)** diff --git a/doc/user/project/integrations/aws_codepipeline.md b/doc/user/project/integrations/aws_codepipeline.md index 5404101b4f6..ec398918fde 100644 --- a/doc/user/project/integrations/aws_codepipeline.md +++ b/doc/user/project/integrations/aws_codepipeline.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # AWS CodePipeline **(FREE SAAS)** diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 85cab40626d..f2b8c9efc1c 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Atlassian Bamboo **(FREE ALL)** diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 8b04d6aad8e..d9971f9a5fa 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Bugzilla **(FREE ALL)** @@ -39,7 +39,7 @@ project pages. This link takes you to the appropriate Bugzilla project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). ## Reference Bugzilla issues in GitLab diff --git a/doc/user/project/integrations/clickup.md b/doc/user/project/integrations/clickup.md index dc93ff8ed06..53db9f22c54 100644 --- a/doc/user/project/integrations/clickup.md +++ b/doc/user/project/integrations/clickup.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ClickUp **(FREE ALL)** @@ -34,7 +34,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). ## Reference ClickUp issues in GitLab diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 0a31e66fe96..4eb71f815a2 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom issue tracker **(FREE ALL)** diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 29d92b16e32..e8e33eade1a 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Discord Notifications **(FREE ALL)** diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 5c1130c7893..029803f3cc4 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Emails on push **(FREE ALL)** diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 831078e4e4b..8ec62d22a73 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Engineering Workflow Management (EWM) **(FREE ALL)** diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index c368a9da2f6..9249ee68c04 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitHub **(PREMIUM ALL)** diff --git a/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md b/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md new file mode 100644 index 00000000000..363e7c2c364 --- /dev/null +++ b/doc/user/project/integrations/gitlab_slack_app_troubleshooting.md @@ -0,0 +1,48 @@ +--- +stage: Manage +group: Import and Integrate +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting GitLab for Slack app **(FREE ALL)** + +When configuring the GitLab for Slack app on GitLab.com, you might encounter the following issues. + +For self-managed GitLab, see [GitLab for Slack app administration](../../../administration/settings/slack_app.md#troubleshooting). + +## The app does not appear in the list of integrations + +The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../../administration/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. + +The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). + +## Project or alias not found + +Some Slack commands must have a project full path or alias and fail with the following error +if the project cannot be found: + +```plaintext +GitLab error: project or alias not found +``` + +To resolve this issue, ensure: + +- The project full path is correct. +- If using a [project alias](gitlab_slack_application.md#create-a-project-alias-for-slash-commands), the alias is correct. +- The GitLab for Slack app is [enabled for the project](gitlab_slack_application.md#from-project-integration-settings). + +## Slash commands return an error in Slack + +Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. +To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../../administration/settings/slack_app.md) on your self-managed instance. + +## Notifications are not received to a channel + +If you're not receiving notifications to a Slack channel, ensure: + +- The channel name you configured is correct. +- If the channel is private, you've [added the GitLab for Slack app to the channel](gitlab_slack_application.md#receive-notifications-to-a-private-channel). + +## The App Home does not display properly + +If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](gitlab_slack_application.md#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index abfd4243e07..0a42b363eb6 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab for Slack app **(FREE ALL)** @@ -20,7 +20,7 @@ you run in Slack is run by your linked GitLab user. Prerequisites: - You must have the [appropriate permissions to add apps to your Slack workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). -- On self-managed GitLab, an administrator must [enable the integration](../../admin_area/settings/slack_app.md). +- On self-managed GitLab, an administrator must [enable the integration](../../../administration/settings/slack_app.md). In GitLab 15.0 and later, the GitLab for Slack app uses [granular permissions](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). @@ -170,46 +170,3 @@ The following events are available for Slack notifications: | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | - -## Troubleshooting - -When configuring the GitLab for Slack app on GitLab.com, you might encounter the following issues. - -For self-managed GitLab, see [GitLab for Slack app administration](../../../administration/settings/slack_app.md#troubleshooting). - -### The app does not appear in the list of integrations - -The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../../administration/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. - -The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). - -### Project or alias not found - -Some Slack commands must have a project full path or alias and fail with the following error -if the project cannot be found: - -```plaintext -GitLab error: project or alias not found -``` - -As a workaround, ensure: - -- The project full path is correct. -- If using a [project alias](#create-a-project-alias-for-slash-commands), the alias is correct. -- The GitLab for Slack app is [enabled for the project](#from-project-integration-settings). - -### Slash commands return an error in Slack - -Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. -To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../../administration/settings/slack_app.md) on your self-managed instance. - -### Notifications are not received to a channel - -If you're not receiving notifications to a Slack channel, ensure: - -- The channel name you configured is correct. -- If the channel is private, you've [added the GitLab for Slack app to the channel](#receive-notifications-to-a-private-channel). - -### The App Home does not display properly - -If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/google_play.md b/doc/user/project/integrations/google_play.md index 1affa7abfb4..70a1fe5b054 100644 --- a/doc/user/project/integrations/google_play.md +++ b/doc/user/project/integrations/google_play.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Play **(FREE ALL)** diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index e0d30f63ad9..da7fbabd84e 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Chat **(FREE ALL)** diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 9d6be5da810..af81dda6ac1 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Harbor **(FREE ALL)** diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 01dbdd0b3f2..bf1d0826e11 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project integrations **(FREE ALL)** @@ -23,7 +23,7 @@ You can use: ## Manage group-level default settings for a project integration -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the group. @@ -64,7 +64,7 @@ is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). ### Remove a group-level default setting -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the group. @@ -79,7 +79,7 @@ Resetting a group-level default setting removes integrations that use default se ## Use instance-level or group-level default settings for a project integration -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. @@ -95,7 +95,7 @@ To use instance-level or group-level default settings for a project integration: ## Use custom settings for a project or group integration -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project or group. @@ -131,7 +131,7 @@ To use custom settings for a project or group integration: | [GitHub](github.md) | Receive statuses for commits and pull requests. | **{dotted-circle}** No | | [GitLab for Slack app](gitlab_slack_application.md) | Use the native Slack app to receive notifications and run commands. | **{dotted-circle}** No | | [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat. | **{dotted-circle}** No | -| [Harbor](harbor.md) | Use Harbor as the Container Registry for GitLab. | **{dotted-circle}** No | +| [Harbor](harbor.md) | Use Harbor as the container registry for GitLab. | **{dotted-circle}** No | | [irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | | [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | | JetBrains TeamCity | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 146123f97cd..4b55dda5388 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # irker (IRC gateway) **(FREE ALL)** diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 9588fbff922..0a82a94d998 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mattermost notifications **(FREE ALL)** diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 715e744988c..f78f637a4df 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mattermost slash commands **(FREE ALL)** @@ -67,8 +67,7 @@ To get configuration values from GitLab: 1. In a different browser tab, sign in to GitLab as a user with administrator access. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Mattermost slash commands**. GitLab displays potential values for Mattermost settings. 1. Copy the **Request URL** value. All other values are suggestions. @@ -109,7 +108,7 @@ Your slash command can now communicate with your GitLab project. ## Connect your GitLab account to Mattermost -Prerequisite: +Prerequisites: - To run [slash commands](gitlab_slack_application.md#slash-commands), you must have [permission](../../permissions.md#project-members-permissions) to diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index dea34709dff..889849f2182 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Microsoft Teams notifications **(FREE ALL)** diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md deleted file mode 100644 index ce092d10d20..00000000000 --- a/doc/user/project/integrations/mlflow_client.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../ml/experiment_tracking/mlflow_client.md' -remove_date: '2023-10-12' ---- - -This document was moved to [another location](../ml/experiment_tracking/mlflow_client.md). - -<!-- This redirect file can be deleted after <2023-10-12>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index ddd000f4c0e..745e70d7d1e 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mock CI **(FREE ALL)** diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md index bf485d73691..cc9f2f468a0 100644 --- a/doc/user/project/integrations/pipeline_status_emails.md +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline status emails **(FREE ALL)** diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index cd0a1819afd..a94391b9362 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pivotal Tracker **(FREE ALL)** diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index 3f1907d04cb..d5adee65456 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pumble **(FREE ALL)** @@ -26,8 +26,7 @@ notifications: 1. To enable the integration for your group or project: 1. In your group or project, on the left sidebar, select **Settings > Integrations**. 1. To enable the integration for your instance: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select the **Pumble** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index a66aa9cd00a..adc362fa07b 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redmine **(FREE ALL)** @@ -38,7 +38,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). ## Reference Redmine issues in GitLab diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index 156ff4a54aa..67613c35657 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ServiceNow **(FREE ALL)** diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index 6ea0cfa6fff..9ed1b471101 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -1,38 +1,12 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2024-02-13' +redirect_to: 'index.md' --- -# Shimo (deprecated) **(FREE ALL)** +# Shimo (removed) **(FREE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 [with a flag](../../../administration/feature_flags.md) named `shimo_integration`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. Feature flag `shimo_integration` removed. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7. -This change is a breaking change. - -[Shimo](https://shimo.im/) is a productivity suite that includes documents, spreadsheets, and slideshows in one interface. -With this integration, you can use the Shimo wiki directly in GitLab instead of the [GitLab group or project wiki](../wiki/index.md). - -## Configure settings in GitLab - -To enable the Shimo integration for your project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > Integrations**. -1. Select **Shimo**. -1. Under **Enable integration**, ensure the **Active** checkbox is selected. -1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). -1. Select **Save changes**. - -On the left sidebar, **Shimo** now appears instead of **Wiki**. - -## View the Shimo Workspace - -To view the Shimo Workspace from your group or project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Shimo**. -1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136143) in 16.7. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index d48fd929d54..9b92fa35e24 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!--- start_remove The following content will be removed on remove_date: '2024-05-22' --> @@ -11,8 +11,6 @@ WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) in GitLab 15.9 and is planned for removal in 17.0. Use the [GitLab for Slack app](gitlab_slack_application.md) instead. This change is a breaking change. -For the planned support of the GitLab for Slack app for self-managed instances, -see [epic 1211](https://gitlab.com/groups/gitlab-org/-/epics/1211). The Slack notifications integration enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 67894e158c8..49fbd0eb694 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Slack slash commands **(FREE SELF)** diff --git a/doc/user/project/integrations/squash_tm.md b/doc/user/project/integrations/squash_tm.md index 75849d61551..6a1ca89f4b7 100644 --- a/doc/user/project/integrations/squash_tm.md +++ b/doc/user/project/integrations/squash_tm.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Squash TM **(FREE SELF)** diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md index 94d0f887730..a7a0a58b922 100644 --- a/doc/user/project/integrations/telegram.md +++ b/doc/user/project/integrations/telegram.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Telegram **(FREE ALL)** @@ -43,8 +43,7 @@ After you invite the bot to a Telegram channel, you can configure GitLab to send 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. - **For your instance:** - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select **Telegram**. 1. Under **Enable integration**, select the **Active** checkbox. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 34f8cf262cd..e0dbf3e59aa 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unify Circuit **(FREE ALL)** diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index b675ffa7a36..2a7ad52d9d3 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webex Teams **(FREE ALL)** @@ -29,8 +29,7 @@ notifications: 1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Settings > Integrations**. - At the instance level: - 1. On the left sidebar, select **Search or go to**. - 1. Select **Admin Area**. + 1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Integrations**. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 73450971434..11d164d68e9 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webhook events **(FREE ALL)** @@ -1492,7 +1492,7 @@ Payload example: "docker" ] }, - "environment": null + "environment": null, "source_pipeline":{ "project":{ "id": 41, diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 1ecc14edcd3..33da78191c0 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webhooks **(FREE ALL)** diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index c05083a1d83..bf0c3ff215f 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # YouTrack **(FREE ALL)** @@ -30,7 +30,7 @@ project pages. This link takes you to the appropriate YouTrack project. You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. For more information about the steps and consequences of disabling GitLab issues, see -Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/index.md#configure-project-features-and-permissions). +Configure project [visibility](../../../user/public_access.md#change-project-visibility), [features, and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). ## Reference YouTrack issues in GitLab diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index 64967e94f68..d6f4816b7bb 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ZenTao (deprecated) **(PREMIUM ALL)** diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 8e3310d3234..e6fd302e4f0 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue boards **(FREE ALL)** @@ -133,10 +133,10 @@ With [multiple issue boards](#multiple-issue-boards), each team can have their own board to organize their workflow individually. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=2IaMXteKSD4">Portfolio Planning - Portfolio Management</a>. + See the video: <a href="https://www.youtube.com/watch?v=d9scVJUIF4c">Portfolio Planning - Portfolio Management</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/2IaMXteKSD4" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/d9scVJUIF4c" frameborder="0" allowfullscreen> </iframe> </figure> #### Scrum team diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index e112c5ebd0d..87611a9cda6 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Associate a Zoom meeting with an issue **(FREE ALL)** diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 60b50251555..21cdd88d701 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Confidential issues **(FREE ALL)** diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index cd4ef43d333..a86a94fdea0 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create an issue **(FREE ALL)** diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 882e4d97938..de321cedebd 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Crosslinking issues **(FREE ALL)** diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 34a9b69038b..d87fb9e1775 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export issues to CSV **(FREE ALL)** diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 9770c333cdd..f2f56f5566e 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Importing issues from CSV **(FREE ALL)** @@ -13,6 +13,7 @@ You can import issues to a project by uploading a CSV file with the following co | `title` | **{check-circle}** Yes | Issue title. | | `description` | **{check-circle}** Yes | Issue description. | | `due_date` | **{dotted-circle}** No | Issue due date in `YYYY-MM-DD` format. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91317) in GitLab 15.2. | +| `milestone` | **{dotted-circle}** No | Title of the issue milestone. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112204) in GitLab 16.7. | Data in other columns is not imported. @@ -29,6 +30,7 @@ You must have at least the Developer role for a project to import issues. - Consider importing a test file containing only a few issues. There is no way to undo a large import without using the GitLab API. - Ensure your CSV file meets the [file format](#csv-file-format) requirements. +- If your CSV includes the milestone header, ensure all unique milestones titles in the file already exist in the project or its parent groups. ## Import the file @@ -41,7 +43,7 @@ To import issues: 1. Select the file you want to import, and then select **Import issues**. The file is processed in the background, and a notification email is sent -to you after the import is complete. +to you if any errors are detected or after the import is complete. ## CSV file format @@ -50,7 +52,7 @@ To import issues, GitLab requires CSV files have a specific format: | Element | Format | |------------------------|--------| | header row | CSV files must include the following headers: `title` and `description`. The case of the headers does not matter. | -| columns | Data from columns outside of `title`, `description`, and `due_date` are not imported. | +| columns | Data from columns outside of `title`, `description`, `due_date`, and `milestone` are not imported. | | separators | The column separator is detected from the header row. Supported separator characters are commas (`,`), semicolons (`;`), and tabs (`\t`). The row separator can be either `CRLF` or `LF`. | | double-quote character | The double-quote (`"`) character is used to quote fields, enabling the use of the column separator in a field (see the third line in the sample CSV data below). To insert a double-quote (`"`) in a quoted field use two double-quote characters in succession (`""`). | | data rows | After the header row, following rows must use the same column order. The issue title is required, but the description is optional. | @@ -67,7 +69,7 @@ Also when using [quick actions](../quick_actions.md): Sample CSV data: ```plaintext -title,description,due_date +title,description,due_date,milestone My Issue Title,My Issue Description,2022-06-28 Another Title,"A description, with a comma", "One More Title","One More Description", @@ -75,6 +77,7 @@ An Issue with Quick Actions,"Hey can we change the frontend? /assign @sjones /label ~frontend ~documentation", +An issue with milestone,"My milestone is created",,v1.0 ``` ### File size diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 9850dcc22fc..01bd840ed0e 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Design management **(FREE ALL)** @@ -23,7 +23,7 @@ For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube. - On self-managed instances, a GitLab administrator must [enable LFS globally](../../../administration/lfs/index.md). - On both GitLab.com and self-managed instances, LFS must be - [enabled for the project itself](../settings/index.md#configure-project-features-and-permissions). + [enabled for the project itself](../settings/project_features_permissions.md#configure-project-features-and-permissions). If enabled globally, LFS is enabled by default for all projects. If you have disabled it for your project, you must enable it again. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 322d603aced..8b58866c256 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Due dates **(FREE ALL)** diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 0b64328fe03..cdbf6d5b5b3 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues **(FREE ALL)** @@ -23,10 +23,10 @@ Issues are always associated with a specific project. If you have multiple projects in a group, you can view all of the projects' issues at once. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=tTE6omrBBZI">Issues - Setting up your Organization with GitLab</a>. + See the video: <a href="https://www.youtube.com/watch?v=Mt1EzlKToig">Issues - Setting up your Organization with GitLab</a>. </div> <figure class="video-container"> - <iframe src="https://www.youtube-nocookie.com/embed/tTE6omrBBZI" frameborder="0" allowfullscreen> </iframe> + <iframe src="https://www.youtube-nocookie.com/embed/Mt1EzlKToig" frameborder="0" allowfullscreen> </iframe> </figure> <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index ddd08ee1de0..234ebf4913f 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue weight **(PREMIUM ALL)** diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a162c2d1709..6f2d0083ae8 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage issues **(FREE ALL)** @@ -132,7 +132,7 @@ To move an issue: You can move multiple issues at the same time when you're in a project. You can't move tasks or test cases. -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the project. diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 3ec3b72b173..ea0149db8f7 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple assignees for issues **(PREMIUM ALL)** diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 10c7899ac30..517d289b282 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -1,7 +1,7 @@ --- stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked issues **(FREE ALL)** @@ -75,7 +75,7 @@ Access our [permissions](../../permissions.md) page for more information. When you [add a linked issue](#add-a-linked-issue), you can show that it **blocks** or **is blocked by** another issue. -Issues that block other issues have an icon (**{issue-block}**) next to their title, shown in the +Issues blocked by other issues have an icon (**{issue-block}**) next to their title, shown in the issue lists and [boards](../issue_board.md). The icon disappears when the blocking issue is closed or their relationship is changed or [removed](#remove-a-linked-issue). diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index f2ecfc1f24b..74b106335fc 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sorting and ordering issue lists **(FREE ALL)** diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index eb872a24767..2cc38e6a31c 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Labels **(FREE ALL)** @@ -322,8 +322,12 @@ An issue, merge request, or epic cannot have two scoped labels, of the form `key with the same `key`. If you add a new label with the same `key` but a different `value`, the previous `key` label is replaced with the new label. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a video overview, see [Scoped Labels Speed Run](https://www.youtube.com/watch?v=ebyCiKMFODg). +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=7l7tnEva6I8">Scoped Labels - Setting up your Organization with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/7l7tnEva6I8" frameborder="0" allowfullscreen> </iframe> +</figure> ### Filter by scoped labels diff --git a/doc/user/project/members/img/project_members_filter_direct_v14_4.png b/doc/user/project/members/img/project_members_filter_direct_v14_4.png Binary files differdeleted file mode 100644 index 79cee06bc30..00000000000 --- a/doc/user/project/members/img/project_members_filter_direct_v14_4.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_filter_inherited_v14_4.png b/doc/user/project/members/img/project_members_filter_inherited_v14_4.png Binary files differdeleted file mode 100644 index ce2a0ebf088..00000000000 --- a/doc/user/project/members/img/project_members_filter_inherited_v14_4.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_search_v14_4.png b/doc/user/project/members/img/project_members_search_v14_4.png Binary files differdeleted file mode 100644 index 8c52c5788d4..00000000000 --- a/doc/user/project/members/img/project_members_search_v14_4.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_sort_v14_4.png b/doc/user/project/members/img/project_members_sort_v14_4.png Binary files differdeleted file mode 100644 index 20834b9307e..00000000000 --- a/doc/user/project/members/img/project_members_sort_v14_4.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 6df33a4fb06..92aaee1ae54 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Members of a project **(FREE ALL)** @@ -17,9 +17,9 @@ Users can become members of a group or project in different ways, which define t | Membership type | Membership process | | --------------------------------------------- | ------------------ | | [Direct](#add-users-to-a-project) | The user is added directly to the current group or project. | -| [Inherited](#inherited-membership) | The user is a member of an ancestor group or project that is added to the current group or project. | +| [Inherited](#inherited-membership) | The user is a member of a parent group that contains the current group or project. | | [Direct shared](share_project_with_groups.md) | The user is a member of a group or project that is shared into the current group or project. | -| [Inherited shared](../../group/manage.md#share-a-group-with-another-group) | The user is a member of an ancestor of a group or project that is shared into the current group or project. | +| [Inherited shared](../../group/manage.md#share-a-group-with-another-group) | The user is a member of a parent of a group or project that is shared into the current group or project. | ```mermaid flowchart RL @@ -45,64 +45,6 @@ flowchart RL G-->|Group C shared with Project A|E ``` -### Inherited membership - -When your project belongs to a group, project members inherit their role -from the group. - - - -In this example: - -- Three members have access to the project. -- **User 0** is a Reporter and has inherited their role in the project from the **demo** group, - which contains the project. -- **User 1** belongs directly to the project. In the **Source** column, they are listed - as a **Direct member**. -- **Administrator** is the [Owner](../../permissions.md) and member of all groups. - They have inherited their role in the project from the **demo** group. - -If a user is: - -- A direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. -- An inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. - -### Membership and visibility rights - -Depending on their membership type, members of groups or projects are granted different [visibility levels](../../../user/public_access.md) -and rights into the group or project. - -| Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member | -| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | -| Generate boards | ✓ | ✓ | ✓ | ✓ | -| View issues of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | -| View labels of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | -| View milestones of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | -| Be shared into other groups | ✓ | | | | -| Be shared into other projects | ✓ | ✓ | ✓ | ✓ | -| Share the group with other members | ✓ | ✓ | ✓ | ✓ | - -In the following example, `User` is a: - -- Direct member of `subgroup`. -- Inherited member of `subsubgroup`. -- Indirect member of `subgroup-2` and `subgroup-3`. -- Indirect inherited member of `subsubgroup-2` and `subsubgroup-3`. - -```mermaid -graph TD - classDef user stroke:green,color:green; - - root --> subgroup --> subsubgroup - root-2 --> subgroup-2 --> subsubgroup-2 - root-3 --> subgroup-3 --> subsubgroup-3 - subgroup -. shared .-> subgroup-2 -. shared .-> subgroup-3 - - User-. member .- subgroup - - class User user -``` - ## Add users to a project > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. @@ -113,9 +55,10 @@ graph TD Add users to a project so they become direct members and have permission to perform actions. -Prerequisite: +Prerequisites: - You must have the Owner or Maintainer role. +- [Group membership lock](../../group/access_and_permissions.md#prevent-members-from-being-added-to-projects-in-a-group) must be disabled. To add a user to a project: @@ -158,6 +101,28 @@ role for the group. For example, the maximum role you can set is: In GitLab 14.8 and earlier, direct members of a project have a maximum role of Maintainer. The Owner [role](../../permissions.md#project-members-permissions) can be added for the group only. +## Inherited membership + +When your project belongs to a group, project members inherit their role +from the group. + + + +In this example: + +- Three members have access to the project. +- **User 0** is a Reporter and has inherited their role in the project from the **demo** group, + which contains the project. +- **User 1** has been added directly to the project. In the **Source** column, they are listed + as a **Direct member**. +- **Administrator** is the [Owner](../../permissions.md) and member of all groups. + They have inherited their role in the project from the **demo** group. + +If a user is: + +- A direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. +- An inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group that the member originates from. + ## Add groups to a project > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. @@ -189,19 +154,27 @@ To add a group to a project: From that date onward, the group can no longer access the project. 1. Select **Invite**. -The members of the group are not displayed on the **Members** tab. +The invited group is displayed on the **Groups** tab. Private groups are masked from unauthorized users. +The members of the invited group are not displayed on the **Members** tab. The **Members** tab shows: -- Members who are directly assigned to the project. -- If the project was created in a group [namespace](../../namespace/index.md), members of that group. +- Members who were directly added to the project. +- Inherited members of the group [namespace](../../namespace/index.md) that the project was added to. + +## Share a project with a group + +Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). ## Import members from another project -You can import another project's members to your own project. +You can import another project's direct members to your own project. Imported project members retain the same permissions as the project you import them from. -Prerequisite: +NOTE: +Only direct members of a project are imported. Inherited or shared members of a project are not imported. + +Prerequisites: - You must have the Maintainer or Owner role. @@ -210,7 +183,7 @@ If the importing member's role in the target project is: - Maintainer, then members with the Owner role in the source project are imported with the Maintainer role. - Owner, then members with the Owner role in the source project are imported with the Owner role. -To import users: +To import a project's members: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. @@ -218,7 +191,8 @@ To import users: 1. Select the project. You can view only the projects for which you're a maintainer. 1. Select **Import project members**. -After the success message displays, refresh the page to view the new members. +If the import is successful, a success message is displayed. +To view the imported members on the **Members** tab, refresh the page. ## Remove a member from a project @@ -264,7 +238,7 @@ To avoid this problem, GitLab administrators can: - Remove the malicious user account. - Change the password for the malicious user account. -## Filter and sort members +## Filter and sort project members > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. @@ -272,6 +246,13 @@ To avoid this problem, GitLab administrators can: You can filter and sort members in a project. +### Display direct members + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Manage > Members**. +1. In the **Filter members** box, select `Membership` `=` `Direct`. +1. Press <kbd>Enter</kbd>. + ### Display inherited members 1. On the left sidebar, select **Search or go to** and find your project. @@ -279,28 +260,31 @@ You can filter and sort members in a project. 1. In the **Filter members** box, select `Membership` `=` `Inherited`. 1. Press <kbd>Enter</kbd>. - +### Search for members in a project -### Display direct members +To search for a project member: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Manage > Members**. -1. In the **Filter members** box, select `Membership` `=` `Direct`. +1. In the search box, enter the member's name, username, or email. 1. Press <kbd>Enter</kbd>. - - -### Search - -You can search for members by name, username, or email. +### Sort members in a project - +You can sort members in ascending or descending order by: -### Sort +- **Account** name +- **Access granted** date +- **Max role** the members have in the group +- **User created** date +- **Last activity** date +- **Last sign-in** date -You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. +To sort members: - +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Manage > Members**. +1. At the top of the member list, from the dropdown list, select the item you want to sort by. ## Request access to a project @@ -311,24 +295,29 @@ GitLab users can request to become a member of a project.  -An email is sent to the most recently active project maintainers or owners. -Up to ten project maintainers or owners are notified. -Any project owner or maintainer can approve or decline the request. -Project maintainers cannot approve Owner role access requests. +An email is sent to the most recently active project Maintainers or Owners. +Up to ten project Maintainers or Owners are notified. +Any project Owner or Maintainer can approve or decline the request. +Project Maintainers cannot approve Owner role access requests. + +If a project does not have any direct Owners or Maintainers, the notification is sent to the +most recently active Owners of the project's parent group. + +### Withdraw an access request to a project -If a project does not have any direct owners or maintainers, the notification is sent to the -most recently active owners of the project's group. +You can withdraw an access request to a project before the request is approved. +To withdraw the access request: -If you change your mind before your request is approved, select -**Withdraw Access Request**. +1. On the left sidebar, select **Search or go to** and find the project you requested access to. +1. Next to the project name, select **Withdraw Access Request**. ## Prevent users from requesting access to a project You can prevent users from requesting access to a project. -Prerequisite: +Prerequisites: -- You must be the project owner. +- You must have the Owner role for the project. 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. @@ -336,6 +325,57 @@ Prerequisite: 1. Under **Project visibility**, select **Users can request access**. 1. Select **Save changes**. -## Share a project with a group +## Membership and visibility rights -Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). +Depending on their membership type, members of groups or projects are granted different [visibility levels](../../../user/public_access.md) +and rights into the group or project. + +The following table lists the membership and visibility rights of project members. + +| Action | Direct project member | Inherited project member | Direct shared project member | Inherited shared project member | +| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | +| Generate boards | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View issues of parent groups <sup>1</sup> | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View labels of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View milestones of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| Be shared into other groups | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | +| Be imported into other projects | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | **{dotted-circle}** No | +| Share the project with other members | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | + +The following table lists the membership and visibility rights of group members. + +| Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member | +| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | +| Generate boards | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View issues of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View labels of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| View milestones of parent groups | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | + +<html> +<small>Footnotes: + <ol> + <li>Users can view only issues of projects they have access to.</li> + </ol> +</small> +</html> + +In the following example, `User` is a: + +- Direct member of `subgroup`. +- Inherited member of `subsubgroup`. +- Indirect member of `subgroup-2` and `subgroup-3`. +- Indirect inherited member of `subsubgroup-2` and `subsubgroup-3`. + +```mermaid +graph TD + classDef user stroke:green,color:green; + + root --> subgroup --> subsubgroup + root-2 --> subgroup-2 --> subsubgroup-2 + root-3 --> subgroup-3 --> subsubgroup-3 + subgroup -. shared .-> subgroup-2 -. shared .-> subgroup-3 + + User-. member .- subgroup + + class User user +``` diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 94dbb922c0b..3881220ec7a 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Share a project with a group **(FREE ALL)** diff --git a/doc/user/project/merge_requests/ai_in_merge_requests.md b/doc/user/project/merge_requests/ai_in_merge_requests.md index 2b4b28dafa2..daddf5477ca 100644 --- a/doc/user/project/merge_requests/ai_in_merge_requests.md +++ b/doc/user/project/merge_requests/ai_in_merge_requests.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Duo in merge requests **(ULTIMATE SAAS EXPERIMENT)** @@ -61,8 +61,7 @@ This feature is an [Experiment](../../../policy/experiment-beta-support.md) on G When you've completed your review of a merge request and are ready to [submit your review](reviews/index.md#submit-a-review), generate a GitLab Duo Code review summary: 1. When you are ready to submit your review, select **Finish review**. -1. Select **AI Actions** (**{tanuki}**). -1. Select **Summarize my code review**. +1. Select **Summarize my pending comments**. The summary is displayed in the comment box. You can edit and refine the summary prior to submitting your review. @@ -80,7 +79,7 @@ Provide feedback on this experimental feature in [issue 408991](https://gitlab.c This feature is an [Experiment](../../../policy/experiment-beta-support.md) on GitLab.com. -When preparing to merge your merge request you may wish to edit the proposed squash or merge commit message. +When preparing to merge your merge request you might wish to edit the proposed squash or merge commit message. To generate a commit message with GitLab Duo: @@ -93,7 +92,7 @@ Provide feedback on this experimental feature in [issue 408994](https://gitlab.c **Data usage**: When you use this feature, the following data is sent to the large language model referenced above: - Contents of the file -- The filename +- The file name ## Generate suggested tests in merge requests @@ -118,4 +117,4 @@ Feedback on this experimental feature can be provided in [issue 408995](https:// **Data usage**: When you use this feature, the following data is sent to the large language model referenced above: - Contents of the file -- The filename +- The file name diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 8ca87f4518e..225ca0cc10d 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Collaborate on merge requests across forks **(FREE ALL)** diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index bace1dfb8b5..5436edf9f8d 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, concepts +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Merge request approvals **(FREE ALL)** @@ -26,7 +25,7 @@ group-level settings for merge request approval rules is tracked in this [GitLab Premium](https://about.gitlab.com/pricing/) and [GitLab Ultimate](https://about.gitlab.com/pricing/) self-managed GitLab instances can also configure approvals -[for the entire instance](../../../admin_area/merge_requests_approvals.md). +[for the entire instance](../../../../administration/admin_area.md). ## How approvals work @@ -129,7 +128,7 @@ Invalid approval rules created through a scan result policy are presented with ## Related topics - [Merge request approvals API](../../../../api/merge_request_approvals.md) -- [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations +- [Instance-level approval rules](../../../../administration/admin_area.md) for self-managed installations <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 87ff6376ebd..c284df8d9aa 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request approval rules **(PREMIUM ALL)** @@ -16,7 +16,7 @@ You can define approval rules: - [As project defaults](#add-an-approval-rule). - [Per merge request](#edit-or-override-merge-request-approval-rules). -- [At the instance level](../../../admin_area/merge_requests_approvals.md) +- [At the instance level](../../../../administration/admin_area.md) If you don't define a [default approval rule](#add-an-approval-rule), any user can approve a merge request. Even if you don't define a rule, you can still @@ -114,16 +114,23 @@ more of these: - The project. - The project's immediate parent [group](#group-approvers). -- A group that has access to the project via a [share](../../members/share_project_with_groups.md). +- A group that has been [shared](../../members/share_project_with_groups.md) with the project. - A [group added as approvers](#group-approvers). -The following users can approve merge requests if they have Developer or -higher [permissions](../../../permissions.md): +The following users can approve merge requests if they have at least the Developer role: - Users added as approvers at the project or merge request level. - Users who are [Code owners](#code-owners-as-eligible-approvers) of the files changed in the merge request. +Users with the Reporter role can approve only if both of the following are true: + +- The users are part of a group that has been [shared](../../members/share_project_with_groups.md) with the project. + The group must have at least the Reporter role. +- The group has been added as merge request approvers. + +For detailed instructions, see [Merge request approval segregation of duties](#merge-request-approval-segregation-of-duties). + To show who has participated in the merge request review, the Approvals widget in a merge request displays a **Commented by** column. This column lists eligible approvers who commented on the merge request. It helps authors and reviewers identify who to @@ -183,21 +190,24 @@ for protected branches. ## Merge request approval segregation of duties -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. -> - Moved to GitLab Premium in 13.9. - You may have to grant users with the Reporter role permission to approve merge requests before they can merge to a protected branch. Some users (like managers) may not need permission to push or merge code, but still need -oversight on proposed work. To enable approval permissions for these users without -granting them push access: +oversight on proposed work. + +Prerequisites: + +- You must select a specific branch, as this method does **not** work with `All Branches` or `All protected branches` settings. +- The shared group must be added to an approval rule and not individual users, even when the added user is part of the group. + +To enable approval permissions for these users without granting them push access: 1. [Create a protected branch](../../protected_branches.md) 1. [Create a new group](../../../group/index.md#create-a-group). 1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), and select the Reporter role for the user. 1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group), - based on the Reporter role. + with at least the Reporter role. 1. Go to your project and select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval rules**, and either: - For a new rule, select **Add approval rule** and target the protected branch. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 3be546faabe..f9e40a6714c 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request approval settings **(PREMIUM ALL)** @@ -57,7 +57,7 @@ this setting, unless you configure one of these options: - [Prevent overrides of default approvals](#prevent-editing-approval-rules-in-merge-requests) at the project level. - *(Self-managed instances only)* Prevent overrides of default approvals - [at the instance level](../../../admin_area/merge_requests_approvals.md). When configured + [at the instance level](../../../../administration/admin_area.md). When configured at the instance level, you can't edit this setting at the project or individual merge request levels. @@ -68,7 +68,7 @@ this setting, unless you configure one of these options: > - [Feature flag `keep_merge_commits_for_approvals`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131778) removed in GitLab 16.5. This check now includes merge commits. By default, users who commit to a merge request can still approve it. At both -the project level or [instance level](../../../admin_area/merge_requests_approvals.md), +the project level or [instance level](../../../../administration/admin_area.md), you can prevent committers from approving merge requests that are partially their own. To do this: @@ -76,7 +76,7 @@ their own. To do this: 1. In the **Merge request approvals** section, scroll to **Approval settings** and select **Prevent approvals by users who add commits**. If this checkbox is cleared, an administrator has disabled it - [at the instance level](../../../admin_area/merge_requests_approvals.md), and + [at the instance level](../../../../administration/admin_area.md), and it can't be changed at the project level. 1. Select **Save changes**. @@ -104,26 +104,38 @@ on merge requests, you can disable this setting: This change affects all open merge requests. +When this field is changed, it can affect all open merge requests depending on the setting: + +- If users could edit approval rules previously, and you disable this behavior, + all open merge requests are updated to enforce the approval rules. +- If users could **not** edit approval rules previously, and you enable approval rule + editing, open merge requests remain unchanged. This preserves any changes already + made to approval rules in those merge requests. + ## Require user re-authentication to approve -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. -> - Moved to GitLab Premium in 13.9. -> - SAML authentication for GitLab.com groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 16.6. +> - Requiring re-authentication by using SAML authentication for GitLab.com groups [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 16.6 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default. +> - Requiring re-authentication by using SAML authentication for self-managed instances [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/431415) in GitLab 16.7 [with a flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. Disabled by default. + +FLAG: +On self-managed GitLab, by default requiring re-authentication by using SAML authentication is not available. To make it available, an administrator can +[enable the feature flag](../../../../administration/feature_flags.md) named `ff_require_saml_auth_to_approve`. On GitLab.com, this feature is not available. You can force potential approvers to first authenticate with either: - A password. -- SAML. Available on GitLab.com groups only. +- SAML. -This -permission enables an electronic signature for approvals, such as the one defined by -[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)): +This permission enables an electronic signature for approvals, such as the one defined by +[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)). This +setting is only available on top-level groups. For more information, see [Settings cascading](#settings-cascading). -1. Enable password authentication and SAML authentication (available only on GitLab.com groups). For more information on: +1. Enable password authentication and SAML authentication. For more information on: - Password authentication, see [sign-in restrictions documentation](../../../../administration/settings/sign_in_restrictions.md#password-authentication-enabled). - SAML authentication for GitLab.com groups, see [SAML SSO for GitLab.com groups documentation](../../../../user/group/saml_sso). + - SAML authentication for self-managed instances, see [SAML SSO for self-managed GitLab instances](../../../../integration/saml.md). 1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval settings** and select **Require user re-authentication (password or SAML) to approve**. @@ -153,7 +165,7 @@ However, approvals are reset if the target branch is changed. If you only want to remove approvals by Code Owners whose files have been changed when a commit is added: -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for a project. @@ -172,7 +184,7 @@ To do this: You can also enforce merge request approval settings: -- At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups +- At the [instance level](../../../../administration/admin_area.md), which apply to all groups on an instance and, therefore, all projects. - On a [top-level group](../../../group/manage.md#group-merge-request-approval-settings), which apply to all subgroups and projects. @@ -182,6 +194,6 @@ that inherited them. ## Related topics -- [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) +- [Instance-level merge request approval settings](../../../../administration/admin_area.md) - [Compliance center](../../../compliance/compliance_center/index.md) - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 75c9083332a..f0f2d3777f1 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request workflows **(FREE ALL)** @@ -64,7 +63,7 @@ forks. Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. +important to describe those, too. Think of things that might go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 18f19197f4c..780041ac411 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Changes in merge requests **(FREE ALL)** @@ -24,7 +23,8 @@ in our development documentation. To view the diff of changes included in a merge request: -1. Go to your merge request. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. 1. Below the merge request title, select **Changes**. 1. If the merge request changes many files, you can jump directly to a specific file: 1. Select **Show file browser** (**{file-tree}**) or press <kbd>F</kbd> to display the file tree. @@ -44,7 +44,9 @@ so it [applies to all merge requests](#in-all-merge-requests-show-only-one-file- To temporarily change your viewing preferences for a specific merge request: -1. Go to your merge request, and below the merge request title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the merge request title, select **Changes**. 1. Select **Preferences** (**{settings}**). 1. Select or clear the **Show one file at a time** checkbox. @@ -70,7 +72,9 @@ merge requests. To view other changed files, either: You can view the changes inline: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Select **Preferences** (**{settings}**). 1. In the **Compare changes** area, select **Inline**. @@ -80,10 +84,12 @@ The changes are displayed after the original text. ## Compare changes side-by-side -Depending on the length of the changes in your merge request, you may find it +Depending on the length of the changes in your merge request, you might find it easier to view the changes inline, or side-by-side: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Select **Preferences** (**{settings}**). 1. In the **Compare changes** area, select **Side-by-side**. @@ -95,14 +101,18 @@ The changes are displayed across from one another. When reviewing code changes, you can hide inline comments: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Scroll to the file that contains the comments you want to hide. 1. Scroll to the line the comment is attached to, and select **Collapse** (**{collapse}**):  To expand inline comments and show them again: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Scroll to the file that contains the collapsed comments you want to show. 1. Scroll to the line the comment is attached to, and select the user avatar:  @@ -112,7 +122,9 @@ To expand inline comments and show them again: Whitespace changes can make it more difficult to see the substantive changes in a merge request. You can choose to hide or show whitespace changes: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. Before the list of changed files, select **Preferences** (**{settings}**). 1. Select or clear the **Show whitespace changes** checkbox: @@ -126,7 +138,9 @@ a merge request. You can choose to hide or show whitespace changes: When reviewing a merge request with many files multiple times, you can ignore files you've already reviewed. To hide files that haven't changed since your last review: -1. Go to your merge request, and below the title, select **Changes**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests** and find your merge request. +1. Below the title, select **Changes**. 1. In the file's header, select the **Viewed** checkbox. Files marked as viewed are not shown to you again unless either: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index af76aa100c1..3d3d302856f 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cherry-pick changes **(FREE ALL)** diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 5ca097da29f..2f4dae5178a 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Commit message templates **(FREE ALL)** @@ -23,7 +22,7 @@ Commit templates use syntax similar to the syntax for Change the commit templates for your project if the default templates don't contain the information you need. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for a project. @@ -37,7 +36,7 @@ To do this: 1. For your desired commit type, enter your default message. You can use both static text and [variables](#supported-variables-in-commit-templates). Each template is limited to a maximum of 500 characters, though after replacing the templates - with data, the final message may be longer. + with data, the final message might be longer. 1. Select **Save changes**. ## Default template for merge commits diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 502dfd7acab..f446750352e 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request commits **(FREE ALL)** @@ -83,3 +82,12 @@ To view the changes between previously merged commits: If you selected to add previously merged commits for context, those commits are also shown in the list. + +## Find the merge request that introduced a change + +When you view the commit details page, GitLab links to one or more merge requests +that contain that commit. + +This behavior only applies to commits that are in the most recent version of a merge +request. If the commits were in a merge request and were rebased out of that merge +request, the commits are not linked. diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 901da6d4cf8..1067beef909 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests for confidential issues **(FREE ALL)** @@ -33,8 +33,8 @@ permissions in your downstream private fork without action by you. These users c immediately push code to branches in your private fork to help fix the confidential issue. WARNING: -Your private fork may expose confidential information, if you create it in a different -namespace than the upstream repository. The two namespaces may not contain the same users. +Your private fork might expose confidential information, if you create it in a different +namespace than the upstream repository. The two namespaces might not contain the same users. Prerequisites: @@ -45,8 +45,9 @@ Prerequisites: To create a confidential merge request: -1. Go to the confidential issue's page. Scroll below the issue description and - select **Create confidential merge request**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues** and find the issue you want to create a merge request for. +1. Scroll below the issue description, and select **Create confidential merge request**. 1. Select the item that meets your needs: - *To create both a branch and a merge request,* select **Create confidential merge request and branch**. Your merge request will diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index e132ddfb729..53d1269a940 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -1,24 +1,44 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge conflicts **(FREE ALL)** -_Merge conflicts_ happen when the two branches in a merge request (the source and target) each have different +Merge conflicts happen when the two branches in a merge request (the source and target) each have different changes, and you must decide which change to accept. In a merge request, Git compares the two versions of the files line by line. In most cases, GitLab can merge changes together. However, if two branches both change the same lines, GitLab blocks the merge, -and you must choose which change you want to keep. +and you must choose which change you want to keep: -A merge request cannot merge until you either: + + +A merge request with conflicts cannot merge until you either: - Create a merge commit. - Resolve the conflict through a rebase. - +GitLab resolves conflicts by creating a merge commit in the source branch, but +does not merge it into the target branch. You can then review and test the +merge commit. Verify it contains no unintended changes and doesn't break your build. + +## Understand the conflict block + +When Git detects a conflict that requires a decision on your part, it marks the +beginning and end of the conflict block with conflict markers: + +- `<<<<<<< HEAD` marks the beginning of the conflict block. +- Your changes are shown. +- `=======` marks the end of your changes. +- The latest changes in the target branch are shown. +- `>>>>>>>` marks the end of the conflict. + +When you resolve a conflict, you delete: + +1. The version of the conflicted lines you don't want to keep. +1. The three conflict markers: the beginning, the end, and the `=======` line between + the two versions. ## Conflicts you can resolve in the user interface @@ -39,23 +59,23 @@ criteria, you must resolve the conflict manually. GitLab does not detect conflicts when both branches rename a file to different names. For example, these changes don't create a conflict: -1. On branch `a`, doing `git mv example.txt example1.txt` -1. On branch `b`, doing `git mv example1.txt example3.txt`. +1. Branch `one` renames `example.txt` to `example1.txt` +1. Branch `two` renames `example.txt` to `example_old.txt`. -When these branches merge, both `example1.txt` and `example3.txt` are present. +When these branches merge, both `example1.txt` and `example_old` are present. ## Methods of resolving conflicts GitLab shows [conflicts available for resolution](#conflicts-you-can-resolve-in-the-user-interface) in the user interface, and you can also resolve conflicts locally through the command line: -- [Interactive mode](#resolve-conflicts-in-interactive-mode): UI method best for +- **Interactive mode**: UI method best for conflicts that only require you to select which version of a line to keep, without edits. -- [Inline editor](#resolve-conflicts-in-the-inline-editor): UI method best for more complex conflicts that require you to +- **Inline editor**: UI method best for more complex conflicts that require you to edit lines and manually blend changes together. -- [Command line](#resolve-conflicts-from-the-command-line): provides complete control over the most complex conflicts. +- **Command line**: provides complete control over the most complex conflicts. -## Resolve conflicts in interactive mode +### In interactive mode To resolve less-complex conflicts from the GitLab user interface: @@ -63,14 +83,15 @@ To resolve less-complex conflicts from the GitLab user interface: 1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. - GitLab shows a list of files with merge conflicts. The conflicts are + GitLab shows a list of files with merge conflicts. The lines that conflict are highlighted: -  +  + 1. For each conflict, select **Use ours** or **Use theirs** to mark the version of the conflicted lines you want to keep. This decision is known as "resolving the conflict." -1. Enter a **Commit message**. +1. When you've resolved all of the conflicts, enter a **Commit message**. 1. Select **Commit to source branch**. Resolving conflicts merges the target branch of the merge request into the @@ -78,27 +99,35 @@ source branch, using the version of the text you chose. If the source branch is `feature` and the target branch is `main`, these actions are similar to running `git switch feature; git merge main` locally. -## Resolve conflicts in the inline editor +### In the inline editor -Some merge conflicts are more complex, requiring you to manually modify lines to -resolve their conflicts. Use the merge conflict resolution editor to resolve complex -conflicts in the GitLab interface: +Some merge conflicts are more complex, and you must manually modify lines to +resolve their conflicts. The merge conflict resolution editor helps you resolve +these complex conflicts in the GitLab interface: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. -1. Select **Edit inline** to open the editor: -  +1. Find the file to edit manually, and scroll to the conflict block. +1. In the header for that file, select **Edit inline** to open the editor. In this + example, the conflict block begins at line 1350 and ends at line 1356: + +  + 1. After you resolve the conflict, enter a **Commit message**. 1. Select **Commit to source branch**. -## Resolve conflicts from the command line +### From the command line While most conflicts can be resolved through the GitLab user interface, some are too complex. Complex conflicts are best fixed locally, from the command line, to give you the -most control over each change: +most control over each change. + +Prerequisites: + +- You must have permission to force push to branches. 1. Open the terminal and check out your feature branch. For example, `my-feature-branch`: @@ -106,7 +135,7 @@ most control over each change: git switch my-feature-branch ``` -1. [Rebase your branch](../../../topics/git/git_rebase.md#regular-rebase) against the +1. [Rebase your branch](../../../topics/git/git_rebase.md#rebase-by-using-git) against the target branch (here, `main`) so Git prompts you with the conflicts: ```shell @@ -115,12 +144,7 @@ most control over each change: ``` 1. Open the conflicting file in your preferred code editor. -1. Find the conflict block: - - It begins with the marker: `<<<<<<< HEAD`. - - Next, it displays your changes. - - The marker `=======` indicates the end of your changes. - - Next, it displays the latest changes in the target branch. - - The marker `>>>>>>>` indicates the end of the conflict. +1. Find the conflict block. 1. Edit the file: 1. Choose which version (before or after `=======`) you want to keep. 1. Delete the version you don't want to keep. @@ -151,28 +175,10 @@ most control over each change: running `git rebase`. After you run `git rebase --continue`, you cannot abort the rebase. -1. [Force-push](../../../topics/git/git_rebase.md#force-push) the changes to your +1. [Force-push](../../../topics/git/git_rebase.md#force-pushing) the changes to your remote branch. -## Merge commit strategy - -GitLab resolves conflicts by creating a merge commit in the source branch, but -does not merge it into the target branch. You can then review and test the -merge commit. Verify it contains no unintended changes and doesn't break your build. - ## Related topics - [Introduction to Git rebase and force-push](../../../topics/git/git_rebase.md) - [Git applications for visualizing the Git workflow](https://git-scm.com/downloads/guis) - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, for example `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index ec269bec84d..951c848dee1 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "How to create merge requests in GitLab." --- @@ -22,63 +22,71 @@ You can create a merge request from the list of merge requests. 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests**. 1. In the upper-right corner, select **New merge request**. -1. Select a source and target branch and then **Compare branches and continue**. -1. Fill out the fields and select **Create merge request**. +1. Select a source and target branch, then select **Compare branches and continue**. +1. Complete the fields on the **New merge request** page, then select **Create merge request**. -NOTE: -Merge requests are designed around a one-to-one (1:1) branch relationship. Only one open merge request may -be associated with a given target branch at a time. +Each branch can be associated with only one open merge request. If a merge request +already exists for this branch, a link to the existing merge request is shown. ## From an issue -> The **Create merge request** button [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) to open the merge request creation form in GitLab 14.8. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) the behavior of the **Create merge request** button to open the merge request creation form in GitLab 14.8. If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. After merging the merge request, the issue is closed automatically, unless -[automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown list below the issue description. +[automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing): -NOTE: -In GitLab 14.8 and later, selecting **Create merge request** -[redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) -instead of immediately creating the merge request. +::Tabs -**Create merge request** doesn't display if: +:::TabTitle Merge request and branch -- A branch with the same name already exists. -- A merge request already exists for this branch. -- Your project has an active fork relationship. -- Your project is private and the issue is confidential. +To create a branch and a merge request at the same time: -To make this button appear, one possible workaround is to -[remove your project's fork relationship](../repository/forking_workflow.md#unlink-a-fork). -After removal, the fork relationship cannot be restored. This project can no longer -be able to receive or send merge requests to the source project, or other forks. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues** and find your issue. +1. Go to the bottom of the issue description. +1. Select **Create merge request > Create merge request and branch**. +1. In the dialog, review the suggested branch name. It's based on your project's + [branch name template](../repository/branches/index.md) Rename it if the + branch name is already taken, or you need a different branch name. +1. Select a source branch or tag. +1. Select **Create merge request**. -The dropdown list contains the options **Create merge request and branch** and **Create branch**. +:::TabTitle Branch only -After selecting one of these options, a new branch or branch and merge request -is created based on your project's [default branch](../repository/branches/default.md). -The branch name is based on your project's [branch name template](../repository/branches/index.md), -but this value can be changed. +To create only a branch directly from an issue: -When you select **Create branch** in an empty -repository project, GitLab performs these actions: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues** and find your issue. +1. Go to the bottom of the issue description. +1. Select **Create merge request > Create branch**. +1. In the dialog, review the suggested branch name. It's based on your project's + [branch name template](../repository/branches/index.md) Rename it if the + branch name is already taken, or you need a different branch name. +1. Select a source branch or tag. +1. Select **Create branch**. + +::EndTabs + +If your Git repository is empty, GitLab: - Creates a default branch. - Commits a blank `README.md` file to it. - Creates and redirects you to a new branch based on the issue title. -- _If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes,_ +- If your project is [configured with a deployment service](../integrations/index.md) like Kubernetes, GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) by helping you create a `.gitlab-ci.yml` file. -After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly-created branch, -the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the -merge request is merged. +If the name of the branch you create is +[prefixed with the issue number](../repository/branches/index.md#prefix-branch-names-with-issue-numbers), +GitLab cross-links the issue and merge request, and adds the +[issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +to the description of the merge request. In most cases, this looks like `Closes #ID`, +where `ID` is the ID of the issue. If your project is configured with a +[closing pattern](../issues/managing_issues.md#default-closing-pattern), the issue closes +when the merge request merges. ## When you add, edit, or upload a file @@ -86,10 +94,11 @@ You can create a merge request when you add, edit, or upload a file to a reposit 1. [Add, edit, or upload](../repository/web_editor.md) a file to the repository. 1. In the **Commit message**, enter a reason for the commit. -1. Select the **Target branch** or create a new branch by typing the name (without spaces). +1. Select the **Target branch** or create a new branch by typing the name. 1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only if the target is not the same as the source branch, or if the source branch is protected. -1. Select **Commit changes**. +1. Select **Upload file**. +1. Fill out the fields and select **Create merge request**. ## When you create a branch @@ -112,20 +121,27 @@ You can create a merge request by running Git commands on your local machine. git checkout -b my-new-branch ``` -1. Create, edit, or delete files. The stage and commit them: +1. Create, edit, or delete files as needed. + +1. Mark the files as ready to commit (staging them) and commit them locally: ```shell + # Mark the files as ready to commit git add . + # Commit the changes locally git commit -m "My commit message" ``` -1. [Push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): +1. [Push your branch and its commits to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlab): ```shell git push origin my-new-branch ``` - GitLab prompts you with a direct link for creating a merge request: + To reduce the number of fields to edit later in the merge request, use + [push options](../push_options.md) to set the value of fields. + +1. In the response to the `git push`, GitLab provides a direct link to create the merge request: ```plaintext ... @@ -135,9 +151,6 @@ You can create a merge request by running Git commands on your local machine. 1. Copy the link and paste it in your browser. -You can add other [flags to commands when pushing through the command line](../push_options.md) -to reduce the need for editing merge requests manually through the UI. - ## When you work in a fork You can create a merge request from your fork to contribute back to the main project. @@ -189,8 +202,7 @@ A merge request is created. ### Add attachments when creating a merge request by email You can add commits to a merge request by adding -patches as attachments to the email. All attachments with a filename -ending in `.patch` are considered patches and are processed +patches as attachments to the email. All attachments with a file name ending in `.patch` are considered patches and are processed ordered by name. The combined size of the patches can be 2 MB. @@ -221,3 +233,19 @@ To have merge requests from a fork by default target your own fork 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. + +## Troubleshooting + +### No option to create a merge request on an issue + +The option to **Create merge request** doesn't display on an issue if: + +- A branch with the same name already exists. +- A merge request already exists for this branch. +- Your project has an active fork relationship. +- Your project is private and the issue is confidential. + +To make this button appear, one possible workaround is to +[remove your project's fork relationship](../repository/forking_workflow.md#unlink-a-fork). +After removal, the fork relationship cannot be restored. This project can no longer +be able to receive or send merge requests to the source project, or other forks. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index cc7fa050766..4f22b2ab273 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export merge requests to CSV **(FREE ALL)** diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index 8fb5230c497..25e967a8f86 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.md @@ -1,12 +1,14 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request dependencies **(PREMIUM ALL)** +> - Support for complex merge dependencies [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `remove_mr_blocking_constraints`. Disabled by default. +> - Support for complex merge dependencies [generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136775) in GitLab 16.7. Feature flag `remove_mr_blocking_constraints` removed. + A single feature can span several merge requests, spread out across multiple projects, and the order in which the work merges can be significant. Use merge request dependencies when it's important to merge work in a specific order. Some examples: @@ -48,6 +50,26 @@ enforced only for the dependent merge request. A merge request in a **PREMIUM** project can depend on a merge request in a **FREE** project, but a merge request in a **FREE** project cannot be marked as dependent. +## Nested dependencies + +Indirect, nested dependencies are supported in GitLab 16.7 and later. +A single merge request can be blocked by up to 10 merge requests, and, +in turn, can block up to 10 merge requests. In this example, `myfriend/library!10` +depends on `herfriend/another-lib!1`, which in turn depends on `mycorp/example!100`: + +```mermaid +graph LR; + A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1] + B-->|depends on| C[mycorp/example!100] +``` + +Nested dependencies do not display in the GitLab UI, but UI support has +been proposed in [epic 5308](https://gitlab.com/groups/gitlab-org/-/epics/5308). + +NOTE: +A merge request can't be made dependent on itself (self-referential), but +it's possible to create circular dependencies. + ## View dependencies for a merge request If a merge request is dependent on another, the merge request reports section shows @@ -99,7 +121,7 @@ To create a new merge request and mark it as dependent on another: You can edit an existing merge request and mark it as dependent on another. -Prerequisite: +Prerequisites: - You must have at least the Developer role or be allowed to edit merge requests in the project. @@ -116,7 +138,7 @@ To do this: You can edit a dependent merge request and remove a dependency. -Prerequisite: +Prerequisites: - You must have a role in the project that allows you to edit merge requests. @@ -142,32 +164,3 @@ No API support exists for managing dependencies. For more information, read Dependencies are not preserved when projects are imported or exported. For more information, read [issue #12549](https://gitlab.com/gitlab-org/gitlab/-/issues/12549). - -### Complex merge order dependencies are unsupported - -- Support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11393) in GitLab 16.6 [with a flag](../../../administration/feature_flags.md) named `remove_mr_blocking_constraints`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `remove_mr_blocking_constraints`. -On GitLab.com, this feature is available. - -If you attempt to create an indirect, nested dependency, GitLab shows the error message: - -- Dependencies failed to save: Dependency chains are not supported - -GitLab supports direct dependencies between merge requests, but does not support -[indirect (nested) dependencies](https://gitlab.com/gitlab-org/gitlab/-/issues/11393). - -Acceptable dependency patterns include: - -- A single merge request can directly depend on a single merge request. -- A single merge request can directly depend on multiple merge requests. -- Multiple merge requests can directly depend on a single merge request. - -The indirect, nested dependency between `myfriend/library!10` and `mycorp/example!100` shown in this example is not supported: - -```mermaid -graph LR; - A[myfriend/library!10]-->|depends on| B[herfriend/another-lib!1] - B-->|depends on| C[mycorp/example!100] -``` diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index a3b1920e375..67d24e72fed 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Draft merge requests **(FREE ALL)** @@ -56,7 +55,8 @@ are notified. When you view or search in your project's merge requests list, to include or exclude draft merge requests: -1. Go to your project and select **Code > Merge requests**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests**. 1. To filter by merge request status, select **Open**, **Merged**, **Closed**, or **All** in the navigation bar. 1. Select the search box to display a list of filters and select **Draft**, or @@ -78,7 +78,7 @@ if you want to run [merged results pipelines](../../../ci/pipelines/merged_resul Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. +important to describe those, too. Think of things that might go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. diff --git a/doc/user/project/merge_requests/img/conflict_section.png b/doc/user/project/merge_requests/img/conflict_section.png Binary files differdeleted file mode 100644 index cfc17013218..00000000000 --- a/doc/user/project/merge_requests/img/conflict_section.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/conflict_section_v16_7.png b/doc/user/project/merge_requests/img/conflict_section_v16_7.png Binary files differnew file mode 100644 index 00000000000..40701e46b50 --- /dev/null +++ b/doc/user/project/merge_requests/img/conflict_section_v16_7.png diff --git a/doc/user/project/merge_requests/img/conflicts_v16_7.png b/doc/user/project/merge_requests/img/conflicts_v16_7.png Binary files differnew file mode 100644 index 00000000000..1de03b5cfe0 --- /dev/null +++ b/doc/user/project/merge_requests/img/conflicts_v16_7.png diff --git a/doc/user/project/merge_requests/img/merge_conflict_editor.png b/doc/user/project/merge_requests/img/merge_conflict_editor.png Binary files differdeleted file mode 100644 index f10efbce5f5..00000000000 --- a/doc/user/project/merge_requests/img/merge_conflict_editor.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_conflict_editor_v16_7.png b/doc/user/project/merge_requests/img/merge_conflict_editor_v16_7.png Binary files differnew file mode 100644 index 00000000000..b56ee2abdd7 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_conflict_editor_v16_7.png diff --git a/doc/user/project/merge_requests/img/merge_request_widget.png b/doc/user/project/merge_requests/img/merge_request_widget.png Binary files differdeleted file mode 100644 index 58562fcb034..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_widget.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions.png b/doc/user/project/merge_requests/img/versions.png Binary files differdeleted file mode 100644 index 8355fd62dcb..00000000000 --- a/doc/user/project/merge_requests/img/versions.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_compare.png b/doc/user/project/merge_requests/img/versions_compare.png Binary files differdeleted file mode 100644 index 0957a0310ac..00000000000 --- a/doc/user/project/merge_requests/img/versions_compare.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png b/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png Binary files differdeleted file mode 100644 index 61cf72e7bf9..00000000000 --- a/doc/user/project/merge_requests/img/versions_compare_head_v12_10.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_dropdown.png b/doc/user/project/merge_requests/img/versions_dropdown.png Binary files differdeleted file mode 100644 index 831c92db2c0..00000000000 --- a/doc/user/project/merge_requests/img/versions_dropdown.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_dropdown_v16_6.png b/doc/user/project/merge_requests/img/versions_dropdown_v16_6.png Binary files differnew file mode 100644 index 00000000000..9dd6b63d26f --- /dev/null +++ b/doc/user/project/merge_requests/img/versions_dropdown_v16_6.png diff --git a/doc/user/project/merge_requests/img/versions_system_note.png b/doc/user/project/merge_requests/img/versions_system_note.png Binary files differdeleted file mode 100644 index 97d552692c9..00000000000 --- a/doc/user/project/merge_requests/img/versions_system_note.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/versions_system_note_v16_6.png b/doc/user/project/merge_requests/img/versions_system_note_v16_6.png Binary files differnew file mode 100644 index 00000000000..b26e58c7697 --- /dev/null +++ b/doc/user/project/merge_requests/img/versions_system_note_v16_6.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 63e5cc93e7d..3555d9ffa01 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,13 +1,12 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests **(FREE ALL)** -To incorporate changes from a source branch to a target branch, you use a *merge request* (MR). +A merge request (MR) is a proposal to incorporate changes from a source branch to a target branch. When you open a merge request, you can visualize and collaborate on the changes before merge. Merge requests include: @@ -463,7 +462,7 @@ merge request to display an incorrect message: `merged into <branch-name>`. ### Close a merge request from the Rails console **(FREE SELF)** -If closing a merge request doesn't work through the UI or API, you may want to attempt to close it in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): +If closing a merge request doesn't work through the UI or API, you might want to attempt to close it in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): WARNING: Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. @@ -477,7 +476,7 @@ MergeRequests::CloseService.new(project: p, current_user: u).execute(m) ### Delete a merge request from the Rails console **(FREE SELF)** -If deleting a merge request doesn't work through the UI or API, you may want to attempt to delete it in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): +If deleting a merge request doesn't work through the UI or API, you might want to attempt to delete it in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): WARNING: Any command that changes data directly could be damaging if not run correctly, @@ -514,6 +513,7 @@ This error can happen if your merge request: - Contains many diffs. - Is many commits behind the target branch. +- References a Git LFS file that is locked. Users in self-managed installations can request an administrator review server logs to determine the cause of the error. GitLab SaaS users should diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index c4c38ef9eaf..a9cad78449b 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auto-merge **(FREE ALL)** @@ -110,7 +109,7 @@ When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent merge requests from being merged. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role in the project. diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 959ada4928e..dd70052cd31 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, concepts +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge methods **(FREE ALL)** @@ -199,7 +198,7 @@ In these merge methods, you can merge only when your source branch is up-to-date If a fast-forward merge is not possible but a conflict-free rebase is possible, GitLab provides: -- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#from-the-gitlab-ui). +- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-ui). - The option to select **Rebase** in the user interface. You must rebase the source branch locally before a fast-forward merge if both @@ -220,8 +219,11 @@ considered equivalent to rebasing. To rebase a merge request's branch without triggering a CI/CD pipeline, select **Rebase without pipeline** from the merge request reports section. -This option is available when fast-forward merge is not possible but a conflict-free -rebase is possible. + +This option is: + +- Available when fast-forward merge is not possible but a conflict-free rebase is possible. +- Not available when the **Pipelines must succeed** option is enabled. Rebasing without a CI/CD pipeline saves resources in projects with a semi-linear workflow that requires frequent rebases. diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 4476ec8c670..07523b9f34c 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,7 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Revert changes **(FREE ALL)** @@ -92,7 +92,7 @@ you must revert the commit from the command line: Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. +important to describe those, too. Think of things that might go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index b32c527ab75..0499e5a0bb7 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -1,8 +1,7 @@ --- stage: AI-powered group: AI Model Validation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Suggested Reviewers Data Usage **(ULTIMATE SAAS)** diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png Binary files differdeleted file mode 100644 index 476c50b9098..00000000000 --- a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview_v16_6.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview_v16_6.png Binary files differnew file mode 100644 index 00000000000..f35a2c5e8a1 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview_v16_6.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v16_6.png Binary files differindex 6f29107146d..6f29107146d 100644 --- a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v16_6.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index d3124b716da..23b1207619e 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request reviews **(FREE ALL)** @@ -15,7 +14,7 @@ from the user interface. When your work is reviewed, your team members can choos to accept or reject it. You can review merge requests from the GitLab interface. If you install the -[GitLab Workflow VS Code extension](../../repository/vscode.md), you can also +[GitLab Workflow VS Code extension](../../../../editor_extensions/visual_studio_code/index.md), you can also review merge requests in Visual Studio Code. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 90a276dc303..908e8c67c3b 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Suggest changes **(FREE ALL)** @@ -18,9 +17,8 @@ merge request, authored by the user who suggested the changes. 1. Select **Code > Merge requests** and find your merge request. 1. On the secondary menu, select **Changes**. 1. Find the lines of code you want to change. - - To select a single line: - - Hover over the line number, and - select **Add a comment to this line** (**{comment}**). + - To select a single line, hover over the line number and + select **Add a comment to this line** (**{comment}**). - To select multiple lines: 1. Hover over the line number, and select **Add a comment to this line** (**{comment}**). 1. Select and drag your selection until all desired lines are included. To @@ -35,8 +33,11 @@ merge request, authored by the user who suggested the changes. ```` 1. Edit the pre-populated code block to add your suggestion. -1. Select either **Start a review** or **Add to review** to add your comment to a - [review](index.md), or **Add comment now** to add the comment to the thread immediately. +1. Select whether you want your comment to appear immediately: + + - **Start a review** or **Add to review** creates your comment in a pending state + as part of a [review](index.md). + - **Add comment now** adds your comment immediately. ### Multi-line suggestions @@ -45,23 +46,24 @@ in a single suggestion, by either: - Selecting and dragging, as described in [Create suggestions](#create-suggestions). GitLab creates a suggestion block for you. -- Selecting a single line, then manually adjusting the range offsets. +- Selecting a single line, then manually editing the range offsets in the suggestion block. The range offsets in the first line of the suggestion describe line numbers relative to the line you selected. The offsets specify the lines your suggestion intends to replace. -For example, this suggestion covers 3 lines above and 4 lines below the +For example, this suggestion covers 2 lines above and 2 lines below the commented line: ````markdown -```suggestion:-3+4 - "--talk-name=ca.desrt.dconf", - "--socket=wayland", +```suggestion:-2+2 +## Prevent approval by author + +By default, the author of a merge request cannot approve it. To change this setting: ``` ```` -When applied, the suggestion replaces from 3 lines above to 4 lines below the commented line: +When applied, the suggestion replaces from 2 lines above to 2 lines below the commented line: - + Suggestions for multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line. This allows for up to 200 changed lines per @@ -74,7 +76,7 @@ suggestion. > - Feature flag `content_editor_on_issues` removed in GitLab 16.5. When you insert suggestions, you can use the WYSIWYG -[rich text editor](https://about.gitlab.com/direction/plan/knowledge/content_editor/) to move +[rich text editor](../../../rich_text_editor.md) to move up and down the source file's line numbers in the UI. To add or subtract changed lines, next to **From line**, select **+** or **-**. @@ -119,7 +121,7 @@ git config --global receive.advertisepushoptions true ```` ````` - + ## Configure the commit message for applied suggestions @@ -133,9 +135,14 @@ Apply 3 suggestion(s) to 2 file(s) ``` Merge requests created from forks use the template defined in the target project. +To meet your project's needs, customize these messages and include other +placeholder variables. + +Prerequisites: -To meet your project's needs, you can customize these messages and include other -placeholder variables: +- You must have the Maintainer role. + +To do this: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Merge requests**. @@ -166,12 +173,16 @@ For example, to customize the commit message to output > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. -To reduce the number of commits added to your branch, you can apply multiple +Prerequisites: + +- You must have a role in the project that allows you to commit to the source branch. + +To reduce the number of commits added to your branch, apply multiple suggestions in a single commit. 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Code > Merge requests** and find your merge request. -1. For each suggestion you want to apply, and select **Add suggestion to batch**. +1. For each suggestion you want to apply, select **Add suggestion to batch**. 1. Optional. To remove a suggestion, select **Remove from batch**. 1. After you add your desired suggestions, select **Apply suggestions**. diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index a6d55ee44e2..d7635763f9e 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Squash and merge **(FREE ALL)** diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index c330af0fc9b..b13f0a70295 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -1,8 +1,7 @@ --- stage: Govern group: Compliance -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, concepts +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # External status checks **(ULTIMATE ALL)** @@ -172,8 +171,7 @@ To retry a failed status check: An organization might have a policy that does not allow merging merge requests if external status checks do not pass. However, the details in the widget are for informational -purposes only. GitLab does not prevent merging of merge requests that fail status checks. -Support to allow merges to be blocked when external status checks fail is proposed in epic [&8516](https://gitlab.com/groups/gitlab-org/-/epics/8516). +purposes only. NOTE: GitLab cannot guarantee that the external status checks are properly processed by diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index a5635d22530..62cee897b49 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,78 +1,69 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Merge requests versions **(FREE ALL)** +# Merge request diff versions **(FREE ALL)** -Every time you push to a branch that is tied to a merge request, a new version -of merge request diff is created. When you visit a merge request that contains -more than one pushes, you can select and compare the versions of those merge -request diffs. +When you create a merge request, you select two branches to compare. The differences +between the two branches are shown as a **diff** in the merge request. Each time +you push commits to a branch connected to a merge request, GitLab updates the +merge request diff to a new **diff version**. - +NOTE: +Diff versions are updated on each push, not each commit. If a push contains multiple +commits, only one new diff version is created. -## Selecting a version +By default, GitLab compares the latest push in your source branch (`feature`) +against the most recent commit in the target branch, often `main`. -By default, the latest version of changes is shown. However, you -can select an older one from version dropdown list. +## Compare diff versions - +If you've pushed to your branch multiple times, the diff version from each previous push +is available for comparison. When your merge request contains many changes or +sequential changes to the same file, you might want to compare a smaller number of changes. -Merge request versions are based on push not on commit. So, if you pushed 5 -commits in a single push, it displays as a single option in the dropdown list. If you -pushed 5 times, that counts for 5 options. +Prerequisites: -You can also compare the merge request version with an older one to see what has -changed since then. +- The merge request branch must contain commits from multiple pushes. Individual commits + in the same push do not generate new diff versions. - +To compare diff versions: -Comments are disabled while viewing outdated merge versions or comparing to -versions other than base. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Merge requests**. +1. Select a merge request. +1. To view the current diff version for this merge request, select **Changes**. +1. Next to **Compare** (**{file-tree}**), select the pushes to compare. This example + compares `main` to the most recent push (latest diff version) of the branch: -Every time you push new changes to the branch, a link to compare the last -changes appears as a system note. +  - + This example branch has four commits, but the branch contains only three diff versions + because two commits were pushed at the same time. -## Find the merge request that introduced a change +## View diff versions from a system note -When viewing the commit details page, GitLab links to the merge request (or -merge requests, if it's in more than one) containing that commit. +GitLab adds a system note to a merge request each time you push new changes to +the merge request's branch. In this example, a single push added two commits: -This only applies to commits that are in the most recent version of a merge -request - if commits were in a merge request, then rebased out of that merge -request, they aren't linked. + -## `HEAD` comparison mode for merge requests +To view the diff for that commit, select the commit SHA. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) in GitLab 12.10. +For more information, see how to [show or filter system notes on a merge request](../system_notes.md#on-a-merge-request). -Merge requests, particularly the **Changes** tab, is where source code -is reviewed and discussed. In circumstances where the target branch was -merged into the source branch of the merge request, the changes in the -source and target branch can be shown mixed together making it hard to -understand which changes are being added and which already exist in the -target branch. +## Related topics -In GitLab 12.10, we added a comparison mode, which -shows a diff calculated by simulating how it would look like once merged - a more accurate -representation of the changes rather than using the base of the two -branches. The new mode is available from the comparison target drop down -by selecting **main (HEAD)**. In GitLab 13.9, it -[replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the -old default comparison. For technical details, additional information is available in the -[developer documentation](../../../development/merge_request_concepts/diffs/index.md#merge-request-diffs-against-the-head-of-the-target-branch). - - +- [Merge request diffs for developers](../../../development/merge_request_concepts/diffs/index.md) +- [Merge request diff storage for administrators](../../../administration/merge_request_diffs.md) <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. +important to describe those, too. Think of things that might go wrong and include them here. This is important to minimize requests for support, and to avoid doc comments with questions that you know someone might ask. diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index da766b685a3..d60bd660b53 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request widgets **(FREE ALL)** diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 65cc9477c49..b67078614a8 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Burndown and burnup charts **(PREMIUM ALL)** diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 328e56e2bd8..a959507b338 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -1,8 +1,7 @@ --- -type: index, reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Milestones **(FREE ALL)** @@ -46,7 +45,7 @@ In a group, GitLab displays milestones that belong to the group and all projects ### View milestones in a project with issues turned off If a project has issue tracking -[turned off](../settings/index.md#configure-project-features-and-permissions), +[turned off](../settings/project_features_permissions.md#configure-project-features-and-permissions), to get to the milestones page, enter its URL. To do so: diff --git a/doc/user/project/ml/experiment_tracking/mlflow_client.md b/doc/user/project/ml/experiment_tracking/mlflow_client.md index 9cedb5780ed..35972f0ad7f 100644 --- a/doc/user/project/ml/experiment_tracking/mlflow_client.md +++ b/doc/user/project/ml/experiment_tracking/mlflow_client.md @@ -1,20 +1,20 @@ --- -stage: Create -group: Incubation -info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. +stage: ModelOps +group: MLOps +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# MLflow client compatibility **(FREE ALL)** +# MLflow client compatibility **(FREE ALL EXPERIMENT)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. NOTE: -Model experiment tracking is an [experimental feature](../../../../policy/experiment-beta-support.md). -Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. +Model registry and model experiment tracking are [Experiments](../../../../policy/experiment-beta-support.md). +Provide feedback [for model experiment tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/381660). Provide feedback for [model registry](https://gitlab.com/gitlab-org/gitlab/-/epics/9423). [MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning Experiment Tracking. -GitLab [Model experiment tracking](index.md) is compatible with MLflow Client, -[logging experiments](index.md). The setup requires minimal changes to existing code. +GitLab [Model experiment tracking](index.md) and GitLab +[Model registry](../model_registry/index.md) are compatible with the MLflow client. The setup requires minimal changes to existing code. GitLab plays the role of a MLflow server. Running `mlflow server` is not necessary. @@ -37,18 +37,18 @@ To use MLflow client compatibility from a local environment: export MLFLOW_TRACKING_TOKEN="<your_access_token>" ``` -1. If your training code contains the call to `mlflow.set_tracking_uri()`, remove it. +1. If the training code contains the call to `mlflow.set_tracking_uri()`, remove it. -When running the training code, MLflow creates experiments, runs, log parameters, metrics, metadata -and artifacts on GitLab. +## Model experiments + +When running the training code, MLflow client can be used to create experiments, runs, +models, model versions, log parameters, metrics, metadata and artifacts on GitLab. After experiments are logged, they are listed under `/<your project>/-/ml/experiments`. -Runs are registered as: -- Model Candidates, which can be explored by selecting an experiment. -- Tags, which are registered as metadata. +Runs are registered as candidates, which can be explored by selecting an experiment, model, or model version. -## Associating a candidate to a CI/CD job +### Associating a candidate to a CI/CD job > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119454) in GitLab 16.1. @@ -71,10 +71,179 @@ candidate metadata. To associate a candidate to a CI/CD job: # End of snippet to be included ``` +## Model registry + +You can also manage models and model versions by using the MLflow +client. Models are registered under `/<your project>/-/ml/models`. + +### Models + +#### Creating a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +description = 'Model description' +model = client.create_registered_model(model_name, description=description) +``` + +**Notes** + +- `create_registered_model` argument `tags` is ignored. +- `name` must be unique within the project. +- `name` cannot be the name of an existing experiment. + +#### Fetching a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +model = client.get_registered_model(model_name) +``` + +#### Updating a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +description = 'New description' +client.update_registered_model(model_name, description=description) +``` + +#### Deleting a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +client.delete_registered_model(model_name) +``` + +### Logging candidates to a model + +Every model has an associated experiment with the same name. To log a candidate/run to the model, +use the experiment with the name of the model: + +```python +client = MlflowClient() +model_name = '<your_model_name>' +exp = client.get_experiment_by_name(model_name) +run = client.create_run(exp.experiment_id) +``` + +### Model version + +#### Creating a model version + +```python +client = MlflowClient() +model_name = '<your_model_name>' +description = 'Model version description' +model_version = client.create_model_version(model_name, source="", description=description) +``` + +**Notes** + +- Argument `run_id` is ignored. Every model version behaves as a Candidate/Run. Creating a mode version from a run is not yet supported. +- Argument `source` is ignored. GitLab will create a package location for the model version files. +- Argument `tags` is ignored. +- Argument `run_link` is ignored. +- Argument `await_creation_for` is ignored. + +#### Updating a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +description = 'New description' +client.update_model_version(model_name, version, description=description) +``` + +#### Fetching a model version + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +client.get_model_version(model_name, version) +``` + +#### Getting latest versions of a model + +```python +client = MlflowClient() +model_name = '<your_model_name>' +client.get_latest_versions(model_name) +``` + +**Notes** + +- Argument `stages` is ignored. +- Versions are ordered by last created. + +#### Logging metrics and parameters to a model version + +Every model version is also a candidate/run, allowing users to log parameters +and metrics. The run ID can either be found at the Model version page in GitLab, +or by using the MLflow client: + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +model_version = client.get_model_version(model_name, version) +run_id = model_version.run_id + +# Your training code + +client.log_metric(run_id, '<metric_name>', '<metric_value>') +client.log_param(run_id, '<param_name>', '<param_value>') +client.log_batch(run_id, metric_list, param_list, tag_list) +``` + +#### Logging artifacts to a model version + +GitLab creates a package that can be used by the MLflow client to upload files. + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +model_version = client.get_model_version(model_name, version) +run_id = model_version.run_id + +# Your training code + +client.log_artifact(run_id, '<local/path/to/file.txt>', artifact_path="") +client.log_figure(run_id, figure, artifact_file="my_plot.png") +client.log_dict(run_id, my_dict, artifact_file="my_dict.json") +client.log_image(run_id, image, artifact_file="image.png") +``` + +Artifacts will then be available under `https/<your project>/-/ml/models/<model_id>/versions/<version_id>`. + +#### Linking a model version to a CI/CD job + +Similar to candidates, it is also possible to link a model version to a CI/CD job: + +```python +client = MlflowClient() +model_name = '<your_model_name>' +version = '<your_version>' +model_version = client.get_model_version(model_name, version) +run_id = model_version.run_id + +# Your training code + +if os.getenv('GITLAB_CI'): + client.set_tag(model_version.run_id, 'gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID')) +``` + ## Supported MLflow client methods and caveats GitLab supports these methods from the MLflow client. Other methods might be supported but were not -tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). +tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). The MlflowClient counterparts +of the methods below are also supported with the same caveats. | Method | Supported | Version Added | Comments | |--------------------------|------------------|----------------|-------------------------------------------------------------------------------------| @@ -102,9 +271,23 @@ tested. More information can be found in the [MLflow Documentation](https://www. | `update_run` | Yes | 15.11 | | | `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. | +Other MLflowClient methods: + +| Method | Supported | Version added | Comments | +|---------------------------|------------------|---------------|--------------------------------------------------| +| `create_registered_model` | Yes with caveats | 16.8 | [See notes](#creating-a-model) | +| `get_registered_model` | Yes | 16.8 | | +| `delete_registered_model` | Yes | 16.8 | | +| `update_registered_model` | Yes | 16.8 | | +| `create_model_version` | Yes with caveats | 16.8 | [See notes](#creating-a-model-version) | +| `get_model_version` | Yes | 16.8 | | +| `get_latest_versions` | Yes with caveats | 16.8 | [See notes](#getting-latest-versions-of-a-model) | +| `update_model_version` | Yes | 16.8 | | +| `create_registered_model` | Yes | 16.8 | | +| `create_registered_model` | Yes | 16.8 | | + ## Limitations -- The API GitLab supports is the one defined at MLflow version 1.28.0. -- API endpoints not listed above are not supported. +- The API GitLab supports is the one defined at MLflow version 2.7.1. +- MLflow client methods not listed above are not supported. - During creation of experiments and runs, ExperimentTags are stored, even though they are not displayed. -- MLflow Model Registry is not supported. diff --git a/doc/user/project/ml/model_registry/index.md b/doc/user/project/ml/model_registry/index.md new file mode 100644 index 00000000000..492ec9940ab --- /dev/null +++ b/doc/user/project/ml/model_registry/index.md @@ -0,0 +1,79 @@ +--- +stage: ModelOps +group: MLOps +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Model registry **(FREE ALL EXPERIMENT)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9423) in GitLab 16.8 as an [Experiment](../../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. To enable the feature, an administrator can [enable the feature flag](../../../../administration/feature_flags.md) named `model_registry`. + +NOTE: +Model registry is an [Experiment](../../../../policy/experiment-beta-support.md). [Provide feedback](https://gitlab.com/groups/gitlab-org/-/epics/9423). + +Model registry allows data scientists and developers to manage their machine learning +models, along with all metadata associated with their creation: parameters, performance +metrics, artifacts, logs and more. For the full list of currently supported features, +see [epic 9423](https://gitlab.com/groups/gitlab-org/-/epics/9423). + +## Access the model registry + +To set the model registry [visibility level](../../../public_access.md) to public, private or disabled: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Under **Model registry**, ensure the toggle is on and select who you want to have access. + Users must have +at least the [Reporter role](../../../permissions.md#roles) to modify or delete models and model versions. + +## Exploring models, model versions and model candidates + +Model registry can be accessed on `https/<your-project>-/ml/models`. + +## Creating machine learning models and model versions + +Models and model versions can be created using the [MLflow](https://www.mlflow.org/docs/latest/tracking.html) client compatibility. +See [MLflow client compatibility](../experiment_tracking/mlflow_client.md#model-registry) on how to +create and manage models and model versions. + +## Upload files, log metrics, log parameters to a model version + +Files can either be uploaded to a model version using: + +- The package registry, where a model version is associated to a package of name `<model_name>/<model_version>`. +- The MLflow client compatibility. [View details](../experiment_tracking/mlflow_client.md#logging-artifacts-to-a-model-version). + +Users can log metrics and a parameters of a model version through the MLflow client compatibility, [see details](../experiment_tracking/mlflow_client.md#logging-metrics-and-parameters-to-a-model-version) + +## Link a model version to a CI/CD job + +When creating a model version through a GitLab CI/CD job, you can link the model +version to the job, giving easy access to the job's logs, merge request, and pipeline. +This can be done through the MLflow client compatibility. [View details](../experiment_tracking/mlflow_client.md#linking-a-model-version-to-a-cicd-job). + +## Model versions and semantic versioning + +The version of a model version in GitLab must follow [Semantic Version specification](https://semver.org/). +Using semantic versioning facilitates model deployment, by communicating which +if a new version can be deployed without changes to the application: + +- A change in the major component signifies a breaking change in the model, and that the application + that consumes the model must be updated to properly use this new version. + A new algorithm or the addition of a mandatory feature column are examples of breaking + changes that would require a bump at the major component. + +- A change in the minor component signifies a non-breaking change, and that the + consumer can safely use the new version without breaking, although it might + need to be updated to use its new functionality. For example, adding a non-mandatory + feature column to the model is a minor bump, because when that feature is not passed, + it will still work. + +- A change in the patch component means that a new version is out that does not + require any action by the application. For example, a daily retrain of the + model does not change the feature set or how the application consumes the + model version. Auto updating to a new patch is a safe update. + +## Related topics + +- Development details, feedback, and feature requests in [epic 9423](https://gitlab.com/groups/gitlab-org/-/epics/9423). diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index b280a2645c5..d41825af613 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Organize work with projects **(FREE ALL)** diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 4d8675b104d..5f55aca93b0 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -1,8 +1,7 @@ --- -type: concepts stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages DNS records **(FREE ALL)** diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 1c2b342f5d3..345a30da198 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages custom domains **(FREE ALL)** @@ -273,7 +273,7 @@ meet these requirements. **Do not** open certificates or encryption keys in regular text editors. Always use code editors (such as -Sublime Text, Atom, Dreamweaver, Brackets, etc). +Sublime Text, Dreamweaver, Brackets, etc). ## Force HTTPS for GitLab Pages websites diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 3d9fe4b04e9..6ccd3033b57 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -1,9 +1,8 @@ --- -type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages Let's Encrypt certificates **(FREE ALL)** @@ -43,7 +42,7 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. Turn on the **Automatic certificate management using Let's Encrypt** toggle. @@ -70,7 +69,7 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Next to the domain name, select **Edit**. 1. In **Verification status**, select **Retry verification** (**{retry}**). 1. If you're still getting the same error: @@ -85,7 +84,7 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Next to the domain name, select **Remove**. 1. [Add the domain again, and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index f42fdf4fc40..50ccc885bcb 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -1,8 +1,7 @@ --- -type: concepts stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages SSL/TLS certificates **(FREE ALL)** diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 90fc1a72eb3..07b400710f0 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab Pages website from a CI/CD template **(FREE ALL)** diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index e3b3b99b8e1..e3c374eaacc 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab Pages website from a forked sample project **(FREE ALL)** diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 545fc6a568b..9de2703b82b 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create a GitLab Pages website from scratch **(FREE ALL)** diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index fe073fe6de7..b931d2d3911 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab Pages website from a project template **(FREE ALL)** diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 8fa927bd61c..25f91880d5a 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab Pages deployment for a static site **(FREE ALL)** @@ -34,7 +34,7 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. A **Get Started with Pages** form appears. If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index ec511ee0a5f..e9e8d5d69de 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages default domain names and URLs **(FREE ALL)** diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 418c97c9433..d658a09e760 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -2,7 +2,7 @@ description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages **(FREE ALL)** @@ -154,3 +154,106 @@ cookies manually with JavaScript. By default, every project in a group shares the same domain, for example, `group.gitlab.io`. This means that cookies are also shared for all projects in a group. To ensure each project uses different cookies, enable the Pages [unique domains](introduction.md#enable-unique-domains) feature for your project. + +## Create multiple deployments **(PREMIUM ALL EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/129534) in GitLab 16.7 as an [Experiment](../../../policy/experiment-beta-support.md) [with a flag](../../feature_flags.md) named `pages_multiple_versions_setting`, disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +an administrator can [enable the feature flag](../../../administration/feature_flags.md) named +`pages_multiple_versions_setting`. On GitLab.com, this feature is not available. This feature is not ready for production use. + +Use the [`pages.path_prefix`](../../../ci/yaml/index.md#pagespagespath_prefix) CI/CD option to configure a prefix for the GitLab Pages URL. A prefix allows you +to differentiate between multiple GitLab Pages deployments. + +Multiple GitLab Pages deployments (pages created with a `path_prefix`) count toward your [storage](../../../user/usage_quotas.md) usage. + +### Enable multiple deployments + +To enable multiple GitLab Pages deployments: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Deploy > Pages**. +1. Select **Use multiple deployments**. + +### Path clash + +`pages.path_prefix` can take dynamic values from [CI/CD variables](../../../ci/variables/index.md) +that can create pages deployments which could clash with existing paths in your site. +For example, given an existing GitLab Pages site with the following paths: + +```plaintext +/index.html +/documents/index.html +``` + +If a `pages.path_prefix` is `documents`, that version will override the existing path. +In other words, `https://namespace.gitlab.io/project/documents/index.html` will point to the +`/index.html` on the `documents` deployment of the site, instead of `documents/index.html` of the +`main` deployment of the site. + +Mixing [CI/CD variables](../../../ci/variables/index.md) with other strings can reduce the path clash +possibility. For example: + +```yaml +pages: + stage: deploy + script: + - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}" + variables: + PAGES_PREFIX: "" # No prefix by default (master) + pages: + path_prefix: "$PAGES_PREFIX" + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run on default branch (with default PAGES_PREFIX) + - if: $CI_COMMIT_BRANCH == "staging" # Run on master (with default PAGES_PREFIX) + variables: + PAGES_PREFIX: '_stg' # Prefix with _stg for the staging branch + - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Conditionally change the prefix for Merge Requests + when: manual # Run pages manually on Merge Requests + variables: + PAGES_PREFIX: 'mr$CI_MERGE_REQUEST_IID' # Prefix with the mr<iid>, like `mr123` +``` + +Some other examples of mixing [variables](../../../ci/variables/index.md) with strings for dynamic prefixes: + +- `pages.path_prefix: '__$CI_COMMIT_REF_SLUG'`: Branch or tag name prefixed with `__`, like `__branch-name`. +- `pages.path_prefix: '-${CI_MERGE_REQUEST_IID}-'`: Merge request number prefixed and suffixed with `-`, like `-123-`. + +### Use multiple deployments to create pages environments + +You can use multiple GitLap Pages deployments to create a new [environment](../../../ci/environments/index.md). +For example: + +```yaml +pages: + stage: deploy + script: + - echo "Pages accessible through ${CI_PAGES_URL}/${PAGES_PREFIX}" + variables: + PAGES_PREFIX: "" # no prefix by default (master) + pages: + path_prefix: "$PAGES_PREFIX" + environment: + name: "Pages ${PAGES_PREFIX}" + url: "${CI_PAGES_URL}/${PAGES_PREFIX}" + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == "staging" # ensure to run on master (with default PAGES_PREFIX) + variables: + PAGES_PREFIX: '_stg' # prefix with _stg for the staging branch + - if: $CI_PIPELINE_SOURCE == "merge_request_event" # conditionally change the prefix on Merge Requests + when: manual # run pages manually on Merge Requests + variables: + PAGES_PREFIX: 'mr$CI_MERGE_REQUEST_IID' # prefix with the mr<iid>, like `mr123` +``` + +With this configuration, users will have the access to each GitLab Pages deployment through the UI. +When using [environments](../../../ci/environments/index.md) for pages, all pages environments are +listed on the project environment list. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 664c80e0351..42a05e0b1bb 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages settings **(FREE ALL)** @@ -65,7 +65,7 @@ You can configure redirects for your site using a `_redirects` file. For more in To remove your pages: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Select **Remove pages**. ## Subdomains of subdomains @@ -100,7 +100,7 @@ By default, every project in a group shares the same domain, for example, `group To ensure your project uses a unique Pages domain, enable the unique domains feature for the project: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Pages**. +1. Select **Deploy > Pages**. 1. Select the **Use unique domain** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 26f28be72ae..1c7aa0f182c 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages access control **(FREE ALL)** @@ -15,8 +15,9 @@ on your GitLab instance. When enabled, only authenticated <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v=tSPAr5mQYc8). -1. Navigate to your project's **Settings > General** and expand **Visibility, project features, permissions**. - +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. 1. Toggle the **Pages** button to enable the access control. If you don't see the toggle button, that means it isn't enabled. Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 39d80517bc7..4f8549c1589 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -3,7 +3,7 @@ description: 'Learn how to configure the build output folder for the most common static site generators' stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages public folder **(FREE ALL)** diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index ff1f138e5b7..d13f30060e7 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages redirects **(FREE ALL)** diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index f8f44d344d1..0377ab389a5 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected branches **(FREE ALL)** @@ -43,6 +43,9 @@ When a branch is protected, the default behavior enforces these restrictions on for that branch at the project level are ignored. All other protections continue to use project level settings. +You can implement a [scan result policy](../application_security/policies/scan-result-policies.md#approval_settings) +to prevent protected branches being unprotected or deleted. + ### When a branch matches multiple rules When a branch matches multiple rules, the **most permissive rule** determines the @@ -128,7 +131,7 @@ specific branch is configured with **Allowed to force push** settings at both th group and project levels, the **Allowed to force push** setting at the _project_ level is ignored in favor of the group level setting. -Prerequisite: +Prerequisites: - You must have the Owner role in the group. @@ -153,7 +156,7 @@ If more than one rule applies to a branch, the _most permissive_ rule controls how the branch behaves. For merge controls to work properly, set **Allowed to push and merge** to a broader set of users than **Allowed to merge**. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role. @@ -264,7 +267,7 @@ Deploy keys are not available in the **Allowed to merge** dropdown list. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 [with a flag](../../administration/feature_flags.md) named `allow_force_push_to_protected_branches`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. Feature flag `allow_force_push_to_protected_branches` removed. -You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to +You can allow [force pushes](../../topics/git/git_rebase.md#force-pushing) to protected branches. To protect a new branch and enable force push: @@ -360,6 +363,10 @@ Thus, they can skip merge request approval rules, Code Owners included. The permission to merge or push to protected branches defines whether or not a user can run CI/CD pipelines and execute actions on jobs. +Because [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md) run on the source +branch, a pipeline isn't created if the user opening a merge request does not have permission to merge +or push to the source branch. + See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches) for details about the pipelines security model. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index b312acd49f4..104433be2dc 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected tags **(FREE ALL)** @@ -125,7 +125,7 @@ To allow a deploy key to create a protected tag: You can manually delete protected tags with the GitLab API, or the GitLab user interface. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role in your project. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 6c89e09bd47..a129e6f6cd0 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Push options **(FREE ALL)** diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 16967a3a46e..be119275cd3 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab quick actions **(FREE ALL)** @@ -55,7 +54,6 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | | `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | | `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | -| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. | | `/blocked_by <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocked by other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). | | `/blocks <issue1> <issue2>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark the issue as blocking other issues. The `<issue>` value should be in the format of `#issue`, `group/project#issue`, or the full issue URL. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214232) in GitLab 16.0). | | `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line created a specific type of to-do item notification. | @@ -88,6 +86,7 @@ To auto-format this table, use the VS Code Markdown Table formatter: `https://do | `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). In [GitLab 15.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/376760), you can also use the quick action when creating a new issue. | | `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | | `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md). | +| `/react :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle an emoji reaction. [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/409884) from `/award` in GitLab 16.7. `/award` is still available as an aliased command. | | `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). | | `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | | `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 17ea0e3f694..6c31b2ad5d3 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Releases **(FREE ALL)** @@ -75,7 +75,7 @@ Prerequisites: To create a release in the Releases page: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Releases** and select **New release**. +1. Select **Deploy > Releases** and select **New release**. 1. From the [**Tag name**](release_fields.md#tag-name) dropdown list, either: - Select an existing Git tag. Selecting an existing tag that is already associated with a release results in a validation error. @@ -216,7 +216,7 @@ To delete a release, use either the In the UI: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Deploy > Releases**. +1. Select **Deploy > Releases**. 1. In the upper-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. @@ -321,7 +321,7 @@ To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with the Maintainer role. 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. +1. Select **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Select **Expand** to see the deploy freeze table. 1. Select **Add deploy freeze** to open the deploy freeze modal. @@ -360,7 +360,7 @@ Releases can be made accessible to non-project members while keeping repository- projects that use releases as a way to give access to new versions of software but do not want the source code to be public. -To make releases available publicly, set the following [project settings](../settings/index.md#configure-project-features-and-permissions): +To make releases available publicly, set the following [project settings](../settings/project_features_permissions.md#configure-project-features-and-permissions): - Repository is enabled and set to **Only Project Members** - Releases is enabled and set to **Everyone With Access** diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index 7b5e808641c..fc21e157753 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release CI/CD examples diff --git a/doc/user/project/releases/release_cli.md b/doc/user/project/releases/release_cli.md index 9daa6705ad8..1770b7b0931 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -29,7 +29,7 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description \ ## Install the `release-cli` for the Shell executor **(FREE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/release-cli/-/issues/21) in GitLab 13.8. -> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the Package Registry](https://gitlab.com/gitlab-org/release-cli/-/packages). +> - [Changed](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/108) in GitLab 14.2, the `release-cli` binaries are also [available in the package registry](https://gitlab.com/gitlab-org/release-cli/-/packages). When you use a runner with the Shell executor, you can download and install the `release-cli` manually for your [supported OS and architecture](https://release-cli-downloads.s3.amazonaws.com/latest/index.html). @@ -37,7 +37,7 @@ Once installed, [the `release` keyword](../../../ci/yaml/index.md#release) is av ### Install on Unix/Linux -1. Download the binary for your system from the GitLab Package Registry. +1. Download the binary for your system from the GitLab package registry. For example, if you use an amd64 system: ```shell diff --git a/doc/user/project/releases/release_evidence.md b/doc/user/project/releases/release_evidence.md index 7f8624fc520..83865b95c1f 100644 --- a/doc/user/project/releases/release_evidence.md +++ b/doc/user/project/releases/release_evidence.md @@ -1,7 +1,7 @@ --- stage: Govern group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release evidence **(FREE ALL)** diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index d26ca87e384..c74ebaab89d 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -1,7 +1,7 @@ --- stage: Deploy group: Environments -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release fields @@ -182,7 +182,7 @@ to store any artifacts from a release or tag pipeline, that can also be used for attaching binary files to an individual release entry. You basically need to: -1. [Push the artifacts to the Generic Package Registry](../../packages/generic_packages/index.md#publish-a-package-file). +1. [Push the artifacts to the Generic package registry](../../packages/generic_packages/index.md#publish-a-package-file). 1. [Attach the package link to the release](#links). The following example generates release assets, publishes them diff --git a/doc/user/project/remote_development/connect_machine.md b/doc/user/project/remote_development/connect_machine.md index 6bbc0b8123a..cf46774741c 100644 --- a/doc/user/project/remote_development/connect_machine.md +++ b/doc/user/project/remote_development/connect_machine.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Connect a remote machine to the Web IDE **(FREE ALL BETA)** diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md index 8ca505be500..ac8d7102e40 100644 --- a/doc/user/project/remote_development/index.md +++ b/doc/user/project/remote_development/index.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Remote development **(FREE ALL BETA)** diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index fdc822ca49f..4fc83cf77ea 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: concepts, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Default branch **(FREE ALL)** @@ -68,8 +67,7 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. For **Initial default branch name**, select a new default branch. @@ -128,8 +126,7 @@ you must either: Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand **Default branch**. 1. Select [**Initial default branch protection**](#protect-initial-default-branches). @@ -146,8 +143,7 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > Repository**. 1. Expand the **Default branch** section. 1. Clear the **Allow owners to manage default branch protection per group** checkbox. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 3640beebdfb..0a0cbcbb9c8 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Branches **(FREE ALL)** @@ -289,7 +289,8 @@ To do this: ## Configure rules for target branches **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127115) in GitLab 16.4 [with a flag](../../../../administration/feature_flags.md) named `target_branch_rules_flag`. Enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127115) in GitLab 16.4 [with a flag](../../../../administration/feature_flags.md) named `target_branch_rules_flag`. Enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136431) in GitLab 16.7. Some projects use multiple long-term branches for development, like `develop` and `qa`. In these projects, you might want to keep `main` as the default branch, but expect diff --git a/doc/user/project/repository/code_suggestions/index.md b/doc/user/project/repository/code_suggestions/index.md index b44e26f8daf..9e52da6068c 100644 --- a/doc/user/project/repository/code_suggestions/index.md +++ b/doc/user/project/repository/code_suggestions/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Suggestions **(FREE ALL BETA)** @@ -17,16 +16,18 @@ Beta users should read about the [known limitations](#known-limitations). We loo Write code more efficiently by using generative AI to suggest code while you're developing. -Code Suggestions supports two distinct types of interactions: +With Code Suggestions, you get: - Code Completion, which suggests completions the current line you are typing. These suggestions are usually low latency. - Code Generation, which generates code based on a natural language code comment block. Generating code can exceed multiple seconds. +## Start using Code Suggestions + GitLab Duo Code Suggestions are available: -- On [self-managed](self_managed.md) and [SaaS](saas.md). +- On [self-managed](self_managed.md) and [SaaS](saas.md). View these pages to get started. - In VS Code, Microsoft Visual Studio, JetBrains IDEs, and Neovim. You must have the corresponding GitLab extension installed. -- In the GitLab WebIDE. +- In the GitLab Web IDE. <div class="video-fallback"> <a href="https://youtu.be/wAYiy05fjF0">View how to setup and use GitLab Duo Code Suggestions</a>. @@ -36,34 +37,7 @@ GitLab Duo Code Suggestions are available: </figure> During Beta, usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). -Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). As Code Suggestions matures to General Availibility it will be governed by our [AI Functionality Terms](https://about.gitlab.com/handbook/legal/ai-functionality-terms/). - -## Use Code Suggestions - -Prerequisites: - -- Code Suggestions must be enabled for [SaaS](saas.md#enable-code-suggestions) or for [self-managed](self_managed.md#enable-code-suggestions-on-self-managed-gitlab). -- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). - -To use Code Suggestions: - -1. Author your code. As you type, suggestions are displayed. Code Suggestions, depending on the cursor position, either provides code snippets or completes the current line. -1. Describe the requirements in natural language. Be concise and specific. Code Suggestions generates functions and code snippets as appropriate. -1. To accept a suggestion, press <kbd>Tab</kbd>. -1. To ignore a suggestion, keep typing as you usually would. -1. To explicitly reject a suggestion, press <kbd>esc</kbd>. - -Things to remember: - -- AI is non-deterministic, so you may not get the same suggestion every time with the same input. -- Just like product requirements, writing clear, descriptive, and specific tasks results in quality generated code. - -### Progressive enhancement - -This feature is designed as a progressive enhancement to developer's IDEs. -Code Suggestions offer a completion if a suitable recommendation is provided to the user in a timely matter. -In the event of a connection issue or model inference failure, the feature gracefully degrades. -Code Suggestions do not prevent you from writing code in your IDE. +Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). As Code Suggestions matures to General Availability it will be governed by our [AI Functionality Terms](https://about.gitlab.com/handbook/legal/ai-functionality-terms/). ## Supported languages @@ -168,6 +142,13 @@ However, Code Suggestions may generate suggestions that are: - Insecure code - Offensive or insensitive +## Progressive enhancement + +This feature is designed as a progressive enhancement to developer's IDEs. +Code Suggestions offer a completion if a suitable recommendation is provided to the user in a timely matter. +In the event of a connection issue or model inference failure, the feature gracefully degrades. +Code Suggestions do not prevent you from writing code in your IDE. + ## Feedback Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). diff --git a/doc/user/project/repository/code_suggestions/saas.md b/doc/user/project/repository/code_suggestions/saas.md index ac64aba4335..1af5eef585c 100644 --- a/doc/user/project/repository/code_suggestions/saas.md +++ b/doc/user/project/repository/code_suggestions/saas.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Suggestions on GitLab SaaS **(FREE SAAS BETA)** @@ -20,12 +19,11 @@ Learn about [data usage when using Code Suggestions](index.md#code-suggestions-d ## Enable Code Suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/121079) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. -You must enable Code Suggestions for both your user account and your group: - -- [Enable Code Suggestions for all group members](../../../group/manage.md#enable-code-suggestions). (You must be a group owner). -- [Enable Code Suggestions for your own account](../../../profile/preferences.md#enable-code-suggestions). +A group owner must +[enable Code Suggestions for your top-level group](../../../group/manage.md#enable-code-suggestions-for-a-group). NOTE: If you are having issues enabling Code Suggestions, view the @@ -35,7 +33,31 @@ If you are having issues enabling Code Suggestions, view the Prerequisites: -- Ensure Code Suggestions is enabled for your user and group. -- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). +- You must have configured Code Suggestions in a + [supported IDE editor extension](index.md#supported-editor-extensions). +- Code Suggestions must be enabled for: + - [The top-level group](../../../group/manage.md#enable-code-suggestions-for-a-group). + - [Your own account](../../../profile/preferences.md#enable-code-suggestions), if your + account is not part of the percentage rollout. + +To use Code Suggestions: + +1. Determine if your user account is part of the percentage rollout. See + [Enable Code Suggestions](../../../profile/preferences.md#enable-code-suggestions) + for more information. +1. Author your code. As you type, suggestions are displayed. + Code Suggestions provide code snippets or complete the current line, depending on the cursor position. +1. Describe the requirements in natural language. Be concise and specific. Code Suggestions generates functions and code snippets as appropriate. +1. To accept a suggestion, press <kbd>Tab</kbd>. +1. To ignore a suggestion, keep typing as you usually would. +1. To explicitly reject a suggestion, press <kbd>Esc</kbd>. + +Things to remember: + +- AI is non-deterministic, so you may not get the same suggestion every time with the same input. +- Just like product requirements, writing clear, descriptive, and specific tasks results in quality generated code. + +## Disable Code Suggestions -[Use Code Suggestions](index.md#use-code-suggestions). +Individual users can disable Code Suggestions by disabling the feature in their +[installed IDE editor extension](index.md#supported-editor-extensions). diff --git a/doc/user/project/repository/code_suggestions/self_managed.md b/doc/user/project/repository/code_suggestions/self_managed.md index fd363e56021..26850bc8b5f 100644 --- a/doc/user/project/repository/code_suggestions/self_managed.md +++ b/doc/user/project/repository/code_suggestions/self_managed.md @@ -1,11 +1,10 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Code Suggestions on self-managed GitLab **(PREMIUM SELF BETA)** +# Code Suggestions on self-managed GitLab **(SELF BETA)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta) on self-managed GitLab. > - [Introduced support for Google Vertex AI Codey APIs](https://gitlab.com/groups/gitlab-org/-/epics/10562) in GitLab 16.1. @@ -15,28 +14,30 @@ type: index, reference Write code more efficiently by using generative AI to suggest code while you're developing. GitLab Duo Code Suggestions are available on GitLab Enterprise Edition. -Cloud licensing is required for Premium and Ultimate subscription tiers. Code Suggestions are not available for GitLab Community Edition. -WARNING: -In GitLab 16.3 and later, only Premium and Ultimate customers can participate in the free trial of Code Suggestions on self-managed GitLab. +> In GitLab 16.3 and later, to participate in the free trial of Code Suggestions on self-managed GitLab, you must: +> +> - Be a Premium or Ultimate customer. +> - Have activated cloud licensing. Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). Learn about [data usage when using Code Suggestions](index.md#code-suggestions-data-usage). -## Enable Code Suggestions on self-managed GitLab **(FREE SELF)** +## Enable Code Suggestions on self-managed GitLab -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10653) in GitLab 16.1 as [Beta](../../../../policy/experiment-beta-support.md#beta). +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139916) in GitLab 16.8. Available to a percentage of users. When you enable Code Suggestions for your self-managed instance, you: - Agree to the [GitLab testing agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). - Acknowledge that GitLab sends data from the instance, including personal data, to GitLab.com infrastructure. -How you enable Code Suggestions differs depending on your version of GitLab. +How you enable Code Suggestions for your instance differs depending on your version of GitLab. -### GitLab 16.3 and later +### GitLab 16.3 and later **(PREMIUM)** Prerequisites: @@ -46,9 +47,8 @@ Prerequisites: To enable Code Suggestions for your self-managed GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Code Suggestions** and select **Turn on Code Suggestions for this instance**. In GitLab 16.3, you do not need to enter anything into the **Personal access token** field. In GitLab 16.4 and later, there is no **Personal access token** field. @@ -65,6 +65,9 @@ The users in your instance can now use Code Suggestions. ### GitLab 16.2 and earlier +FLAG: +On self-managed GitLab 16.0 and earlier, GitLab Duo Code Suggestions is not available. To use this feature, you must have GitLab 16.1 or later. For optimal performance and full feature access, you should upgrade to GitLab 16.3 or later, which supports cloud licensing. + Prerequisites: - You are an administrator. @@ -95,9 +98,8 @@ To enable Code Suggestions for your GitLab SaaS account: To enable Code Suggestions for your self-managed GitLab instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. -1. On the left sidebar, select **Settings > General**. +1. On the left sidebar, at the bottom, select **Admin Area**. +1. Select **Settings > General**. 1. Expand **Code Suggestions** and: - Select **Turn on Code Suggestions for this instance**. - In **Personal access token**, enter your GitLab SaaS personal access token. @@ -126,14 +128,14 @@ If your GitLab instance uses an HTTP proxy server to access the internet, ensure the server is configured to allow outbound connections, including the [`gitlab_workhorse` environment variable](https://docs.gitlab.com/omnibus/settings/environment-variables.html). -### Update GitLab +### Upgrade GitLab In GitLab 16.3 and later, GitLab is enforcing the cloud licensing requirement for Code Suggestions: -- The Premium and Ultimate subscription tiers support cloud Licensing. +- The Premium and Ultimate subscription tiers support cloud licensing. - GitLab Free does not have cloud licensing support. -If you have a GitLab Free subscription and update to GitLab 16.3 or later, +If you have a GitLab Free subscription and upgrade to GitLab 16.3 or later, to continue having early access to Code Suggestions, you must: 1. Have a [subscription that supports cloud licensing](https://about.gitlab.com/pricing/). @@ -144,8 +146,8 @@ to continue having early access to Code Suggestions, you must: You must [manually synchronize your subscription](../../../../subscriptions/self_managed/index.md#manually-synchronize-your-subscription-details) if either: -- You have already updated to GitLab 16.3 and have just bought a Premium or Ultimate tier subscription. -- You already have a Premium or Ultimate tier subscription and have just updated to GitLab 16.3. +- You have already upgraded to GitLab 16.3 and have just bought a Premium or Ultimate tier subscription. +- You already have a Premium or Ultimate tier subscription and have just upgraded to GitLab 16.3. Without the manual synchronization, it might take up to 24 hours to active Code Suggestions on your instance. @@ -153,10 +155,22 @@ Without the manual synchronization, it might take up to 24 hours to active Code Prerequisites: -- Code Suggestions must be enabled [for the instance](#enable-code-suggestions-on-self-managed-gitlab). -- You must have installed and configured a [supported IDE editor extension](index.md#supported-editor-extensions). +- You must have a [supported IDE editor extension](index.md#supported-editor-extensions). +- Code Suggestions must be enabled [for your instance](self_managed.md#enable-code-suggestions-on-self-managed-gitlab). + +To use Code Suggestions: + +1. Author your code. As you type, suggestions are displayed. + Code Suggestions provide code snippets or complete the current line, depending on the cursor position. +1. Describe the requirements in natural language. Be concise and specific. Code Suggestions generates functions and code snippets as appropriate. +1. To accept a suggestion, press <kbd>Tab</kbd>. +1. To ignore a suggestion, keep typing as you usually would. +1. To explicitly reject a suggestion, press <kbd>Esc</kbd>. -[Use Code Suggestions](index.md#use-code-suggestions). +Things to remember: + +- AI is non-deterministic, so you may not get the same suggestion every time with the same input. +- Just like product requirements, writing clear, descriptive, and specific tasks results in quality generated code. ### Data privacy @@ -170,3 +184,8 @@ The Code Suggestions service then securely returns an AI-generated code suggesti Neither GitLab nor Google Vertex AI Codey APIs have any visibility into a self-managed customer's code other than what is sent to generate the code suggestion. + +## Disable Code Suggestions + +Individual users can disable Code Suggestions by disabling the feature in their +[installed IDE editor extension](index.md#supported-editor-extensions). diff --git a/doc/user/project/repository/code_suggestions/troubleshooting.md b/doc/user/project/repository/code_suggestions/troubleshooting.md index 86400ea8860..c18ea2dd26b 100644 --- a/doc/user/project/repository/code_suggestions/troubleshooting.md +++ b/doc/user/project/repository/code_suggestions/troubleshooting.md @@ -1,8 +1,7 @@ --- stage: Create group: Code Creation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting Code Suggestions **(FREE ALL BETA)** @@ -11,12 +10,12 @@ When working with GitLab Duo Code Suggestions, you might encounter the following ## Code Suggestions aren't displayed -If Code Suggestions are not displayed, try the following troubleshooting steps. +If Code Suggestions are not displayed, and you have [installed a supported IDE extension](index.md#supported-editor-extensions), try the following troubleshooting steps. In GitLab, ensure Code Suggestions is enabled: - [For your user account](../../../profile/preferences.md#enable-code-suggestions). -- [For *all* top-level groups your account belongs to](../../../group/manage.md#enable-code-suggestions). If you don't have a role that lets you view the top-level group's settings, contact a group owner. +- [For **all** top-level groups your account belongs to](../../../group/manage.md#enable-code-suggestions-for-a-group). If you don't have a role that lets you view the top-level group's settings, contact a group owner. ### Code Suggestions not displayed in VS Code or GitLab WebIDE diff --git a/doc/user/project/repository/csv.md b/doc/user/project/repository/csv.md index fcf8d538431..8f0596bddeb 100644 --- a/doc/user/project/repository/csv.md +++ b/doc/user/project/repository/csv.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CSV files **(FREE ALL)** diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 5dd8ad39889..a2084d8a157 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File finder **(FREE ALL)** diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index c71c89b68c3..a1efb7b1ea6 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -1,10 +1,10 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Project forking workflow **(FREE ALL)** +# Forks **(FREE ALL)** Whenever possible, it's recommended to work in a common Git repository and use branching strategies to manage your work. However, @@ -69,6 +69,10 @@ or the command line. GitLab Premium and Ultimate tiers can also automate updates > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 16.0. Feature flag `synchronize_fork` removed. +Prerequisite: + +- The fork must be created from an [unprotected branch](../protected_branches.md) in upstream repository. + To update your fork from the GitLab UI: 1. On the left sidebar, select **Search or go to**. @@ -78,7 +82,7 @@ To update your fork from the GitLab UI: information box to determine if your fork is ahead, behind, or both. In this example, the fork is behind the upstream repository: -  +  1. If your fork is **ahead** of the upstream repository, select **Create merge request** to propose adding your fork's changes to the upstream repository. diff --git a/doc/user/project/repository/geojson.md b/doc/user/project/repository/geojson.md index eb66a667deb..e454387b7f1 100644 --- a/doc/user/project/repository/geojson.md +++ b/doc/user/project/repository/geojson.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GeoJSON files **(FREE ALL)** diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 3f49f1e05f2..a602638d244 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Documentation on Git file blame." --- @@ -21,48 +20,59 @@ Prerequisites: To view the blame for a file: -1. Go to your project's **Code > Repository**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Repository**. 1. Select the file you want to review. -1. In the upper-right corner, select **Blame**. +1. In the upper-right corner, select **Blame**, and go to the line you want to see. When you select **Blame**, this information is displayed: - + -If you hover over a commit in the UI, the commit's precise date and time -are shown. +To see the precise date and time of the commit, hover over the date. The vertical bar +to the left of the user avatar shows the general age of the commit. The newest +commits have a dark blue bar. As the age of the commit increases, the bar color +changes to light gray. -## Blame previous commit +### Blame previous commit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19299) in GitLab 12.7. +To see earlier revisions of a specific line: -To see earlier revisions of a specific line, select **View blame prior to this change** -until you've found the changes you're interested in viewing: - - +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Code > Repository**. +1. Select the file you want to review. +1. In the upper-right corner, select **Blame**, and go to the line you want to see. +1. Select **View blame prior to this change** (**{doc-versions}**) + until you've found the changes you're interested in viewing. ## Associated `git` command If you're running `git` from the command line, the equivalent command is `git blame <filename>`. For example, if you want to find `blame` information -about a `README.md` file in the local directory, run the following command: +about a `README.md` file in the local directory: -```shell -git blame README.md -``` +1. Run this command `git blame README.md`. +1. If the line you want to see is not in the first page of results, press <kbd>Space</kbd> + until you find the line you want. +1. To exit out of the results, press <kbd>Q</kbd>. -The output looks similar to the following, which includes the commit time -in UTC format: +The `git blame` output in the CLI looks like this: ```shell -62e2353a (Achilleas Pipinellis 2019-07-11 14:52:18 +0300 1) [](https://gitlab.com/gitlab-com/gitlab-docs/commits/master) -fb0fc7d6 (Achilleas Pipinellis 2016-11-07 22:21:22 +0100 2) -^764ca75 (Connor Shea 2016-10-05 23:40:24 -0600 3) # GitLab Documentation -^764ca75 (Connor Shea 2016-10-05 23:40:24 -0600 4) -0e62ed6d (Mike Jang 2019-11-26 21:44:53 +0000 5) This project hosts the repository used to generate the GitLab -0e62ed6d (Mike Jang 2019-11-26 21:44:53 +0000 6) documentation website and deployed to https://docs.gitlab.com. It uses the +58233c4f1054c (Dan Rhodes 2022-05-13 07:02:20 +0000 1) ## Contributor License Agreement +b87768f435185 (Jamie Hurewitz 2017-10-31 18:09:23 +0000 2) +8e4c7f26317ff (Brett Walker 2023-10-20 17:53:25 +0000 3) Contributions to this repository are subject to the +58233c4f1054c (Dan Rhodes 2022-05-13 07:02:20 +0000 4) ``` -## File blame through the API +The output includes: + +- The SHA of the commit. +- The name of the committer. +- The date and time in UTC format. +- The line number. +- The contents of the line. + +## Related topics -You can also get this information over the [Git file blame REST API](../../../api/repository_files.md#get-file-blame-from-repository). +- [Git file blame REST API](../../../api/repository_files.md#get-file-blame-from-repository). diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index db50e6d185e..45c59a02f8b 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments description: "Documentation on Git file history." --- diff --git a/doc/user/project/repository/img/file_blame_output_v12_6.png b/doc/user/project/repository/img/file_blame_output_v12_6.png Binary files differdeleted file mode 100644 index c1186429917..00000000000 --- a/doc/user/project/repository/img/file_blame_output_v12_6.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_blame_output_v16_6.png b/doc/user/project/repository/img/file_blame_output_v16_6.png Binary files differnew file mode 100644 index 00000000000..5eff95541fe --- /dev/null +++ b/doc/user/project/repository/img/file_blame_output_v16_6.png diff --git a/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png b/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png Binary files differdeleted file mode 100644 index 2da9e28c84f..00000000000 --- a/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png +++ /dev/null diff --git a/doc/user/project/repository/img/update-fork_v15_11.png b/doc/user/project/repository/img/update-fork_v15_11.png Binary files differdeleted file mode 100644 index 244868d80ae..00000000000 --- a/doc/user/project/repository/img/update-fork_v15_11.png +++ /dev/null diff --git a/doc/user/project/repository/img/update-fork_v16_6.png b/doc/user/project/repository/img/update-fork_v16_6.png Binary files differnew file mode 100644 index 00000000000..59901db6a49 --- /dev/null +++ b/doc/user/project/repository/img/update-fork_v16_6.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 96b92a057cf..dd8ee61f6ae 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository **(FREE ALL)** @@ -23,9 +23,25 @@ To create a repository, you can: You can add files to a repository: - When you create a project. -- After you create a project: - - By using [the web editor](web_editor.md). - - From the command line. +- After you create a project, by using: + - [The web editor](web_editor.md#upload-a-file). + - [The UI](#add-a-file-from-the-ui). + - [The command line](../../../topics/git/git_add.md). + +### Add a file from the UI + +You can upload a file from the GitLab UI. + +<!-- Original source for this list: doc/user/project/repository/web_editor.md#upload-a-file --> +<!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> + +1. On the left sidebar, select **Search or go to** and find your project. +1. Go to the directory where you want to upload the file. +1. Next to the directory name, select the plus icon (**{plus}**) > **Upload file**. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). +1. Select **Upload file**. ## Commit changes to a repository @@ -80,7 +96,7 @@ prompted to open Xcode. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. All projects can be cloned into Visual Studio Code from the GitLab user interface, but you -can also install the [GitLab Workflow VS Code extension](vscode.md) to clone from +can also install the [GitLab Workflow VS Code extension](../../../editor_extensions/visual_studio_code/index.md) to clone from Visual Studio Code: - From the GitLab interface: @@ -90,7 +106,7 @@ Visual Studio Code: 1. Select a folder to clone the project into. After Visual Studio Code clones your project, it opens the folder. -- From Visual Studio Code, with the [extension](vscode.md) installed, use the +- From Visual Studio Code, with the [extension](../../../editor_extensions/visual_studio_code/index.md) installed, use the extension's [`Git: Clone` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#clone-gitlab-projects). ### Clone and open in IntelliJ IDEA @@ -193,8 +209,7 @@ These files can either be plain text or have the extension of a > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19515) in GitLab 12.6. -GitLab can render OpenAPI specification files. The filename -must include `openapi` or `swagger` and the extension must be `yaml`, +GitLab can render OpenAPI specification files. The file name must include `openapi` or `swagger` and the extension must be `yaml`, `yml`, or `json`. The following examples are all correct: - `openapi.yml` @@ -237,12 +252,12 @@ updated, at most, every 15 minutes. The file size includes repository files, art The size can differ slightly from one instance to another due to compression, housekeeping, and other factors. -Administrators can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md). +Administrators can set a [repository size limit](../../../administration/settings/account_and_limit_settings.md). [GitLab sets the size limits for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). -## Repository contributor statistics +## Repository contributor analytics -You can view a list and charts of commits made by project members in [Contributor statistics](../../analytics/contributor_statistics.md). +You can view a list and charts of commits made by project members in [Contributor analytics](../../analytics/contributor_analytics.md). ## Repository history graph @@ -259,7 +274,7 @@ When a repository path changes, GitLab handles the transition from the old location to the new one with a redirect. When you [rename a user](../../profile/index.md#change-your-username), -[change a group path](../../group/manage.md#change-a-groups-path), or [rename a repository](../settings/index.md#rename-a-repository): +[change a group path](../../group/manage.md#change-a-groups-path), or [rename a repository](../../project/working_with_projects.md#rename-a-repository): - URLs for the namespace and everything under it, like projects, are redirected to the new URLs. @@ -270,15 +285,19 @@ When you [rename a user](../../profile/index.md#change-your-username), work after a rename. - The redirects are available as long as the original path is not claimed by another group, user, or project. +- [API redirects](../../../api/rest/index.md#redirects) may need to be followed explicitly. + +After you change a path, you must update the existing URL in the following resources, +because they can't follow redirects: -WARNING: -The [CI/CD `includes` keyword](../../../ci/yaml/includes.md) can't follow project -redirects. Pipelines fail with a syntax error when configured to use `includes` -to fetch configuration from a project that is renamed or moved. +- [Include statements](../../../ci/yaml/includes.md) except [`include:component`](../../../ci/components/index.md), otherwise pipelines fail with a syntax error. CI/CD component references can follow redirects. +- Namespaced API calls that use the [encoded path](../../../api/rest/index.md#namespaced-path-encoding) instead of the numeric namespace and project IDs. +- [Docker image references](../../../ci/yaml/index.md#image). +- Variables that specify a project or namespace. ## Related topics -- [GitLab Workflow VS Code extension](vscode.md) +- [GitLab Workflow VS Code extension](../../../editor_extensions/visual_studio_code/index.md) - [Lock files and prevent change conflicts](../file_lock.md) - [Repository API](../../../api/repositories.md) - [Find files](file_finder.md) diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 2a1fc0cddf8..2e14c52d2a7 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Jupyter Notebook files **(FREE ALL)** diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 9d97f53cb43..d4ab550cb8a 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Bidirectional mirroring **(PREMIUM ALL)** @@ -45,7 +45,7 @@ To create the webhook in the downstream instance: 1. Create a [personal access token](../../../profile/personal_access_tokens.md) with `API` scope. 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > Webhooks**. +1. Select **Settings > Webhooks**. 1. Add the webhook **URL**, which (in this case) uses the [Pull Mirror API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project) request to trigger an immediate pull after a repository update: diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index b16197e45b2..34a2757bb67 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository mirroring **(FREE ALL)** @@ -107,7 +107,7 @@ While mirrors are scheduled to update automatically, you can force an immediate - The [interval, in seconds](../../../../administration/instance_limits.md#pull-mirroring-interval) for pull mirroring limits has not elapsed after its last update. -Prerequisite: +Prerequisites: - You must have at least the Maintainer role for the project. diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 5b3c76d982a..0a57681c90d 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pull from a remote repository **(PREMIUM ALL)** diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index e18e3631d7f..3aa4c768ebe 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Push mirroring **(FREE ALL)** diff --git a/doc/user/project/repository/mirror/troubleshooting.md b/doc/user/project/repository/mirror/troubleshooting.md index a83231ceb63..57a9351e85d 100644 --- a/doc/user/project/repository/mirror/troubleshooting.md +++ b/doc/user/project/repository/mirror/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Troubleshooting repository mirroring **(FREE ALL)** diff --git a/doc/user/project/repository/monorepos/index.md b/doc/user/project/repository/monorepos/index.md index 144f46cd7d5..36b0521235d 100644 --- a/doc/user/project/repository/monorepos/index.md +++ b/doc/user/project/repository/monorepos/index.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing monorepos @@ -20,7 +20,7 @@ size. Monorepos can be large for [many reasons](https://about.gitlab.com/blog/2022/09/06/speed-up-your-monorepo-workflow-in-git/#characteristics-of-monorepos). -Large repositories pose a performance risk performance when used in GitLab, especially if a large monorepo receives many clones or pushes a day, which is common for them. +Large repositories pose a performance risk when used in GitLab, especially if a large monorepo receives many clones or pushes a day, which is common for them. Git itself has performance limitations when it comes to handling monorepos. @@ -189,7 +189,7 @@ You might experience a `fatal: the remote end hung up unexpectedly` error when a - The same large repository in parallel. You can attempt to mitigate this issue by increasing the default negotiation timeout values. For more information, see -[Configure negotiation timeouts](../../../../administration/gitaly/configure_gitaly.md#configure-negotiation-timeouts). +[Configure the negotiation timeouts](../../../../administration/settings/gitaly_timeouts.md#configure-the-negotiation-timeouts). ## Optimize your repository diff --git a/doc/user/project/repository/monorepos/observability.md b/doc/user/project/repository/monorepos/observability.md index a54b4bef9d5..9d99dac2eba 100644 --- a/doc/user/project/repository/monorepos/observability.md +++ b/doc/user/project/repository/monorepos/observability.md @@ -1,7 +1,7 @@ --- stage: Systems group: Gitaly -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metrics for measuring monorepo performance diff --git a/doc/user/project/repository/monorepos/troubleshooting.md b/doc/user/project/repository/monorepos/troubleshooting.md new file mode 100644 index 00000000000..208464c3e0f --- /dev/null +++ b/doc/user/project/repository/monorepos/troubleshooting.md @@ -0,0 +1,98 @@ +--- +stage: Systems +group: Gitaly +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting monorepo performance + +Review these suggestions for performance problems with monorepos. + +## Slowness during `git clone` or `git fetch` + +There are a few key causes of slowness with clones and fetches. + +### High CPU utilization + +If the CPU utilization on your Gitaly nodes is high, you can also check +how much CPU is taken up from clones by [filtering on certain values](../../../../user/project/repository/monorepos/observability.md#cpu-and-memory). + +In particular, the `command.cpu_time_ms` field can indicate how +much CPU is being taken up by clones and fetches. + +In most cases, the bulk of server load is generated from `git-pack-objects` +processes, which is initiated during clones and fetches. Monorepos are often very busy +and CI/CD systems send a lot of clone and fetch commands to the server. + +High CPU utilization is a common cause of slow performance. +The following non-mutually exclusive causes are possible: + +- [Too many clones for Gitaly to handle](#cause-too-many-large-clones). +- [Poor read distribution on Gitaly Cluster](#cause-poor-read-distribution). + +#### Cause: too many large clones + +You might have too many large clones for Gitaly to handle. Gitaly can struggle to keep up +because of a number of factors: + +- The size of a repository. +- The volume of clones and fetches. +- Lack of CPU capacity. + +To help Gitaly process many large clones, you might need to reduce the burden on Gitaly servers through some optimization strategies +such as: + +- Turn on [pack-objects-cache](../../../../administration/gitaly/configure_gitaly.md#pack-objects-cache) + to reduce the work that `git-pack-objects` has to do. +- Change [Git strategy](../../../../user/project/repository/monorepos/index.md#git-strategy) + in CI/CD settings from `clone` to `fetch` or `none`. +- [Stop fetching tags](../../../../user/project/repository/monorepos/index.md#git-fetch-extra-flags), + unless your tests require them. +- [Use shallow clones](../../../../user/project/repository/monorepos/index.md#shallow-cloning) + whenever possible. + +The other option is to increase CPU capacity on Gitaly servers. + +#### Cause: poor read distribution + +You might have poor read distribution on Gitaly Cluster. + +To observe if most read traffic is going to the primary Gitaly node instead of +getting distributed across the cluster, use the +[read distribution Prometheus metric](observability.md#read-distribution). + +If the secondary Gitaly nodes aren't receiving much traffic, it might be that +the secondary nodes are perpetually out of sync. This problem is exacerbated in +a monorepo. + +Monorepos are often both large and busy. This leads to two effects. Firstly, +monorepos are pushed to often and have lots of CI jobs running. There can be +times when write operations such as deleting a branch fails a proxy call to the +secondary nodes. This triggers a replication job in Gitaly Cluster so that +the secondary node will catch up eventually. + +The replication job is essentially a `git fetch` from the secondary node to the +primary node, and because monorepos are often very large, this fetch can take a +long time. + +If the next call fails before the previous replication job completes, and this +keeps happening, you can end up in a state where your monorepo is constantly +behind in its secondaries. This leads to all traffic going to the primary node. + +One reason for these failed proxied writes is a known issue with the Git +`$GIT_DIR/packed-refs` file. The file must be locked to +remove an entry in the file, which can lead to a race condition that causes a +delete to fail when concurrent deletes happen. + +Engineers at GitLab have developed mitigations to try to batch reference deletions. + +Turn on the following [feature flags](../../../../administration/feature_flags.md) to allow GitLab to batch ref deletions. +These feature flags do not need downtime to enable. + +- `merge_request_cleanup_ref_worker_async` +- `pipeline_cleanup_ref_worker_async` +- `pipeline_delete_gitaly_refs_in_batches` +- `merge_request_delete_gitaly_refs_in_batches` + +[Epic 4220](https://gitlab.com/groups/gitlab-org/-/epics/4220) proposes to add RefTable support in GitLab, +which is considered a long-term solution. diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index d61d09301a5..fc36748a8dd 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Push rules **(PREMIUM ALL)** @@ -33,14 +33,13 @@ All projects created after you configure global push rules inherit this configuration. However, each existing project must be updated manually, using the process described in [Override global push rules per project](#override-global-push-rules-per-project). -Prerequisite: +Prerequisites: - You must be an administrator. To create global push rules: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Push Rules**. 1. Expand **Push rules**. 1. Set the rule you want. @@ -80,6 +79,19 @@ Use these rules for your commit messages. The word boundary character (`\b`) prevents false negatives, because Git adds a newline character (`\n`) to the end of the commit message. + Commit messages created in GitLab UI set `\r\n` as a newline character. + Use `(\r\n?|\n)` instead of `\n` in your regular expression to correctly match + it. + + For example, given the following multi-line commit description: + + ```plaintext + JIRA: + Description + ``` + + You can validate it with this regular expression: `JIRA:(\r\n?|\n)\w+`. + - **Reject expression in commit messages**: Commit messages must not match the expression. To allow any commit message, leave empty. Uses multiline mode, which can be disabled by using `(?-m)`. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index ca7f2ae2043..a060973d89f 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce repository size **(FREE ALL)** diff --git a/doc/user/project/repository/signed_commits/gpg.md b/doc/user/project/repository/signed_commits/gpg.md index 88f6917d4b6..4b644a79c71 100644 --- a/doc/user/project/repository/signed_commits/gpg.md +++ b/doc/user/project/repository/signed_commits/gpg.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign commits with GPG **(FREE ALL)** diff --git a/doc/user/project/repository/signed_commits/index.md b/doc/user/project/repository/signed_commits/index.md index e6632ecb81a..cbea5e4e2f5 100644 --- a/doc/user/project/repository/signed_commits/index.md +++ b/doc/user/project/repository/signed_commits/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Signed commits **(FREE ALL)** @@ -22,15 +22,14 @@ Sign commits with your: ## Verify commits You can review commits for a merge request, or for an entire project, to confirm -they are signed: - -1. To review commits for a project: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Code > Commits**. -1. To review commits for a merge request: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. On the left sidebar, select **Merge requests**, then select your merge request. - 1. Select **Commits**. +they are signed. + +1. On the left sidebar, select **Search or go to** and find your project. +1. To review commits: + - For a project, select **Code > Commits**. + - For a merge request: + 1. Select **Code > Merge requests**, then select your merge request. + 1. Select **Commits**. 1. Identify the commit you want to review. Signed commits show either a **Verified** or **Unverified** badge, depending on the verification status of the signature. Unsigned commits do not display a badge: diff --git a/doc/user/project/repository/signed_commits/ssh.md b/doc/user/project/repository/signed_commits/ssh.md index c87a992fdac..e1c2a73be3e 100644 --- a/doc/user/project/repository/signed_commits/ssh.md +++ b/doc/user/project/repository/signed_commits/ssh.md @@ -48,8 +48,7 @@ To configure Git to use your key: git config --global gpg.format ssh ``` -1. Specify which public SSH key to use as the signing key and change the filename - (`~/.ssh/examplekey.pub`) to the location of your key. The filename might +1. Specify which public SSH key to use as the signing key and change the file name (`~/.ssh/examplekey.pub`) to the location of your key. The file name might differ, depending on how you generated your key: ```shell diff --git a/doc/user/project/repository/signed_commits/x509.md b/doc/user/project/repository/signed_commits/x509.md index 17767cbd8f4..18c967698fa 100644 --- a/doc/user/project/repository/signed_commits/x509.md +++ b/doc/user/project/repository/signed_commits/x509.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign commits and tags with X.509 certificates **(FREE ALL)** diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md index 1f1b8dfc9cd..232f2e387d1 100644 --- a/doc/user/project/repository/tags/index.md +++ b/doc/user/project/repository/tags/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tags **(FREE ALL)** diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md deleted file mode 100644 index 476cfc55298..00000000000 --- a/doc/user/project/repository/vscode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../editor_extensions/visual_studio_code/index.md' -remove_date: '2023-10-31' ---- - -This document was moved to [another location](../../../editor_extensions/visual_studio_code/index.md). - -<!-- This redirect file can be deleted after <2023-10-31>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 3acc62186a3..3899890ea7e 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,114 +1,97 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web Editor **(FREE ALL)** -You can use the Web Editor to make changes to a single file directly from the -GitLab UI. To make changes to multiple files, see [Web IDE](../web_ide/index.md). +You can use the Web Editor to make changes to a single file directly from the GitLab UI. +To make changes to multiple files, see [Web IDE](../web_ide/index.md). -In the Web Editor, you can: - -- [Create a file](#create-a-file). -- [Edit a file](#edit-a-file). -- [Upload a file](#upload-a-file). -- [Create a directory](#create-a-directory). -- [Create a branch](#create-a-branch). -- [Create a tag](#create-a-tag). - -Your [primary email address is used by default](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) -for any change you commit through the Web Editor. +Your [primary email address](../../profile/index.md#change-the-email-displayed-on-your-commits) +is used by default for any change you commit with the Web Editor. ## Create a file To create a text file in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, - select the plus icon (**{plus}**). -1. From the dropdown list, select **New file**. +1. Go to the directory where you want to create the new file. +1. Next to the directory name, select the plus icon (**{plus}**) > **New file**. 1. Complete the fields. -1. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected, if you had chosen a **Target branch** other than the [default branch (such as `main`)](../../../user/project/repository/branches/default.md). + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). 1. Select **Commit changes**. -### Create a file from a template +### From a template + +To create a text file from a template in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Code > Repository**. -1. Next to the project name, select the plus icon (**{plus}**) to display a - dropdown list, then select **New file** from the list. -1. For **Filename**, provide one of the filenames that GitLab provides a template for: +1. Go to the directory where you want to create the new file. +1. Next to the directory name, select the plus icon (**{plus}**) > **New file**. +1. In **Filename**, enter a filename that GitLab provides a template for: - `.gitignore` - `.gitlab-ci.yml` - `LICENSE` - `Dockerfile` -1. Select **Apply a template**, then select the template you want to apply. -1. Make your changes to the file. -1. Provide a **Commit message**. -1. Enter a **Target branch** to merge into. To create a new merge request with - your changes, enter a branch name that is not your repository's - [default branch](../../../user/project/repository/branches/default.md), -1. Select **Commit changes** to add the commit to your branch. +1. From the **Apply a template** dropdown list, select a template. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). +1. Select **Commit changes**. ## Edit a file To edit a text file in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. Go to your file. -1. In the upper right, select **Edit > Edit single file**. - -### Keyboard shortcuts - -When you [edit a file](#edit-a-file) in the Web Editor, you can use the same keyboard shortcuts for the Web IDE. -See the [available shortcuts](../../shortcuts.md#web-ide). +1. Go to the file you want to edit. +1. Select **Edit > Edit single file**. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). +1. Select **Commit changes**. ### Preview Markdown > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378966) in GitLab 15.6. -To preview Markdown content in the Web Editor: - -1. [Edit a file](#edit-a-file). -1. Do one of the following: - - Select the **Preview** tab. - - From the context menu, select **Preview Markdown**. +To preview a Markdown file in the Web Editor: -In the **Preview** tab, you can see a live Markdown preview alongside your content. +1. On the left sidebar, select **Search or go to** and find your project. +1. Go to the file you want to preview. +1. Select **Edit > Edit single file**. +1. Select the **Preview** tab. -To close the preview panel, do one of the following: +You can see a live Markdown preview alongside your content. -- Select the **Write** tab. -- From the context menu, select **Hide Live Preview**. +To close the preview panel, select the **Write** tab. ### Link to specific lines -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11. - To link to single or multiple lines in the Web Editor, add hash information to the filename segment of the URL. For example: - `MY_FILE.js#L3` highlights line 3 in `MY_FILE.js`. - `MY_FILE.js#L3-10` highlights lines 3 to 10 in `MY_FILE.js`. -To link to a single line, you can also: - -1. [Edit a file](#edit-a-file). -1. Select a line number. +When you edit a file, you can also link to a single line by selecting a line number. ## Upload a file -To upload a binary file in the Web Editor: +To upload a file in the Web Editor: -<!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> +<!-- This list is duplicated at doc/user/project/repository/index.md#add-a-file-from-the-ui --> <!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **Upload file**. -1. Complete the fields. To create a merge request with the uploaded file, ensure the **Start a new merge request with these changes** toggle is turned on. +1. Go to the directory where you want to upload the file. +1. Next to the directory name, select the plus icon (**{plus}**) > **Upload file**. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). 1. Select **Upload file**. ## Create a directory @@ -116,9 +99,11 @@ To upload a binary file in the Web Editor: To create a directory in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **New directory**. -1. Complete the fields. To create a merge request with the new directory, ensure the **Start a new merge request with these changes** toggle is turned on. +1. Go to the directory where you want to create the new directory. +1. Next to the directory name, select the plus icon (**{plus}**) > **New directory**. +1. Complete the fields. + - To create a merge request with your changes, enter a branch name + that's not your repository's [default branch](branches/default.md). 1. Select **Create directory**. ## Create a branch @@ -126,8 +111,7 @@ To create a directory in the Web Editor: To create a [branch](branches/index.md) in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **New branch**. +1. Next to the repository name, select the plus icon (**{plus}**) > **New branch**. 1. Complete the fields. 1. Select **Create branch**. @@ -137,7 +121,6 @@ You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: 1. On the left sidebar, select **Search or go to** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). -1. From the dropdown list, select **New tag**. +1. Next to the repository name, select the plus icon (**{plus}**) > **New tag**. 1. Complete the fields. 1. Select **Create tag**. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index d99729e3c1b..0594f3fe2ee 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Plan group: Product Planning -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Requirements management **(ULTIMATE ALL)** @@ -43,7 +42,7 @@ For a more in-depth walkthrough see [GitLab Requirements Traceability Walkthroug A paginated list of requirements is available in each project, and there you can create a new requirement. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -73,7 +72,7 @@ next to the requirement title. You can edit a requirement from the requirements list page. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -89,7 +88,7 @@ To edit a requirement: You can archive an open requirement while you're in the **Open** tab. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -101,7 +100,7 @@ As soon as a requirement is archived, it no longer appears in the **Open** tab. You can view the list of archived requirements in the **Archived** tab. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. @@ -294,7 +293,7 @@ By exporting requirements, you and your team can import them into another tool o your customers. Exporting requirements can aid collaboration with higher-level systems, as well as audit and regulatory compliance tasks. -Prerequisite: +Prerequisites: - You must have at least the Reporter role. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md deleted file mode 100644 index cd09f84641e..00000000000 --- a/doc/user/project/service_desk.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'service_desk/index.md' -remove_date: '2023-10-24' ---- - -This document was moved to [another location](service_desk/index.md). - -<!-- This redirect file can be deleted after <2023-10-24>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/service_desk/configure.md b/doc/user/project/service_desk/configure.md index 8d0fbd81ebd..91dbe7a38dd 100644 --- a/doc/user/project/service_desk/configure.md +++ b/doc/user/project/service_desk/configure.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Service Desk **(FREE ALL)** @@ -17,7 +17,7 @@ Prerequisites: [email sub-addressing](../../../administration/incoming_email.md#email-sub-addressing), but you can also use [catch-all mailboxes](../../../administration/incoming_email.md#catch-all-mailbox). To do this, you must have administrator access. -- You must have enabled [issue](../settings/index.md#configure-project-features-and-permissions) +- You must have enabled [issue](../settings/project_features_permissions.md#configure-project-features-and-permissions) tracker for the project. To enable Service Desk in your project: @@ -120,7 +120,7 @@ You can set description templates at various levels: The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. -Prerequisite: +Prerequisites: - You must have [created a description template](../description_templates.md#create-an-issue-template). @@ -155,15 +155,36 @@ To edit the custom email display name: 1. Below **Email display name**, enter a new name. 1. Select **Save changes**. +## Reopen issues when an external participant comments + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8549) in GitLab 16.7 + +You can configure GitLab to reopen closed issues when an external participant adds +a new comment on an issue by email. This also adds an internal comment that mentions +the assignees of the issue and creates to-do items for them. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a walkthrough, see [a short showcase video](https://youtu.be/163wDM1e43o). + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To enable this setting: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Service Desk**. +1. Select the **Reopen issues on a new note from an external participant** checkbox. +1. Select **Save changes**. + ## Custom email address **(BETA)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329990) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `service_desk_custom_email`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.4. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for -your entire instance, an administrator can [disable the feature flag](../../../administration/feature_flags.md) -named `service_desk_custom_email`. On GitLab.com, this feature is available. +> - Ability to select the SMTP authentication method [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429680) in GitLab 16.6. +> - [Feature flag `service_desk_custom_email` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/387003) in GitLab 16.7. +> - Local network allowed for SMTP host on GitLab self-managed [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/435206) in GitLab 16.7 Configure a custom email address to show as the sender of your support communication. Maintain brand identity and instill confidence among support requesters with a domain they recognize. @@ -193,6 +214,8 @@ The custom email address you want to use must meet all of the following requirem - You have SMTP credentials (ideally, you should use an app password). The username and password are stored in the database using the Advanced Encryption Standard (AES) with a 256-bit key. +- The **SMTP host** must be resolvable from the network of your GitLab instance (on GitLab self-managed) + or the public internet (on GitLab SaaS). - You must have at least the Maintainer role for the project. - Service Desk must be configured for the project. @@ -206,8 +229,7 @@ Configure and verify a custom email address when you want to send Service Desk e 1. Note the presented Service Desk address of this project, and with your email provider (for example, Gmail), set up email forwarding from the custom email address to the Service Desk address. -1. Back in GitLab, complete the fields. **SMTP host** must be resolvable from the network of your GitLab instance (on GitLab self-managed) - or the public internet (on GitLab SaaS). +1. Back in GitLab, complete the fields. 1. Select **Save & test settings**. The configuration has been saved and the verification of the custom email address is triggered. @@ -237,6 +259,56 @@ If the verification failed, the email also contains details of the reason. If the verification was successful, the custom email address is ready to be used. You can now enable sending Service Desk emails via the custom email address. +#### Troubleshooting your configuration + +When configuring a custom email you might encounter the following issues. + +##### Invalid credentials + +You might get an error that states that invalid credentials were used. + +This occurs when the SMTP server returns that the authentication wasn't successful. + +To troubleshoot this: + +1. Check your SMTP credentials, especially the username and password. +1. Sometimes GitLab cannot automatically select an authentication method that the SMTP server supports. Either: + - Try the available authentication methods (**Plain**, **Login** and **CRAM-MD5**). + - Check which authentication methods your SMTP server supports, using the + [`swaks` command line tool](https://www.jetmore.org/john/code/swaks/): + 1. Run the following command with your credentials and look for a line that starts with `250-AUTH`: + + ```shell + swaks --to user@example.com \ + --from support@example.com \ + --auth-user support@example.com \ + --server smtp@example.com:587 \ + -tls-optional \ + --auth-password your-app-password + ``` + + 1. Select one of the supported authentication methods in the custom email setup form. + +##### Incorrect forwarding target + +You might get an error that states that an incorrect forwarding target was used. + +This occurs when the verification email was forwarded to a different email address than the +project-specific Service Desk address that's displayed in the custom email configuration form. + +You must use the Service Desk address generated from `incoming_email`. Forwarding to the additional +Service Desk alias address generated from `service_desk_email` is not supported because it doesn't support +all reply by email functionalities. + +To troubleshoot this: + +1. Find the correct email address to forward emails to. Either: + - Note the address from the verification result email that all project owners and the user that + triggered the verification process receive. + - Copy the address from the **Service Desk email address to forward emails to** input in the + custom email setup form. +1. Forward all emails to the custom email address to the correct target email address. + ### Enable or disable the custom email address After the custom email address has been verified, administrators can enable or disable sending Service Desk emails via the custom email address. @@ -353,6 +425,7 @@ In GitLab: - **SMTP port**: `587`. - **SMTP username**: Prefilled with the custom email address. - **SMTP password**: The app password you previously created for the custom email account. + - **SMTP authentication method**: Let GitLab select a server-supported method (recommended) 1. Select **Save and test connection** 1. After the [verification process](#verification) you should be able to [enable the custom email address](#enable-or-disable-the-custom-email-address). diff --git a/doc/user/project/service_desk/index.md b/doc/user/project/service_desk/index.md index ab807553436..9ab69c4bdb8 100644 --- a/doc/user/project/service_desk/index.md +++ b/doc/user/project/service_desk/index.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Desk **(FREE ALL)** @@ -46,6 +46,7 @@ Meanwhile: - [Customize emails sent to the requester](configure.md#customize-emails-sent-to-the-requester) - [Use a custom template for Service Desk tickets](configure.md#use-a-custom-template-for-service-desk-tickets) - [Support Bot user](configure.md#support-bot-user) + - [Reopen issues when an external participant comments](configure.md#reopen-issues-when-an-external-participant-comments) - [Custom email address (Beta)](configure.md#custom-email-address) - [Use an additional Service Desk alias email](configure.md#use-an-additional-service-desk-alias-email) - [Configure email ingestion in multi-node environments](configure.md#configure-email-ingestion-in-multi-node-environments) @@ -61,3 +62,33 @@ Meanwhile: Your emails might be ignored because they contain one of the [email headers that GitLab ignores](../../../administration/incoming_email.md#rejected-headers). + +### Email ingestion doesn't work in 16.6.0 self-managed + +GitLab self-managed `16.6.0` introduced a regression that prevents `mail_room` (email ingestion) from starting. +Service Desk and other reply-by-email features don't work. +[Issue 432257](https://gitlab.com/gitlab-org/gitlab/-/issues/432257) tracks fixing this problem. + +The workaround is to run the following commands in your GitLab installation +to patch the affected files: + +::Tabs + +:::TabTitle Linux package (Omnibus) + +```shell +curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff" +patch -p1 -d /opt/gitlab/embedded/service/gitlab-rails < /tmp/mailroom.patch +gitlab-ctl restart mailroom +``` + +:::TabTitle Docker + +```shell +curl --output /tmp/mailroom.patch --url "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137279.diff" +cd /opt/gitlab/embedded/service/gitlab-rails +patch -p1 < /tmp/mailroom.patch +gitlab-ctl restart mailroom +``` + +::EndTabs diff --git a/doc/user/project/service_desk/using_service_desk.md b/doc/user/project/service_desk/using_service_desk.md index 5f3c725b83b..7db84f6988b 100644 --- a/doc/user/project/service_desk/using_service_desk.md +++ b/doc/user/project/service_desk/using_service_desk.md @@ -1,7 +1,7 @@ --- -stage: Monitor +stage: Service Management group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Service Desk **(FREE ALL)** diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 22eb7c54d12..fc9b24362e0 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Migrating projects using file exports **(FREE ALL)** @@ -86,8 +86,7 @@ Before you can migrate projects on a self-managed GitLab instance using file exp To enable file exports as an import source for the destination instance: -1. On the left sidebar, select **Search or go to**. -1. Select **Admin Area**. +1. On the left sidebar, at the bottom, select **Admin Area**. 1. Select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Scroll to **Import sources**. @@ -206,7 +205,7 @@ may be possible for an attacker to steal your sensitive data. - You must have [exported the project and its data](#export-a-project-and-its-data). - Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later - than the GitLab version you exported to. + than the GitLab version you exported from. - Review [compatibility](#compatibility) for any issues. - At least the Maintainer role on the destination group to migrate to. diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index 79401a7734a..3f2b9a23f2d 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import and Integrate -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Troubleshooting file export project migrations @@ -86,7 +86,7 @@ reduce the repository size for another import attempt: 1. To reduce the repository size, work on this `smaller-tmp-main` branch: [identify and remove large files](../repository/reducing_the_repo_size_using_git.md) - or [interactively rebase and fixup](../../../topics/git/git_rebase.md#interactive-rebase) + or [interactively rebase and fixup](../../../topics/git/git_rebase.md#rebase-interactively-by-using-git) to reduce the number of commits. ```shell diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 623c61744f7..0456577f1ff 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,368 +1,11 @@ --- -stage: Data Stores -group: Tenant Scale -info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments' -type: reference, index, howto +redirect_to: '../working_with_projects.md' +remove_date: '2024-02-28' --- -# Project settings **(FREE ALL)** +This document was moved to [another location](../working_with_projects.md). -Use the **Settings** page to manage the configuration options in your [project](../index.md). - -## View project settings - -Prerequisite: - -- You must have at least the Maintainer role for the project. - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. To display all settings in a section, select **Expand**. -1. Optional. Use the search box to find a setting. - -## Edit project name and description - -Use the project general settings to edit your project details. - -Prerequisite: - -- You must have at least the Maintainer role for the project. - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. In the **Project name** text box, enter your project name. -1. In the **Project description** text box, enter your project description. -1. Under **Project avatar**, to change your project avatar, select **Choose file**. - -## Assign topics to a project - -Use [topics](../working_with_projects.md#organizing-projects-with-topics) to categorize projects and find similar new projects. - -To assign topics to a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings** > **General**. -1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. -1. Select **Save changes**. - -If you're an instance administrator, you can administer all project topics from the -[Admin Area's Topics page](../../../administration/admin_area.md#administering-topics). - -NOTE: -The assigned topics are visible only to users with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. - -## Rename a repository - -A project's repository name defines its URL and its place on the file disk -where GitLab is installed. - -Prerequisite: - -- You must be an administrator or have the Maintainer or Owner role for the project. - -NOTE: -When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see -[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). - -To rename a repository: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Change path** text box, edit the path. -1. Select **Change path**. - -## Configure project features and permissions - -To configure features and permissions for a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. To allow users to request access to the project, select the **Users can request access** checkbox. -1. To enable or disable features in the project, use the feature toggles. -1. Select **Save changes**. - -When you disable a feature, the following additional features are also disabled: - -- If you disable the **Issues** feature, project users cannot use: - - - **Issue Boards** - - **Service Desk** - - Project users can still access **Milestones** from merge requests. - -- If you disable **Issues** and **Merge Requests**, project users cannot use: - - - **Labels** - - **Milestones** - -- If you disable **Repository**, project users cannot access: - - - **Merge requests** - - **CI/CD** - - **Git Large File Storage** - - **Packages** - -- The metrics dashboard requires read access to project environments and deployments. - Users with access to the metrics dashboard can also access environments and deployments. - -## Configure merge request settings for a project - -Configure your project's merge request settings: - -- Set up the [merge request method](../merge_requests/methods/index.md) (merge commit, fast-forward merge). -- Add merge request [description templates](../description_templates.md). -- Enable: - - [Merge request approvals](../merge_requests/approvals/index.md). - - [Status checks](../merge_requests/status_checks.md). - - [Merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - - [Merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). - - [Required associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). - - [GitLab Duo Suggested Reviewers](../merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) - - [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). -- Configure: - - [Suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - - [Merge and squash commit message templates](../merge_requests/commit_templates.md). - - [Default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. - -### Delete the source branch on merge by default - -In merge requests, you can change the default behavior so that the -**Delete the source branch** checkbox is always selected. - -To set this default: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > Merge requests**. -1. Select **Enable "Delete source branch" option by default**. -1. Select **Save changes**. - -## Export project - -You can [export a project and its data](import_export.md#export-a-project-and-its-data). - -## Transfer a project to another namespace - -When you transfer a project to another namespace, you move the project to a different group. - -Prerequisites: - -- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) you are transferring to. -- You must be the Owner of the project you transfer. -- The group must allow creation of new projects. -- The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). -- The project must not have a security policy. - If a security policy is assigned to the project, it is automatically unassigned during the transfer. -- If the root namespace changes, you must remove npm packages that follow the [naming convention](../../../user/packages/npm_registry/index.md#naming-convention) from the project. - After you transfer the project you can either: - - - Update the package scope with the new root namespace path, and publish it again to the project. - - Republish the package to the project without updating the root namespace path, which causes the package to no longer follow the naming convention. - If you republish the package without updating the root namespace path, it will not be available at the [instance level endpoint](../../../user/packages/npm_registry/index.md#install-from-the-instance-level). - -To transfer a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. Under **Transfer project**, choose the namespace to transfer the project to. -1. Select **Transfer project**. -1. Enter the project's name and select **Confirm**. - -You are redirected to the project's new page and GitLab applies a redirect. For more information about repository redirects, see [What happens when a repository path changes](../repository/index.md#what-happens-when-a-repository-path-changes). - -NOTE: -If you are an administrator, you can also use the [administration interface](../../../administration/admin_area.md#administering-projects) -to move any project to any namespace. - -### Transferring a GitLab SaaS project to a different subscription tier - -When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free: - -- [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked. -- [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) - and [test cases](../../../ci/test_cases/index.md) are deleted. - -## Archive a project - -When you archive a project, the repository, packages, issues, merge requests, and all -other features become read-only. Archived projects are also hidden from project lists. - -To archive a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Archive project** section, select **Archive project**. -1. To confirm, select **OK**. - -## Unarchive a project - -When you unarchive a project, the read-only restriction is removed, -and the project becomes available in project lists. - -Prerequisite: - -- You must be an administrator or have the Owner role for the project. - -1. Find the archived project. - 1. On the left sidebar, select **Search or go to**. - 1. Select **View all my projects**. - 1. Select **Explore projects**. - 1. In the **Sort projects** dropdown list, select **Show archived projects**. - 1. In the **Filter by name** field, enter the project name. - 1. Select the project link. -1. On the left sidebar, select **Settings > General**. -1. Under **Advanced**, select **Expand**. -1. In the **Unarchive project** section, select **Unarchive project**. -1. To confirm, select **OK**. - -## Delete a project - -> - Default deletion behavior for projects changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. -> - Default deletion behavior for projects changed to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -> - Default deletion behavior for projects on the Premium and Ultimate tier changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0. -> - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -You can mark a project to be deleted. -After you delete a project: - -- Projects in personal namespaces are deleted immediately. -- Projects in groups are deleted after a retention period. - -Prerequisite: - -- You must have the Owner role for a project. - -To delete a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Delete this project** section, select **Delete project**. -1. On the confirmation dialog, enter the project name and select **Yes, delete project**. - -This action deletes the project and all associated resources (such as issues and merge requests). - -You can also [delete projects using the Rails console](../working_with_projects.md#delete-a-project-using-console). - -### Delayed project deletion **(PREMIUM ALL)** - -> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. -> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. -> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -Prerequisite: - -- You must have the Owner role for the project. - -Projects in a group (not a personal namespace) can be deleted after a delay period. - -On self-managed instances, group administrators can define a deletion delay period of between 1 and 90 days. -On SaaS, there is a non-adjustable default retention period of seven days. - -You can [view projects that are pending deletion](../working_with_projects.md#view-projects-pending-deletion), -and use the Rails console to -[find projects that are pending deletion](../working_with_projects.md#find-projects-that-are-pending-deletion). - -### Delete a project immediately - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. -> - Option to delete projects immediately from the Admin Area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - -Prerequisites: - -- You must have the Owner role for the project. -- The project must be [marked for deletion](#delete-a-project). - -If you don't want to wait for delayed deletion, you can delete a project immediately. To do this, perform the steps for [deleting a projects](#delete-a-project) again. - -In the first cycle of deleting a project, the project is moved to the delayed deletion queue and automatically deleted after the retention period has passed. -If during this delayed deletion time you run a second deletion cycle, the project is deleted immediately. - -To immediately delete a project marked for deletion: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the **Delete this project** section, select **Delete project**. -1. On the confirmation dialog, enter the project name and select **Yes, delete project**. - -## Restore a project **(PREMIUM ALL)** - -Prerequisites: - -- You must have the Owner role for the project. -- The project must be [marked for deletion](#delete-a-project). - -To restore a project marked for deletion: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Advanced**. -1. In the Restore project section, select **Restore project**. - -## Disable project analytics - -By default, [analytics for a project](../../analytics/index.md#project-level-analytics) are displayed under the **Analyze** item in the left sidebar. -To disable this feature and remove the **Analyze** item from the left sidebar: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Turn off the **Analytics** toggle. -1. Select **Save changes**. - -## Disable CVE identifier request in issues **(FREE SAAS)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. - -In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue. - -To disable the CVE identifier request option in issues in your project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. -1. Select **Save changes**. - -## Disable project email notifications - -Prerequisite: - -- You must have the Owner role for the project. - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Clear the **Disable email notifications** checkbox. - -## Related topics - -- [Alert integrations](../../../operations/incident_management/integrations.md#configuration) -- [PagerDuty incident management](../../../operations/incident_management/manage_incidents.md#using-the-pagerduty-webhook) -- [SLA countdown timer](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) -- [Error tracking](../../../operations/error_tracking.md) -- [Incidents sync](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) -- [Service Desk](../service_desk/index.md) - -## Troubleshooting - -When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks. - -### Transfer a project through console - -If transferring a project through the UI or API is not working, you can attempt the transfer in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -```ruby -p = Project.find_by_full_path('<project_path>') - -# To set the owner of the project -current_user = p.creator - -# Namespace where you want this to be moved -namespace = Namespace.find_by_full_path("<new_namespace>") - -Projects::TransferService.new(p, current_user).execute(namespace) -``` +<!-- This redirect file can be deleted after <2024-02-28>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/settings/migrate_projects.md b/doc/user/project/settings/migrate_projects.md new file mode 100644 index 00000000000..70e6ff5da28 --- /dev/null +++ b/doc/user/project/settings/migrate_projects.md @@ -0,0 +1,126 @@ +--- +stage: Data Stores +group: Tenant Scale +info: 'To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments' +--- + +# Migrate projects **(FREE ALL)** + +## Export a project + +You can [export a project and its data](import_export.md#export-a-project-and-its-data). + +## Transfer a project to another namespace + +When you transfer a project to another namespace, you move the project to a different group. + +Prerequisites: + +- You must have at least the Maintainer role for the [group](../../group/index.md#create-a-group) you are transferring to. +- You must be the Owner of the project you transfer. +- The group must allow creation of new projects. +- The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). +- The project must not have a security policy. + If a security policy is assigned to the project, it is automatically unassigned during the transfer. +- If the root namespace changes, you must remove npm packages that follow the [naming convention](../../../user/packages/npm_registry/index.md#naming-convention) from the project. + After you transfer the project you can either: + + - Update the package scope with the new root namespace path, and publish it again to the project. + - Republish the package to the project without updating the root namespace path, which causes the package to no longer follow the naming convention. + If you republish the package without updating the root namespace path, it will not be available at the [instance level endpoint](../../../user/packages/npm_registry/index.md#install-from-the-instance-level). + +To transfer a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. Under **Transfer project**, choose the namespace to transfer the project to. +1. Select **Transfer project**. +1. Enter the project's name and select **Confirm**. + +You are redirected to the project's new page and GitLab applies a redirect. For more information about repository redirects, see [What happens when a repository path changes](../repository/index.md#what-happens-when-a-repository-path-changes). + +NOTE: +If you are an administrator, you can also use the [administration interface](../../../administration/admin_area.md#administering-projects) +to move any project to any namespace. + +### Transferring a GitLab SaaS project to a different subscription tier + +When you transfer a project from a namespace licensed for GitLab SaaS Premium or Ultimate to GitLab Free: + +- [Project access tokens](../../../user/project/settings/project_access_tokens.md) are revoked. +- [Pipeline subscriptions](../../../ci/pipelines/index.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) + and [test cases](../../../ci/test_cases/index.md) are deleted. + +## Archive a project + +When you archive a project, the repository, packages, issues, merge requests, and all +other features become read-only. Archived projects are also hidden from project lists. + +To archive a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Archive project** section, select **Archive project**. +1. To confirm, select **OK**. + +## Unarchive a project + +When you unarchive a project, the read-only restriction is removed, +and the project becomes available in project lists. + +Prerequisites: + +- You must be an administrator or have the Owner role for the project. + +1. Find the archived project. + 1. On the left sidebar, select **Search or go to**. + 1. Select **View all my projects**. + 1. Select **Explore projects**. + 1. In the **Sort projects** dropdown list, select **Show archived projects**. + 1. In the **Filter by name** field, enter the project name. + 1. Select the project link. +1. On the left sidebar, select **Settings > General**. +1. Under **Advanced**, select **Expand**. +1. In the **Unarchive project** section, select **Unarchive project**. +1. To confirm, select **OK**. + +## Restore a project **(PREMIUM ALL)** + +Prerequisites: + +- You must have the Owner role for the project. +- The project must be [marked for deletion](../working_with_projects.md#delete-a-project). + +To restore a project marked for deletion: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the Restore project section, select **Restore project**. + +## Troubleshooting + +When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks. + +### Transfer a project through console + +If transferring a project through the UI or API is not working, you can attempt the transfer in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +```ruby +p = Project.find_by_full_path('<project_path>') + +# To set the owner of the project +current_user = p.creator + +# Namespace where you want this to be moved +namespace = Namespace.find_by_full_path("<new_namespace>") + +Projects::TransferService.new(p, current_user).execute(namespace) +``` + +## Related topics + +- [Migrating projects using file exports](import_export.md) +- [Troubleshooting file export project migrations](import_export_troubleshooting.md) diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 3526425c912..f22fe603f81 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,8 +1,7 @@ --- stage: Govern group: Authentication -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference, howto +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Project access tokens @@ -24,7 +23,7 @@ Use a project access token to authenticate: - The project access token as the password. Project access tokens are similar to [group access tokens](../../group/settings/group_access_tokens.md) -and [personal access tokens](../../profile/personal_access_tokens.md). +and [personal access tokens](../../profile/personal_access_tokens.md), but project access tokens are scoped to a project, so you cannot use them to access resources from other projects. In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) as personal access tokens if the limit is set. @@ -57,6 +56,7 @@ To create a project access token: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Access Tokens**. +1. Select **Add new token**. 1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Enter an expiry date for the token. - The token expires on that date at midnight UTC. @@ -65,7 +65,7 @@ To create a project access token: - An instance-wide [maximum lifetime](../../../administration/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-project-access-token). -1. Select **Create project access token**. +1. Select **Create project access token**. A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you can't view it again. @@ -75,7 +75,7 @@ To revoke a project access token: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Access Tokens**. -1. Next to the project access token to revoke, select **Revoke**. +1. Next to the project access token to revoke, select **Revoke** (**{remove}**). ## Scopes for a project access token @@ -87,17 +87,17 @@ The scope determines the actions you can perform when you authenticate with a pr NOTE: See the warning in [create a project access token](#create-a-project-access-token) regarding internal projects. -| Scope | Description | -|:-------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `api` | Grants complete read and write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | -| `read_registry` | Grants read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `write_registry` | Grants write access (push) to the [Container Registry](../../packages/container_registry/index.md). | -| `read_repository` | Grants read access (pull) to the repository. | -| `write_repository` | Grants read and write access (pull and push) to the repository. | -| `create_runner` | Grants permission to create runners in the project. | -| `ai_features` | Grants permission to perform API actions for GitLab Duo. | -| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in the project. | +| Scope | Description | +|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped project API, including the [container registry](../../packages/container_registry/index.md), the [dependency proxy](../../packages/dependency_proxy/index.md), and the [package registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped project API, including the [package registry](../../packages/package_registry/index.md). | +| `read_registry` | Grants read access (pull) to the [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | Grants write access (push) to the [container registry](../../packages/container_registry/index.md). | +| `read_repository` | Grants read access (pull) to the repository. | +| `write_repository` | Grants read and write access (pull and push) to the repository. | +| `create_runner` | Grants permission to create runners in the project. | +| `ai_features` | Grants permission to perform API actions for GitLab Duo. This scope is designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see scope requirements. | +| `k8s_proxy` | Grants permission to perform Kubernetes API calls using the agent for Kubernetes in the project. | ## Enable or disable project access token creation @@ -108,7 +108,7 @@ To enable or disable project access token creation for all projects in a top-lev 1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Settings > General**. 1. Expand **Permissions and group features**. -1. Under **Permissions**, turn on or off **Allow project and group access token creation**. +1. In **Permissions**, select or clear the **Users can create project access tokens and group access tokens in this group** checkbox. Even when creation is disabled, you can still use and revoke existing project access tokens. diff --git a/doc/user/project/settings/project_features_permissions.md b/doc/user/project/settings/project_features_permissions.md new file mode 100644 index 00000000000..27c0668079c --- /dev/null +++ b/doc/user/project/settings/project_features_permissions.md @@ -0,0 +1,206 @@ +--- +stage: Data Stores +group: Tenant Scale +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Project features and permissions **(FREE ALL)** + +## Configure project features and permissions + +To configure features and permissions for a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. To allow users to request access to the project, select the **Users can request access** checkbox. +1. To enable or disable features in the project, use the feature toggles. +1. Select **Save changes**. + +When you disable a feature, the following additional features are also disabled: + +- If you disable the **Issues** feature, project users cannot use: + + - **Issue Boards** + - **Service Desk** + - Project users can still access **Milestones** from merge requests. + +- If you disable **Issues** and **Merge Requests**, project users cannot use: + + - **Labels** + - **Milestones** + +- If you disable **Repository**, project users cannot access: + + - **Merge requests** + - **CI/CD** + - **Git Large File Storage** + - **Packages** + +- The metrics dashboard requires read access to project environments and deployments. + Users with access to the metrics dashboard can also access environments and deployments. + +## Enable and disable project features + +Enabled project features are visible and accessible to project members. +You can disable specific project features, so that they are not visible and accessible to project members, regardless of their role. + +To enable or disable individual features in a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. To enable a feature, turn on the toggle. To disable a feature, turn off the toggle. +1. Select **Save changes**. + +## Disable project analytics + +By default, [analytics for a project](../../analytics/index.md#project-level-analytics) +are displayed under the **Analyze** item in the left sidebar. +To disable this feature and remove the **Analyze** item from the left sidebar: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Turn off the **Analytics** toggle. +1. Select **Save changes**. + +## Disable CVE identifier request in issues **(FREE SAAS)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. + +In some environments, users can submit a [CVE identifier request](../../application_security/cve_id_request.md) in an issue. + +To disable the CVE identifier request option in issues in your project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Under **Issues**, turn off the **CVE ID requests in the issue sidebar** toggle. +1. Select **Save changes**. + +## Disable project email notifications + +Prerequisites: + +- You must have the Owner role for the project. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Clear the **Disable email notifications** checkbox. + +## Configure merge request settings for a project + +Configure your project's merge request settings: + +- Set up the [merge request method](../merge_requests/methods/index.md) (merge commit, fast-forward merge). +- Add merge request [description templates](../description_templates.md). +- Enable: + - [Merge request approvals](../merge_requests/approvals/index.md). + - [Status checks](../merge_requests/status_checks.md). + - [Merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). + - [Merge only when all threads are resolved](../merge_requests/index.md#prevent-merge-unless-all-threads-are-resolved). + - [Required associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). + - [GitLab Duo Suggested Reviewers](../merge_requests/reviews/index.md#gitlab-duo-suggested-reviewers) + - [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). +- Configure: + - [Suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). + - [Merge and squash commit message templates](../merge_requests/commit_templates.md). + - [Default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. + +### Delete the source branch on merge by default + +In merge requests, you can change the default behavior so that the +**Delete the source branch** checkbox is always selected. + +To set this default: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > Merge requests**. +1. Select **Enable "Delete source branch" option by default**. +1. Select **Save changes**. + +## Project topics + +Topics are labels that you can assign to projects to help you organize and find them. +A topic is typically a short name that describes the content or purpose of a project. +You can assign a topic to several projects. + +For example, you can create and assign the topics `python` and `hackathon` to all projects that use Python and are intended for Hackathon contributions. + +Topics assigned to a project are listed in the **Project overview**, below the project name and activity information. + +Only users with access to the project can see the topics assigned to that project, +but everyone (including unauthenticated users) can see the topics available on the GitLab instance. +Do not include sensitive information in the name of a topic. + +### Explore topics + +To explore project topics: + +1. On the left sidebar, select **Search or go to**. +1. Select **Explore**. +1. On the left sidebar, select **Topics**. +1. To view projects associated with a topic, select a topic. + +The **Explore topics** page shows a list of projects with this topic. + +### Filter and sort topics + +You can filter the list of projects that have a certain topic by: + +- Name +- Language +- Owner +- Archive status +- Visibility + +You can sort the projects by: + +- Date created +- Date updated +- Name +- Number of stars + +### Subscribe to a topic + +If you want to know when new projects are added to a topic, you can use its RSS feed. + +You can do this either from the **Explore topics** page or a project with topics. + +To subscribe to a topic: + +- From the **Explore topics** page: + + 1. On the left sidebar, expand the top-most chevron ({**chevron-down**}). + 1. Select **Explore**. + 1. Select **Topics**. + 1. Select the topic you want to subscribe to. + 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). + +- From a project: + + 1. On the left sidebar, select **Search or go to** and find your project. + 1. In the **Project overview** page, from the **Topics** list select the topic you want to subscribe to. + 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). + +The results are displayed as an RSS feed in Atom format. +The URL of the result contains a feed token and the list of projects that have the topic. You can add this URL to your feed reader. + +### Assign topics to a project + +To assign topics to a project: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings** > **General**. +1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. +1. Select **Save changes**. + +NOTE: +The assigned topics are visible only to users with access to the project, but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. + +### Administer topics + +Instance administrators can administer all project topics from the +[Admin Area's Topics page](../../../administration/admin_area.md#administering-topics). diff --git a/doc/user/project/system_notes.md b/doc/user/project/system_notes.md index 546b3250180..22ecf9833ac 100644 --- a/doc/user/project/system_notes.md +++ b/doc/user/project/system_notes.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # System notes **(FREE ALL)** diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index f1e5247efdb..5f06098f8f6 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -1,8 +1,7 @@ --- -type: reference stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Time tracking **(FREE ALL)** @@ -83,7 +82,7 @@ Prerequisites: To add a time entry using the user interface: -1. In the **Time tracking** section of the sidebar, select **Add time entry** (**{plus}**). A modal opens. +1. In the **Time tracking** section of the sidebar, select **Add time entry** (**{plus}**). A dialog opens. 1. Enter: - The amount of time spent. @@ -155,11 +154,9 @@ To delete all the time spent at once, use the `/remove_time_spent` [quick action ## View a time tracking report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271409) in GitLab 13.12. +### For an issue or merge request -You can view a breakdown of time spent on an issue or merge request. - -To view a time tracking report: +To view a time tracking report of time spent on an issue or merge request: 1. Go to an issue or a merge request. 1. In the right sidebar, select **Time tracking report**. @@ -168,22 +165,46 @@ To view a time tracking report: The breakdown of spent time displayed is limited to a maximum of 100 entries. +### Global time tracking report **(EXPERIMENT)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344002) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `global_time_tracking_report`. Disabled by default. +> - Enabled on GitLab.com in GitLab 16.5. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `global_time_tracking_report`. +On GitLab.com, this feature is available. +This feature is not ready for production use. + +View a report of time spent in issues and merge requests across all of GitLab. + +This feature is an [Experiment](../../policy/experiment-beta-support.md). +If you find a bug, let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/435222). + +To view the global time tracking report: + +1. In your browser, enter the global report's URL: + - For self-managed, add `/-/timelogs` to your base URL. For example, `https://gitlab.example.com/-/timelogs`. + - For GitLab.com, go to <https://gitlab.com/-/timelogs>. +1. Optional. To filter by a specific user, enter their username without the `@` symbol. +1. Select start and end dates. +1. Select **Run report**. + + + ## Available time units The following time units are available: | Time unit | What to type | Conversion rate | | --------- | --------------------------- | --------------- | -| Month | `mo`, `month`, or `months` | 4 w (160 h) | -| Week | `w`, `week`, or `weeks` | 5 d (40 h) | -| Day | `d`, `day`, or `days` | 8 h | -| Hour | `h`, `hour`, or `hours` | 60 m | +| Month | `mo`, `month`, or `months` | 4 w (160 h) | +| Week | `w`, `week`, or `weeks` | 5 d (40 h) | +| Day | `d`, `day`, or `days` | 8 h | +| Hour | `h`, `hour`, or `hours` | 60 m | | Minute | `m`, `minute`, or `minutes` | | ### Limit displayed units to hours **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29469/) in GitLab 12.1. - In GitLab self-managed instances, you can limit the display of time units to hours. To do so: diff --git a/doc/user/project/use_project_as_go_package.md b/doc/user/project/use_project_as_go_package.md new file mode 100644 index 00000000000..54e9eac7756 --- /dev/null +++ b/doc/user/project/use_project_as_go_package.md @@ -0,0 +1,178 @@ +--- +stage: Data Stores +group: Tenant Scale +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" +--- + +# Use a project as a Go package **(FREE ALL)** + +Prerequisites: + +- Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). +- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause +`go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. + +To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: + +- [`go-import`](https://pkg.go.dev/cmd/go#hdr-Remote_import_paths) +- [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) + +## Authenticate Go requests to private projects + +Prerequisites: + +- Your GitLab instance must be accessible with HTTPS. +- You must have a [personal access token](../profile/personal_access_tokens.md) with `read_api` scope. + +To authenticate Go requests, create a [`.netrc`](https://everything.curl.dev/usingcurl/netrc) file with the following information: + +```plaintext +machine gitlab.example.com +login <gitlab_user_name> +password <personal_access_token> +``` + +On Windows, Go reads `~/_netrc` instead of `~/.netrc`. + +The `go` command does not transmit credentials over insecure connections. It authenticates +HTTPS requests made by Go, but does not authenticate requests made +through Git. + +## Authenticate Git requests + +If Go cannot fetch a module from a proxy, it uses Git. Git uses a `.netrc` file to authenticate requests, but you can +configure other authentication methods. + +Configure Git to either: + +- Embed credentials in the request URL: + + ```shell + git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + ``` + +- Use SSH instead of HTTPS: + + ```shell + git config --global url."git@gitlab.example.com:".insteadOf "https://gitlab.example.com/" + ``` + +## Disable Go module fetching for private projects + +To [fetch modules or packages](../../development/go_guide/dependencies.md#fetching), Go uses +the [environment variables](../../development/go_guide/dependencies.md#proxies): + +- `GOPRIVATE` +- `GONOPROXY` +- `GONOSUMDB` + +To disable fetching: + +1. Disable `GOPRIVATE`: + - To disable queries for one project, disable `GOPRIVATE=gitlab.example.com/my/private/project`. + - To disable queries for all projects on GitLab.com, disable `GOPRIVATE=gitlab.example.com`. +1. Disable proxy queries in `GONOPROXY`. +1. Disable checksum queries in `GONOSUMDB`. + +- If the module name or its prefix is in `GOPRIVATE` or `GONOPROXY`, Go does not query module + proxies. +- If the module name or its prefix is in `GONOPRIVATE` or `GONOSUMDB`, Go does not query + Checksum databases. + +## Authenticate Git requests to private subgroups + +If the Go module is located under a private subgroup like +`gitlab.com/namespace/subgroup/go-module`, then the Git authentication doesn't work. +It happens, because `go get` makes an unauthenticated request to discover +the repository path. +Without an HTTP authentication via `.netrc` file, GitLab responds with +`gitlab.com/namespace/subgroup.git` to prevent a security risk of exposing +the project's existence for unauthenticated users. +As a result, the Go module cannot be downloaded. + +Unfortunately, Go doesn't provide any means of request authentication apart +from `.netrc`. In a future version, Go may add support for arbitrary +authentication headers. +Follow [`golang/go#26232`](https://github.com/golang/go/issues/26232) for details. + +### Workaround: use `.git` in the module name + +There is a way to skip `go get` request and force Go to use a Git authentication +directly, but it requires a modification of the module name. + +<!-- markdownlint-disable proper-names --> + +> If the module path has a VCS qualifier (one of .bzr, .fossil, .git, .hg, .svn) +> at the end of a path component, the go command will use everything up to that +> path qualifier as the repository URL. For example, for the module +> example.com/foo.git/bar, the go command downloads the repository +> at example.com/foo.git using git, expecting to find the module +> in the bar subdirectory. + +<!-- markdownlint-enable proper-names --> + +[From Go documentation](https://go.dev/ref/mod#vcs-find) + +1. Go to `go.mod` of the Go module in a private subgroup. +1. Add `.git` to the module name. + For example, rename`module gitlab.com/namespace/subgroup/go-module` to `module gitlab.com/namespace/subgroup/go-module.git`. +1. Commit and push this change. +1. Visit Go projects that depend on this module and adjust their `import` calls. + For example, `import gitlab.com/namespace/subgroup/go-module.git`. + +The Go module should be correctly fetched after this change. +For example, `GOPRIVATE=gitlab.com/namespace/* go mod tidy`. + +## Fetch Go modules from Geo secondary sites + +Use [Geo](../../administration/geo/index.md) to access Git repositories that contain Go modules +on secondary Geo servers. + +You can use SSH or HTTP to access the Geo secondary server. + +### Use SSH to access the Geo secondary server + +To access the Geo secondary server with SSH: + +1. Reconfigure Git on the client to send traffic for the primary to the secondary: + + ```shell + git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" + git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" + ``` + + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. + +1. Ensure the client is set up for SSH access to GitLab repositories. You can test this on the primary, + and GitLab replicates the public key to the secondary. + +The `go get` request generates HTTP traffic to the primary Geo server. When the module +download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. + +### Use HTTP to access the Geo secondary + +You must use persistent access tokens that replicate to the secondary server. You cannot use +CI/CD job tokens to fetch Go modules with HTTP. + +To access the Geo secondary server with HTTP: + +1. Add a Git `insteadOf` redirect on the client: + + ```shell + git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" + ``` + + - For `gitlab.example.com`, use the primary site domain name. + - For `gitlab-secondary.example.com`, use the secondary site domain name. + +1. Generate a [personal access token](../profile/personal_access_tokens.md) and + add the credentials in the client's `~/.netrc` file: + + ```shell + machine gitlab.example.com login USERNAME password TOKEN + machine gitlab-secondary.example.com login USERNAME password TOKEN + ``` + +The `go get` request generates HTTP traffic to the primary Geo server. When the module +download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. diff --git a/doc/user/project/web_ide/img/fuzzy_finder_v15_7.png b/doc/user/project/web_ide/img/fuzzy_finder_v15_7.png Binary files differdeleted file mode 100644 index 66ebae15e98..00000000000 --- a/doc/user/project/web_ide/img/fuzzy_finder_v15_7.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index fb2bd707c56..49efd463334 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,7 +1,7 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web IDE **(FREE ALL)** @@ -58,8 +58,6 @@ To open any file by its name: 1. Press <kbd>Command</kbd>+<kbd>P</kbd>. 1. Enter the name of your file. - - ## Search across files You can use the Web IDE to search all files in the opened folder. @@ -232,6 +230,10 @@ However, you can use a terminal to install dependencies and compile and debug co For more information about configuring a workspace that supports interactive web terminals, see [remote development](../remote_development/index.md). +## Related topics + +- [GitLab Duo Chat in the Web IDE](../../gitlab_duo_chat.md#web-ide) + ## Troubleshooting When working with the Web IDE, you might encounter the following issues. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index ae182f1f183..64f6fa2c75e 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group wikis **(PREMIUM ALL)** diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index fd543263ebd..f4946230360 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Wiki **(FREE ALL)** @@ -272,7 +272,7 @@ A `_sidebar` example, formatted with Markdown: Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) can enable or disable a project wiki by following the instructions in -[Sharing and permissions](../settings/index.md#configure-project-features-and-permissions). +[Sharing and permissions](../settings/project_features_permissions.md#configure-project-features-and-permissions). Administrators for self-managed GitLab installs can [configure additional wiki settings](../../../administration/wikis/index.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 2a4f0b99246..1c60f3bebf3 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Manage projects **(FREE ALL)** @@ -50,92 +50,101 @@ To view projects you have [starred](#star-a-project): 1. On the left sidebar, select your avatar and then your username. 1. On the left sidebar, select **Starred projects**. -## Organizing projects with topics +## Edit project name and description -Topics are labels that you can assign to projects to help you organize and find them. -A topic is typically a short name that describes the content or purpose of a project. -You can assign a topic to several projects. +Use the project general settings to edit your project details. -For example, you can create and assign the topics `python` and `hackathon` to all projects that use Python and are intended for Hackathon contributions. +Prerequisites: -Topics assigned to a project are listed in the **Project overview**, below the project name and activity information. +- You must have at least the Maintainer role for the project. -Only users with access to the project can see the topics assigned to that project, -but everyone (including unauthenticated users) can see the topics available on the GitLab instance. -Do not include sensitive information in the name of a topic. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. In the **Project name** text box, enter your project name. See the [limitations on project names](../../user/reserved_names.md). +1. In the **Project description** text box, enter your project description. The description is limited to 500 characters. +1. Under **Project avatar**, to change your project avatar, select **Choose file**. -### Explore topics +## Star a project -To explore project topics: +You can add a star to projects you use frequently to make them easier to find. -1. On the left sidebar, select **Search or go to**. -1. Select **Explore**. -1. On the left sidebar, select **Topics**. -1. To view projects associated with a topic, select a topic. +To add a star to a project: -The **Explore topics** page shows a list of projects with this topic. +1. On the left sidebar, select **Search or go to** and find your project. +1. In the upper-right corner of the page, select **Star**. -### Filter and sort topics +## Delete a project -You can filter the list of projects that have a certain topic by: +> - Default deletion behavior for projects changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. +> - Default deletion behavior for projects changed to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +> - Default deletion behavior for projects on the Premium and Ultimate tier changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0. +> - Default deletion behavior changed to delayed deletion on the Premium and Ultimate tier [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. -- Name -- Language -- Owner -- Archive status -- Visibility +You can mark a project to be deleted. +After you delete a project: -You can sort the projects by: +- Projects in personal namespaces are deleted immediately. +- Projects in groups are deleted after a retention period. -- Date created -- Date updated -- Name -- Number of stars +Prerequisites: -### Subscribe to a topic +- You must have the Owner role for a project. -If you want to know when new projects are added to a topic, you can use its RSS feed. +To delete a project: -You can do this either from the **Explore topics** page or a project with topics. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Delete this project** section, select **Delete project**. +1. On the confirmation dialog, enter the project name and select **Yes, delete project**. -To subscribe to a topic: +This action deletes the project and all associated resources (such as issues and merge requests). -- From the **Explore topics** page: +You can also [delete projects using the Rails console](#delete-a-project-using-console). - 1. On the left sidebar, expand the top-most chevron ({**chevron-down**}). - 1. Select **Explore**. - 1. Select **Topics**. - 1. Select the topic you want to subscribe to. - 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). +### Delayed project deletion **(PREMIUM ALL)** -- From a project: +> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. +> - [Disabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95495) in GitLab 15.3. +> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. - 1. On the left sidebar, select **Search or go to** and find your project. - 1. In the **Project overview** page, from the **Topics** list select the topic you want to subscribe to. - 1. In the upper-right corner, select **Subscribe to the new projects feed** (**{rss}**). +Prerequisites: -The results are displayed as an RSS feed in Atom format. -The URL of the result contains a feed token and the list of projects that have the topic. You can add this URL to your feed reader. +- You must have the Owner role for the project. -### Assign a topic to a project +Projects in a group (not a personal namespace) can be deleted after a delay period. -You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). +On self-managed instances, group administrators can define a deletion delay period of between 1 and 90 days. +On SaaS, there is a non-adjustable default retention period of seven days. -### Administer topics +You can [view projects that are pending deletion](#view-projects-pending-deletion), +and use the Rails console to +[find projects that are pending deletion](#find-projects-that-are-pending-deletion). -Instance administrators can administer all project topics from the -[Admin Area's Topics page](../../administration/admin_area.md#administering-topics). +### Delete a project immediately -## Star a project +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. +> - Option to delete projects immediately from the Admin Area and as a group setting removed [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0. -You can add a star to projects you use frequently to make them easier to find. +Prerequisites: -To add a star to a project: +- You must have the Owner role for the project. +- The project must be [marked for deletion](#delete-a-project). + +If you don't want to wait for delayed deletion, you can delete a project immediately. To do this, perform the steps for [deleting a projects](#delete-a-project) again. + +In the first cycle of deleting a project, the project is moved to the delayed deletion queue and automatically deleted after the retention period has passed. +If during this delayed deletion time you run a second deletion cycle, the project is deleted immediately. + +To immediately delete a project marked for deletion: 1. On the left sidebar, select **Search or go to** and find your project. -1. In the upper-right corner of the page, select **Star**. +1. Select **Settings > General**. +1. Expand **Advanced**. +1. In the **Delete this project** section, select **Delete project**. +1. On the confirmation dialog, enter the project name and select **Yes, delete project**. -## View projects pending deletion **(PREMIUM ALL)** +### View projects pending deletion > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. > - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. @@ -206,32 +215,45 @@ You can filter projects by the programming language they use. To do this: A list of projects that use the selected language is displayed. -## Change the visibility of individual features in a project +## Rename a repository -You can change the visibility of individual features in a project. +A project's repository name defines its URL and its place on the file disk +where GitLab is installed. -Prerequisite: +Prerequisites: -- You must have the Owner role for the project. +- You must be an administrator or have the Maintainer or Owner role for the project. + +NOTE: +When you change the repository path, users may experience issues if they push to, or pull from, the old URL. For more information, see +[redirects when renaming repositories](../project/repository/index.md#what-happens-when-a-repository-path-changes). + +To rename a repository: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > General**. -1. Expand **Visibility, project features, permissions**. -1. Use the toggle by each feature you want to turn on or off, or change access for. -1. Select **Save changes**. +1. Expand **Advanced**. +1. In the **Change path** text box, edit the path. +1. Select **Change path**. -## Access the Project overview page by using the project ID +## Access the project overview page by using the project ID -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. +> Project ID [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7. To access a project by using the project ID instead of its name, -go to `https://gitlab.example.com/projects/:id`. +go to `https://gitlab.example.com/projects/<id>`. + +To copy the project ID: -The project ID is displayed in the **Project overview** page, under the project name. +1. On the left sidebar, select **Search or go to** and find your project. +1. On the project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**). +1. Select **Copy project ID**. For example, if in your personal namespace `alex` you have a project `my-project` with the ID `123456`, you can access the project either at `https://gitlab.example.com/alex/my-project` or `https://gitlab.example.com/projects/123456`. +You might also need the project ID if you want to interact with it using the [GitLab API](../../api/index.md). + ## Who can view the Project overview page When you select a project, the **Project overview** page shows the project contents. @@ -250,147 +272,24 @@ For users without permission to view the project's code, the landing page shows: ## Leave a project +> The button to leave a project [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/431539) to the Actions menu in GitLab 16.7. + When you leave a project: - You are no longer a project member and cannot contribute. - All the issues and merge requests that were assigned to you are unassigned. -To leave a project: - -1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Leave project**. The **Leave project** option only displays -on the project dashboard when a project is part of a group under a -[group namespace](../namespace/index.md). - -## Use a project as a Go package - -Prerequisites: - -- Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). -- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause -`go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. - -To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: - -- [`go-import`](https://pkg.go.dev/cmd/go#hdr-Remote_import_paths) -- [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) - -### Authenticate Go requests to private projects - Prerequisites: -- Your GitLab instance must be accessible with HTTPS. -- You must have a [personal access token](../profile/personal_access_tokens.md) with `read_api` scope. - -To authenticate Go requests, create a [`.netrc`](https://everything.curl.dev/usingcurl/netrc) file with the following information: - -```plaintext -machine gitlab.example.com -login <gitlab_user_name> -password <personal_access_token> -``` - -On Windows, Go reads `~/_netrc` instead of `~/.netrc`. - -The `go` command does not transmit credentials over insecure connections. It authenticates -HTTPS requests made by Go, but does not authenticate requests made -through Git. - -### Authenticate Git requests - -If Go cannot fetch a module from a proxy, it uses Git. Git uses a `.netrc` file to authenticate requests, but you can -configure other authentication methods. - -Configure Git to either: - -- Embed credentials in the request URL: - - ```shell - git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" - ``` - -- Use SSH instead of HTTPS: - - ```shell - git config --global url."git@gitlab.example.com:".insteadOf "https://gitlab.example.com/" - ``` - -### Disable Go module fetching for private projects - -To [fetch modules or packages](../../development/go_guide/dependencies.md#fetching), Go uses -the [environment variables](../../development/go_guide/dependencies.md#proxies): - -- `GOPRIVATE` -- `GONOPROXY` -- `GONOSUMDB` - -To disable fetching: - -1. Disable `GOPRIVATE`: - - To disable queries for one project, disable `GOPRIVATE=gitlab.example.com/my/private/project`. - - To disable queries for all projects on GitLab.com, disable `GOPRIVATE=gitlab.example.com`. -1. Disable proxy queries in `GONOPROXY`. -1. Disable checksum queries in `GONOSUMDB`. - -- If the module name or its prefix is in `GOPRIVATE` or `GONOPROXY`, Go does not query module - proxies. -- If the module name or its prefix is in `GONOPRIVATE` or `GONOSUMDB`, Go does not query - Checksum databases. - -### Fetch Go modules from Geo secondary sites - -Use [Geo](../../administration/geo/index.md) to access Git repositories that contain Go modules -on secondary Geo servers. - -You can use SSH or HTTP to access the Geo secondary server. - -#### Use SSH to access the Geo secondary server - -To access the Geo secondary server with SSH: - -1. Reconfigure Git on the client to send traffic for the primary to the secondary: - - ```shell - git config --global url."git@gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" - git config --global url."git@gitlab-secondary.example.com".insteadOf "http://gitlab.example.com" - ``` - - - For `gitlab.example.com`, use the primary site domain name. - - For `gitlab-secondary.example.com`, use the secondary site domain name. - -1. Ensure the client is set up for SSH access to GitLab repositories. You can test this on the primary, - and GitLab replicates the public key to the secondary. +- You can leave a project this way only when a project is part of a group under a [group namespace](../namespace/index.md). +- You must be a [direct member](members/index.md#membership-types) of the project. -The `go get` request generates HTTP traffic to the primary Geo server. When the module -download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. - -#### Use HTTP to access the Geo secondary - -You must use persistent access tokens that replicate to the secondary server. You cannot use -CI/CD job tokens to fetch Go modules with HTTP. - -To access the Geo secondary server with HTTP: - -1. Add a Git `insteadOf` redirect on the client: - - ```shell - git config --global url."https://gitlab-secondary.example.com".insteadOf "https://gitlab.example.com" - ``` - - - For `gitlab.example.com`, use the primary site domain name. - - For `gitlab-secondary.example.com`, use the secondary site domain name. - -1. Generate a [personal access token](../profile/personal_access_tokens.md) and - add the credentials in the client's `~/.netrc` file: - - ```shell - machine gitlab.example.com login USERNAME password TOKEN - machine gitlab-secondary.example.com login USERNAME password TOKEN - ``` +To leave a project: -The `go get` request generates HTTP traffic to the primary Geo server. When the module -download starts, the `insteadOf` configuration sends the traffic to the secondary Geo server. +1. On the left sidebar, select **Search or go to** and find your project. +1. On the project overview page, in the upper-right corner, select **Actions** (**{ellipsis_v}**). +1. Select **Leave project**, then **Leave project** again. ## Add a compliance framework to a project **(PREMIUM)** @@ -412,14 +311,6 @@ Prerequisites: 1. To use LDAP groups to manage access to a project, [add the LDAP-synchronized group as a member](../group/manage.md) to the project. -## Related topics - -- [Import a project](../../user/project/import/index.md). -- [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). -- [Fork a project](repository/forking_workflow.md#create-a-fork). -- Adjust [project visibility](../../user/public_access.md#change-project-visibility) and [permissions](settings/index.md#configure-project-features-and-permissions). -- [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) - ## Troubleshooting When working with projects, you might encounter the following issues, or require alternate methods to complete specific tasks. @@ -519,3 +410,11 @@ end To find features that can be toggled, run `pp p.project_feature`. Available permission levels are listed in [concerns/featurable.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/featurable.rb). + +## Related topics + +- [Import a project](../../user/project/import/index.md). +- [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). +- [Fork a project](repository/forking_workflow.md#create-a-fork). +- Adjust [project visibility](../../user/public_access.md#change-project-visibility) and [permissions](settings/project_features_permissions.md#configure-project-features-and-permissions). +- [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 37b79c8f1a8..b7ee354ed9a 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project and group visibility **(FREE ALL)** @@ -35,7 +34,7 @@ For internal projects, **any authenticated user**, including users with the Gues Only internal members can view internal content. -[External users](admin_area/external_users.md) cannot clone the project. +[External users](../administration/external_users.md) cannot clone the project. Internal groups can have internal or private subgroups. @@ -63,18 +62,32 @@ then `/public` is visible only to authenticated users. You can change the visibility of a project. -Prerequisite: +Prerequisites: - You must have the Owner role for a project. 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Visibility, project features, permissions**. -1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. +1. From the **Project visibility** dropdown list, select an option. The visibility setting for a project must be at least as restrictive as the visibility of its parent group. 1. Select **Save changes**. +## Change the visibility of individual features in a project + +You can change the visibility of individual features in a project. + +Prerequisites: + +- You must have the Owner role for the project. + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. To enable or disable a feature, turn on or off the feature toggle. +1. Select **Save changes**. + ## Change group visibility You can change the visibility of all projects in a group. @@ -87,9 +100,9 @@ Prerequisites: to private if a subgroup or project in that group is public. 1. On the left sidebar, select **Search or go to** and find your group. -1. On the left sidebar, select **Settings > General**. +1. Select **Settings > General**. 1. Expand **Naming, visibility**. -1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. +1. For **Visibility level**, select an option. The visibility setting for a project must be at least as restrictive as the visibility of its parent group. 1. Select **Save changes**. @@ -101,10 +114,6 @@ This setting can help prevent users from publicly exposing their repositories by For more information, see [Restrict visibility levels](../administration/settings/visibility_and_access_controls.md#restrict-visibility-levels). -## Related topics - -- [Change the visibility of features](project/working_with_projects.md#change-the-visibility-of-individual-features-in-a-project) - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/read_only_namespaces.md b/doc/user/read_only_namespaces.md index d5697ec5a94..ee89a84e3a9 100644 --- a/doc/user/read_only_namespaces.md +++ b/doc/user/read_only_namespaces.md @@ -1,7 +1,7 @@ --- stage: Growth group: Acquisition -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Read-only namespaces **(FREE SAAS)** @@ -22,7 +22,7 @@ information, see [Restricted actions](#restricted-actions). To restore a namespace to its standard state, you can: - For exceeded free user limits: - - [Reduce the number of members](free_user_limit.md#manage-members-in-your-namespace) in your namespace. + - [Reduce the number of members](free_user_limit.md#manage-members-in-your-group-namespace) in your namespace. - [Start a free trial](https://gitlab.com/-/trial_registrations/new), which includes an unlimited number of members. - [Purchase a paid tier](https://about.gitlab.com/pricing/). - For exceeded storage quota: @@ -33,9 +33,9 @@ To restore a namespace to its standard state, you can: | Feature | Action restricted | |---------|-------------------| -| Container Registry | Create, edit, and delete cleanup policies <br> Push an image to the container registry | +| Container registry | Create, edit, and delete cleanup policies <br> Push an image to the container registry | | Merge Requests | Create and update an MR | -| Package Registry | Publish a package | +| Package registry | Publish a package | | Repositories | Add tags <br> Create new branches <br> Create and update commit status <br> Push and force push to non-protected branches <br> Push and force push to protected branches <br> Upload files <br> Create merge requests | | CI/CD | Create, edit, admin, and run pipelines <br> Create, edit, admin, and run builds <br> Create and edit admin environments <br> Create and edit admin deployments <br> Create and edit admin clusters <br> Create and edit admin releases | | Namespaces | **For exceeded free user limits:** Invite new users | diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index 9e13d1fe263..1eb02b2f263 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -1,7 +1,7 @@ --- stage: Govern group: Anti-Abuse -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Report abuse **(FREE ALL)** @@ -43,7 +43,7 @@ To report abuse from a user's profile page: To report abuse from a user's comment: 1. In the comment, in the upper-right corner, select **More actions** (**{ellipsis_v}**). -1. Select **Report abuse to administrator**. +1. Select **Report abuse**. 1. Select a reason for reporting the user. 1. Complete an abuse report. 1. Select **Send report**. @@ -63,7 +63,7 @@ A URL to the reported user's comment is pre-filled in the abuse report's ## Report abuse from a merge request 1. On the merge request, in the upper-right corner, select **Merge request actions** (**{ellipsis_v}**). -1. Select **Report abuse to administrator**. +1. Select **Report abuse**. 1. Select a reason for reporting this user. 1. Complete an abuse report. 1. Select **Send report**. diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 697f5711396..24610e25542 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Tenant Scale -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reserved project and group names **(FREE ALL)** diff --git a/doc/user/rich_text_editor.md b/doc/user/rich_text_editor.md index fe3ac56b79c..24293b9f3b1 100644 --- a/doc/user/rich_text_editor.md +++ b/doc/user/rich_text_editor.md @@ -1,8 +1,7 @@ --- stage: Plan group: Knowledge -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rich text editor **(FREE ALL)** diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index c1da3e9e2ba..3b715fb13da 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Advanced search **(PREMIUM ALL)** @@ -23,7 +22,7 @@ You can use advanced search in: - Merge requests - Milestones - Users -- Epics (in groups only) +- Epics - Code - Comments - Commits @@ -34,6 +33,7 @@ You can use advanced search in: - On GitLab.com, advanced search is enabled for groups with paid subscriptions. - For self-managed GitLab instances, an administrator must [enable advanced search](../../integration/advanced_search/elasticsearch.md#enable-advanced-search). +- For GitLab Dedicated, advanced search is enabled. ## Syntax diff --git a/doc/user/search/command_palette.md b/doc/user/search/command_palette.md index 0f42e727eda..21c0a915e3d 100644 --- a/doc/user/search/command_palette.md +++ b/doc/user/search/command_palette.md @@ -1,8 +1,7 @@ --- stage: Manage group: Foundations -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Command palette **(FREE ALL)** @@ -17,7 +16,7 @@ find an object more quickly. To open the command palette: -1. On the left sidebar, at the top, select **Search or go to** or use the <kbd>/</kbd> key to enable. +1. On the left sidebar, select **Search or go to** or use the <kbd>/</kbd> key to enable. 1. Type one of the special characters: - <kbd>></kbd> - Create a new object or find a menu item. diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md index 48445ccfc3c..f3554804397 100644 --- a/doc/user/search/exact_code_search.md +++ b/doc/user/search/exact_code_search.md @@ -1,8 +1,7 @@ --- stage: Data Stores group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Exact Code Search **(PREMIUM ALL)** @@ -33,6 +32,7 @@ This table shows some example queries for exact code search. | Query | Description | | -------------------- |-------------------------------------------------------------------------------------- | | `foo` | Returns files that contain `foo` | +| `foo file:^doc/` | Returns files that contain `foo` in directories that start with `doc/` | | `"class foo"` | Returns files that contain the exact string `class foo` | | `class foo` | Returns files that contain both `class` and `foo` | | `foo or bar` | Returns files that contain either `foo` or `bar` | @@ -42,5 +42,5 @@ This table shows some example queries for exact code search. | `foo file:js` | Searches for `foo` in files with names that contain `js` | | `foo -file:test` | Searches for `foo` in files with names that do not contain `test` | | `foo lang:ruby` | Searches for `foo` in Ruby source code | -| `foo f:\.js$` | Searches for `foo` in files with names that end with `.js` | +| `foo file:\.js$` | Searches for `foo` in files with names that end with `.js` | | `foo.*bar` | Searches for strings that match the regular expression `foo.*bar` | diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 79782b1c880..6faf45cbc3d 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Global Search -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Searching in GitLab **(FREE ALL)** diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index e504ee90821..ff1e065de65 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -1,8 +1,7 @@ --- stage: Manage group: Foundations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab keyboard shortcuts **(FREE ALL)** @@ -14,7 +13,7 @@ To display a window in GitLab that lists its keyboard shortcuts, use one of the following methods: - Press <kbd>?</kbd>. -- In the Help menu, in the upper-right corner of the application, select **Keyboard shortcuts**. +- In the lower-left corner of the application, select **Help** and then **Keyboard shortcuts**. Although [global shortcuts](#global-shortcuts) work from any area of GitLab, you must be in specific pages for the other shortcuts to be available, as @@ -77,7 +76,7 @@ relatively quickly to work, and they take you to another page in the project. | <kbd>g</kbd> + <kbd>n</kbd> | Go to the [repository graph](#repository-graph) page (**Code > Repository graph**). | | <kbd>g</kbd> + <kbd>d</kbd> | Go to repository charts (**Analyze > Repository analytics**). | | <kbd>g</kbd> + <kbd>i</kbd> | Go to the project issues list (**Plan > Issues**). | -| <kbd>i</kbd> | Go to the New Issue page (**Pan > Issues**, select **New issue** ). | +| <kbd>i</kbd> | Go to the New Issue page (**Plan > Issues**, select **New issue** ). | | <kbd>g</kbd> + <kbd>b</kbd> | Go to the project issue boards list (**Plan > Issue boards**). | | <kbd>g</kbd> + <kbd>m</kbd> | Go to the project [merge requests](project/merge_requests/index.md) list (**Code > Merge requests**). | | <kbd>g</kbd> + <kbd>p</kbd> | Go to the CI/CD pipelines list (**Build > Pipelines**). | diff --git a/doc/user/snippets.md b/doc/user/snippets.md index fe782227701..e1d6b857b31 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" -type: reference +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Snippets **(FREE ALL)** @@ -15,7 +14,7 @@ You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and and you can maintain your snippets with the [snippets API](../api/snippets.md). You can create and manage your snippets through the GitLab user interface, or by -using the [GitLab Workflow VS Code extension](project/repository/vscode.md). +using the [GitLab Workflow VS Code extension](../editor_extensions/visual_studio_code/index.md).  @@ -43,20 +42,22 @@ You can create snippets in multiple ways, depending on whether you want to creat **New snippet**. - From a project: On the left sidebar, select **Create new** (**{plus}**). Below **In GitLab**, select **New snippet**. - From any other page: On the left sidebar, select **Create new** (**{plus}**) and then **New snippet**. - - If you installed the [GitLab Workflow VS Code extension](project/repository/vscode.md), + - If you installed the [GitLab Workflow VS Code extension](../editor_extensions/visual_studio_code/index.md), use the [`Gitlab: Create snippet` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet). - **To create a project snippet**: Go to your project's page. Select **Create new** (**{plus}**). Below **In this project**, select **New snippet**. -1. Add a **Title** and **Description**. -1. Name your **File** with an appropriate extension, such as `example.rb` or `index.html`. +1. In **Title**, add a title. +1. Optional. In **Description**, describe the snippet. +1. In **Files**, give your file an appropriate name and extension, such as `example.rb` or `index.html`. Filenames with appropriate extensions display [syntax highlighting](#filenames). Failure to add a filename can cause a known - [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). If you don't provide a filename, GitLab [creates a name for you](#filenames). + [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). + If you do not provide a filename, GitLab [creates a name for you](#filenames). 1. Optional. Add [multiple files](#add-or-remove-multiple-files) to your snippet. 1. Select a visibility level, and select **Create snippet**. After you create a snippet, you can still [add more files to it](#add-or-remove-multiple-files). -In GitLab versions 13.0 and later, snippets are [versioned by default](#versioned-snippets). +In GitLab 13.0 and later, snippets are [versioned by default](#versioned-snippets). ## Discover snippets @@ -84,8 +85,7 @@ To discover all snippets visible to you in GitLab, you can: Project snippets are enabled and available by default. To change their default visibility: -1. In your project, - go to **Settings**. +1. In your project, go to **Settings > General**. 1. Expand the **Visibility, project features, permissions** section, and scroll to **Snippets**. 1. Toggle the default visibility, and select whether snippets can be viewed by everyone, or only project members. @@ -95,7 +95,7 @@ default visibility: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/239) in GitLab 13.0. -In GitLab versions 13.0 and later, snippets (both personal and project snippets) +In GitLab 13.0 and later, snippets (both personal and project snippets) have version control enabled by default. This means that all snippets get their own underlying repository initialized with @@ -104,7 +104,7 @@ new commit to the default branch is recorded. Commit messages are automatically generated. The snippet's repository has only one branch. You can't delete this branch, or create other branches. -Existing snippets were automatically migrated in 13.0. Their current +Existing snippets were automatically migrated in GitLab 13.0. Their current content was saved as the initial commit to the snippets' repository. ## Filenames @@ -186,9 +186,10 @@ To embed a snippet: 1. Confirm your snippet is publicly visible: - *If it's a project snippet*, the project must be public. - The snippet is publicly visible. - - In **Project > Settings > Permissions**, the snippets - permissions are set to **Everyone with access**. -1. In your snippet's **Embed** section, select **Copy** to copy a one-line script you can add to any website or blog post. For example: + - In your project, go to **Settings > General**. Expand the **Visibility, project features, permissions** + section, and scroll to **Snippets**. Set the snippet permission to **Everyone with access**. +1. In your snippet's **Embed** section, select **Copy** to copy a one-line script + you can add to any website or blog post. For example: ```html <script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script> @@ -231,7 +232,7 @@ Prerequisites: To do this task: 1. On the left sidebar, select **Search or go to** and find your project. -1. On the left sidebar, select **Code > Snippets**. +1. Select **Code > Snippets**. 1. Select the snippet you want to report as spam. 1. Select **Submit as spam**. diff --git a/doc/user/ssh.md b/doc/user/ssh.md index 482c473e285..1cce1cda20b 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -1,7 +1,7 @@ --- stage: Govern group: Authentication -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use SSH keys to communicate with GitLab **(FREE ALL)** @@ -352,6 +352,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: Verify that your SSH key was added correctly. The following commands use the example hostname `gitlab.example.com`. Replace this example hostname with your GitLab instance's hostname, for example, `git@gitlab.com`. +By default, GitLab uses `git` username to authenticate. It can be different if it was [changed by the administrator](https://docs.gitlab.com/omnibus/settings/configuration.html#change-the-name-of-the-git-user-or-group). 1. To ensure you're connecting to the correct server, check the server's SSH host keys fingerprint. For: - GitLab.com, see the [SSH host keys fingerprints](gitlab_com/index.md#ssh-host-keys-fingerprints) documentation. diff --git a/doc/user/storage_management_automation.md b/doc/user/storage_management_automation.md index a83af4ab6c6..f25ae8ba92d 100644 --- a/doc/user/storage_management_automation.md +++ b/doc/user/storage_management_automation.md @@ -1,8 +1,7 @@ --- -type: howto stage: Fulfillment group: Utilization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Automate storage management **(FREE ALL)** @@ -838,8 +837,8 @@ you can configure: - The number of days before an image tag can be deleted (`older_than`) WARNING: -On GitLab.com, due to the scale of the Container Registry, the number of tags deleted by this API is limited. -If your Container Registry has a large number of tags to delete, only some of them are deleted. You might need +On GitLab.com, due to the scale of the container registry, the number of tags deleted by this API is limited. +If your container registry has a large number of tags to delete, only some of them are deleted. You might need to call the API multiple times. To schedule tags for automatic deletion, use a [cleanup policy](#create-a-cleanup-policy-for-containers) instead. The following example uses the [`python-gitlab` API library](https://python-gitlab.readthedocs.io/en/stable/gl_objects/repository_tags.html) to fetch a list of tags, and calls the `delete_in_bulk()` method with filter parameters. @@ -892,7 +891,7 @@ echo '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":tr You can optimize container images to reduce the image size and overall storage consumption in the container registry. Learn more in the [pipeline efficiency documentation](../ci/pipelines/pipeline_efficiency.md#optimize-docker-images). -## Manage Package Registry storage +## Manage package registry storage Package registries are available [for projects](../api/packages.md#for-a-project) or [for groups](../api/packages.md#for-a-group). diff --git a/doc/user/tasks.md b/doc/user/tasks.md index 173d2e44cf1..1ec211dcab3 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tasks **(FREE ALL)** @@ -53,6 +53,8 @@ Prerequisites: To create a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select **Add**. 1. Select **New task**. 1. Enter the task title. @@ -66,9 +68,9 @@ Prerequisites: - You must have at least the Reporter role for the project. -In an issue description with task list items: - -1. Hover over a task list item and select the options menu (**{ellipsis_v}**). +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, hover over a task list item and select the options menu (**{ellipsis_v}**). 1. Select **Convert to task**. The task list item is removed from the issue description and a task is created in the tasks widget from its contents. @@ -84,6 +86,8 @@ Prerequisites: To add a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select **Add**. 1. Select **Existing task**. 1. Search tasks by title. @@ -98,6 +102,8 @@ Prerequisites: To edit a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the task you want to edit. The task window opens. 1. Optional. To edit the title, select it and make your changes. @@ -124,7 +130,9 @@ Prerequisites: To edit the description of a task: -1. In the **Tasks** section, select the title of the task you want to edit. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Description**, select the edit icon (**{pencil}**). The description text box appears. 1. Above the text box, select **Rich text**. @@ -151,7 +159,10 @@ It's not possible to connect them again. To remove a task from an issue: -1. In the issue description, in the **Tasks** section, next to the task you want to remove, select the options menu (**{ellipsis_v}**). +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select the options menu (**{ellipsis_v}**) + next to the task you want to remove. 1. Select **Remove task**. ## Delete a task @@ -164,6 +175,8 @@ Prerequisites: To delete a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the task you want to edit. 1. In the task window, in the options menu (**{ellipsis_v}**), select **Delete task**. 1. Select **OK**. @@ -195,6 +208,8 @@ Prerequisites: To change the assignee on a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Assignees**, select **Add assignees**. @@ -211,6 +226,8 @@ Prerequisites: To add [labels](project/labels.md) to a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Labels**, select **Add labels**. 1. From the dropdown list, select the labels to add. @@ -231,6 +248,8 @@ You can set start and due dates on a task to show when work should begin and end To set a due date: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. If the task already has a due date next to **Due date**, select it. Otherwise, select **Add due date**. @@ -263,6 +282,8 @@ Prerequisites: To add a task to a milestone: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Milestone**, select **Add to milestone**. @@ -271,7 +292,8 @@ To add a task to a milestone: ## Set task weight **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.3. +> - Edit button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429137) in GitLab 16.7. Prerequisites: @@ -282,10 +304,13 @@ This value is visible only when you view a task. To set issue weight of a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. -1. Next to **Weight**, enter a whole, positive number. -1. Select the close icon (**{close}**). +1. Next to **Weight**, select **Edit**. +1. Enter a whole, positive number. +1. Select **Apply** or press <kbd>Enter</kbd>. ## Add a task to an iteration **(PREMIUM ALL)** @@ -306,6 +331,8 @@ Prerequisites: To add a task to an iteration: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Iteration**, select **Add to iteration**. @@ -337,7 +364,8 @@ To refer to a task elsewhere in GitLab, you can use its full URL or a short refe To copy the task reference to your clipboard: 1. On the left sidebar, select **Search or go to** and find your project. -1. Select **Plan > Issues**, then select your task to view it. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select your task. 1. In the top right corner, select the vertical ellipsis (**{ellipsis_v}**), then select **Copy Reference**. You can now paste the reference into another description or comment. @@ -364,13 +392,15 @@ To copy the task's email address: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11198) in GitLab 16.5. -Prerequisite: +Prerequisites: - You must have at least the Reporter role for the project. - The issue and task must belong to the same project. To set an issue as a parent of a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. 1. In the issue description, in the **Tasks** section, select the title of the task you want to edit. The task window opens. 1. Next to **Parent**, from the dropdown list, select the parent to add. @@ -461,16 +491,16 @@ When enabled, tasks use a two-column layout, similar to issues. The description and threads are on the left, and attributes, such as labels or assignees, on the right. - + -## Linked items in Tasks +## Linked items in tasks -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416558) in GitLab 16.5 [with a flag](../administration/feature_flags.md) named `linked_work_items`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139394) in GitLab 16.7. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../administration/feature_flags.md) named `linked_work_items`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../administration/feature_flags.md) named `linked_work_items`. +On GitLab.com, this feature is available. Linked items are a bi-directional relationship and appear in a block below the emoji reactions section. You can link an objective, key result, or a task in the same project with each other. @@ -479,14 +509,17 @@ The relationship only shows up in the UI if the user can see both items. ### Add a linked item -Prerequisite: +Prerequisites: - You must have at least the Guest role for the project. To link an item to a task: +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select your task. 1. In the **Linked items** section of a task, - select the **Add** button. + select **Add**. 1. Select the relationship between the two items. Either: - **relates to** - **blocks** @@ -501,11 +534,14 @@ them categorized so their relationships can be better understood visually. ### Remove a linked item -Prerequisite: +Prerequisites: - You must have at least the Guest role for the project. -In the **Linked items** section of a task, -next to each item, select the vertical ellipsis (**{ellipsis_v}**) and then select **Remove**. +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Plan > Issues**, then select your issue to view it. +1. In the issue description, in the **Tasks** section, select your task. +1. In the **Linked items** section of a task, next to each item, select the vertical + ellipsis (**{ellipsis_v}**) and then select **Remove**. Due to the bi-directional relationship, the relationship no longer appears in either item. diff --git a/doc/user/todos.md b/doc/user/todos.md index 8e207a786c3..9de15480a5c 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -1,7 +1,7 @@ --- stage: Plan group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # To-Do List **(FREE ALL)** diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index ae47a9156c7..8641b73e3a8 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Updating to GitLab 13.2: Email confirmation issues diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 7dea2b97249..973ad9d0b07 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -1,112 +1,85 @@ --- -type: howto stage: Fulfillment group: Utilization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Storage **(FREE ALL)** +# Storage **(FREE SAAS)** -Storage usage statistics are available for projects and namespaces. You can use that information to -manage storage usage within the applicable quotas. +All projects on GitLab SaaS have 10 GiB of free storage for their Git repository and Large File Storage (LFS). -Statistics include: +When a project's repository and LFS exceed 10 GiB, the project is set to a read-only state. +You cannot push changes to a read-only project. To increase storage of the project's repository and LFS to more than 10 GiB, +you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). -- Storage usage across projects in a namespace. -- Storage usage that exceeds the storage SaaS limit or [self-managed storage quota](../administration/settings/account_and_limit_settings.md#repository-size-limit). -- Available purchased storage for SaaS. +GitLab plans to introduce storage limits for namespaces on GitLab SaaS. After these storage limits have been applied, +storage usage will be calculated across the entire namespace and project storage limits will no longer apply. -Storage and network usage are calculated with the binary measurement system (1024 unit multiples). -Storage usage is displayed in kibibytes (KiB), mebibytes (MiB), -or gibibytes (GiB). 1 KiB is 2^10 bytes (1024 bytes), -1 MiB is 2^20 bytes (1024 kibibytes), 1 GiB is 2^30 bytes (1024 mebibytes). +## View storage **(FREE ALL)** -NOTE: -Storage usage labels are being transitioned from `KB` to `KiB`, `MB` to `MiB`, and `GB` to `GiB`. During this transition, -you might see references to `KB`, `MB`, and `GB` in the UI and documentation. +You can view the following statistics for storage usage in projects and namespaces: -## View storage usage +- Storage usage that exceeds the GitLab SaaS storage limit or [self-managed storage limits](../administration/settings/account_and_limit_settings.md#repository-size-limit). +- Available purchased storage for GitLab SaaS. Prerequisites: - To view storage usage for a project, you must have at least the Maintainer role for the project or Owner role for the namespace. - To view storage usage for a group namespace, you must have the Owner role for the namespace. +To view storage: + 1. On the left sidebar, select **Search or go to** and find your project or group. -1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select **Settings > Usage Quotas**. 1. Select the **Storage** tab to see namespace storage usage. -1. To view storage usage for a project, select one of the projects from the table at the bottom of the **Storage** tab of the **Usage Quotas** page. - -The information on the **Usage Quotas** page is updated every 90 minutes. +1. To view storage usage for a project, in the table at the bottom, select a project. Storage usage is updated every 90 minutes. If your namespace shows `'Not applicable.'`, push a commit to any project in the namespace to recalculate the storage. -### View project fork storage usage **(FREE SAAS)** +Storage and network usage is calculated with the binary measurement system (1024 unit multiples). +Storage usage is displayed in kibibytes (KiB), mebibytes (MiB), +or gibibytes (GiB). 1 KiB is 2^10 bytes (1024 bytes), +1 MiB is 2^20 bytes (1024 kibibytes), and 1 GiB is 2^30 bytes (1024 mebibytes). + +NOTE: +Storage usage labels are being transitioned from `KB` to `KiB`, `MB` to `MiB`, and `GB` to `GiB`. During this transition, +you might see references to `KB`, `MB`, and `GB` in the UI and documentation. + +## View project fork storage usage A cost factor is applied to the storage consumed by project forks so that forks consume less namespace storage than their actual size. To view the amount of namespace storage the fork has used: 1. On the left sidebar, select **Search or go to** and find your project or group. -1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select **Settings > Usage Quotas**. 1. Select the **Storage** tab. The **Total** column displays the amount of namespace storage used by the fork as a portion of the actual size of the fork on disk. The cost factor applies to the project repository, LFS objects, job artifacts, packages, snippets, and the wiki. The cost factor does not apply to private forks in namespaces on the Free plan. -## Manage storage usage - -To manage your storage, if you are a namespace Owner you can [purchase more storage for the namespace](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). - -Depending on your role, you can also use the following methods to manage or reduce your storage: - -- [Reduce package registry storage](packages/package_registry/reduce_package_registry_storage.md). -- [Reduce dependency proxy storage](packages/dependency_proxy/reduce_dependency_proxy_storage.md). -- [Reduce repository size](project/repository/reducing_the_repo_size_using_git.md). -- [Reduce container registry storage](packages/container_registry/reduce_container_registry_storage.md). -- [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size). -- [Manage artifact expiration period](../ci/yaml/index.md#artifactsexpire_in). -- [Reduce build artifact storage](../ci/jobs/job_artifacts.md#delete-job-log-and-artifacts). - -To automate storage usage analysis and management, see the [storage management automation](storage_management_automation.md) documentation. - -## Set usage quotas **(FREE SELF)** - -There are no application limits on the amount of storage and transfer for self-managed instances. The administrators are responsible for the underlying infrastructure costs. Administrators can set [repository size limits](../administration/settings/account_and_limit_settings.md#repository-size-limit) to manage your repositories’ size. - -## Storage limits **(FREE SAAS)** - -### Project storage limit - -Projects on GitLab SaaS have a 10 GiB storage limit on their Git repository and LFS storage. Limits on project storage -will be removed before limits are applied to GitLab SaaS namespace storage in the future. - -When a project's repository and LFS reaches the quota, the project is set to a read-only state. -You cannot push changes to a read-only project. To monitor the size of each -repository in a namespace, including a breakdown for each project, -[view storage usage](#view-storage-usage). To allow a project's repository and LFS to exceed the free quota -you must purchase additional storage. For more details, see [Excess storage usage](#excess-storage-usage). +## Excess storage usage -#### Excess storage usage +Excess storage usage is the amount that exceeds the 10 GiB free storage of a project's repository and LFS. If no purchased storage is available, +the project is set to a read-only state. You cannot push changes to a read-only project. -Excess storage usage is the amount that a project's repository and LFS exceeds the [project storage limit](#project-storage-limit). If no -purchased storage is available the project is set to a read-only state. You cannot push changes to a read-only project. -To remove the read-only state you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) -for the namespace. When the purchase is completed, read-only projects are automatically restored to their standard state. The -amount of purchased storage available must always be greater than zero. +To remove the read-only state, you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) +for the namespace. After the purchase has completed, the read-only state is removed and projects are automatically +restored. The amount of available purchased storage must always +be greater than zero. -The **Storage** tab of the **Usage Quotas** page warns you of the following: +The **Storage** tab of the **Usage Quotas** page displays the following: - Purchased storage available is running low. - Projects that are at risk of becoming read-only if purchased storage available is zero. - Projects that are read-only because purchased storage available is zero. Read-only projects are marked with an information icon (**{information-o}**) beside their name. -#### Excess storage example +### Excess storage example -The following example describes an excess storage scenario for a namespace: +The following example describes an excess storage scenario for projects in a namespace: | Repository | Storage used | Excess storage | Quota | Status | |------------|--------------|----------------|--------|----------------------| @@ -133,23 +106,47 @@ available decreases. All projects no longer have the read-only status because 40 | Yellow | 5 GiB | 0 GiB | 10 GiB | Not read-only | | **Totals** | **45 GiB** | **10 GiB** | - | - | -### Namespace storage limit **(FREE SAAS)** +## Namespace storage limit -GitLab plans to enforce a storage limit for namespaces on GitLab SaaS. For more information, see -the FAQs for the following tiers: +GitLab plans to introduce the following storage limits per top-level group: -- [Free tier](https://about.gitlab.com/pricing/faq-efficient-free-tier/#storage-limits-on-gitlab-saas-free-tier). -- [Premium and Ultimate](https://about.gitlab.com/pricing/faq-paid-storage-transfer/). +| Subscription tier | Storage limit | +|-----------------------|---------------| +| Free | 5 GiB | +| Premium | 50 GiB | +| Ultimate | 250 GiB <sup>1</sup> | -Namespaces on GitLab SaaS have a [10 GiB project limit](#project-storage-limit) with a soft limit on -namespace storage. Soft storage limits are limits that have not yet been enforced by GitLab, and will become -hard limits after namespace storage limits apply. To avoid your namespace from becoming -[read-only](../user/read_only_namespaces.md) after namespace storage limits apply, -you should ensure that your namespace storage adheres to the soft storage limit. +<html> +<small> + <ol> + <li>Applies to GitLab Trial, GitLab for Open Source, GitLab for Education, and GitLab for Startups.</li> + </ol> +</small> +</html> + +If you have a multi-year contract for GitLab Premium or Ultimate, storage limits will not apply until your first renewal after GitLab introduces the namespace storage limits. + +Any additional storage you purchase before the introduction of namespace storage limits, including additional storage purchased due to project storage limits, will apply to the top-level group. + +Namespaces have a 10 GiB project limit with +a soft limit on namespace storage. After GitLab applies namespace storage limits, +soft limits will become hard limits and your namespace will be [read-only](../user/read_only_namespaces.md). + +To prevent your namespace from becoming read-only: + +- Manage your storage usage. +- [Purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). +- If you are eligible, apply for a [community program subscription](../subscriptions/community_programs.md): + - GitLab for Education + - GitLab for Open Source + - GitLab for Startups +- If you have GitLab Free, [start a trial](https://about.gitlab.com/free-trial/) or upgrade to [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), which has higher storage limits and more features. +- Consider a self-managed subscription, which does not have storage limits. +- [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. -Namespace storage limits do not apply to self-managed deployments, but administrators can [manage the repository size](../administration/settings/account_and_limit_settings.md#repository-size-limit). +### Storage types in namespace storage usage -Storage types that add to the total namespace storage are: +Storage types that count toward the total namespace storage are: - Git repository - Git LFS @@ -160,25 +157,33 @@ Storage types that add to the total namespace storage are: - Wiki - Snippets -If your total namespace storage exceeds the available namespace storage quota, all projects under the namespace become read-only. Your ability to write new data is restricted until the read-only state is removed. For more information, see [Restricted actions](../user/read_only_namespaces.md#restricted-actions). +### Excess storage notifications -To notify you that you have nearly exceeded your namespace storage quota: +Storage limits are included in GitLab subscription terms but do not apply. At least 60 days before GitLab introduces storage limits, +GitLab will notify you of namespaces that exceed, or are close to exceeding, the storage limit. -- In the command-line interface, a notification displays after each `git push` action when your namespace has reached between 95% and 100%+ of your namespace storage quota. -- In the GitLab UI, a notification displays when your namespace has reached between 75% and 100%+ of your namespace storage quota. -- GitLab sends an email to members with the Owner role to notify them when namespace storage usage is at 70%, 85%, 95%, and 100%. +- In the command-line interface, a notification displays after each `git push` +action when your namespace has reached between 95% and 100% of your namespace storage quota. +- In the GitLab UI, a notification displays when your namespace has reached between +75% and 100% of your namespace storage quota. +- GitLab sends an email to members with the Owner role to notify them when namespace +storage usage is at 70%, 85%, 95%, and 100%. -To prevent exceeding the namespace storage limit, you can: +## Manage storage usage -- [Manage your storage usage](#manage-storage-usage). -- If you meet the eligibility requirements, you can apply for: - - [GitLab for Education](https://about.gitlab.com/solutions/education/join/) - - [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/) - - [GitLab for Startups](https://about.gitlab.com/solutions/startups/) -- Consider using a [self-managed instance](../subscriptions/self_managed/index.md) of GitLab, which does not have these limits on the Free tier. -- [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60 per year for 10 GiB of storage. -- [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), which include higher limits and features to enable growing teams to ship faster without sacrificing on quality. -- [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. +To manage your storage, if you are a namespace Owner, you can [purchase more storage for the namespace](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer). + +Depending on your role, you can also use the following methods to manage or reduce your storage: + +- [Reduce package registry storage](packages/package_registry/reduce_package_registry_storage.md). +- [Reduce dependency proxy storage](packages/dependency_proxy/reduce_dependency_proxy_storage.md). +- [Reduce repository size](project/repository/reducing_the_repo_size_using_git.md). +- [Reduce container registry storage](packages/container_registry/reduce_container_registry_storage.md). +- [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size). +- [Manage artifact expiration period](../ci/yaml/index.md#artifactsexpire_in). +- [Reduce build artifact storage](../ci/jobs/job_artifacts.md#delete-job-log-and-artifacts). + +To automate storage usage analysis and management, see [storage management automation](storage_management_automation.md). ## Related Topics diff --git a/doc/user/version.md b/doc/user/version.md index b7846988e06..d39c0394610 100644 --- a/doc/user/version.md +++ b/doc/user/version.md @@ -1,7 +1,7 @@ --- stage: none group: none -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Find the GitLab version diff --git a/doc/user/workspace/configuration.md b/doc/user/workspace/configuration.md index 3684845c2c7..7c365611742 100644 --- a/doc/user/workspace/configuration.md +++ b/doc/user/workspace/configuration.md @@ -1,23 +1,14 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Workspace configuration **(PREMIUM ALL BETA)** +# Workspace configuration **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. - -FLAG: -On self-managed GitLab, by default this feature is available. -To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. -On GitLab.com, this feature is available. -The feature is not ready for production use. - -WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. -To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed. You can use [workspaces](index.md) to create and manage isolated development environments for your GitLab projects. Each workspace includes its own set of dependencies, libraries, and tools, @@ -29,26 +20,19 @@ which you can customize to meet the specific needs of each project. ### Prerequisites -- Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports. +- Set up a Kubernetes cluster that the GitLab agent supports. See the [supported Kubernetes versions](../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features). - Ensure autoscaling for the Kubernetes cluster is enabled. -- In the Kubernetes cluster, verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) +- In the Kubernetes cluster: + - Verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) is defined so that volumes can be dynamically provisioned for each workspace. -- In the Kubernetes cluster, install an Ingress controller of your choice (for example, `ingress-nginx`) - and make that controller accessible over a domain. For example, point `*.workspaces.example.dev` and - `workspaces.example.dev` to the load balancer exposed by the Ingress controller. -- In the Kubernetes cluster, [install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions). -- In the Kubernetes cluster, [install the GitLab agent for Kubernetes](../clusters/agent/install/index.md). -- Configure remote development settings for the GitLab agent with this snippet and update `dns_zone` as needed: - - ```yaml - remote_development: - enabled: true - dns_zone: "workspaces.example.dev" - ``` - - You can use any agent defined under the root group of your project, - provided that remote development is properly configured for that agent. + - Install an Ingress controller of your choice (for example, `ingress-nginx`) and make + that controller accessible over a domain. + - In development environments, add an entry to the `/etc/hosts` file or update your DNS records. + - In production environments, point `*.<workspaces.example.dev>` and `<workspaces.example.dev>` + to the load balancer exposed by the Ingress controller. + - [Install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions). + - [Install](../clusters/agent/install/index.md) and [configure](gitlab_agent_configuration.md) the GitLab agent. - You must have at least the Developer role in the root group. - In each project you want to use this feature for, create a [devfile](index.md#devfile): 1. On the left sidebar, select **Search or go to** and find your project. @@ -101,7 +85,7 @@ When you connect to `gitlab-workspaces-proxy` through the TCP load balancer, ### Set up `gitlab-workspaces-proxy` for SSH connections -Prerequisite: +Prerequisites: - You must have an SSH host key for client verification. @@ -177,18 +161,6 @@ RUN chmod 775 /etc/shadow USER gitlab-workspaces ``` -## Disable remote development in the GitLab agent for Kubernetes - -You can stop the `remote_development` module of the GitLab agent for Kubernetes from communicating with GitLab. -To disable remote development in the GitLab agent configuration, set this property: - -```yaml -remote_development: - enabled: false -``` - -If you already have running workspaces, an administrator must manually delete these workspaces in Kubernetes. - ## Related topics - [Quickstart guide for GitLab remote development workspaces](https://go.gitlab.com/AVKFvy) diff --git a/doc/user/workspace/create_image.md b/doc/user/workspace/create_image.md index df70ff31194..6da12b2f70a 100644 --- a/doc/user/workspace/create_image.md +++ b/doc/user/workspace/create_image.md @@ -1,19 +1,14 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Create a custom workspace image that supports arbitrary user IDs **(PREMIUM ALL BETA)** +# Tutorial: Create a custom workspace image that supports arbitrary user IDs **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. On GitLab.com, this feature is available. The feature is not ready for production use. - -WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed. In this tutorial, you'll learn how to create a custom workspace image that supports arbitrary user IDs. You can then use this custom image with any [workspace](index.md) you create in GitLab. @@ -23,12 +18,12 @@ To create a custom workspace image that supports arbitrary user IDs, you'll: 1. [Create a base Dockerfile](#create-a-base-dockerfile). 1. [Add support for arbitrary user IDs](#add-support-for-arbitrary-user-ids). 1. [Build the custom workspace image](#build-the-custom-workspace-image). -1. [Push the custom workspace image to the GitLab Container Registry](#push-the-custom-workspace-image-to-the-gitlab-container-registry). +1. [Push the custom workspace image to the GitLab container registry](#push-the-custom-workspace-image-to-the-gitlab-container-registry). 1. [Use the custom workspace image in GitLab](#use-the-custom-workspace-image-in-gitlab). ## Prerequisites -- A GitLab account with permission to create and push container images to the GitLab Container Registry +- A GitLab account with permission to create and push container images to the GitLab container registry - Docker installation ## Create a base Dockerfile @@ -78,9 +73,9 @@ docker run -ti my-gitlab-workspace sh You should now be able to run commands as the `gitlab-workspaces` user. -## Push the custom workspace image to the GitLab Container Registry +## Push the custom workspace image to the GitLab container registry -To push the custom workspace image to the GitLab Container Registry: +To push the custom workspace image to the GitLab container registry: 1. Sign in to your GitLab account: @@ -88,19 +83,19 @@ To push the custom workspace image to the GitLab Container Registry: docker login registry.gitlab.com ``` -1. Tag the image with the GitLab Container Registry URL: +1. Tag the image with the GitLab container registry URL: ```shell docker tag my-gitlab-workspace registry.gitlab.com/your-namespace/my-gitlab-workspace:latest ``` -1. Push the image to the GitLab Container Registry: +1. Push the image to the GitLab container registry: ```shell docker push registry.gitlab.com/your-namespace/my-gitlab-workspace:latest ``` -Now that you've pushed the custom workspace image to the GitLab Container Registry, you can use the image in GitLab. +Now that you've pushed the custom workspace image to the GitLab container registry, you can use the image in GitLab. ## Use the custom workspace image in GitLab diff --git a/doc/user/workspace/gitlab_agent_configuration.md b/doc/user/workspace/gitlab_agent_configuration.md new file mode 100644 index 00000000000..0e35c72c5ef --- /dev/null +++ b/doc/user/workspace/gitlab_agent_configuration.md @@ -0,0 +1,154 @@ +--- +stage: Create +group: IDE +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# GitLab agent configuration **(PREMIUM ALL)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed. + +When you [set up a workspace](configuration.md#set-up-a-workspace), +you must configure the GitLab agent for remote development. +The remote development settings are available in the agent +configuration file under `remote_development`. + +You can use any agent defined under the root group of your project, +provided that the agent is properly configured for remote development. + +## Remote development settings + +| Setting | Description | +|-------------------------------------------------------|:---------------------------------------------------------------------| +| [`enabled`](#enabled) | Indicates whether remote development is enabled for the GitLab agent | +| [`dns_zone`](#dns_zone) | DNS zone where workspaces are available | +| [`gitlab_workspaces_proxy`](#gitlab_workspaces_proxy) | Namespace where [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy) is installed | +| [`network_policy`](#network_policy) | Firewall rules for workspaces | + +NOTE: +If a setting has an invalid value, it's not possible to update any setting until you fix that value. + +### `enabled` + +Use this setting to define whether: + +- The GitLab agent can communicate with the GitLab instance. +- You can [create a workspace](configuration.md#set-up-a-workspace) with the GitLab agent. + +The default value is `false`. + +To enable remote development in the agent configuration, set `enabled` to `true`: + +```yaml +remote_development: + enabled: true +``` + +If remote development is disabled, an administrator must manually delete any +running workspaces to remove those workspaces from the Kubernetes cluster. + +### `dns_zone` + +Use this setting to define the DNS zone of the URL where workspaces are available. +When you set `dns_zone`, you can no longer update the setting. + +**Example configuration:** + +```yaml +remote_development: + dns_zone: "<workspaces.example.dev>" +``` + +### `gitlab_workspaces_proxy` + +Use this setting to define the namespace where +[`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy) is installed. +The default value for `gitlab_workspaces_proxy.namespace` is `gitlab-workspaces`. + +**Example configuration:** + +```yaml +remote_development: + gitlab_workspaces_proxy: + namespace: "<custom-gitlab-workspaces-proxy-namespace>" +``` + +### `network_policy` + +Use this setting to define the network policy for each workspace. +This setting controls network traffic for workspaces. + +The default value is: + +```yaml +remote_development: + network_policy: + egress: + - allow: "0.0.0.0/0" + except: + - "10.0.0.0/8" + - "172.16.0.0/12" + - "192.168.0.0/16" +``` + +In this configuration: + +- The network policy is generated for each workspace because `enabled` is `true`. +- The egress rules allow all traffic to the internet (`0.0.0.0/0`) except to the + IP CIDR ranges `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16`. + +The behavior of the network policy depends on the Kubernetes network plugin. +For more information, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/network-policies/). + +#### `network_policy.enabled` + +Use this setting to define whether the network policy is generated for each workspace. +The default value for `network_policy.enabled` is `true`. + +#### `network_policy.egress` + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11629) in GitLab 16.7. + +Use this setting to define a list of IP CIDR ranges to allow as egress destinations from a workspace. + +Define egress rules when: + +- The GitLab instance is on a private IP range. +- The workspace must access a cloud resource on a private IP range. + +Each element of the list defines an `allow` attribute with an optional `except` attribute. +`allow` defines an IP range to allow traffic from. +`except` lists IP ranges to exclude from the `allow` range. + +**Example configuration:** + +```yaml +remote_development: + network_policy: + egress: + - allow: "0.0.0.0/0" + except: + - "10.0.0.0/8" + - "172.16.0.0/12" + - "192.168.0.0/16" + - allow: "172.16.123.1/32" +``` + +In this example, traffic from the workspace is allowed if: + +- The destination IP is any range except `10.0.0.0/8`, `172.16.0.0/12`, or `192.168.0.0/16`. +- The destination IP is `172.16.123.1/32`. + +## Configuring user access with remote development + +You can configure the `user_access` module to access the connected Kubernetes cluster with your GitLab credentials. +This module is configured and runs independently of the `remote_development` module. + +Be careful when configuring both `user_access` and `remote_development` in the same GitLab agent. +The `remote_development` clusters manage user credentials (such as personal access tokens) as Kubernetes Secrets. +Any misconfiguration in `user_access` might cause this private data to be accessible over the Kubernetes API. + +For more information about configuring `user_access`, see +[Configure Kubernetes access](../../user/clusters/agent/user_access.md#configure-kubernetes-access). diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 21905381577..d24102afcf9 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -1,23 +1,14 @@ --- stage: Create group: IDE -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Workspaces **(PREMIUM ALL BETA)** +# Workspaces **(PREMIUM ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112397) in GitLab 15.11 [with a flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/391543) in GitLab 16.0. - -FLAG: -On self-managed GitLab, by default this feature is available. -To hide the feature, an administrator can [disable the feature flag](../../administration/feature_flags.md) named `remote_development_feature_flag`. -On GitLab.com, this feature is available. -The feature is not ready for production use. - -WARNING: -This feature is in [Beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice. -To leave feedback, see the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/410031). +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136744) in GitLab 16.7. Feature flag `remote_development_feature_flag` removed. A workspace is a virtual sandbox environment for your code in GitLab. You can use workspaces to create and manage isolated development environments for your GitLab projects. |
