diff options
Diffstat (limited to 'doc')
1647 files changed, 11682 insertions, 7673 deletions
diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 43ccaf6bd7a..5d268fdb241 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -143,6 +143,7 @@ crosslinks Crossplane Crowdin CSV +customappsso cybersecurity Dangerfile Datadog @@ -439,6 +440,7 @@ onboarding OpenID OpenShift Opsgenie +outdent Overcommit Packagist parallelization @@ -642,6 +644,8 @@ stunnel stylelint subchart subcharts +subcommand +subcommands subfolder subfolders subgraph diff --git a/doc/administration/application_settings_cache.md b/doc/administration/application_settings_cache.md index 88e39a50b6c..d04056beb96 100644 --- a/doc/administration/application_settings_cache.md +++ b/doc/administration/application_settings_cache.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Application Performance -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 index 9ec7b81bfd0..ca60b6142fe 100644 --- a/doc/administration/audit_event_streaming.md +++ b/doc/administration/audit_event_streaming.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit event streaming **(ULTIMATE)** @@ -831,3 +831,49 @@ X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN> "event_type": "project_group_link_destroy" } ``` + +## Audit event streaming on invalid merge request approver state + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374566) in GitLab 15.5. + +Stream audit events that relate to invalid merge request approver states within a project. + +### Headers + +Headers are formatted as follows: + +```plaintext +POST /logs HTTP/1.1 +Host: <DESTINATION_HOST> +Content-Type: application/x-www-form-urlencoded +X-Gitlab-Event-Streaming-Token: <DESTINATION_TOKEN> +X-Gitlab-Audit-Event-Type: audit_operation +``` + +### Example payload + +```json +{ + "id": 1, + "author_id": 1, + "entity_id": 6, + "entity_type": "Project", + "details": { + "author_name": "example_username", + "target_id": 20, + "target_type": "MergeRequest", + "target_details": { title: "Merge request title", iid: "Merge request iid", id: "Merge request id" }, + "custom_message": "Invalid merge request approver rules", + "ip_address": "127.0.0.1", + "entity_path": "example-group/example-project" + }, + "ip_address": "127.0.0.1", + "author_name": "example_username", + "entity_path": "example-group/example-project", + "target_details": "merge request title", + "created_at": "2022-03-09T06:53:11.181Z", + "target_type": "MergeRequest", + "target_id": 20, + "event_type": "audit_operation" +} +``` diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index b6c267bfd0c..11600bc2da6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit Events **(PREMIUM)** diff --git a/doc/administration/audit_reports.md b/doc/administration/audit_reports.md index e363e7862ea..8e91466d345 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/engineering/ux/technical-writing/#assignments +info: To 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: '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 bd48cfdbc4f..a047e7c1f0b 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auditor users **(PREMIUM SELF)** diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 1d20d87bdf4..b02ac06b67f 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Atlassian OmniAuth Provider **(FREE SELF)** @@ -11,7 +11,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu ## Atlassian application registration -1. Go to <https://developer.atlassian.com/console/myapps/> and sign-in with the Atlassian +1. Go to the [Atlassian developer console](https://developer.atlassian.com/console/myapps/) and sign-in with the Atlassian account to administer the application. 1. Select **Create a new app**. 1. Choose an App Name, such as 'GitLab', and select **Create**. @@ -51,8 +51,8 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu { name: "atlassian_oauth2", # label: "Provider name", # optional label for login button, defaults to "Atlassian" - app_id: "YOUR_CLIENT_ID", - app_secret: "YOUR_CLIENT_SECRET", + app_id: "<your_client_id>", + app_secret: "<your_client_secret>", args: { scope: "offline_access read:jira-user read:jira-work", prompt: "consent" } } ] @@ -63,13 +63,13 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu ```yaml - { name: "atlassian_oauth2", # label: "Provider name", # optional label for login button, defaults to "Atlassian" - app_id: "YOUR_CLIENT_ID", - app_secret: "YOUR_CLIENT_SECRET", + app_id: "<your_client_id>", + app_secret: "<your_client_secret>", args: { scope: "offline_access read:jira-user read:jira-work", prompt: "consent" } } ``` -1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in [application registration](#atlassian-application-registration) steps. +1. Change `<your_client_id>` and `<your_client_secret>` to the Client credentials you received during [application registration](#atlassian-application-registration). 1. Save the configuration file. 1. For the changes to take effect: diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index 61ce2b5ab25..1ac62b06fe7 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -2,12 +2,12 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Authentiq OmniAuth Provider **(FREE SELF)** -To enable the Authentiq OmniAuth provider for passwordless authentication you must register an application with Authentiq. +To enable the Authentiq OmniAuth provider for passwordless authentication, you must register an application with Authentiq. Authentiq generates a Client ID and the accompanying Client Secret for you to use. @@ -38,8 +38,8 @@ Authentiq generates a Client ID and the accompanying Client Secret for you to us { name: "authentiq", # label: "Provider name", # optional label for login button, defaults to "Authentiq" - app_id: "YOUR_CLIENT_ID", - app_secret: "YOUR_CLIENT_SECRET", + app_id: "<your_client_id>", + app_secret: "<your_client_secret>", args: { "scope": 'aq:name email~rs address aq:push' } @@ -52,22 +52,28 @@ Authentiq generates a Client ID and the accompanying Client Secret for you to us ```yaml - { name: 'authentiq', # label: 'Provider name', # optional label for login button, defaults to "Authentiq" - app_id: 'YOUR_CLIENT_ID', - app_secret: 'YOUR_CLIENT_SECRET', + app_id: '<your_client_id>', + app_secret: '<your_client_secret>', args: { scope: 'aq:name email~rs address aq:push' } } ``` -1. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits. +1. The `scope` is set to request the: + - User's name. + - Required and signed email. + - Permission to send push notifications to sign in on subsequent visits. + See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers. -1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in step 1. +1. Change `<your_client_id>` and `<your_client_secret>` to the Client credentials you received from Authentiq. 1. Save the configuration file. -1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. +1. For the changes to take effect: + - [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) if you installed GitLab using Omnibus. + - [Restart GitLab](../restart_gitlab.md#installations-from-source) if you installed GitLab from source. On the sign in page there should now be an Authentiq icon below the regular sign in form. Select the icon to begin the authentication process. If the user: @@ -77,7 +83,7 @@ icon to begin the authentication process. If the user: 1. Decide what personal details to share. 1. Sign in to your GitLab installation. - Does not have the app installed, they are prompted to download the app and then follow the - procedure above. + previous procedure. If everything works, the user is returned to GitLab and is signed in. diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index db8cdd3e7bb..bb06d5d1a58 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -2,41 +2,42 @@ type: concepts, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Amazon Web Services Cognito **(FREE SELF)** Amazon Cognito lets you add user sign-up, sign-in, and access control to your GitLab instance. -The following documentation enables Cognito as an OAuth2 provider. +The following documentation enables Cognito as an OAuth 2.0 provider. ## Configure AWS Cognito -To enable the [AWS Cognito](https://aws.amazon.com/cognito/) OAuth2 OmniAuth provider, register your application with Cognito. This process generates a Client ID and Client Secret for your application. -Any settings you configure in the following procedure can be modified later. -The following steps enable AWS Cognito as an authentication provider: +To enable the [AWS Cognito](https://aws.amazon.com/cognito/) OAuth 2.0 OmniAuth provider, register your application with Cognito. This process generates a Client ID and Client Secret for your application. +To enable AWS Cognito as an authentication provider, complete the following steps. You can modify any settings you configure later. 1. Sign in to the [AWS console](https://console.aws.amazon.com/console/home). -1. Select **Cognito** from the **Services** menu. -1. Select **Manage User Pools**, and select the **Create a user pool** button in the top right corner. -1. Enter the pool name and then select the **Step through settings** button. +1. From the **Services** menu, select **Cognito**. +1. Select **Manage User Pools** and then select **Create a user pool** in the top right corner. +1. Enter the user pool name and then select **Step through settings**. 1. Under **How do you want your end users to sign in?**, select **Email address or phone number** and **Allow email addresses**. 1. Under **Which standard attributes do you want to require?**, select **email**. -1. Go to the next steps of configuration and set the rest of the settings to suit your needs - in the basic setup they are not related to GitLab configuration. -1. In the **App clients** settings, select **Add an app client**, add **App client name** and select the **Enable username password based authentication** checkbox. +1. Configure the remaining settings to suit your needs. In the basic setup, these settings do not affect GitLab configuration. +1. In the **App clients** settings: + 1. Select **Add an app client**. + 1. Add the **App client name**. + 1. Select the **Enable username password based authentication** checkbox. 1. Select **Create app client**. -1. In the next step, you can set up AWS Lambda functions for sending emails. You can then finish creating the pool. +1. Set up the AWS Lambda functions for sending emails and finish creating the user pool. 1. After creating the user pool, go to **App client settings** and provide the required information: - **Enabled Identity Providers** - select all - - **Callback URL** - `https://gitlab.example.com/users/auth/cognito/callback` - - Substitute the URL of your GitLab instance for `gitlab.example.com` + - **Callback URL** - `https://<your_gitlab_instance_url>/users/auth/cognito/callback` - **Allowed OAuth Flows** - Authorization code grant - **Allowed OAuth2 Scopes** - `email`, `openid`, and `profile` 1. Save changes for the app client settings. -1. Under **Domain name** include the AWS domain name for your AWS Cognito application. -1. Under **App Clients**, find your app client ID and app client secret. These values correspond to the OAuth2 Client ID and Client Secret. Save these values. +1. Under **Domain name**, include the AWS domain name for your AWS Cognito application. +1. Under **App Clients**, find your app client ID. Select **Show details* to display the app client secret. These values correspond to the OAuth 2.0 Client ID and Client Secret. Save these values. ## Configure GitLab @@ -49,8 +50,13 @@ The following steps enable AWS Cognito as an authentication provider: sudo editor /etc/gitlab/gitlab.rb ``` -1. In the following code block, substitute the Client ID (`app_id`), Client Secret (`app_secret`), and the Amazon domain name (`site`) for your AWS Cognito application. -Include the code block in the `/etc/gitlab/gitlab.rb` file: +1. In the following code block, enter your AWS Cognito application information in the following parameters: + + - `app_id`: Your client ID. + - `app_secret`: Your client secret. + - `site`: Your Amazon domain and region. + + Include the code block in the `/etc/gitlab/gitlab.rb` file: ```ruby gitlab_rails['omniauth_allow_single_sign_on'] = ['cognito'] @@ -59,12 +65,12 @@ Include the code block in the `/etc/gitlab/gitlab.rb` file: name: "cognito", label: "Provider name", # optional label for login button, defaults to "Cognito" icon: nil, # Optional icon URL - app_id: "CLIENT ID", - app_secret: "CLIENT SECRET", + app_id: "<client_id>", + app_secret: "<client_secret>", args: { scope: "openid profile email", client_options: { - site: "https://your_domain.auth.your_region.amazoncognito.com", + site: "https://<your_domain>.auth.<your_region>.amazoncognito.com", authorize_url: "/oauth2/authorize", token_url: "/oauth2/token", user_info_url: "/oauth2/userInfo" @@ -84,8 +90,9 @@ Include the code block in the `/etc/gitlab/gitlab.rb` file: 1. Save the configuration file. 1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. -Your sign-in page should now display a Cognito button below the regular sign-in form. -To begin the authentication process, select the icon, and AWS Cognito asks the user to sign in and authorize the GitLab application. -If successful, the user is redirected and signed in to your GitLab instance. +Your sign-in page should now display a Cognito option below the regular sign-in form. +Select this option to begin the authentication process. +AWS Cognito then asks you to sign in and authorize the GitLab application. +If the authorization is successful, you're redirected and signed in to your GitLab instance. For more information, see [Configure initial settings](../../integration/omniauth.md#configure-initial-settings). diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index ced7cdb7119..4395309e91e 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Atlassian Crowd OmniAuth provider (deprecated) **(FREE SELF)** diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 2644e3a1f50..307d9a4518d 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -3,7 +3,7 @@ comments: false type: index stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab authentication and authorization **(FREE SELF)** diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 71ab084065a..c7e7253ef72 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # JWT OmniAuth provider **(FREE SELF)** diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 7f399f7e730..2077c6f7baf 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 19f656d2f14..3bb9350e960 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate LDAP with GitLab **(FREE SELF)** @@ -13,7 +13,7 @@ to support user authentication. This integration works with most LDAP-compliant directory servers, including: - Microsoft Active Directory. - [Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) + [Microsoft Active Directory Trusts](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) are not supported. - Apple Open Directory. - Open LDAP. @@ -98,7 +98,7 @@ gitlab_rails['ldap_servers'] = { 'main' => { 'label' => 'LDAP', 'host' => 'ldap.mydomain.com', - 'port' => 389, + 'port' => 636, 'uid' => 'sAMAccountName', 'encryption' => 'simple_tls', 'verify_certificates' => true, @@ -312,7 +312,7 @@ To limit access to the nested members of an Active Directory group, use the foll ``` For more information about `LDAP_MATCHING_RULE_IN_CHAIN` filters, see -[Search Filter Syntax](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax). +[Search Filter Syntax](https://learn.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax). Support for nested members in the user filter shouldn't be confused with [group sync nested groups](ldap_synchronization.md#supported-ldap-group-typesattributes) support. diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index a68e6ae2649..0ec482648a9 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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 LDAP **(FREE SELF)** @@ -866,3 +866,36 @@ To enable debug output in the rails console, [enter the rails console](#rails-co ```ruby Rails.logger.level = Logger::DEBUG ``` + +#### Get all error messages associated with groups, subgroups, members, and requesters + +Collect error messages associated with groups, subgroups, members, and requesters. This +captures error messages that may not appear in the Web interface. This can be especially helpful +for troubleshooting issues with [LDAP group sync](ldap_synchronization.md#group-sync) +and unexpected behavior with users and their membership in groups and subgroups. + +```ruby +# Find the group and subgroup +group = Group.find_by_full_path("parent_group") +subgroup = Group.find_by_full_path("parent_group/child_group") + +# Group and subgroup errors +group.valid? +group.errors.map(&:full_messages) + +subgroup.valid? +subgroup.errors.map(&:full_messages) + +# Group and subgroup errors for the members AND requesters +group.requesters.map(&:valid?) +group.requesters.map(&:errors).map(&:full_messages) +group.members.map(&:valid?) +group.members.map(&:errors).map(&:full_messages) +group.members_and_requesters.map(&:errors).map(&:full_messages) + +subgroup.requesters.map(&:valid?) +subgroup.requesters.map(&:errors).map(&:full_messages) +subgroup.members.map(&:valid?) +subgroup.members.map(&:errors).map(&:full_messages) +subgroup.members_and_requesters.map(&:errors).map(&:full_messages) +``` diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index 37a27fc058e..af2b1400670 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # LDAP synchronization **(PREMIUM SELF)** diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index 9f3c96902f8..bb263512e06 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -2,14 +2,16 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OpenID Connect OmniAuth provider **(FREE SELF)** -GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider. +GitLab can use [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. +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. 1. On your GitLab server, open the configuration file. @@ -27,7 +29,7 @@ The OpenID Connect provides you with a client's details and secret for you to us sudo -u git -H editor config/gitlab.yml ``` - See [Configure initial settings](../../integration/omniauth.md#configure-initial-settings) for initial settings. +1. [Configure initial settings](../../integration/omniauth.md#configure-initial-settings). 1. Add the provider configuration. @@ -83,32 +85,51 @@ The OpenID Connect provides you with a client's details and secret for you to us ``` NOTE: - For more information on each configuration option refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage) - and the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html). + For more information on each configuration option, refer to the: + + - [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage). + - [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html). + +1. For the provider configuration, change the values for the provider to match your + OpenID Connect client setup. Use the following as a guide: -1. For the configuration above, change the values for the provider to match your OpenID Connect client setup. Use the following as a guide: - `<your_oidc_label>` is the label that appears on the login page. - - `<custom_provider_icon>` (optional) is the icon that appears on the login page. Icons for the major social login platforms are built-in into GitLab, - but can be overridden by specifying this parameter. Both local paths and absolute URLs are accepted. - - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`. - If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`. - - If `discovery` is set to `true`, the OpenID Connect provider attempts to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`. - - `client_auth_method` (optional) specifies the method used for authenticating the client with the OpenID Connect provider. + - `<custom_provider_icon>` (optional) is the icon that appears on the login page. + Icons for the major social login platforms are built into GitLab, + but you can override these icons by specifying this parameter. GitLab accepts both + local paths and absolute URLs. + - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect + provider (for example, `https://example.com/auth/realms/your-realm`). + If this value is not provided, the URL is constructed from `client_options` + in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`. + - If `discovery` is set to `true`, the OpenID Connect provider attempts to automatically + discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. + Defaults to `false`. + - `client_auth_method` (optional) specifies the method used for authenticating + the client with the OpenID Connect provider. - Supported values are: - - `basic` - HTTP Basic Authentication - - `jwt_bearer` - JWT based authentication (private key and client secret signing) - - `mtls` - Mutual TLS or X.509 certificate validation - - Any other value POSTs the client ID and secret in the request body - - If not specified, defaults to `basic`. - - `<uid_field>` (optional) is the field name from the `user_info.raw_attributes` that defines the value for `uid`. For example, `preferred_username`. - If this value is not provided or the field with the configured value is missing from the `user_info.raw_attributes` details, the `uid` uses the `sub` field. - - `send_scope_to_token_endpoint` is `true` by default. In other words, the `scope` parameter is normally included in requests to the token endpoint. - However, if your OpenID Connect provider does not accept the `scope` parameter in such requests, set this to `false`. + - `basic` - HTTP Basic Authentication. + - `jwt_bearer` - JWT-based authentication (private key and client secret signing). + - `mtls` - Mutual TLS or X.509 certificate validation. + - Any other value posts the client ID and secret in the request body. + - If not specified, this value defaults to `basic`. + - `<uid_field>` (optional) is the field name from `user_info.raw_attributes` + that defines the value for `uid` (for example, `preferred_username`). + If you do not provide this value, or the field with the configured value is missing + from the `user_info.raw_attributes` details, `uid` uses the `sub` field. + - `send_scope_to_token_endpoint` is `true` by default, so the `scope` parameter + is normally included in requests to the token endpoint. + However, if your OpenID Connect provider does not accept the `scope` parameter + in such requests, set this to `false`. - `client_options` are the OpenID Connect client-specific options. Specifically: - `identifier` is the client identifier as configured in the OpenID Connect service provider. - - `secret` is the client secret as configured in the OpenID Connect service provider. - - `redirect_uri` is the GitLab URL to redirect the user to after successful login. For example, `http://example.com/users/auth/openid_connect/callback`. - - `end_session_endpoint` (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful. + - `secret` is the client secret as configured in the OpenID Connect service provider. For example, + [OmniAuth OpenIDConnect](https://github.com/omniauth/omniauth_openid_connect)) requires this. If the service provider doesn't require a secret, + provide any value and it is ignored. + - `redirect_uri` is the GitLab URL to redirect the user to after successful login + (for example, `http://example.com/users/auth/openid_connect/callback`). + - `end_session_endpoint` (optional) is the URL to the endpoint that ends the + session. You can provide this URL if auto-discovery is disabled or unsuccessful. - The following `client_options` are optional unless auto-discovery is disabled or unsuccessful: - `authorization_endpoint` is the URL to the endpoint that authorizes the end user. - `token_endpoint` is the URL to the endpoint that provides Access Token. @@ -116,20 +137,22 @@ The OpenID Connect provides you with a client's details and secret for you to us - `jwks_uri` is the URL to the endpoint where the Token signer publishes its keys. 1. Save the configuration file. -1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) - for the changes to take effect if you installed GitLab via Omnibus or from source respectively. +1. For changes to take effect, if you installed GitLab: + + - With Omnibus, [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + - From source, [restart GitLab](../restart_gitlab.md#installations-from-source). -On the sign in page, there should now be an OpenID Connect icon below the regular sign in form. -Select the icon to begin the authentication process. The OpenID Connect provider asks the user to -sign in and authorize the GitLab application (if confirmation required by the client). If everything goes well, the user -is redirected to GitLab and signed in. +On the sign in page, you have an OpenID Connect option below the regular sign in form. +Select this option to begin the authentication process. The OpenID Connect provider +asks you to sign in and authorize the GitLab application if confirmation is required +by the client. You are redirected to GitLab and signed in. ## Example configurations The following configurations illustrate how to set up OpenID with different providers with Omnibus GitLab. -### Google +### Configure Google See the [Google documentation](https://developers.google.com/identity/protocols/oauth2/openid-connect) for more details: @@ -157,16 +180,16 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -### Microsoft Azure +### Configure Microsoft Azure -The OpenID Connect (OIDC) protocol for Microsoft Azure uses the [Microsoft identity platform (v2) endpoints](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/azure-ad-endpoint-comparison). -To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, you need the -following information: +The OpenID Connect (OIDC) protocol for Microsoft Azure uses the [Microsoft identity platform (v2) endpoints](https://learn.microsoft.com/en-us/azure/active-directory/azuread-dev/azure-ad-endpoint-comparison). +To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, +you need the following information: -- A tenant ID. You may already have one. For more information, review the - [Microsoft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. +- A tenant ID. You may already have one. For more information, see the + [Microsoft Azure Tenant](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. - A client ID and a client secret. Follow the instructions in the - [Microsoft Quickstart Register an Application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) documentation + [Microsoft Quickstart Register an Application](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) documentation to obtain the tenant ID, client ID, and client secret for your app. Example Omnibus configuration block: @@ -194,49 +217,51 @@ gitlab_rails['omniauth_providers'] = [ ] ``` -Microsoft has documented how its platform works with [the OIDC protocol](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc). +Microsoft has documented how its platform works with [the OIDC protocol](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc). -### Microsoft Azure Active Directory B2C +### Configure Microsoft Azure Active Directory B2C -While GitLab works with [Azure Active Directory B2C](https://docs.microsoft.com/en-us/azure/active-directory-b2c/overview), it requires special -configuration to work. To get started, sign in to the [Azure Portal](https://portal.azure.com). +GitLab requires special +configuration to work with [Azure Active Directory B2C](https://learn.microsoft.com/en-us/azure/active-directory-b2c/overview). To get started, sign in to the [Azure Portal](https://portal.azure.com). For your app, you need the following information from Azure: - A tenant ID. You may already have one. For more information, review the - [Microsoft Azure Tenant](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. + [Microsoft Azure Tenant](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant) documentation. - A client ID and a client secret. Follow the instructions in the - [Microsoft tutorial](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga) documentation to obtain the + [Microsoft tutorial](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga) documentation to obtain the client ID and client secret for your app. -- The user flow or policy name. Follow the instructions in the [Microsoft tutorial](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-user-flow). +- The user flow or policy name. Follow the instructions in the [Microsoft tutorial](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-user-flow). -If your GitLab domain is `gitlab.example.com`, ensure the app has the following `Redirect URI`: +Configure the app: -`https://gitlab.example.com/users/auth/openid_connect/callback` +1. Set the app `Redirect URI`. For example, If your GitLab domain is `gitlab.example.com`, + set the app `Redirect URI` to `https://gitlab.example.com/users/auth/openid_connect/callback`. -In addition, ensure that [ID tokens are enabled](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga#enable-id-token-implicit-grant). +1. [Enable the ID tokens](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications?tabs=app-reg-ga#enable-id-token-implicit-grant). -Add the following API permissions to the app: +1. Add the following API permissions to the app: -- `openid` -- `offline_access` + - `openid` + - `offline_access` #### Configure custom policies -Azure B2C [offers two ways of defining the business logic for logging in a user](https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview): +Azure B2C [offers two ways of defining the business logic for logging in a user](https://learn.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview): -- [User flows](https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview#user-flows) -- [Custom policies](https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview#custom-policies) +- [User flows](https://learn.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview#user-flows) +- [Custom policies](https://learn.microsoft.com/en-us/azure/active-directory-b2c/user-flow-overview#custom-policies) -While cumbersome to configure, custom policies are required because -standard Azure B2C user flows [do not send the OpenID `email` claim](https://github.com/MicrosoftDocs/azure-docs/issues/16566). In -other words, they do not work with the [`allow_single_sign_on` or `auto_link_user` parameters](../../integration/omniauth.md#configure-initial-settings). +Custom policies are required because standard Azure B2C user flows +[do not send the OpenID `email` claim](https://github.com/MicrosoftDocs/azure-docs/issues/16566). +Therefore, the standard user flows do not work with the +[`allow_single_sign_on` or `auto_link_user` parameters](../../integration/omniauth.md#configure-initial-settings). With a standard Azure B2C policy, GitLab cannot create a new account or -link to an existing one with an email address. +link to an existing account with an email address. -Carefully follow the instructions for [creating a custom policy](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy). +First, [create a custom policy](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy). -The Microsoft instructions use `SocialAndLocalAccounts` in the [custom policy starter pack](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#custom-policy-starter-pack), -but `LocalAccounts` works for authenticating against local, Active Directory accounts. Before you follow the instructions to [upload the polices](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies), do the following: +The Microsoft instructions use `SocialAndLocalAccounts` in the [custom policy starter pack](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#custom-policy-starter-pack), +but `LocalAccounts` authenticates against local Active Directory accounts. Before you [upload the polices](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies), do the following: 1. To export the `email` claim, modify the `SignUpOrSignin.xml`. Replace the following line: @@ -250,9 +275,9 @@ but `LocalAccounts` works for authenticating against local, Active Directory acc <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" /> ``` -1. For OIDC discovery to work with B2C, the policy must be configured with an issuer compatible with the +1. For OIDC discovery to work with B2C, configure the policy with an issuer compatible with the [OIDC specification](https://openid.net/specs/openid-connect-discovery-1_0.html#rfc.section.4.3). - See the [token compatibility settings](https://docs.microsoft.com/en-us/azure/active-directory-b2c/configure-tokens?pivots=b2c-custom-policy#token-compatibility-settings). + See the [token compatibility settings](https://learn.microsoft.com/en-us/azure/active-directory-b2c/configure-tokens?pivots=b2c-custom-policy#token-compatibility-settings). In `TrustFrameworkBase.xml` under `JwtIssuer`, set `IssuanceClaimPattern` to `AuthorityWithTfp`: ```xml @@ -268,22 +293,22 @@ but `LocalAccounts` works for authenticating against local, Active Directory acc ... ``` -1. Now [upload the policy](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies). Overwrite +1. [Upload the policy](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#upload-the-policies). Overwrite the existing files if you are updating an existing policy. -1. Determine the issuer URL using the sign-in policy. The issuer URL is in the form: +1. To determine the issuer URL, use the sign-in policy. The issuer URL is in the form: ```markdown https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/ ``` - The policy name is lowercased in the URL. For example, `B2C_1A_signup_signin` + The policy name is lowercase in the URL. For example, `B2C_1A_signup_signin` policy appears as `b2c_1a_signup_sigin`. -The trailing forward slash is required. + Ensure you include the trailing forward slash. -1. Verify the operation of the OIDC discovery URL and issuer URL, append `.well-known/openid-configuration` - to the issuer URL: +1. Verify the operation of the OIDC discovery URL and issuer URL and append + `.well-known/openid-configuration` to the issuer URL: ```markdown https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/.well-known/openid-configuration @@ -327,33 +352,35 @@ The trailing forward slash is required. - Ensure all occurrences of `yourtenant.onmicrosoft.com`, `ProxyIdentityExperienceFrameworkAppId`, and `IdentityExperienceFrameworkAppId` match your B2C tenant hostname and the respective client IDs in the XML policy files. -- Add `https://jwt.ms` as a redirect URI to the app, and use the [custom policy tester](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#test-the-custom-policy). - Make sure the payload includes `email` that matches the user's email access. -- After you enable the custom policy, users might see "Invalid username or password" after they try to sign in. This might be a configuration - issue with the `IdentityExperienceFramework` app. See [this Microsoft comment](https://docs.microsoft.com/en-us/answers/questions/50355/unable-to-sign-on-using-custom-policy.html?childToView=122370#comment-122370) - that suggests checking that the app manifest contains these settings: +- Add `https://jwt.ms` as a redirect URI to the app, and use the [custom policy tester](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy#test-the-custom-policy). + Ensure the payload includes `email` that matches the user's email access. +- After you enable the custom policy, users might see `Invalid username or password` + after they try to sign in. This might be a configuration issue with the `IdentityExperienceFramework` + app. See [this Microsoft comment](https://learn.microsoft.com/en-us/answers/questions/50355/unable-to-sign-on-using-custom-policy.html?childToView=122370#comment-122370) that suggests you check that the app manifest + contains these settings: - `"accessTokenAcceptedVersion": null` - `"signInAudience": "AzureADMyOrg"` This configuration corresponds with the `Supported account types` setting used when - creating the `IdentityExperienceFramework` app. +creating the `IdentityExperienceFramework` app. -### Keycloak +### Configure Keycloak -GitLab works with OpenID providers that use HTTPS. Although a Keycloak -server can be set up using HTTP, GitLab can only communicate -with a Keycloak server that uses HTTPS. +GitLab works with OpenID providers that use HTTPS. Although you can set up a +Keycloak server that uses HTTP, GitLab can only communicate with a Keycloak server +that uses HTTPS. -We highly recommend configuring Keycloak to use public key encryption algorithms (for example, -RSA256, RSA512, and so on) instead of symmetric key encryption algorithms (for example, HS256 or HS358) to -sign tokens. Public key encryption algorithms are: +Configure Keycloak to use public key encryption algorithms (for example, +RSA256 or RSA512) instead of symmetric key encryption algorithms (for example, +HS256 or HS358) to sign tokens. Public key encryption algorithms are: - Easier to configure. - More secure because leaking the private key has severe security consequences. -The signature algorithm can be configured in the Keycloak administration console under -**Realm Settings > Tokens > Default Signature Algorithm**. +1. Open the Keycloak administration console. +1. Select **Realm Settings > Tokens > Default Signature Algorithm**. +1. Configure the signature algorithm. Example Omnibus configuration block: @@ -385,38 +412,40 @@ gitlab_rails['omniauth_providers'] = [ > Introduced in GitLab 14.2. WARNING: -The instructions below are included for completeness, but symmetric key -encryption should only be used when absolutely necessary. +The following instructions are included for completeness, but only use symmetric key +encryption if absolutely necessary. To use symmetric key encryption: -1. Extract the secret key from the Keycloak database. Keycloak doesn't expose this value in the Web - interface. The client secret seen in the Web interface is the OAuth2 client secret, which is - different from the secret used to sign JSON Web Tokens. - - For example, if you're using PostgreSQL as the backend database for Keycloak, log in to the - database console and extract the key via this SQL query: - - ```sql - $ psql -U keycloak - psql (13.3 (Debian 13.3-1.pgdg100+1)) - Type "help" for help. - - keycloak=# SELECT c.name, value FROM component_config CC INNER JOIN component C ON(CC.component_id = C.id) WHERE C.realm_id = 'master' and provider_id = 'hmac-generated' AND CC.name = 'secret'; - -[ RECORD 1 ]--------------------------------------------------------------------------------- - name | hmac-generated - value | lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g - -[ RECORD 2 ]--------------------------------------------------------------------------------- - name | fallback-HS384 - value | UfVqmIs--U61UYsRH-NYBH3_mlluLONpg_zN7CXEwkJcO9xdRNlzZfmfDLPtf2xSTMvqu08R2VhLr-8G-oZ47A - ``` +1. Extract the secret key from the Keycloak database. Keycloak does not expose this + value in the web interface. The client secret seen in the web interface is the + OAuth 2.0 client secret, which is different from the secret used to sign JSON Web Tokens. - In this example, there are two private keys: one for HS256 (`hmac-generated`), and another for - HS384 (`fallback-HS384`). We use the first `value` to configure GitLab. + For example, if you use PostgreSQL as the backend database for Keycloak: -1. Convert `value` to standard base64. As [discussed in the post](https://keycloak.discourse.group/t/invalid-signature-with-hs256-token/3228/9), - `value` is encoded in ["Base 64 Encoding with URL and Filename Safe Alphabet" in RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-5). - This needs to be converted to [standard base64 as defined in RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045). + - Sign into the database console. + - Run the following SQL query to extract the key: + + ```sql + $ psql -U keycloak + psql (13.3 (Debian 13.3-1.pgdg100+1)) + Type "help" for help. + + keycloak=# SELECT c.name, value FROM component_config CC INNER JOIN component C ON(CC.component_id = C.id) WHERE C.realm_id = 'master' and provider_id = 'hmac-generated' AND CC.name = 'secret'; + -[ RECORD 1 ]--------------------------------------------------------------------------------- + name | hmac-generated + value | lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g + -[ RECORD 2 ]--------------------------------------------------------------------------------- + name | fallback-HS384 + value | UfVqmIs--U61UYsRH-NYBH3_mlluLONpg_zN7CXEwkJcO9xdRNlzZfmfDLPtf2xSTMvqu08R2VhLr-8G-oZ47A + ``` + + In this example, there are two private keys: one for HS256 (`hmac-generated`) + and another for HS384 (`fallback-HS384`). We use the first `value` to configure GitLab. + +1. Convert `value` to standard base64. As discussed in the [**Invalid signature with HS256 token** post](https://keycloak.discourse.group/t/invalid-signature-with-hs256-token/3228/9), + `value` is encoded in the [**Base 64 Encoding with URL and Filename Safe Alphabet** section](https://datatracker.ietf.org/doc/html/rfc4648#section-5) of RFC 4648. + This must be converted to [standard base64 as defined in RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045). The following Ruby script does this: ```ruby @@ -458,17 +487,19 @@ To use symmetric key encryption: ] ``` -If after reconfiguring, you see the error `JSON::JWS::VerificationFailed` error message, this means -the incorrect secret was specified. +If you see a `JSON::JWS::VerificationFailed` error, +you have specified the wrong secret. ### Casdoor -GitLab works with OpenID providers that use HTTPS. To connect to GitLab using OpenID with Casdoor, use HTTPS instead of HTTP. +GitLab works with OpenID providers that use HTTPS. Use HTTPS to connect to GitLab +through OpenID with Casdoor. For your app, complete the following steps on Casdoor: 1. Get a client ID and a client secret. -1. Add your GitLab redirect URL. For example, if your GitLab domain is `gitlab.example.com`, ensure the Casdoor app has the following +1. Add your GitLab redirect URL. For example, if your GitLab domain is `gitlab.example.com`, + ensure the Casdoor app has the following `Redirect URI`: `https://gitlab.example.com/users/auth/openid_connect/callback`. See the [Casdoor documentation](https://casdoor.org/docs/integration/gitlab) for more details. @@ -520,23 +551,21 @@ Example installations from source configuration (file path: `config/gitlab.yml`) } ``` -## General troubleshooting - -If you're having trouble, here are some tips: +## Troubleshooting -1. Ensure `discovery` is set to `true`. Setting it to `false` requires - specifying all the URLs and keys required to make OpenID work. +1. Ensure `discovery` is set to `true`. If you set it to `false`, you must + specify all the URLs and keys required to make OpenID work. 1. Check your system clock to ensure the time is synchronized properly. -1. As mentioned in [the documentation](https://github.com/m0n9oose/omniauth_openid_connect), +1. As mentioned in [the OmniAuth OpenID Connect documentation](https://github.com/m0n9oose/omniauth_openid_connect), make sure `issuer` corresponds to the base URL of the Discovery URL. For example, `https://accounts.google.com` is used for the URL `https://accounts.google.com/.well-known/openid-configuration`. 1. The OpenID Connect client uses HTTP Basic Authentication to send the - OAuth2 access token if `client_auth_method` is not defined or if set to `basic`. - If you are seeing 401 errors upon retrieving the `userinfo` endpoint, you may - want to check your OpenID Web server configuration. For example, for - [`oauth2-server-php`](https://github.com/bshaffer/oauth2-server-php), you - may need to [add a configuration parameter to Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778). + OAuth 2.0 access token if `client_auth_method` is not defined or if set to `basic`. + If you see 401 errors when retrieving the `userinfo` endpoint, check + your OpenID web server configuration. For example, for + [`oauth2-server-php`](https://github.com/bshaffer/oauth2-server-php), you may have to + [add a configuration parameter to Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778). diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index 0590410bf31..11117e8a74c 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -13,7 +13,7 @@ GitLab supports authentication using smartcards. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33669) in GitLab 12.6. -By default, existing users can continue to log in with a username and password when smartcard +By default, existing users can continue to sign in with a username and password when smartcard authentication is enabled. To force existing users to use only smartcard authentication, @@ -101,7 +101,7 @@ Certificate: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7693) in GitLab 11.8 as an experimental feature. Smartcard authentication against an LDAP server may change or be removed completely in the future. GitLab implements a standard way of certificate matching following -[RFC4523](https://tools.ietf.org/html/rfc4523). It uses the +[RFC4523](https://www.rfc-editor.org/rfc/rfc4523). It uses the `certificateExactMatch` certificate matching rule against the `userCertificate` attribute. As a prerequisite, you must use an LDAP server that: diff --git a/doc/administration/cicd.md b/doc/administration/cicd.md index 5e061320c5b..6899b572e8f 100644 --- a/doc/administration/cicd.md +++ b/doc/administration/cicd.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -69,7 +69,8 @@ can choose a custom limit. For example, to set the limit to `100`: Plan.default.actual_limits.update!(ci_needs_size_limit: 100) ``` -To disable directed acyclic graphs (DAG), set the limit to `0`. +To disable directed acyclic graphs (DAG), set the limit to `0`. Pipelines with jobs +configured to use `needs` then return the error `job can only need 0 others`. ## Change maximum scheduled pipeline frequency diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index 82bb1a35e02..d7e1c9af1de 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install the GitLab agent server for Kubernetes (KAS) **(FREE SELF)** @@ -28,9 +28,13 @@ Or, you can [use an external agent server](#use-an-external-installation). ### For Omnibus -For [Omnibus](https://docs.gitlab.com/omnibus/) package installations: +You can enable the agent server for [Omnibus](https://docs.gitlab.com/omnibus/) package installations on a single node, or on multiple nodes at once. -1. To enable the agent server, edit `/etc/gitlab/gitlab.rb`: +#### Enable on a single node + +To enable the agent server on a single node: + +1. Edit `/etc/gitlab/gitlab.rb`: ```ruby gitlab_kas['enable'] = true @@ -41,6 +45,33 @@ For [Omnibus](https://docs.gitlab.com/omnibus/) package installations: For additional configuration options, see the **Enable GitLab KAS** section of the [`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-config-template/gitlab.rb.template). +#### Enable on multiple nodes + +To enable the agent server on multiple nodes: + +1. For each agent server node, edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_kas['enable'] = true + gitlab_kas['api_secret_key'] = '<32_bytes_long_base64_encoded_value>' + gitlab_kas['private_api_secret_key'] = '<32_bytes_long_base64_encoded_value>' + gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155' + gitlab_kas['env'] = { + 'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/", + 'OWN_PRIVATE_API_URL' => 'grpc://<ip_or_hostname_of_this_host>:8155' + } + ``` + + In this configuration: + + - `gitlab_kas['private_api_listen_address']` is the address the agent server listens on. You can set it to `0.0.0.0` or an IP address reachable by other nodes in the cluster. + - `OWN_PRIVATE_API_URL` is the environment variable used by the KAS process for service discovery. You can set it to a hostname or IP address of the node you're configuring. The node must be reachable by other nodes in the cluster. + - `gitlab_kas['api_secret_key']` is the shared secret used for authentication between KAS and GitLab. This value must be Base64-encoded and exactly 32 bytes long. + - `gitlab_kas['private_api_secret_key']` is the shared secret used for authentication between different KAS instances. This value must be Base64-encoded and exactly 32 bytes long. + +1. For each application node, follow the steps in: [Use an external installation](../clusters/kas.md#use-an-external-installation). +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + ### For GitLab Helm Chart For GitLab [Helm Chart](https://docs.gitlab.com/charts/) installations: diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 573ffbf4686..ad345461776 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance features **(FREE)** @@ -48,9 +48,9 @@ settings and automation to ensure that whatever a compliance team has configured stays configured and working correctly. These features can help you automate compliance: -- [**Compliance frameworks**](../user/project/settings/index.md#compliance-frameworks) (for groups): Create a custom +- [**Compliance frameworks**](../user/group/manage.md#compliance-frameworks) (for groups): Create a custom compliance framework at the group level to describe the type of compliance requirements any child project needs to follow. -- [**Compliance pipelines**](../user/project/settings/index.md#compliance-pipeline-configuration) (for groups): Define a +- [**Compliance pipelines**](../user/group/manage.md#configure-a-compliance-pipeline) (for groups): Define a pipeline configuration to run for any projects with a given compliance framework. ## Audit management diff --git a/doc/administration/configure.md b/doc/administration/configure.md index 4335c6d972f..40f03d25e8d 100644 --- a/doc/administration/configure.md +++ b/doc/administration/configure.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/consul.md b/doc/administration/consul.md index e282960c857..a6f76882c4d 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md index 3f5d4adc95c..9021a795523 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Host the GitLab product documentation **(FREE SELF)** @@ -261,7 +261,7 @@ To upgrade to a later version [using your own web-server](#self-host-the-product If you self-host the product documentation: -- The version dropdown displays additional versions that don't exist. Selecting +- The version dropdown list displays additional versions that don't exist. Selecting these versions displays a `404 Not Found` page. - The search displays results from `docs.gitlab.com` and not the local site. - By default, the landing page redirects to the diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index a96a4c4405d..648f6d7018e 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -17,17 +17,17 @@ GitLab can read settings for certain features from encrypted settings files. The To enable the encrypted configuration settings, a new base key must be generated for `encrypted_settings_key_base`. The secret can be generated in the following ways: -**Omnibus Installation** +**Omnibus** Starting with 13.7 the new secret is automatically generated for you, but you must ensure your `/etc/gitlab/gitlab-secrets.json` contains the same values on all nodes. -**GitLab Cloud Native Helm Chart** +**Helm chart** Starting with GitLab 13.7, the new secret is automatically generated if you have the `shared-secrets` chart enabled. Otherwise, you need to follow the [secrets guide for adding the secret](https://docs.gitlab.com/charts/installation/secrets.html#gitlab-rails-secret). -**Source Installation** +**Source** The new secret can be generated by running: diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index e70758e2774..beaef7afe57 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/external_pipeline_validation.md b/doc/administration/external_pipeline_validation.md index b9bf0cfdc50..e6f825f7cb8 100644 --- a/doc/administration/external_pipeline_validation.md +++ b/doc/administration/external_pipeline_validation.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index 75e65c2a9d6..4f8f7c22a55 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/engineering/ux/technical-writing/#assignments +info: To 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: "GitLab administrator: enable and disable GitLab features deployed behind feature flags" --- @@ -27,8 +27,9 @@ Features behind flags can be gradually rolled out, typically: 1. The feature flag is removed. These features can be enabled and disabled to allow or prevent users from using -them. It can be done by GitLab administrators with access to GitLab Rails -console. +them. It can be done by GitLab administrators with access to the +[Rails console](#how-to-enable-and-disable-features-behind-flags) or the +[Feature flags API](../api/features.md). When you disable a feature flag, the feature is hidden from users and all of the functionality is turned off. For example, data is not recorded and services do not run. diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md index ed5dbd83a8e..8fafb258593 100644 --- a/doc/administration/file_hooks.md +++ b/doc/administration/file_hooks.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index d3aa2c97833..699fe6851eb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Automatic background verification **(PREMIUM SELF)** diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index 1991b747af0..dda2c5d34d3 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index e82c130ba01..156a87614e6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Disaster Recovery (Geo) **(PREMIUM SELF)** @@ -10,8 +10,6 @@ Geo replicates your database, your Git repositories, and few other assets, but there are some [limitations](../index.md#limitations). WARNING: -Disaster recovery for multi-secondary configurations is in [**Alpha**](../../../policy/alpha-beta-support.md#alpha-features). -For the latest updates, check the [Disaster Recovery epic for complete maturity](https://gitlab.com/groups/gitlab-org/-/epics/3574). Multi-secondary configurations require the complete re-synchronization and re-configuration of all non-promoted secondaries and causes downtime. @@ -342,7 +340,7 @@ with the **secondary** site: 1. Promote the replica database associated with the **secondary** site. This sets the database to read-write. The instructions vary depending on where your database is hosted: - [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Promote) - - [Azure PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication) + - [Azure PostgreSQL](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication) - [Google Cloud SQL](https://cloud.google.com/sql/docs/mysql/replication/manage-replicas#promote-replica) - For other external PostgreSQL databases, save the following script in your secondary site, for example `/tmp/geo_promote.sh`, and modify the connection @@ -413,7 +411,7 @@ required: 1. Promote the replica database associated with the **secondary** site. This sets the database to read-write. The instructions vary depending on where your database is hosted: - [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Promote) - - [Azure PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication) + - [Azure PostgreSQL](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication) - [Google Cloud SQL](https://cloud.google.com/sql/docs/mysql/replication/manage-replicas#promote-replica) - For other external PostgreSQL databases, save the following script in your secondary site, for example `/tmp/geo_promote.sh`, and modify the connection @@ -617,9 +615,9 @@ Now we need to make each **secondary** site listen to changes on the new **prima to [initiate the replication process](../setup/database.md#step-3-initiate-the-replication-process) again but this time for another **primary** site. All the old replication settings are overwritten. -## Promoting a secondary Geo cluster in GitLab Cloud Native Helm Charts +## Promoting a secondary Geo cluster in the GitLab Helm chart -When updating a Cloud Native Geo deployment, the process for updating any node that is external to the secondary Kubernetes cluster does not differ from the non Cloud Native approach. As such, you can always defer to [Promoting a secondary Geo site in single-secondary configurations](#promoting-a-secondary-geo-site-in-single-secondary-configurations) for more information. +When updating a cloud-native Geo deployment, the process for updating any node that is external to the secondary Kubernetes cluster does not differ from the non cloud-native approach. As such, you can always defer to [Promoting a secondary Geo site in single-secondary configurations](#promoting-a-secondary-geo-site-in-single-secondary-configurations) for more information. The following sections assume you are using the `gitlab` namespace. If you used a different namespace when setting up your cluster, you should also replace `--namespace gitlab` with your namespace. diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index d0dbecce43a..60101f5af8e 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -233,7 +233,7 @@ At this point, your **secondary** site contains an up-to-date copy of everything ## Promote the **secondary** site -After the replication is finished, [promote the **secondary** site to a **primary** site](index.md). This process causes a brief outage on the **secondary** site, and users may need to log in again. If you follow the steps correctly, the old primary Geo site should still be disabled and user traffic should go to the newly-promoted site instead. +After the replication is finished, [promote the **secondary** site to a **primary** site](index.md). This process causes a brief outage on the **secondary** site, and users may need to sign in again. If you follow the steps correctly, the old primary Geo site should still be disabled and user traffic should go to the newly-promoted site instead. When the promotion is completed, the maintenance window is over, and your new **primary** site now begins to diverge from the old one. If problems do arise at this point, failing 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 11baf383c67..8c18aaa944d 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,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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -121,7 +121,7 @@ follow these steps to avoid unnecessary data loss: ``` From this point, users are unable to view their data or make changes on the - **primary** site. They are also unable to log in to the **secondary** site. + **primary** site. They are also unable to sign in to the **secondary** site. However, existing sessions must work for the remainder of the maintenance period, and so public data is accessible throughout. 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 2958c119c20..f9d99095951 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,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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -106,7 +106,7 @@ follow these steps to avoid unnecessary data loss: ``` From this point, users are unable to view their data or make changes on the - **primary** site. They are also unable to log in to the **secondary** site. + **primary** site. They are also unable to sign in to the **secondary** site. However, existing sessions need to work for the remainder of the maintenance period, and so public data is accessible throughout. diff --git a/doc/administration/geo/glossary.md b/doc/administration/geo/glossary.md index c9d4ccacae3..9abd7ea9347 100644 --- a/doc/administration/geo/glossary.md +++ b/doc/administration/geo/glossary.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index db298d4fdfc..a336f5ff8bc 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo **(PREMIUM SELF)** @@ -206,6 +206,7 @@ This list of limitations only reflects the latest version of GitLab. If you are - [Selective synchronization](replication/configuration.md#selective-synchronization) only limits what repositories and files are replicated. The entire PostgreSQL data is still replicated. Selective synchronization is not built to accommodate compliance / export control use cases. - [Pages access control](../../user/project/pages/pages_access_control.md) doesn't work on secondaries. See [GitLab issue #9336](https://gitlab.com/gitlab-org/gitlab/-/issues/9336) for details. - [GitLab chart with Geo](https://docs.gitlab.com/charts/advanced/geo/) does not support [Unified URLs](secondary_proxy/index.md#set-up-a-unified-url-for-geo-sites). See [GitLab issue #3522](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/3522) for more details. +- [Disaster recovery](disaster_recovery/index.md) for multi-secondary sites causes downtime due to the complete re-synchronization and re-configuration of all non-promoted secondaries. ### Limitations on replication/verification diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 39d1f5ae602..fa74f16cdc8 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/replication/container_registry.md b/doc/administration/geo/replication/container_registry.md index 01ba81b6dbe..abf34efa56e 100644 --- a/doc/administration/geo/replication/container_registry.md +++ b/doc/administration/geo/replication/container_registry.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 40b71684bac..566df2ee509 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -59,6 +59,10 @@ verification methods: | Blobs | Pages _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | CI Secure Files _(file system)_ | Geo with API | SHA256 checksum | | Blobs | CI Secure Files _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Incident Metric Images _(file system)_ | Geo with API/Managed | SHA256 checksum | +| Blobs | Incident Metric Images _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Alert Metric Images _(file system)_ | Geo with API | SHA256 checksum | +| Blobs | Alert Metric Images _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | - (*1*): Redis replication can be used as part of HA with Redis sentinel. It's not used between Geo sites. - (*2*): Object storage replication can be performed by Geo or by your object storage provider/appliance @@ -197,7 +201,8 @@ successfully, you must replicate their data using some other means. |[CI job artifacts](../../../ci/pipelines/job_artifacts.md) | **Yes** (10.4) | **Yes** (14.10) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | 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) | [No](object_storage.md#verification-of-files-in-object-storage) | 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) | [No](object_storage.md#verification-of-files-in-object-storage) | 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) | No | No | No | Disabled by default. See [instructions](container_registry.md) to enable. | +|[Container Registry](../../packages/container_registry.md) | **Yes** (12.3)* | No | No | No | Replication is behind feature flag `geo_container_repository_replication`, enabled by default. +Requires additional configuration. See [instructions](container_registry.md) to set up the Container Registry replication. | |[Infrastructure Registry](../../../user/packages/infrastructure_registry/index.md) | **Yes** (14.0) | **Yes** (14.0) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | N/A | N/A | 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) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_package_file_replication`, enabled by default. | @@ -206,9 +211,11 @@ successfully, you must replicate their data using some other means. |[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) | N/A | N/A | Verification was implemented behind the feature flag `geo_snippet_repository_verification` in 13.11, and the feature flag was removed in 14.2. | |[GitLab Pages](../../pages/index.md) | [**Yes** (14.3)](https://gitlab.com/groups/gitlab-org/-/epics/589) | **Yes** (14.6) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_pages_deployment_replication`, enabled by default. Verification was behind the feature flag `geo_pages_deployment_verification`, removed in 14.7. | |[Project-level Secure files](../../../ci/secure_files/index.md) | **Yes** (15.3) | **Yes** (15.3) | **Yes** (15.3) | [No](object_storage.md#verification-of-files-in-object-storage) | | -|[Incident Metric Images](../../../operations/incident_management/incidents.md#metrics) | [Planned](https://gitlab.com/gitlab-org/gitlab/-/issues/362561) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/362561) | No | No | | -|[Alert Metric Images](../../../operations/incident_management/alerts.md#metrics-tab) | [Planned](https://gitlab.com/gitlab-org/gitlab/-/issues/362564) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/362564) | No | No | | +| [Incident Metric Images](../../../operations/incident_management/incidents.md#metrics) | **Yes** (15.5) | **Yes**(15.5) | **Yes** (15.5) | [No](object_storage.md#verification-of-files-in-object-storage) | Replication/Verification is handled via the Uploads data type. | | +|[Alert Metric Images](../../../operations/incident_management/alerts.md#metrics-tab) | **Yes** (15.5) | **Yes** (15.5) | **Yes** (15.5) | [No](object_storage.md#verification-of-files-in-object-storage) | Replication/Verification is handled via the Uploads data type. | |[Server-side Git hooks](../../server_hooks.md) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/1867) | No | N/A | N/A | Not planned because of current implementation complexity, low customer interest, and availability of alternatives to hooks. | -|[Elasticsearch integration](../../../integration/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) | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/259694) | No | No | No | Blocked by [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Replication of this cache is not needed for disaster recovery purposes because it can be recreated from external sources. | +|[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) | [Planned](https://gitlab.com/groups/gitlab-org/-/epics/8833) | No | No | No | Blocked by [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Replication of this cache is not needed for disaster recovery purposes because it can be recreated from external sources. | |[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. | + +\* 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 84bc2e034b9..3230a92136f 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -63,7 +63,7 @@ Geo node in a PostgreSQL console (`sudo gitlab-psql`): ## Remove Geo-related configuration -1. For each node on your primary Geo site, SSH into the node and log in as root: +1. For each node on your primary Geo site, SSH into the node and sign in as root: ```shell sudo -i diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index 7a67af1cfa2..81afcc19bb1 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo Frequently Asked Questions **(PREMIUM SELF)** @@ -69,6 +69,6 @@ That's totally fine. We use HTTP(s) to fetch repository changes from the **prima Yes. See [Container Registry for a **secondary** site](container_registry.md). -## Can you log in to a secondary site? +## Can you sign in to a secondary site? Yes, but secondary sites receive all authentication data (like user accounts and logins) from the primary instance. This means you are re-directed to the primary for authentication and then routed back. diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index 7b59cdda1aa..8fa5a45b579 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 18103211580..e0e113eebbd 100644 --- a/doc/administration/geo/replication/location_aware_git_url.md +++ b/doc/administration/geo/replication/location_aware_git_url.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index afa4f4eb552..5be7d40890c 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -53,7 +53,7 @@ you already have a working GitLab instance that is in-use, it can be used as a The second GitLab site serves as the Geo **secondary** site. Again, use the [GitLab reference architectures documentation](../../reference_architectures/index.md) to set this up. -It's a good idea to log in and test it. However, be aware that its data is +It's a good idea to sign in and test it. However, be aware that its data is wiped out as part of the process of replicating from the **primary** site. ## Configure a GitLab site to be the Geo **primary** site diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index 0336a1669f9..8128eaf5310 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/replication/remove_geo_site.md b/doc/administration/geo/replication/remove_geo_site.md index b136f6cc8b8..62b1d9fdf7b 100644 --- a/doc/administration/geo/replication/remove_geo_site.md +++ b/doc/administration/geo/replication/remove_geo_site.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/replication/security_review.md b/doc/administration/geo/replication/security_review.md index bc08b7b71e7..0231da53b9c 100644 --- a/doc/administration/geo/replication/security_review.md +++ b/doc/administration/geo/replication/security_review.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index d64ad2549e8..3f16c1552ad 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/engineering/ux/technical-writing/#assignments +info: To 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 Geo **(PREMIUM SELF)** @@ -311,6 +311,51 @@ sudo gitlab-rake gitlab:geo:check When performing a PostgreSQL major version (9 > 10) update this is expected. Follow the [initiate-the-replication-process](../setup/database.md#step-3-initiate-the-replication-process). +### Repository verification failures + +[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +to gather the following, basic troubleshooting information. + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +#### Get the number of verification failed repositories + +```ruby +Geo::ProjectRegistry.verification_failed('repository').count +``` + +#### Find the verification failed repositories + +```ruby +Geo::ProjectRegistry.verification_failed('repository') +``` + +#### Find repositories that failed to sync + +```ruby +Geo::ProjectRegistry.sync_failed('repository') +``` + +### Resync repositories + +[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +to enact the following, basic troubleshooting steps. + +#### Queue up all repositories for resync. Sidekiq handles each sync + +```ruby +Geo::ProjectRegistry.update_all(resync_repository: true, resync_wiki: true) +``` + +#### Sync individual repository now + +```ruby +project = Project.find_by_full_path('<group/project>') + +Geo::RepositorySyncService.new(project).execute +``` + ## Fixing replication errors The following sections outline troubleshooting steps for fixing replication @@ -779,7 +824,7 @@ This behavior affects only the following data types through GitLab 14.6: | Data type | From version | | ------------------------ | ------------ | | Package Registry | 13.10 | -| Pipeline Artifacts | 13.11 | +| CI Pipeline Artifacts | 13.11 | | Terraform State Versions | 13.12 | | Infrastructure Registry | 14.0 | | External MR diffs | 14.6 | @@ -792,6 +837,120 @@ This behavior affects only the following data types through GitLab 14.6: to make Geo visibly surface data loss risks. The sync/verification loop is therefore short-circuited. `last_sync_failure` is now set to `The file is missing on the Geo primary site`. +### Blob types + +- `Ci::JobArtifact` +- `Ci::PipelineArtifact` +- `Ci::SecureFile` +- `LfsObject` +- `MergeRequestDiff` +- `Packages::PackageFile` +- `PagesDeployment` +- `Terraform::StateVersion` +- `Upload` + +`Packages::PackageFile` is used in the following +[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +examples, but things generally work the same for the other types. + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +#### The Replicator + +The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it): + +```ruby +model_record = Packages::PackageFile.last +model_record.replicator.registry.replicator.model_record # just showing that these methods exist +``` + +#### Replicate a package file, synchronously, given an ID + +```ruby +model_record = Packages::PackageFile.find(id) +model_record.replicator.send(:download) +``` + +#### Replicate a package file, synchronously, given a registry ID + +```ruby +registry = Geo::PackageFileRegistry.find(registry_id) +registry.replicator.send(:download) +``` + +#### Verify package files on the secondary manually + +This iterates over all package files on the secondary, looking at the +`verification_checksum` stored in the database (which came from the primary) +and then calculate this value on the secondary to check if they match. This +does not change anything in the UI: + +```ruby +# Run on secondary +status = {} + +Packages::PackageFile.find_each do |package_file| + primary_checksum = package_file.verification_checksum + secondary_checksum = Packages::PackageFile.hexdigest(package_file.file.path) + verification_status = (primary_checksum == secondary_checksum) + + status[verification_status.to_s] ||= [] + status[verification_status.to_s] << package_file.id +end + +# Count how many of each value we get +status.keys.each {|key| puts "#{key} count: #{status[key].count}"} + +# See the output in its entirety +status +``` + +### Repository types newer than project/wiki repositories + +- `SnippetRepository` +- `GroupWikiRepository` + +`SnippetRepository` is used in the examples below, but things generally work the same for the other Repository types. + +#### The Replicator + +The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it). + +```ruby +model_record = SnippetRepository.last +model_record.replicator.registry.replicator.model_record # just showing that these methods exist +``` + +#### Replicate a snippet repository, synchronously, given an ID + +```ruby +model_record = SnippetRepository.find(id) +model_record.replicator.send(:sync_repository) +``` + +#### Replicate a snippet repository, synchronously, given a registry ID + +```ruby +registry = Geo::SnippetRepositoryRegistry.find(registry_id) +registry.replicator.send(:sync_repository) +``` + +### Find failed artifacts + +[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +to run the following commands: + +```ruby +Geo::JobArtifactRegistry.failed +``` + +#### Find `ID` of synced artifacts that are missing on primary + +```ruby +Geo::JobArtifactRegistry.synced.missing_on_primary.pluck(:artifact_id) +``` + #### Failed syncs with GitLab-managed object storage replication There is [an issue in GitLab 14.2 through 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/299819#note_822629467) diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index 370c50c93db..ab9263ad344 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/replication/upgrading_the_geo_sites.md b/doc/administration/geo/replication/upgrading_the_geo_sites.md index ce1ff4fe6a5..55395a55857 100644 --- a/doc/administration/geo/replication/upgrading_the_geo_sites.md +++ b/doc/administration/geo/replication/upgrading_the_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md index fe0e06e7ea4..cfaa02e1a17 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- Please update EE::GitLab::GeoGitAccess::GEO_SERVER_DOCS_URL if this file is moved) --> diff --git a/doc/administration/geo/replication/version_specific_upgrades.md b/doc/administration/geo/replication/version_specific_upgrades.md index 6211b5689b1..9aad5cdeaa7 100644 --- a/doc/administration/geo/replication/version_specific_upgrades.md +++ b/doc/administration/geo/replication/version_specific_upgrades.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Version-specific upgrade instructions **(PREMIUM SELF)** @@ -10,6 +10,12 @@ Review this page for upgrade instructions for your version. These steps accompany the [general steps](upgrading_the_geo_sites.md#general-upgrade-steps) for upgrading Geo sites. +## Upgrading to 15.1 + +[Geo proxying](../secondary_proxy/index.md) was [enabled by default for different URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in 15.1. This may be a breaking change. If needed, you may [disable Geo proxying](../secondary_proxy/index.md#disable-geo-proxying). + +If you are using SAML with different URLs, there is a [known issue which requires proxying to be disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/377372). + ## Upgrading to 14.9 **Do not** upgrade to GitLab 14.9.0. Instead, use 14.9.1 or later. @@ -33,6 +39,10 @@ results in a loop that consistently fails for all objects stored in object stora For information on how to fix this, see [Troubleshooting - Failed syncs with GitLab-managed object storage replication](troubleshooting.md#failed-syncs-with-gitlab-managed-object-storage-replication). +## Upgrading to 14.6 + +[Geo proxying](../secondary_proxy/index.md) was [enabled by default for unified URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/325732) in 14.6. This may be a breaking change. If needed, you may [disable Geo proxying](../secondary_proxy/index.md#disable-geo-proxying). + ## Upgrading to 14.4 There is [an issue in GitLab 14.4.0 through 14.4.2](../../../update/index.md#1440) that can affect Geo and other features that rely on cronjobs. We recommend upgrading to GitLab 14.4.3 or later. @@ -80,9 +90,9 @@ GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab ## Upgrading to GitLab 14.0/14.1 -### Primary sites can not be removed from the UI +### Primary sites cannot be removed from the UI -We found an issue where [Primary sites can not be removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/338231). +We found an issue where [Primary sites cannot be removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/338231). This bug only exists in the UI and does not block the removal of Primary sites using any other method. diff --git a/doc/administration/geo/secondary_proxy/index.md b/doc/administration/geo/secondary_proxy/index.md index 731b5012663..2786982bb51 100644 --- a/doc/administration/geo/secondary_proxy/index.md +++ b/doc/administration/geo/secondary_proxy/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -147,6 +147,13 @@ for details. - [Viewing projects and designs data from a primary site is not possible when using a unified URL](../index.md#view-replication-data-on-the-primary-site). +- When secondary proxying is used together with separate URLs, registering [GitLab runners](https://docs.gitlab.com/runner/) to clone from +secondary sites is not supported. The runner registration will succeed, but the clone URL will default to the primary site. The runner +[clone URL](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) is configured per GitLab deployment +and cannot be configured per Geo site. Therefore, all runners will clone from the primary site (or configured clone URL) irrespective of +which Geo site they register on. For information about GitLab CI using a specific Geo secondary to clone from, see issue +[3294](https://gitlab.com/gitlab-org/gitlab/-/issues/3294#note_1009488466). + ## Behavior of secondary sites when the primary Geo site is down Considering that web traffic is proxied to the primary, the behavior of the secondary sites differs when the primary 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 1430e99557f..b983230a314 100644 --- a/doc/administration/geo/secondary_proxy/location_aware_external_url.md +++ b/doc/administration/geo/secondary_proxy/location_aware_external_url.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 8a919a0a269..8ea8d6c4d8e 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index b87baa658a1..eabed7c10f3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo with external PostgreSQL instances **(PREMIUM SELF)** @@ -69,14 +69,13 @@ To set up an external database, you can either: Given you have a primary site set up on AWS EC2 that uses RDS. You can now just create a read-only replica in a different region and the -replication process is managed by AWS. Make sure you've set Network ACL (Access Control List), Subnet, and -Security Group according to your needs, so the secondary Rails node(s) can access the database. +replication process is managed by AWS. Make sure you've set Network ACL (Access Control List), Subnet, and Security Group according to your needs, so the secondary Rails nodes can access the database. The following instructions detail how to create a read-only replica for common cloud providers: - Amazon RDS - [Creating a Read Replica](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Create) -- Azure Database for PostgreSQL - [Create and manage read replicas in Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal) +- Azure Database for PostgreSQL - [Create and manage read replicas in Azure Database for PostgreSQL](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal) - Google Cloud SQL - [Creating read replicas](https://cloud.google.com/sql/docs/postgres/replication/create-replica) Once your read-only replica is set up, you can skip to [configure your secondary site](#configure-secondary-site-to-use-the-external-read-replica) @@ -195,7 +194,7 @@ to grant additional roles to your tracking database user (by default, this is `gitlab_geo`): - Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role. -- Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. +- Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. - Google Cloud SQL requires the [`cloudsqlsuperuser`](https://cloud.google.com/sql/docs/postgres/users#default-users) role. This is for the installation of extensions during installation and upgrades. As an alternative, diff --git a/doc/administration/geo/setup/index.md b/doc/administration/geo/setup/index.md index 79b52ef71da..c794b8ef219 100644 --- a/doc/administration/geo/setup/index.md +++ b/doc/administration/geo/setup/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -16,14 +16,14 @@ You must use a [GitLab Premium](https://about.gitlab.com/pricing/) license or hi but you only need one license for all the sites. WARNING: -The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all sites. Do not create an account or log in to the new secondary.** +The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all sites. Do not create an account or sign in to the new secondary.** ## Using Omnibus GitLab If you installed GitLab using the Omnibus packages (highly recommended): 1. Confirm the [requirements for running Geo](../index.md#requirements-for-running-geo) are met. -1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the nodes that serve as the **secondary** site. **Do not create an account or log in** to the new **secondary** site. The **GitLab version must match** across primary and secondary sites. +1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the nodes that serve as the **secondary** site. **Do not create an account or sign in** to the new **secondary** site. The **GitLab version must match** across primary and secondary sites. 1. [Add the GitLab License](../../../user/admin_area/license.md) on the **primary** site to unlock Geo. The license must be for [GitLab Premium](https://about.gitlab.com/pricing/) or higher. 1. [Confirm network connectivity](../index.md#firewall-rules) between the **primary** and **secondary** site. 1. [Set up the database replication](database.md) (`primary (read-write) <-> secondary (read-only)` topology). diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index 44b09ef185a..4099ddc16f8 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -1,5 +1,5 @@ --- -info: For assistance with this TAM Onboarding page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this TAM Onboarding page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. stage: none group: unassigned --- @@ -283,7 +283,7 @@ You can learn more about how to administer GitLab. ### Free GitLab training -- GitLab basics: Discover self-service guides on [Git and GitLab basics](../gitlab-basics/index.md). +- GitLab basics: Discover self-service guides on [Git and GitLab basics](../tutorials/index.md). - GitLab Learn: Learn new GitLab skills in a structured course at [GitLab Learn](https://about.gitlab.com/learn/). ### Third-party training diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 3612487f456..f900c5a6867 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/engineering/ux/technical-writing/#assignments +info: To 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: "Set and configure Git protocol v2" --- @@ -15,7 +15,7 @@ configuration is required by an administrator. More details about the new features and improvements are available in the [Google Open Source Blog](https://opensource.googleblog.com/2018/05/introducing-git-protocol-version-2.html) -and the [protocol documentation](https://github.com/git/git/blob/master/Documentation/technical/protocol-v2.txt). +and the [protocol documentation](https://github.com/git/git/blob/master/Documentation/gitprotocol-v2.txt). ## Requirements diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index bfd252a9f42..e4aef2db9a8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Gitaly **(FREE SELF)** @@ -555,12 +555,15 @@ Additionally, the certificate (or its certificate authority) must be installed o - Gitaly servers. - Gitaly clients that communicate with it. -Note the following: +### 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 To configure Gitaly with TLS: diff --git a/doc/administration/gitaly/faq.md b/doc/administration/gitaly/faq.md deleted file mode 100644 index f6571295200..00000000000 --- a/doc/administration/gitaly/faq.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2022-08-24' ---- - -This document was moved to [another location](index.md). diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index c7f7c4c58a5..96447239116 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly and Gitaly Cluster **(FREE SELF)** diff --git a/doc/administration/gitaly/monitoring.md b/doc/administration/gitaly/monitoring.md index a435fff74fc..9b7acd536b3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring Gitaly and Gitaly Cluster diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index bd03aa1bdbc..e3b198d1012 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure Gitaly Cluster **(FREE SELF)** @@ -1320,7 +1320,7 @@ Deletions are disabled by default due to a race condition with repository rename deletions. This is especially prominent in Geo instances as Geo performs more renames than instances without Geo. You should enable deletions only if the [`gitaly_praefect_generated_replica_paths` feature flag](index.md#praefect-generated-replica-paths-gitlab-150-and-later) is enabled. -By default, the worker does not delete invalid metadata records but simply logs them and outputs Prometheus +By default, the worker does not delete invalid metadata records but logs them and outputs Prometheus metrics for them. You can enable deleting invalid metadata records with: diff --git a/doc/administration/gitaly/recovery.md b/doc/administration/gitaly/recovery.md index 4bbf25d7cdd..b51454aa44e 100644 --- a/doc/administration/gitaly/recovery.md +++ b/doc/administration/gitaly/recovery.md @@ -1,14 +1,15 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Recovery options +# Gitaly Cluster recovery options and tools -Gitaly Cluster can [recover from certain types of failure](recovery.md). +Gitaly Cluster can recover from primary-node failure and unavailable repositories. Gitaly Cluster can perform data +recovery and has Praefect tracking database tools. -## Primary Node Failure +## Primary node failure Gitaly Cluster recovers from a failing primary Gitaly node by promoting a healthy secondary as the new primary. @@ -29,14 +30,12 @@ To minimize data loss in GitLab 13.0 to 14.0, Gitaly Cluster: > - Introduced in GitLab 13.0 as [generally available](../../policy/alpha-beta-support.md#generally-available-ga). > - Between GitLab 13.0 and GitLab 13.2, read-only mode applied to the whole virtual storage and occurred whenever failover occurred. -> - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitaly/-/issues/2862), read-only mode applies on a per-repository basis and only occurs if a new primary is out of date. -new primary. If the failed primary contained unreplicated writes, [data loss can occur](#check-for-data-loss). +> - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitaly/-/issues/2862), read-only mode applies on a per-repository basis and only occurs if a new primary is out of date. If the failed primary contained unreplicated writes, [data loss can occur](#check-for-data-loss). > - Removed in GitLab 14.1. Instead, repositories [become unavailable](#unavailable-repositories). -When Gitaly Cluster switches to a new primary in GitLab 13.0 to 14.0, repositories enter -read-only mode if they are out of date. This can happen after failing over to an outdated -secondary. Read-only mode eases data recovery efforts by preventing writes that may conflict -with the unreplicated writes on other nodes. +When Gitaly Cluster switches to a new primary in GitLab 13.0 to 14.0, repositories enter read-only mode if they are +out-of-date. This can happen after failing over to an outdated secondary. Read-only mode eases data recovery efforts by +preventing writes that may conflict with the unreplicated writes on other nodes. To enable writes again in GitLab 13.0 to 14.0, an administrator can: @@ -46,7 +45,7 @@ To enable writes again in GitLab 13.0 to 14.0, an administrator can: [accept data loss](#enable-writes-or-accept-data-loss) if necessary, depending on the version of GitLab. -## Unavailable repositories +### Unavailable repositories > - From GitLab 13.0 through 14.0, repositories became read-only if they were outdated on the primary but fully up to date on a healthy secondary. `dataloss` sub-command displays read-only repositories by default through these versions. > - Since GitLab 14.1, Praefect contains more responsive failover logic which immediately fails over to one of the fully up to date secondaries rather than placing the repository in read-only mode. Since GitLab 14.1, the `dataloss` sub-command displays repositories which are unavailable due to having no fully up to date copies on healthy Gitaly nodes. @@ -252,7 +251,7 @@ These tools reconcile the outdated repositories to bring them fully up to date a > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/2717) in GitLab 13.4. Praefect automatically reconciles repositories that are not up to date. By default, this is done every -five minutes. For each outdated repository on a healthy Gitaly node, the Praefect picks a +five minutes. For each outdated repository on a healthy Gitaly node, Praefect picks a random, fully up-to-date replica of the repository on another healthy Gitaly node to replicate from. A replication job is scheduled only if there are no other replication jobs pending for the target repository. @@ -296,7 +295,7 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3767) in GitLab 14.3. > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4054) in GitLab 14.6, support for dry-run mode. -> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4715) in GitLab 15.3, support for removing repositories from Praefect's database. +> - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/4715) in GitLab 15.3, support for removing repositories from the Praefect tracking database. The `remove-repository` Praefect sub-command removes a repository from a Gitaly Cluster, and all state associated with a given repository including: @@ -311,9 +310,9 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t - Replace `<virtual-storage>` with the name of the virtual storage containing the repository. - Replace `<repository>` with the relative path of the repository to remove. -- In GitLab 15.3 and later, add `-db-only` to remove the Praefect database entry without removing the on-disk repository. Use this option to remove orphaned database entries and to +- In GitLab 15.3 and later, add `-db-only` to remove the Praefect tracking database entry without removing the on-disk repository. Use this option to remove orphaned database entries and to protect on-disk repository data from deletion when a valid repository is accidentally specified. If the database entry is accidentally deleted, re-track the repository with the - [`track-repository` command](#manually-track-repositories). + [`track-repository` command](#manually-add-a-single-repository-to-the-tracking-database). - In GitLab 14.6 and later, add `-apply` to run the command outside of dry-run mode and remove the repository. For example: ```shell @@ -349,7 +348,11 @@ Parts of the repository can continue to exist after running `remove-repository`. If this occurs, run `remove-repository` again. -### Manually list untracked repositories +## Praefect tracking database maintenance + +Common maintenance tasks on the Praefect tracking database are documented in this section. + +### List untracked repositories > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3926) in GitLab 14.4. > - `older-than` option added in GitLab 15.0. @@ -357,10 +360,14 @@ If this occurs, run `remove-repository` again. The `list-untracked-repositories` Praefect sub-command lists repositories of the Gitaly Cluster that both: - Exist for at least one Gitaly storage. -- Aren't tracked in the Praefect database. +- Aren't tracked in the Praefect tracking database. + +Add the `-older-than` option to avoid showing repositories that: -Add the `-older-than` option to avoid showing repositories that are the process of being created and for which a record doesn't yet exist in the -Praefect database. Replace `<duration>` with a time duration (for example, `5s`, `10m`, or `1h`). Defaults to `6h`. +- Are in the process of being created. +- For which a record doesn't yet exist in the Praefect tracking database. + +Replace `<duration>` with a time duration (for example, `5s`, `10m`, or `1h`). Defaults to `6h`. ```shell sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml list-untracked-repositories -older-than <duration> @@ -382,12 +389,12 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t {"virtual_storage":"default","storage":"gitaly-1","relative_path":"@hashed/ab/cd/abcd123456789012345678901234567890123456789012345678901234567891.git"} ``` -### Manually track repositories +### Manually add a single repository to the tracking database > - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5658) in GitLab 14.4. > - [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5789) in GitLab 14.6, support for immediate replication. -The `track-repository` Praefect sub-command adds repositories on disk to the Praefect database to be tracked. +The `track-repository` Praefect sub-command adds repositories on disk to the Praefect tracking database to be tracked. ```shell sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml track-repository -virtual-storage <virtual-storage> -authoritative-storage <storage-name> -repository <repository> -replicate-immediately @@ -427,15 +434,17 @@ The command outputs: This command fails if: -- The repository is already being tracked by the Praefect database. +- The repository is already being tracked by the Praefect tracking database. - The repository does not exist on disk. -### Manually track large numbers of repositories +### Manually add many repositories to the tracking database > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/6319) in GitLab 15.4. -The `track-repositories` Praefect sub-command adds large batches of on-disk repositories to the Praefect database for tracking. This can -be useful when migrating an existing instance to new infrastructure and ingesting all existing repositories into a fresh Gitaly Cluster. +Migrations using the API automatically add repositories to the Praefect tracking database. + +If you are instead manually copying repositories over from existing infrastructure, you can use the `track-repositories` +Praefect subcommand. This subcommand adds large batches of on-disk repositories to the Praefect tracking database. ```shell # Omnibus GitLab install @@ -449,21 +458,21 @@ The command validates that all entries: - Are formatted correctly and contain required fields. - Correspond to a valid Git repository on disk. -- Are not currently tracked in the Praefect database. +- Are not currently tracked in the Praefect tracking database. If any entry fails these checks, the command aborts prior to attempting to track a repository. - `input-path` is the path to a file containing a list of repositories formatted as newline-delimited JSON objects. Objects must contain the following keys: - - `relative_path`: corresponds with `repository` in [track-repositories](#manually-track-repositories). + - `relative_path`: corresponds with `repository` in [`track-repository`](#manually-add-a-single-repository-to-the-tracking-database). - `authoritative-storage`: the storage Praefect is to treat as the primary. - `virtual-storage`: the virtual storage the repository is located in. - For example: + For example: - ```json - {"relative_path":"@hashed/f5/ca/f5ca38f748a1d6eaf726b8a42fb575c3c71f1864a8143301782de13da2d9202b.git","authoritative_storage":"gitaly-1","virtual_storage":"default"} - {"relative_path":"@hashed/f8/9f/f89f8d0e735a91c5269ab08d72fa27670d000e7561698d6e664e7b603f5c4e40.git","authoritative_storage":"gitaly-2","virtual_storage":"default"} - ``` + ```json + {"relative_path":"@hashed/f5/ca/f5ca38f748a1d6eaf726b8a42fb575c3c71f1864a8143301782de13da2d9202b.git","authoritative_storage":"gitaly-1","virtual_storage":"default"} + {"relative_path":"@hashed/f8/9f/f89f8d0e735a91c5269ab08d72fa27670d000e7561698d6e664e7b603f5c4e40.git","authoritative_storage":"gitaly-2","virtual_storage":"default"} + ``` - `-replicate-immediately`, causes the command to replicate the repository to its secondaries immediately. Otherwise, replication jobs are scheduled for execution in the database and are picked up by a Praefect background process. diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 2542848c7a8..3bf1e3136c0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly reference **(FREE SELF)** diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md index 285ec3d2631..1c5f0d43864 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/engineering/ux/technical-writing/#assignments +info: To 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 Gitaly and Gitaly Cluster **(FREE SELF)** @@ -67,6 +67,13 @@ remote: GitLab: 401 Unauthorized You need to sync your `gitlab-secrets.json` file with your GitLab application nodes. +### 500 and `fetching folder content` errors on repository pages + +`Fetching folder content`, and in some cases `500`, errors indicate +connectivity problems between GitLab and Gitaly. +Consult the [client-side gRPC logs](#client-side-grpc-logs) +for details. + ### Client side gRPC logs Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC @@ -81,6 +88,19 @@ You can run a gRPC trace with: sudo GRPC_TRACE=all GRPC_VERBOSITY=DEBUG gitlab-rake gitlab:gitaly:check ``` +If this command fails with a `failed to connect to all addresses` error, +check for an SSL or TLS problem: + +```shell +/opt/gitlab/embedded/bin/openssl s_client -connect <gitaly-ipaddress>:<port> -verify_return_error +``` + +Check whether `Verify return code` field indicates a +[known Omnibus GitLab configuration problem](https://docs.gitlab.com/omnibus/settings/ssl.html). + +If `openssl` succeeds but `gitlab-rake gitlab:gitaly:check` fails, +check [certificate requirements](configure_gitaly.md#certificate-requirements) for Gitaly. + ### Server side gRPC logs gRPC tracing can also be enabled in Gitaly itself with the `GODEBUG=http2debug` diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index cb0156f8e2d..15287b917e7 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Housekeeping **(FREE SELF)** diff --git a/doc/administration/inactive_project_deletion.md b/doc/administration/inactive_project_deletion.md index 824a444fdd2..88d8e3fc648 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Inactive project deletion **(FREE SELF)** diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 9351a101ee4..4959bacaaa4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incoming email **(FREE SELF)** @@ -775,7 +775,7 @@ mailboxes. To configure GitLab for Microsoft Graph, you will need to register an OAuth2 application in your Azure Active Directory that has the `Mail.ReadWrite` permission for all mailboxes. See the [MailRoom step-by-step guide](https://github.com/tpitale/mail_room/#microsoft-graph-configuration) -and [Microsoft instructions](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) +and [Microsoft instructions](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) for more details. Record the following when you configure your OAuth2 application: @@ -792,7 +792,7 @@ to read/write mail in *all* mailboxes. To mitigate security concerns, we recommend configuring an application access policy which limits the mailbox access for all accounts, as described in -[Microsoft documentation](https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access). +[Microsoft documentation](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access). This example for Omnibus GitLab assumes you're using the following mailbox: `incoming@example.onmicrosoft.com`: @@ -822,7 +822,7 @@ gitlab_rails['incoming_email_inbox_options'] = { } ``` -For Microsoft Cloud for US Government or [other Azure deployments](https://docs.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. +For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. - Example for Microsoft Cloud for US Government: diff --git a/doc/administration/index.md b/doc/administration/index.md index 58284a74bf7..7d684daf5a6 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/engineering/ux/technical-writing/#assignments" +info: "To 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: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- @@ -194,7 +194,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Monitoring GitLab](monitoring/index.md): - [Monitoring uptime](../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. - - [IP allowlist](monitoring/ip_whitelist.md): Monitor endpoints that provide health check information when probed. + - [IP allowlist](monitoring/ip_allowlist.md): Monitor endpoints that provide health check information when probed. - [Monitoring GitHub imports](monitoring/github_imports.md): The GitLab GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer. ### Performance Monitoring diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index 0cf2e3a1131..3f44b53a6d5 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -165,7 +165,7 @@ This setting limits global search requests as follows: | Authenticated user | 30 | | Unauthenticated user | 10 | -Depending on the number of enabled [scopes](../user/search/advanced_search.md#global-search-scopes), a global search request can consume two to seven requests per minute. You may want to disable one or more scopes to use fewer requests. Global search requests that exceed the search rate limit per minute return the following error: +Depending on the number of enabled [scopes](../user/search/index.md#global-search-scopes), a global search request can consume two to seven requests per minute. You may want to disable one or more scopes to use fewer requests. Global search requests that exceed the search rate limit per minute return the following error: ```plaintext This endpoint has been requested too many times. Try again later. @@ -289,6 +289,29 @@ For GitLab.com, see the [webhook limits for GitLab.com](../user/gitlab_com/index The maximum webhook payload size is 25 MB. +### Webhook timeout + +The number of seconds GitLab waits for an HTTP response after sending a webhook. + +To change the webhook timeout value: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['webhook_timeout'] = 60 + ``` + +1. Save the file. +1. Reconfigure and restart GitLab for the changes to + take effect: + + ```shell + gitlab-ctl reconfigure + gitlab-ctl restart + ``` + +See also [webhook limits for GitLab.com](../user/gitlab_com/index.md#other-limits). + ### Recursive webhooks > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8. diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index d9126036a16..5516a47637d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance review **(FREE SELF)** diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index fb4659175b0..aa029be90e7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Kroki diagrams **(FREE SELF)** @@ -54,7 +54,7 @@ read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images ## Enable Kroki in GitLab You need to enable Kroki integration from Settings under Admin Area. -To do that, log in with an administrator account and follow these steps: +To do that, sign in with an administrator account and follow these steps: 1. On the top bar, select **Main menu > Admin**. 1. Go to **Settings > General**. diff --git a/doc/administration/integration/mailgun.md b/doc/administration/integration/mailgun.md index 37e81f220cf..baf9e8c8a3b 100644 --- a/doc/administration/integration/mailgun.md +++ b/doc/administration/integration/mailgun.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -45,7 +45,7 @@ you're ready to enable the Mailgun integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. 1. On the top bar, select **Main menu >** **{admin}** **Admin**. 1. On the left sidebar, go to **Settings > General** and expand the **Mailgun** section. -1. Select the **Enable Mailgun** check box. +1. Select the **Enable Mailgun** checkbox. 1. Enter the Mailgun HTTP webhook signing key as described in [the Mailgun documentation](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks-1) and shown in the [API security](https://app.mailgun.com/app/account/security/api_keys) section for your Mailgun account. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index de790c7ce40..f0b3e949b35 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 41984bbe7a7..14da70f6efb 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web terminals (DEPRECATED) **(FREE)** diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md index 20a77691bbc..366cbea5711 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 31e9944d9a4..d10f5320109 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 14749a9c7f6..1e9f20ded55 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs artifacts administration **(FREE SELF)** @@ -233,8 +233,6 @@ by the `gitlab:artifacts:migrate` Rake task. To migrate back to local storage: -1. Set both `direct_upload` and `background_upload` to `false` in `gitlab.rb`, under the artifacts object storage settings. -1. [Reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Run `gitlab-rake gitlab:artifacts:migrate_to_local`. 1. Disable object_storage for artifacts in `gitlab.rb`: - Set `gitlab_rails['artifacts_object_store_enabled'] = false`. diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index 84da4e31d92..5aa0e8f3948 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index 2fcf7d2f276..1b01c665ab8 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/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.html' --- @@ -220,7 +220,6 @@ end To migrate back to local storage: -1. Set both `direct_upload` and `background_upload` to `false` under the LFS object storage settings. Don't forget to restart GitLab. 1. Run `rake gitlab:lfs:migrate_to_local` on your console. 1. Disable `object_storage` for LFS objects in `gitlab.rb`. Remember to restart GitLab afterwards. diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md index 88a46759924..5b2334bff8a 100644 --- a/doc/administration/libravatar.md +++ b/doc/administration/libravatar.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/load_balancer.md b/doc/administration/load_balancer.md index 87b63c6272d..ad89d32183b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 d3529de08db..2bcda759442 100644 --- a/doc/administration/logs/index.md +++ b/doc/administration/logs/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Log system **(FREE SELF)** diff --git a/doc/administration/logs/log_parsing.md b/doc/administration/logs/log_parsing.md index 20b439af49b..dfe434ed1f2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Parsing GitLab logs with `jq` **(FREE SELF)** diff --git a/doc/administration/logs/tracing_correlation_id.md b/doc/administration/logs/tracing_correlation_id.md index 1d3e4955d3a..f651455a088 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Find relevant log entries with a correlation ID **(FREE SELF)** @@ -28,7 +28,7 @@ documentation for some popular browsers. - [Network Monitor - Firefox Developer Tools](https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor) - [Inspect Network Activity In Chrome DevTools](https://developer.chrome.com/docs/devtools/network/) - [Safari Web Development Tools](https://developer.apple.com/safari/tools/) -- [Microsoft Edge Network panel](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/) +- [Microsoft Edge Network panel](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/) To locate a relevant request and view its correlation ID: @@ -187,7 +187,7 @@ You can then view the database details for this request:  -1. A new request is inserted into the `Request Selector` dropdown on the right-hand side of the Performance Bar. Select the new request to view the metrics of the API request: +1. A new request is inserted into the `Request Selector` dropdown list on the right-hand side of the Performance Bar. Select the new request to view the metrics of the API request:  diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md index 60de8e2fd3a..12f3c4c1cc3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Maintenance Mode **(PREMIUM SELF)** @@ -82,7 +82,7 @@ them to disable Maintenance Mode after it's been enabled. ### Authentication -All users can log in and out of the GitLab instance but no new users can be created. +All users can sign in and out of the GitLab instance but no new users can be created. If there are [LDAP syncs](../auth/ldap/index.md) scheduled for that time, they fail since user creation is disabled. Similarly, [user creations based on SAML](../../integration/saml.md#general-setup) fail. @@ -113,9 +113,9 @@ For most JSON requests, `POST`, `PUT`, `PATCH`, and `DELETE` are blocked, and th |:----:|:--------------------------------------:|:----:| | `POST` | `/admin/application_settings/general` | To allow updating application settings in the administrator UI | | `PUT` | `/api/v4/application/settings` | To allow updating application settings with the API | -| `POST` | `/users/sign_in` | To allow users to log in. | -| `POST` | `/users/sign_out`| To allow users to log out. | -| `POST` | `/oauth/token` | To allow users to log in to a Geo secondary for the first time. | +| `POST` | `/users/sign_in` | To allow users to sign in. | +| `POST` | `/users/sign_out`| To allow users to sign out. | +| `POST` | `/oauth/token` | To allow users to sign in to a Geo secondary for the first time. | | `POST` | `/admin/session`, `/admin/session/destroy` | To allow [Admin Mode for GitLab administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158) | | `POST` | Paths ending with `/compare`| Git revision routes. | | `POST` | `.git/git-upload-pack` | To allow Git pull/clone. | diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index fe1c74b0e24..4dec9e52c19 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request diffs storage **(FREE SELF)** @@ -271,3 +271,11 @@ By default, `sudo` does not preserve existing environment variables. You should ```shell sudo gitlab-rake gitlab:external_diffs:force_object_storage START_ID=59946109 END_ID=59946109 UPDATE_DELAY=5 ``` + +## Switching from external storage to object storage + +Automatic migration moves diffs stored in the database, but it does not move diffs between storage types. +To switch from external storage to object storage: + +1. Move files stored on local or NFS storage to object storage manually. +1. Run the Rake task in the [previous section](#correcting-incorrectly-migrated-diffs) to change their location in the database. diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md index e16e9bb0336..097109585af 100644 --- a/doc/administration/monitoring/github_imports.md +++ b/doc/administration/monitoring/github_imports.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitHub imports **(FREE SELF)** diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index 4b62a8ae931..ad864255f02 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Self-monitoring project (DEPRECATED) **(FREE SELF)** diff --git a/doc/administration/monitoring/index.md b/doc/administration/monitoring/index.md index 82a6da1d56a..e57156e6513 100644 --- a/doc/administration/monitoring/index.md +++ b/doc/administration/monitoring/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitLab **(FREE SELF)** @@ -20,7 +20,7 @@ Explore our features to monitor your GitLab instance: importer with various Prometheus metrics. - [Monitoring uptime](../../user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. - - [IP allowlists](ip_whitelist.md): Configure GitLab for monitoring endpoints that + - [IP allowlists](ip_allowlist.md): Configure GitLab for monitoring endpoints that provide health check information when probed. - [`nginx_status`](https://docs.gitlab.com/omnibus/settings/nginx.html#enablingdisabling-nginx_status): Monitor your NGINX server status. diff --git a/doc/administration/monitoring/ip_allowlist.md b/doc/administration/monitoring/ip_allowlist.md index 3151b696182..400c70d0fde 100644 --- a/doc/administration/monitoring/ip_allowlist.md +++ b/doc/administration/monitoring/ip_allowlist.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Application Performance -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # IP whitelist **(FREE SELF)** @@ -15,7 +15,7 @@ that provide health check information when probed. To control access to those endpoints via IP whitelisting, you can add single hosts or use IP ranges: -**For Omnibus installations** +**Omnibus** 1. Open `/etc/gitlab/gitlab.rb` and add or uncomment the following: @@ -27,7 +27,7 @@ hosts or use IP ranges: --- -**For installations using cloud native Helm charts** +**Helm chart** You can set the required IPs under the `gitlab.webservice.monitoring.ipWhitelist` key. For example: @@ -42,7 +42,7 @@ gitlab: --- -**For installations from source** +**Source** 1. Edit `config/gitlab.yml`: diff --git a/doc/administration/monitoring/ip_whitelist.md b/doc/administration/monitoring/ip_whitelist.md deleted file mode 100644 index 9fb4ffe3089..00000000000 --- a/doc/administration/monitoring/ip_whitelist.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'ip_allowlist.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](ip_allowlist.md). - -<!-- This redirect file can be deleted after <2022-08-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 (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/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index 74db35eebc2..cb5852a7dac 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Configuration **(FREE SELF)** diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 6e9ea0d8d42..a003a3f25bc 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Grafana Configuration **(FREE SELF)** @@ -81,7 +81,7 @@ GitLab displays your link in the **Main menu > Admin > Monitoring > Metrics Dash When setting up Grafana through the process above, no scope shows in the screen at **Main menu > Admin > Applications > GitLab Grafana**. However, the `read_user` scope is required and is provided to the application automatically. Setting any scope other than -`read_user` without also including `read_user` leads to this error when you try to log in using +`read_user` without also including `read_user` leads to this error when you try to sign in using GitLab as the OAuth provider: ```plaintext diff --git a/doc/administration/monitoring/performance/index.md b/doc/administration/monitoring/performance/index.md index b063a20dc7f..0bea0836191 100644 --- a/doc/administration/monitoring/performance/index.md +++ b/doc/administration/monitoring/performance/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Performance Monitoring **(FREE SELF)** diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index c23046158e1..de6178a3151 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performance bar **(FREE SELF)** diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md deleted file mode 100644 index d0d05c16ea0..00000000000 --- a/doc/administration/monitoring/performance/request_profiling.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-07-26' -redirect_to: 'index.md' ---- - -# Request profiling (removed) **(FREE SELF)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/352488) in GitLab 14.8 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/350152) in 15.0. diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 15ec880533e..bce35306505 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 00dae8e4dd5..e8bdacb0e14 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Prometheus metrics **(FREE SELF)** @@ -11,7 +11,7 @@ To enable the GitLab Prometheus metrics: 1. Log in to GitLab as a user with administrator access. 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. -1. Find the **Metrics - Prometheus** section, and select **Add link to Prometheus**. +1. Find the **Metrics - Prometheus** section, and select **Enable GitLab Prometheus metrics endpoint**. 1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect. For installations from source you must configure it yourself. @@ -20,7 +20,7 @@ For installations from source you must configure it yourself. GitLab monitors its own internal service metrics, and makes them available at the `/-/metrics` endpoint. Unlike other [Prometheus](https://prometheus.io) exporters, to access -the metrics, the client IP address must be [explicitly allowed](../ip_whitelist.md). +the metrics, the client IP address must be [explicitly allowed](../ip_allowlist.md). These metrics are enabled and collected for [Omnibus GitLab](https://docs.gitlab.com/omnibus/) and Chart installations. For source installations, these metrics must be enabled @@ -302,6 +302,10 @@ configuration option in `gitlab.yml`. These metrics are served from the | `geo_uploads_verification_total` | Gauge | 14.6 | Number of uploads verifications tried on secondary | `url` | | `geo_uploads_verified` | Gauge | 14.6 | Number of uploads verified on secondary | `url` | | `geo_uploads_verification_failed` | Gauge | 14.6 | Number of uploads verifications failed on secondary | `url` | +| `geo_container_repositories` | Gauge | 15.4 | Number of container repositories on primary | `url` | +| `geo_container_repositories_synced` | Gauge | 15.4 | Number of container repositories synced on secondary | `url` | +| `geo_container_repositories_failed` | Gauge | 15.4 | Number of syncable container repositories failed to sync on secondary | `url` | +| `geo_container_repositories_registry` | Gauge | 15.4 | Number of container repositories in the registry | `url` | | `gitlab_sli:rails_request_apdex:total` | Counter | 14.4 | The number of request-apdex measurements, [more information the development documentation](../../../development/application_slis/rails_request_apdex.md) | `endpoint_id`, `feature_category`, `request_urgency` | | `gitlab_sli:rails_request_apdex:success_total` | Counter | 14.4 | The number of successful requests that met the target duration for their urgency. Divide by `gitlab_sli:rails_requests_apdex:total` to get a success ratio | `endpoint_id`, `feature_category`, `request_urgency` | | `geo_ci_secure_files` | Gauge | 15.3 | Number of secure files on primary | `url` | diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index c4aa607fa4d..56583deca89 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GitLab with Prometheus **(FREE SELF)** @@ -205,7 +205,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. Add the Prometheus server IP address to the [monitoring IP allowlist](../ip_whitelist.md). For example: +1. Add the Prometheus server IP address to the [monitoring IP allowlist](../ip_allowlist.md). For example: ```ruby gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '192.168.0.1'] @@ -353,7 +353,7 @@ To add a Prometheus dashboard for a single server GitLab setup: 1. Create a new data source in Grafana. 1. Name your data source (such as GitLab). -1. Select `Prometheus` in the type dropdown box. +1. Select `Prometheus` in the type dropdown list. 1. Add your Prometheus listen address as the URL, and set access to `Browser`. 1. Set the HTTP method to `GET`. 1. Save and test your configuration to verify that it works. @@ -381,7 +381,7 @@ memory, disk, and CPU utilization. The web exporter is a dedicated metrics server that allows splitting end-user and Prometheus traffic into two separate applications to improve performance and availability. -[Read more about the web exporter](puma_exporter.md). +[Read more about the web exporter](web_exporter.md). ### Redis exporter diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index d7a4a96cd9a..c2f84773b3a 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 979a6bcd232..56da3155fd9 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 95a6540bd19..0458a4a5bae 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL Server Exporter **(FREE SELF)** diff --git a/doc/administration/monitoring/prometheus/puma_exporter.md b/doc/administration/monitoring/prometheus/puma_exporter.md deleted file mode 100644 index a3e095f5f09..00000000000 --- a/doc/administration/monitoring/prometheus/puma_exporter.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'web_exporter.md' -remove_date: '2022-09-01' ---- - -This document was moved to [another location](web_exporter.md). - -<!-- This redirect file can be deleted after <2022-09-01>. --> -<!-- 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/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index a5f12bbc52f..b50a2a4aebf 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 f4fa35c206e..b79e97bd937 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 45a8e8d5640..5539526c501 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: Application Performance -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 9967cce5b73..9072bd1f344 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index fd9ab9b5972..0e85635b3d2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Object storage **(FREE SELF)** @@ -20,7 +20,7 @@ GitLab has been tested by vendors and customers on a number of object storage pr - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatible mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) +- [Azure Blob storage](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - On-premises hardware and appliances from various storage vendors, whose list is not officially established. - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. @@ -247,9 +247,9 @@ The connection settings match those provided by [fog-aws](https://github.com/fog | `aws_signature_version` | AWS signature version to use. `2` or `4` are valid options. Digital Ocean Spaces and other providers may need `2`. | `4` | | `enable_signature_v4_streaming` | Set to `true` to enable HTTP chunked transfers with [AWS v4 signatures](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-streaming.html). Oracle Cloud S3 needs this to be `false`. | `true` | | `region` | AWS region. | | -| `host` | S3 compatible host for when not using AWS. For example, `localhost` or `storage.example.com`. HTTPS and port 443 is assumed. | `s3.amazonaws.com` | -| `endpoint` | Can be used when configuring an S3 compatible service such as [MinIO](https://min.io), by entering a URL such as `http://127.0.0.1:9000`. This takes precedence over `host`. | (optional) | -| `path_style` | Set to `true` to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as `false` for AWS S3. | `false`. | +| `host` | DEPRECATED: Use `endpoint` instead. S3 compatible host for when not using AWS. For example, `localhost` or `storage.example.com`. HTTPS and port 443 is assumed. | `s3.amazonaws.com` | +| `endpoint` | Can be used when configuring an S3 compatible service such as [MinIO](https://min.io), by entering a URL such as `http://127.0.0.1:9000`. This takes precedence over `host`. Always use `endpoint` for consolidated form. | (optional) | +| `path_style` | Set to `true` to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Set to `true` for using [MinIO](https://min.io). Leave as `false` for AWS S3. | `false`. | | `use_iam_profile` | Set to `true` to use IAM profile instead of access keys. | `false` | | `aws_credentials_refresh_threshold_seconds` | Sets the [automatic refresh threshold](https://github.com/fog/fog-aws#controlling-credential-refresh-time-with-iam-authentication) when using temporary credentials in IAM. | `15` | @@ -277,10 +277,13 @@ Here are the valid connection parameters for GCS: |------------------------------|-------------------|---------| | `provider` | Provider name. | `Google` | | `google_project` | GCP project name. | `gcp-project-12345` | -| `google_client_email` | Email address of the service account. | `foo@gcp-project-12345.iam.gserviceaccount.com` | | `google_json_key_location` | JSON key path. | `/path/to/gcp-project-12345-abcde.json` | +| `google_json_key_string` | JSON key string. | `{ "type": "service_account", "project_id": "example-project-382839", ... }` | | `google_application_default` | Set to `true` to use [Google Cloud Application Default Credentials](https://cloud.google.com/docs/authentication/production#automatically) to locate service account credentials. | | +GitLab reads the value of `google_json_key_location`, then `google_json_key_string`, and finally, `google_application_default`. +It uses the first of these settings that has a value. + The service account must have permission to access the bucket. Learn more in Google's [Cloud Storage authentication documentation](https://cloud.google.com/storage/docs/authentication). @@ -296,7 +299,6 @@ For Omnibus installations, this is an example of the `connection` setting: gitlab_rails['object_store']['connection'] = { 'provider' => 'Google', 'google_project' => '<GOOGLE PROJECT>', - 'google_client_email' => '<GOOGLE CLIENT EMAIL>', 'google_json_key_location' => '<FILENAME>' } ``` @@ -342,7 +344,7 @@ containers. The [storage-specific form](#storage-specific-configuration) is not supported. For more details, see [how to transition to consolidated form](#transition-to-consolidated-form). The following are the valid connection parameters for Azure. Read the -[Azure Blob storage documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) +[Azure Blob storage documentation](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) to learn more. | Setting | Description | Example | diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 8523b881730..7aeb05457c0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Fast lookup of authorized SSH keys in the database **(FREE SELF)** @@ -157,7 +157,7 @@ The capabilities of GitLab Shell are not limited to Git operations. If you are considering switching from OpenSSH to `gitlab-sshd`, consider these concerns: - The `gitlab-sshd` component is only available for - [Cloud Native Helm Charts](https://docs.gitlab.com/charts/) deployments. + [GitLab Helm chart](https://docs.gitlab.com/charts/) deployments. - `gitlab-sshd` supports the PROXY protocol. It can run behind proxy servers that rely on it, such as HAProxy. The PROXY protocol not enabled by default, but can be enabled with a Helm chart setting. - By default, `gitlab-sshd` binds to port 22, but you can configure a different port in the Helm chart. diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md index a5c4795efea..ec2975baf52 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File system performance benchmarking **(FREE SELF)** diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index 179958c6df1..d18f41becd5 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performing operations in GitLab **(FREE SELF)** diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 4228b792fdc..75078568c44 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 8e7594dfc2d..eb326c06e6a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the bundled Puma instance of the GitLab package **(FREE SELF)** @@ -401,4 +401,4 @@ The output in `/tmp/puma.txt` may help diagnose the root cause. ## Related topics -- [Use a dedicated metrics server to export web metrics](../monitoring/prometheus/puma_exporter.md) +- [Use a dedicated metrics server to export web metrics](../monitoring/prometheus/web_exporter.md) diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index 627dfbeb66c..1ef985b8938 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rails console **(FREE SELF)** @@ -240,6 +240,24 @@ project.id # => 2537 ``` +## Time an operation + +If you'd like to time one or more operations, use the following format, replacing +the placeholder `<operation>` with your Ruby or Rails commands of choice: + +```ruby +# A single operation +Benchmark.measure { <operation> } + +# A breakdown of multiple operations +Benchmark.bm do |x| + x.report(:label1) { <operation_1> } + x.report(:label2) { <operation_2> } +end +``` + +For more information, review [our developer documentation about benchmarks](../../development/performance.md#benchmarks). + ## Active Record objects ### Looking up database-persisted objects @@ -680,3 +698,21 @@ unlike with issues or merge requests. ```ruby ApplicationSetting.current ``` + +### Open object in `irb` + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +Sometimes it is easier to go through a method if you are in the context of the object. You can shim into the namespace of `Object` to let you open `irb` in the context of any object: + +```ruby +Object.define_method(:irb) { binding.irb } + +project = Project.last +# => #<Project id:2537 root/discard>> +project.irb +# Notice new context +irb(#<Project>)> web_url +# => "https://gitlab-example/root/discard" +``` diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index 8069dad4d8d..401451d58b4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User lookup via OpenSSH's AuthorizedPrincipalsCommand **(FREE SELF)** @@ -74,7 +74,7 @@ $ ssh-add -L | grep cert | ssh-keygen -L -f - ``` Technically that's not strictly true, for example, it could be -`prod-aearnfjord` if it's a SSH certificate you'd normally log in to +`prod-aearnfjord` if it's a SSH certificate you'd normally sign in to servers as the `prod-aearnfjord` user, but then you must specify your own `AuthorizedPrincipalsCommand` to do that mapping instead of using our provided default. @@ -108,7 +108,7 @@ Where `{KEY_ID}` is the `%i` argument passed to the script You need to customize the `sshUsers` part of that. It should be some principal that's guaranteed to be part of the key for all users -who can log in to GitLab, or you must provide a list of principals, +who can sign in to GitLab, or you must provide a list of principals, one of which is present for the user, for example: ```plaintext @@ -123,7 +123,7 @@ into multiple lines of `authorized_keys` output, as described in the `AuthorizedPrincipalsFile` documentation in `sshd_config(5)`. Normally when using the `AuthorizedKeysCommand` with OpenSSH the -principal is some "group" that's allowed to log into that +principal is some "group" that's allowed to sign in to that server. However with GitLab it's only used to appease OpenSSH's requirement for it, we effectively only care about the "key ID" being correct. Once that's extracted GitLab enforces its own ACLs for diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md index 65cb8ef1e6c..c6a33ed7ba9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 73059514e1c..d8f4551ca09 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Omnibus GitLab deprecation policy **(FREE SELF)** diff --git a/doc/administration/package_information/index.md b/doc/administration/package_information/index.md index d3a82b87116..4758b453135 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package information **(FREE SELF)** @@ -53,7 +53,7 @@ Documentation on package signatures can be found at [Signed Packages](signed_pac Configuration file in `/etc/gitlab/gitlab.rb` is created on initial installation of the Omnibus GitLab package. On subsequent package upgrades, the configuration -file is not updated with new configuration. This is done in order to avoid +file is not updated with new configuration. This is done to avoid accidental overwrite of user configuration provided in `/etc/gitlab/gitlab.rb`. New configuration options are noted in the @@ -76,7 +76,7 @@ characters on each line. ## Init system detection -Omnibus GitLab attempts to query the underlying system in order to +Omnibus GitLab attempts to query the underlying system to check which init system it uses. This manifests itself as a `WARNING` during the `sudo gitlab-ctl reconfigure` run. diff --git a/doc/administration/package_information/licensing.md b/doc/administration/package_information/licensing.md index e5afe6b85dd..0e46289a308 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 d19f5f67b74..ec406f8b458 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Omnibus based packages and images **(FREE SELF)** diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md index d831e8cea7f..6409c5fdbc9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL versions shipped with Omnibus GitLab **(FREE SELF)** diff --git a/doc/administration/package_information/signed_packages.md b/doc/administration/package_information/signed_packages.md index 351c2ac5d5f..34c8148e807 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 5ccabd66ed0..00f1bc1eec3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Supported operating systems **(FREE SELF)** @@ -31,6 +31,7 @@ The following lists the currently supported OSs and their possible EOL dates. | Ubuntu 20.04 | GitLab CE / GitLab EE 13.2.0 | amd64, arm64 | [Ubuntu Install Documentation](https://about.gitlab.com/install/#ubuntu) | April 2025 | <https://wiki.ubuntu.com/Releases> | | Amazon Linux 2 | GitLab CE / GitLab EE 14.9.0 | amd64, arm64 | [Amazon Linux 2 Install Documentation](https://about.gitlab.com/install/#amazonlinux-2) | June 2023 | <https://aws.amazon.com/amazon-linux-2/faqs/> | | Raspberry Pi OS (Buster) (formerly known as Raspbian Buster) | GitLab CE 12.2.0 | armhf | [Raspberry Pi Install Documentation](https://about.gitlab.com/install/#raspberry-pi-os) | 2024 | [Raspberry Pi Details](https://www.raspberrypi.com/news/new-old-functionality-with-raspberry-pi-os-legacy/) | +| Raspberry Pi OS (Bullseye) | GitLab CE 15.5.0 | armhf | [Raspberry Pi Install Documentation](https://about.gitlab.com/install/#raspberry-pi-os) | 2026 | [Raspberry Pi Details](https://www.raspberrypi.com/news/raspberry-pi-os-debian-bullseye/) | NOTE: CentOS 8 was EOL on December 31, 2021. In GitLab 14.5 and later, diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 537840ce785..d04e3217f57 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Container Registry administration **(FREE SELF)** @@ -40,7 +40,9 @@ if you want to implement this. If you have installed GitLab from source: -1. You must [install Registry](https://docs.docker.com/registry/deploying/) by yourself. +1. You must [deploy a registry](https://docs.docker.com/registry/deploying/) using the image corresponding to the + version of GitLab you are installing + (for example: `registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v3.15.0-gitlab`) 1. After the installation is complete, to enable it, you must configure the Registry's settings in `gitlab.yml`. 1. Use the sample NGINX configuration file from under @@ -158,7 +160,7 @@ If your certificate provider provides the CA Bundle certificates, append them to An administrator may want the container registry listening on an arbitrary port such as `5678`. However, the registry and application server are behind an AWS application load balancer that only -listens on ports `80` and `443`. The administrator may simply remove the port number for +listens on ports `80` and `443`. The administrator may remove the port number for `registry_external_url`, so HTTP or HTTPS is assumed. Then, the rules apply that map the load balancer to the registry from ports `80` or `443` to the arbitrary port. This is important if users rely on the `docker login` example in the container registry. Here's an example: @@ -882,10 +884,41 @@ point to the correct registry URL and copy the `registry.key` file to each Sidek information, see the [Sidekiq configuration](../sidekiq.md) page. -To reduce the amount of [Container Registry disk space used by a given project](../troubleshooting/gitlab_rails_cheat_sheet.md#registry-disk-space-usage-by-project), +To reduce the amount of [Container Registry disk space used by a given project](#registry-disk-space-usage-by-project), administrators can clean up image tags and [run garbage collection](#container-registry-garbage-collection). +### Registry Disk Space Usage by Project + +To find the disk space used by each project, run the following in the +[GitLab Rails console](../operations/rails_console.md#starting-a-rails-console-session): + +```ruby +projects_and_size = [["project_id", "creator_id", "registry_size_bytes", "project path"]] +# You need to specify the projects that you want to look through. You can get these in any manner. +projects = Project.last(100) + +projects.each do |p| + project_total_size = 0 + container_repositories = p.container_repositories + + container_repositories.each do |c| + c.tags.each do |t| + project_total_size = project_total_size + t.total_size unless t.total_size.nil? + end + end + + if project_total_size > 0 + projects_and_size << [p.project_id, p.creator.id, project_total_size, p.full_path] + end +end + +# print it as comma separated output +projects_and_size.each do |ps| + puts "%s,%s,%s,%s" % ps +end +``` + To remove image tags by running the cleanup policy, run the following commands in the [GitLab Rails console](../operations/rails_console.md): @@ -935,7 +968,7 @@ provided by `gitlab-ctl`. Prerequisites: - You must have installed GitLab by using an Omnibus package or the - [cloud native chart](https://docs.gitlab.com/charts/charts/registry/#garbage-collection). + [GitLab Helm chart](https://docs.gitlab.com/charts/charts/registry/#garbage-collection). - You must set the Registry to [read-only mode](#performing-garbage-collection-without-downtime). Running garbage collection causes downtime for the Container Registry. When you run this command on an instance in an environment where another instance is still writing to the Registry storage, @@ -1192,7 +1225,7 @@ and signed with the private key. The Registry then verifies that the signature matches the registry certificate specified in its configuration and allows the operation. GitLab background jobs processing (through Sidekiq) also interacts with Registry. -These jobs talk directly to Registry in order to handle image deletion. +These jobs talk directly to Registry to handle image deletion. ## Troubleshooting @@ -1292,8 +1325,8 @@ Check which files are in use: The output of these `openssl` commands should match, proving that the cert-key pair is a match: ```shell -openssl x509 -noout -modulus -in /var/opt/gitlab/registry/gitlab-registry.crt | openssl sha256 -openssl rsa -noout -modulus -in /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key | openssl sha256 +/opt/gitlab/embedded/bin/openssl x509 -noout -modulus -in /var/opt/gitlab/registry/gitlab-registry.crt | /opt/gitlab/embedded/bin/openssl sha256 +/opt/gitlab/embedded/bin/openssl rsa -noout -modulus -in /var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key | /opt/gitlab/embedded/bin/openssl sha256 ``` If the two pieces of the certificate do not align, remove the files and run `gitlab-ctl reconfigure` diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index 40c1b9d795a..789863e8ed0 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Dependency Proxy administration **(FREE SELF)** diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 56786f334b0..a7ab0fb3246 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Package Registry administration **(FREE SELF)** diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 024fb12a51f..922f9a27aad 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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: 'Learn how to administer GitLab Pages.' --- @@ -243,7 +243,6 @@ control over how the Pages daemon runs and serves content in your environment. | `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), this URL must point to the main GitLab server's API. | | `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`. | | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. | -| `client_cert_key_pairs` | Client certificates and keys used for mutual TLS with the GitLab API. See [Support mutual TLS when calling the GitLab API](#support-mutual-tls-when-calling-the-gitlab-api) for details. [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) in GitLab 14.8. | | `dir` | Working directory for configuration and secrets files. | | `enable` | Enable or disable GitLab Pages on the current system. | | `external_http` | Configure Pages to bind to one or more secondary IP addresses, serving HTTP requests. Multiple addresses can be given as an array, along with exact ports, for example `['1.2.3.4', '1.2.3.5:8063']`. Sets value for `listen_http`. | @@ -525,22 +524,6 @@ Authority (CA) in the system certificate store. For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -### Support mutual TLS when calling the GitLab API - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) in GitLab 14.8. - -If GitLab has been [configured to require mutual TLS](https://docs.gitlab.com/omnibus/settings/ssl.html#enable-2-way-ssl-client-authentication), you need to add the client certificates to Pages: - -1. Configure in `/etc/gitlab/gitlab.rb`: - - ```ruby - gitlab_pages['client_cert_key_pairs'] = ['</path/to/cert>:</path/to/key>'] - ``` - - Where `</path/to/cert>` and `</path/to/key>` are the file paths to the client certificate and its respective key file. - Both of these files must be encoded in PEM format. -1. To configure Pages to validate the server certificates, [add the root CA to the system trust store](#using-a-custom-certificate-authority-ca). - ### ZIP serving and cache configuration > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/392) in GitLab 13.7. @@ -754,7 +737,7 @@ To set the maximum number of GitLab Pages custom domains for a project: ## Running GitLab Pages on a separate server You can run the GitLab Pages daemon on a separate server to decrease the load on -your main application server. +your main application server. This configuration does not support mutual TLS (mTLS). See the [corresponding feature proposal](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/548) for more information. To configure GitLab Pages on a separate server: diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 14ac05e0293..52556809845 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages administration for source installations **(FREE SELF)** diff --git a/doc/administration/polling.md b/doc/administration/polling.md index 7f1e7a047cf..11f26f081cb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Polling interval multiplier **(FREE SELF)** diff --git a/doc/administration/postgresql/database_load_balancing.md b/doc/administration/postgresql/database_load_balancing.md index f53b50192eb..6bf36ef4794 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 7036502e377..8605ee94255 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure GitLab using an external PostgreSQL service **(FREE SELF)** @@ -21,7 +21,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL instance: 1. If you are using a cloud-managed service, you may need to grant additional roles to your `gitlab` user: - Amazon RDS requires the [`rds_superuser`](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.html#Appendix.PostgreSQL.CommonDBATasks.Roles) role. - - Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. Azure Database for PostgreSQL - Flexible Server requires [allow-listing extensions before they can be installed](https://docs.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions). + - Azure Database for PostgreSQL requires the [`azure_pg_admin`](https://learn.microsoft.com/en-us/azure/postgresql/single-server/how-to-create-users#how-to-create-additional-admin-users-in-azure-database-for-postgresql) role. Azure Database for PostgreSQL - Flexible Server requires [allow-listing extensions before they can be installed](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions). - Google Cloud SQL requires the [`cloudsqlsuperuser`](https://cloud.google.com/sql/docs/postgres/users#default-users) role. This is for the installation of extensions during installation and upgrades. As an alternative, diff --git a/doc/administration/postgresql/index.md b/doc/administration/postgresql/index.md index 8b811deee16..f48e537064a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 23d377dba37..96076205281 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Moving GitLab databases to a different PostgreSQL instance **(FREE SELF)** diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index b12edd4b9ad..91c689fadea 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 37471a4f491..0ee48047944 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL replication and failover with Omnibus GitLab **(PREMIUM SELF)** @@ -1123,7 +1123,7 @@ postgresql['trust_auth_cidr_addresses'] = %w(123.123.123.123/32 <other_cidrs>) ### Reinitialize a replica -If a replica cannot start or rejoin the cluster, or when it lags behind and can not catch up, it might be necessary to reinitialize the 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: 1. [Check the replication status](#check-replication-status) to confirm which server needs to be reinitialized. For example: diff --git a/doc/administration/postgresql/standalone.md b/doc/administration/postgresql/standalone.md index 5428e44ccc0..77ff9fd2fe1 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Standalone PostgreSQL using Omnibus GitLab **(FREE SELF)** diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md deleted file mode 100644 index 8f27d41b75f..00000000000 --- a/doc/administration/pseudonymizer.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -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/engineering/ux/technical-writing/#assignments -remove_date: '2022-08-22' -redirect_to: 'index.md' ---- - -# Pseudonymizer (removed) **(ULTIMATE)** - -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/219952) in GitLab 14.7 and removed in 15.0. - -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/219952) in GitLab 14.7. diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index cf569cd81d0..2660caa80b3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 5c6c99d099b..a4d027101dd 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo Rake Tasks **(PREMIUM SELF)** diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 0d724bfd4dc..224ed63d3e6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitHub import **(FREE SELF)** diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index cdad323733d..f6c5f84c500 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 c4401b49180..293efb1b7ae 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maintenance Rake tasks **(FREE SELF)** @@ -310,6 +310,12 @@ To check the status of specific migrations, you can use the following Rake task: sudo gitlab-rake db:migrate:status ``` +To check the [tracking database on a Geo secondary site](../geo/setup/external_database.md#configure-the-tracking-database), you can use the following Rake task: + +```shell +sudo gitlab-rake db:migrate:status:geo +``` + This outputs a table with a `Status` of `up` or `down` for each Migration ID. diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md index b7db3f26a60..d1dbc83ad86 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 00bd71af6c5..e43fbac25e9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project import/export administration **(FREE SELF)** diff --git a/doc/administration/raketasks/smtp.md b/doc/administration/raketasks/smtp.md index 49274501809..5e9e3544902 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SMTP Rake tasks **(FREE SELF)** diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md index fc0ff23c5b1..d740aaa9c96 100644 --- a/doc/administration/raketasks/storage.md +++ b/doc/administration/raketasks/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository storage Rake tasks **(FREE SELF)** @@ -185,8 +185,7 @@ as most of the fixes are relatively high risk, involving running code on the Rai ### Read only projects -If you have [set projects read only](../troubleshooting/gitlab_rails_cheat_sheet.md#make-a-project-read-only-can-only-be-done-in-the-console) -they might fail to migrate. +If you have set projects as read only they might fail to migrate. 1. [Start a Rails console](../operations/rails_console.md#starting-a-rails-console-session). @@ -233,7 +232,7 @@ Delete the project using the Rails console: - Replace `admin_handle` with the handle of an instance administrator or with `root`. - Verify the output before proceeding. **There are no other checks performed**. -1. [Destroy the project](../troubleshooting/gitlab_rails_cheat_sheet.md#destroy-a-project) **immediately**: +1. [Destroy the project](../../user/project/working_with_projects.md#delete-a-project-using-console) **immediately**: ```ruby Projects::DestroyService.new(project, user).execute diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 216c0875645..b6f14bc6fa4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads migrate Rake tasks **(FREE SELF)** @@ -166,33 +166,22 @@ GitLab provides a wrapper Rake task that migrates all uploaded files (for exampl attachments, and favicon) to local storage in one step. The wrapper task invokes individual Rake tasks to migrate files falling under each of these categories one by one. -For details on these Rake tasks, refer to [Individual Rake tasks](#individual-rake-tasks), -keeping in mind the task name in this case is `gitlab:uploads:migrate_to_local`. +For details on these Rake tasks, refer to [Individual Rake tasks](#individual-rake-tasks). +Keep in mind the task name in this case is `gitlab:uploads:migrate_to_local`. -To migrate uploads from object storage to local storage: +To migrate uploads from object storage to local storage, run the following Rake task: -1. Disable both `direct_upload` and `background_upload` under `uploads` settings in `gitlab.rb`: +**Omnibus GitLab installation** - ```ruby - gitlab_rails['uploads_object_store_direct_upload'] = false - gitlab_rails['uploads_object_store_background_upload'] = false - ``` - - Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure). - -1. Run the Rake task: - - **Omnibus Installation** - - ```shell - gitlab-rake "gitlab:uploads:migrate_to_local:all" - ``` +```shell +gitlab-rake "gitlab:uploads:migrate_to_local:all" +``` - **Source Installation** +**Source installation** - ```shell - sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:uploads:migrate_to_local:all - ``` +```shell +sudo RAILS_ENV=production -u git -H bundle exec rake gitlab:uploads:migrate_to_local:all +``` After running the Rake task, you can disable object storage by undoing the changes described in the instructions to [configure object storage](../../uploads.md#using-object-storage). diff --git a/doc/administration/raketasks/uploads/sanitize.md b/doc/administration/raketasks/uploads/sanitize.md index bf6dc4fd776..831abee9739 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 387a1a75393..3718741e2e9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 fb5f6cc3a54..31ea879b289 100644 --- a/doc/administration/redis/index.md +++ b/doc/administration/redis/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 b775b579fd4..1c2515099fe 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis replication and failover with Omnibus GitLab **(PREMIUM SELF)** diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index d624fe28f80..7904fb1ded8 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 bd5b30efb7b..c36d75a566d 100644 --- a/doc/administration/redis/standalone.md +++ b/doc/administration/redis/standalone.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Standalone Redis using Omnibus GitLab **(FREE SELF)** diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md index f9e5390c227..e568daed961 100644 --- a/doc/administration/redis/troubleshooting.md +++ b/doc/administration/redis/troubleshooting.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To 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 Redis **(FREE SELF)** diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index 5d676dac000..45939b48f78 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 10,000 users **(PREMIUM SELF)** @@ -17,30 +17,37 @@ full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 200 RPS, Web: 20 RPS, Git (Pull): 20 RPS, Git (Push): 4 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/10k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|------------------------------------------|-------|-------------------------|------------------|----------------|-----------| -| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | `D8s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Gitaly<sup>5</sup> | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | `D16s v3` | -| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| GitLab Rails | 3 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | `F32s v2` | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|------------------------------------------|-------|-------------------------|------------------|----------------| +| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Gitaly<sup>5</sup> | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | +| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| GitLab Rails | 3 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -151,13 +158,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### 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 the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -293,7 +296,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -506,7 +509,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1276,7 +1279,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Examples of the above could include [Google's Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) or [Amazon RDS](https://aws.amazon.com/rds/). @@ -1693,7 +1696,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1861,7 +1866,9 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. The following IPs will be used as an example: @@ -2012,46 +2019,7 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. If you're [using NFS](#configure-nfs-optional): - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - - 1. Edit `/etc/gitlab/gitlab.rb` and use the following configuration: - - ```ruby - ## Prevent GitLab from starting if NFS data mounts are not available - high_availability['mountpoint'] = '/var/opt/gitlab/git-data' - - ## Ensure UIDs and GIDs match between servers for permissions via NFS - user['uid'] = 9000 - user['gid'] = 9000 - web_server['uid'] = 9001 - web_server['gid'] = 9001 - registry['uid'] = 9002 - registry['gid'] = 9002 - ``` - - 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). 1. Confirm the node can connect to Gitaly: @@ -2189,7 +2157,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2319,9 +2286,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 96b1e541f92..a8e0e23512f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 1,000 users **(FREE SELF)** @@ -12,7 +12,7 @@ full list of reference architectures, see If you are serving up to 1,000 users and you don't have strict availability requirements, a single-node solution with -[frequent backups](index.md#automated-backups) is appropriate for +[frequent backups](index.md#backups) is appropriate for many organizations. > - **Supported users (approximate):** 1,000 @@ -24,6 +24,7 @@ many organizations. > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 20 RPS, Web: 2 RPS, Git (Pull): 2 RPS, Git (Push): 1 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/1k)** +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). | Users | Configuration | GCP | AWS | Azure | |--------------|-------------------------|----------------|--------------|----------| @@ -83,11 +84,7 @@ Any "burstable" instance types are not recommended due to inconsistent performan 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 the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -Be aware of the following specific call outs: - -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Swap diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 423dbc7abfb..7d67ac48b73 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 25,000 users **(PREMIUM SELF)** @@ -17,30 +17,37 @@ full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 500 RPS, Web: 50 RPS, Git (Pull): 50 RPS, Git (Push): 10 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/25k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|------------------------------------------|-------|-------------------------|------------------|--------------|-----------| -| External load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | `D16s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Gitaly<sup>5</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | `D32s v3` | -| Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | `F32s v2` | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|------------------------------------------|-------|-------------------------|------------------|--------------| +| External load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 16 vCPU, 60 GB memory | `n1-standard-16` | `m5.4xlarge` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Gitaly<sup>5</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | +| Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -151,13 +158,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### 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 the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -295,7 +298,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -508,7 +511,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1281,7 +1284,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Once the database is set up, follow the [post configuration](#praefect-postgresql-post-configuration). @@ -1696,7 +1699,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1864,7 +1869,9 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. The following IPs will be used as an example: @@ -2017,46 +2024,8 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. If you're [using NFS](#configure-nfs-optional): - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - - 1. Edit `/etc/gitlab/gitlab.rb` and use the following configuration: - - ```ruby - ## Prevent GitLab from starting if NFS data mounts are not available - high_availability['mountpoint'] = '/var/opt/gitlab/git-data' - - ## Ensure UIDs and GIDs match between servers for permissions via NFS - user['uid'] = 9000 - user['gid'] = 9000 - web_server['uid'] = 9001 - web_server['gid'] = 9001 - registry['uid'] = 9002 - registry['gid'] = 9002 - ``` +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). - 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Confirm the node can connect to Gitaly: ```shell @@ -2192,7 +2161,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2322,9 +2290,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index 99cc6d47f6a..61ea435f63f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 2,000 users **(FREE SELF)** @@ -18,6 +18,7 @@ For a full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 40 RPS, Web: 4 RPS, Git (Pull): 4 RPS, Git (Push): 1 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/2k)** +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). | Service | Nodes | Configuration | GCP | AWS | Azure | |----------------------------|-------|------------------------|-----------------|--------------|----------| @@ -31,9 +32,15 @@ For a full list of reference architectures, see | NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run as reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run as reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and [Azure Database for PostgreSQL](https://azure.microsoft.com/en-gb/services/postgresql/) is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. <!-- markdownlint-enable MD029 --> @@ -89,11 +96,7 @@ Any "burstable" instance types are not recommended due to inconsistent performan 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 the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -Be aware of the following specific call outs: - -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ## Setup components @@ -177,7 +180,7 @@ details about managing SSL certificates and configuring NGINX, see the Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -249,7 +252,7 @@ to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -589,31 +592,6 @@ but this is dependent on workload. On each node perform the following: -1. If you're [using NFS](#configure-nfs-optional): - - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -742,7 +720,10 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). + 1. Run `sudo gitlab-rake gitlab:gitaly:check` to confirm the node can connect to Gitaly. + 1. Tail the logs to see the requests: ```shell @@ -899,7 +880,7 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) +- [Azure Blob storage](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -1026,8 +1007,13 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and [Azure Database for PostgreSQL](https://azure.microsoft.com/en-gb/services/postgresql/) is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. 3. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index 5c227e3dc27..7484fafe1b0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 3,000 users **(PREMIUM SELF)** @@ -27,29 +27,36 @@ For a full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 60 RPS, Web: 6 RPS, Git (Pull): 6 RPS, Git (Push): 1 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/3k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|-------------------------------------------|-------|-----------------------|-----------------|--------------|----------| -| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Redis<sup>2</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| Consul<sup>1</sup> + Sentinel<sup>2</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Gitaly<sup>5</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| GitLab Rails | 3 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | `F8s v2` | -| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|-------------------------------------------|-------|-----------------------|-----------------|--------------| +| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Redis<sup>2</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| Consul<sup>1</sup> + Sentinel<sup>2</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Gitaly<sup>5</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| GitLab Rails | 3 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -157,13 +164,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### 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 the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -296,7 +299,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -790,7 +793,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1221,7 +1224,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Once the database is set up, follow the [post configuration](#praefect-postgresql-post-configuration). @@ -1636,7 +1639,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. The following IPs will be used as an example: @@ -1803,35 +1808,12 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. On each node perform the following: -1. If you're [using NFS](#configure-nfs-optional): - - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -1979,7 +1961,10 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). + 1. Run `sudo gitlab-rake gitlab:gitaly:check` to confirm the node can connect to Gitaly. + 1. Tail the logs to see the requests: ```shell @@ -2129,7 +2114,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2198,12 +2182,12 @@ cluster alongside your instance, read how to ## Supported modifications for lower user counts (HA) -The 3k GitLab reference architecture is the smallest we recommend that achieves High Availability (HA). -However, for environments that need to serve less users but maintain HA, there's several +The 3,000 user GitLab reference architecture is the smallest we recommend that achieves High Availability (HA). +However, for environments that need to serve fewer users but maintain HA, there are several supported modifications you can make to this architecture to reduce complexity and cost. -It should be noted that to achieve HA with GitLab, this architecture's makeup is ultimately what is -required. Each component has various considerations and rules to follow and this architecture +It should be noted that to achieve HA with GitLab, the 3,000 user architecture's makeup is ultimately what is +required. Each component has various considerations and rules to follow, and the 3,000 user architecture meets all of these. Smaller versions of this architecture will be fundamentally the same, but with smaller performance requirements, several modifications can be considered as follows: @@ -2283,9 +2267,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index bddec55ba71..88fc3649b3f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 50,000 users **(PREMIUM SELF)** @@ -17,30 +17,37 @@ full list of reference architectures, see > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 1000 RPS, Web: 100 RPS, Git (Pull): 100 RPS, Git (Push): 20 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/50k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|------------------------------------------|-------|-------------------------|------------------|---------------|-----------| -| External load balancing node<sup>3</sup> | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | `F8s v2` | -| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | `D32s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | `F8s v2` | -| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Gitaly<sup>5</sup> | 3 | 64 vCPU, 240 GB memory | `n1-standard-64` | `m5.16xlarge` | `D64s v3` | -| Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | `F32s v2` | -| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|------------------------------------------|-------|-------------------------|------------------|---------------| +| External load balancing node<sup>3</sup> | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | +| Consul<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | `c5.2xlarge` | +| Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| Gitaly<sup>5</sup> | 3 | 64 vCPU, 240 GB memory | `n1-standard-64` | `m5.16xlarge` | +| Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | `c5.9xlarge` | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -151,13 +158,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### 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 the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -302,7 +305,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer will not be able to connect. @@ -515,7 +518,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1289,7 +1292,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Examples of the above could include [Google's Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) or [Amazon RDS](https://aws.amazon.com/rds/). @@ -1706,7 +1709,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. - `10.6.0.101`: Sidekiq 1 - `10.6.0.102`: Sidekiq 2 @@ -1874,7 +1879,9 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. The following IPs will be used as an example: @@ -2034,46 +2041,8 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. If you're [using NFS](#configure-nfs-optional): - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - - 1. Edit `/etc/gitlab/gitlab.rb` and use the following configuration: - - ```ruby - ## Prevent GitLab from starting if NFS data mounts are not available - high_availability['mountpoint'] = '/var/opt/gitlab/git-data' - - ## Ensure UIDs and GIDs match between servers for permissions via NFS - user['uid'] = 9000 - user['gid'] = 9000 - web_server['uid'] = 9001 - web_server['gid'] = 9001 - registry['uid'] = 9002 - registry['gid'] = 9002 - ``` +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). - 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Confirm the node can connect to Gitaly: ```shell @@ -2209,7 +2178,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2339,9 +2307,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 0e599df7c1f..c8cf35a2e59 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architecture: up to 5,000 users **(PREMIUM SELF)** @@ -24,29 +24,36 @@ costly-to-operate environment by using the > - **Validation and test results:** The Quality Engineering team does [regular smoke and performance tests](index.md#validation-and-test-results) to ensure the reference architectures remain compliant > - **Test requests per second (RPS) rates:** API: 100 RPS, Web: 10 RPS, Git (Pull): 10 RPS, Git (Push): 2 RPS > - **[Latest Results](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/5k)** - -| Service | Nodes | Configuration | GCP | AWS | Azure | -|-------------------------------------------|-------|-------------------------|-----------------|--------------|----------| -| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Redis<sup>2</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| Consul<sup>1</sup> + Sentinel<sup>2</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| PostgreSQL<sup>1</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Gitaly<sup>5</sup> | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | `D8s v3` | -| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | `D2s v3` | -| GitLab Rails | 3 | 16 vCPU, 14.4 GB memory | `n1-highcpu-16` | `c5.4xlarge` | `F16s v2`| -| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | -| Object storage<sup>4</sup> | - | - | - | - | - | -| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | +> - **Unsure which Reference Architecture to use?** [Go to this guide for more info](index.md#deciding-which-architecture-to-use). + +| Service | Nodes | Configuration | GCP | AWS | +|-------------------------------------------|-------|-------------------------|-----------------|--------------| +| External load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Redis<sup>2</sup> | 3 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| Consul<sup>1</sup> + Sentinel<sup>2</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| PostgreSQL<sup>1</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | +| PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Internal load balancing node<sup>3</sup> | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Gitaly<sup>5</sup> | 3 | 8 vCPU, 30 GB memory | `n1-standard-8` | `m5.2xlarge` | +| Praefect<sup>5</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | `m5.large` | +| GitLab Rails | 3 | 16 vCPU, 14.4 GB memory | `n1-highcpu-16` | `c5.4xlarge` | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | +| Object storage<sup>4</sup> | - | - | - | - | +| NFS server (non-Gitaly) | 1 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> @@ -154,13 +161,9 @@ Any "burstable" instance types are not recommended due to inconsistent performan ### 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 the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. - -Be aware of the following specific call outs: +As a general guidance, GitLab should run on most infrastructure such as reputable Cloud Providers (AWS, GCP) and their services, or self managed (ESXi) that meet both the specs detailed above, as well as any requirements in this section. However, this does not constitute a guarantee for every potential permutation. -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/#:~:text=Azure%20Database%20for%20PostgreSQL%20is,high%20availability%2C%20and%20dynamic%20scalability.) is [not recommended](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61) due to known performance issues or missing features. -- [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/) is recommended to be configured with [Premium accounts](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-block-blob-premium) to ensure consistent performance. +See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. ### Praefect PostgreSQL @@ -293,7 +296,7 @@ for details on managing SSL certificates and configuring NGINX. Ensure the external load balancer only routes to working services with built in monitoring endpoints. The [readiness checks](../../user/admin_area/monitoring/health_check.md) -all require [additional configuration](../monitoring/ip_whitelist.md) +all require [additional configuration](../monitoring/ip_allowlist.md) on the nodes being checked, otherwise, the external load balancer is not able to connect. @@ -786,7 +789,7 @@ cluster to be used with GitLab. If you're hosting GitLab on a cloud provider, you can optionally use a managed service for PostgreSQL. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. If you use a cloud-managed service, or provide your own PostgreSQL: @@ -1218,7 +1221,7 @@ you are using Geo, where separate database instances are required for handling r In this setup, the specs of the main database setup shouldn't need to be changed as the impact should be minimal. -A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). +A reputable provider or solution should be used for this. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. Once the database is set up, follow the [post configuration](#praefect-postgresql-post-configuration). @@ -1633,7 +1636,9 @@ To configure Praefect with TLS: Sidekiq requires connection to the [Redis](#configure-redis), [PostgreSQL](#configure-postgresql) and [Gitaly](#configure-gitaly) instances. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. - `10.6.0.71`: Sidekiq 1 - `10.6.0.72`: Sidekiq 2 @@ -1799,35 +1804,12 @@ run [multiple Sidekiq processes](../operations/extra_sidekiq_processes.md). ## Configure GitLab Rails This section describes how to configure the GitLab application (Rails) component. -[Object storage](#configure-the-object-storage) is also required to be configured. +Since it's recommended to use [Object storage](#configure-the-object-storage) +over [NFS](#configure-nfs-optional) for data objects, the following examples +include the Object storage configuration. On each node perform the following: -1. If you're [using NFS](#configure-nfs-optional): - - 1. If necessary, install the NFS client utility packages using the following - commands: - - ```shell - # Ubuntu/Debian - apt-get install nfs-common - - # CentOS/Red Hat - yum install nfs-utils nfs-utils-lib - ``` - - 1. Specify the necessary NFS mounts in `/etc/fstab`. - The exact contents of `/etc/fstab` depends on how you chose - to configure your NFS server. See the [NFS documentation](../nfs.md) - for examples and the various options. - - 1. Create the shared directories. These may be different depending on your NFS - mount locations. - - ```shell - mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data - ``` - 1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab package of your choice. Be sure to follow _only_ installation steps 1 and 2 on the page. @@ -1978,7 +1960,10 @@ On each node perform the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Enable incremental logging](#enable-incremental-logging), unless you are using [NFS](#configure-nfs-optional). + 1. Run `sudo gitlab-rake gitlab:gitaly:check` to confirm the node can connect to Gitaly. + 1. Tail the logs to see the requests: ```shell @@ -2128,7 +2113,6 @@ GitLab has been tested on a number of object storage providers: - [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces) - [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) - [OpenStack Swift (S3 compatibility mode)](https://docs.openstack.org/swift/latest/s3_compat.html) -- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. There are two ways of specifying object storage configuration in GitLab: @@ -2257,9 +2241,15 @@ services where applicable): <!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> <!-- markdownlint-disable MD029 --> -1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. However, Amazon Aurora is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440), and Azure Database for PostgreSQL is **not recommended** due to [performance issues](https://gitlab.com/gitlab-org/quality/reference-architectures/-/issues/61). Consul is primarily used for PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. -2. Can be optionally run on reputable third-party external PaaS Redis solutions. Google Memorystore and AWS ElastiCache are known to work. -3. Can be optionally run on reputable third-party load balancing services (LB PaaS). AWS ELB is known to work. +1. Can be optionally run on reputable third-party external PaaS PostgreSQL solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/high-availability#normal) and [Amazon RDS](https://aws.amazon.com/rds/) are known to work. + - [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + - [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is **incompatible** with load balancing enabled by default in [14.4.0](../../update/index.md#1440). + - Consul is primarily used for Omnibus PostgreSQL high availability so can be ignored when using a PostgreSQL PaaS setup. However, Consul is also used optionally by Prometheus for Omnibus auto host discovery. +2. Can be optionally run on reputable third-party external PaaS Redis solutions. See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Memorystore](https://cloud.google.com/memorystore) and [Amazon ElastiCache](https://aws.amazon.com/elasticache/) are known to work. +3. Can be optionally run on reputable third-party load balancing services (LB PaaS). See [Recommended cloud providers and services](index.md#recommended-cloud-providers-and-services) for more information. + - [Google Cloud Load Balancing](https://cloud.google.com/load-balancing) and [Amazon Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/) are known to work. 4. Should be run on reputable Cloud Provider or Self Managed solutions. More information can be found in the [Configure the object storage](#configure-the-object-storage) section. 5. Gitaly Cluster provides the benefits of fault tolerance, but comes with additional complexity of setup and management. Review the existing [technical limitations and considerations before deploying Gitaly Cluster](../gitaly/index.md#before-deploying-gitaly-cluster). If you want sharded Gitaly, use the same specs listed above for `Gitaly`. <!-- markdownlint-enable MD029 --> diff --git a/doc/administration/reference_architectures/img/reference-architectures.png b/doc/administration/reference_architectures/img/reference-architectures.png Binary files differdeleted file mode 100644 index 0f8e663b57b..00000000000 --- a/doc/administration/reference_architectures/img/reference-architectures.png +++ /dev/null diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 7be12e12386..2cf9f2a1e83 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -2,44 +2,20 @@ 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference architectures **(FREE SELF)** -You can set up GitLab on a single server or scale it up to serve many users. -This page details the recommended Reference Architectures that were built and -verified by the GitLab Quality and Support teams. - -Below is a chart representing each architecture tier and the number of users -they can handle. As your number of users grow with time, it's recommended that -you scale GitLab accordingly. - - -<!-- Internal link: https://docs.google.com/spreadsheets/d/1obYP4fLKkVVDOljaI3-ozhmCiPtEeMblbBKkf2OADKs/edit#gid=1403207183 --> - -For GitLab instances with less than 2,000 users, it's recommended that you use -the [default setup](#automated-backups) by -[installing GitLab](../../install/index.md) on a single machine to minimize -maintenance and resource costs. - -If your organization has more than 2,000 users, the recommendation is to scale the -GitLab components to multiple machine nodes. The machine nodes are grouped by -components. The addition of these nodes increases the performance and -scalability of to your GitLab instance. - -When scaling GitLab, there are several factors to consider: - -- Multiple application nodes to handle frontend traffic. -- A load balancer is added in front to distribute traffic across the application nodes. -- The application nodes connects to a shared file server and PostgreSQL and Redis services on the backend. +The GitLab Reference Architectures have been designed and tested by the +GitLab Quality and Support teams to provide recommended deployments at scale. ## Available reference architectures Depending on your workflow, the following recommended reference architectures may need to be adapted accordingly. Your workload is influenced by factors including how active your users are, how much automation you use, mirroring, -and repository/change size. Additionally the displayed memory values are +and repository/change size. Additionally, the displayed memory values are provided by [GCP machine types](https://cloud.google.com/compute/docs/machine-types). For different cloud vendors, attempt to select options that best match the provided architecture. @@ -70,7 +46,183 @@ The following Cloud Native Hybrid reference architectures, where select recommen A GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/#self-managed) license is required to get assistance from Support with troubleshooting the [2,000 users](2k_users.md) and higher reference architectures. -[Read more about our definition of scaled architectures](https://about.gitlab.com/support/#definition-of-scaled-architecture). +[Read more about our definition of scaled architectures](https://about.gitlab.com/support/definitions/#definition-of-scaled-architecture). + +## Deciding which architecture to use + +The Reference Architectures are designed to strike a balance between two important factors--performance and resilience. + +While they are designed to make it easier to set up GitLab at scale, it can still be a challenge to know which one will meet your requirements. + +As a general guide, **the more performant and/or resilient you want your environment to be, the more involved it will be**. + +This section explains the designs you can choose from. It begins with the least complexity, goes to the most, and ends with a decision tree. + +### Backups + +For environments serving 2,000 or fewer users we generally recommend that an [automated backup](../../raketasks/backup_gitlab.md#configuring-cron-to-make-daily-backups) strategy is used instead of HA. + +Backups can provide a good level of RPO / RTO while avoiding the complexities that come with HA. + +### High Availability (HA) + +High Availability ensures every component in the GitLab setup can handle failures through various mechanisms. To achieve this however is involved, 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 will have a bigger impact against more users. All the architectures in this range have HA built in by design for this reason. + +For users who still need to have HA for a lower number of users this can also be achieved with an [adjusted 3K architecture as detailed here](3k_users.md#supported-modifications-for-lower-user-counts-ha). + +#### Do you need High Availability (HA)? + +As mentioned above, achieving HA does come at a cost. The environment's required are sizable as each component needs to be multiplied, which comes with additional actual and maintenance costs. + +For a lot of our customers with fewer than 3,000 users, we've found a backup strategy is sufficient and even preferable. While this does have a slower recovery time, it also means you have a much smaller architecture and less maintenance costs as a result. + +In general then, we'd only recommend you employ HA in the following scenarios: + +- When you have 3,000 or more users. +- When GitLab being down would critically impact your workflow. + +#### Zero Downtime Upgrades + +[Zero Downtime Upgrades](../../update/zero_downtime.md) are available for standard Reference Architecture environments with HA (Cloud Native Hybrid is not supported at this time). This allows for an environment to stay up during an upgrade, but the process is more involved as a result and has some limitations as detailed in the documentation. + +When going through this process it's worth noting that there may still be brief moments of downtime when the HA mechanisms tale effect. + +In most cases the downtime required for doing an upgrade in general shouldn't be substantial, so this is only recommended if it's a key requirement for you. + +### Cloud Native Hybrid (Kubernetes HA) + +As an additional layer of HA resilience you can deploy select components in Kubernetes, known as a Cloud Native Hybrid Reference Architecture. + +Note that this is an alternative and more **advanced** setup compared to a standard Reference Architecture. Running services in Kubernetes is well known to be complex. **This setup is only recommended** if you have strong working knowledge and experience in Kubernetes. + +### GitLab Geo (Cross Regional Distribution / Disaster Recovery) + +With [GitLab Geo](../geo/index.md) you can have both distributed environments in different regions and a full Disaster Recovery (DR) setup in place. With this setup you would have 2 or more separate environments, with one being a primary that gets replicated to the others. In the rare event the primary site went down completely you could fail over to one of the other environments. + +This is an **advanced and involved** setup and should only be undertaken if you have DR as a key requirement. Decisions then on how each environment are configured would also need to be taken, such as if each environment itself would be the full size and / or have HA. + +### Decision Tree + +Below you can find the above guidance in the form of a decision tree. It's recommended you read through the above guidance in full first before though. + +```mermaid +%%{init: { 'theme': 'base' } }%% +graph TD + L1A(<b>What Reference Architecture should I use?</b>) --> L2A(More than 3000 users?) + L2A -->|No| L3A("<a href=#do-you-need-high-availability-ha>Do you need HA?</a><br>(or Zero-Downtime Upgrades)") --> |Yes| L4A><b>Recommendation</b><br><br>3K architecture with HA<br>including supported modifications] + L3A -->|No| L4B><b>Recommendation</b><br><br>Architecture closest to user<br>count with Backups] + L2A -->|Yes| L3B[Do you have experience with<br/>and want additional resilience<br/>with select components in Kubernetes?] + L3B -->|No| L4C><b>Recommendation</b><br><br>Architecture closest to user<br>count with HA] + L3B -->|Yes| L4D><b>Recommendation</b><br><br>Cloud Native Hybrid architecture<br>closest to user count] + + L5A("<a href=#gitlab-geo-cross-regional-distribution-disaster-recovery>Do you need cross regional distribution or disaster recovery?"</a>) --> |Yes| L6A><b>Additional Recommendation</b><br><br> GitLab Geo] + L4A -.- L5A + L4B -.- L5A + L4C -.- L5A + L4D -.- L5A + +classDef default fill:#FCA326 +linkStyle default fill:none,stroke:#7759C2 +``` + +## Recommended cloud providers and services + +NOTE: +The following lists are non-exhaustive. Generally, other cloud providers not listed +here likely work with the same specs, but this hasn't been validated. +Additionally, when it comes to other cloud provider services not listed here, +it's advised to be cautious as each implementation can be notably different +and should be tested thoroughly before production use. + +Through testing and real life usage, the Reference Architectures are validated and supported on the following cloud providers: + +<table> +<thead> + <tr> + <th>Reference Architecture</th> + <th>GCP</th> + <th>AWS</th> + <th>Azure</th> + <th>Bare Metal</th> + </tr> +</thead> +<tbody> + <tr> + <td>Omnibus</td> + <td>🟢</td> + <td>🟢</td> + <td>🟡<sup>1</sup></td> + <td>🟢</td> + </tr> + <tr> + <td>Cloud Native Hybrid</td> + <td>🟢</td> + <td>🟢</td> + <td></td> + <td></td> + </tr> +</tbody> +</table> + +1. We only recommend smaller setups (up to 2k) at this time on Azure due to performance issues at larger scales. See the [Recommendation Notes for Azure](#recommendation-notes-for-azure) section for more info. + +Additionally, the following cloud provider services are validated and supported for use as part of the Reference Architectures: + +<table> +<thead> + <tr> + <th>Cloud Service</th> + <th>GCP</th> + <th>AWS</th> + <th>Bare Metal</th> + </tr> +</thead> +<tbody> + <tr> + <td>Object Storage</td> + <td>🟢 <a href="https://cloud.google.com/storage" target="_blank">Cloud Storage</a></td> + <td>🟢 <a href="https://aws.amazon.com/s3/" target="_blank">S3</a></td> + <td>🟢 <a href="https://min.io/" target="_blank">MinIO</a></td> + </tr> + <tr> + <td>Database</td> + <td>🟢 <a href="https://cloud.google.com/sql" target="_blank" rel="noopener noreferrer">Cloud SQL</a></td> + <td>🟢 <a href="https://aws.amazon.com/rds/" target="_blank" rel="noopener noreferrer">RDS</a></td> + <td></td> + </tr> + <tr> + <td>Redis</td> + <td></td> + <td>🟢 <a href="https://aws.amazon.com/elasticache/" target="_blank" rel="noopener noreferrer">ElastiCache</a></td> + <td></td> + </tr> +</tbody> +</table> + +### Recommendation notes for the database services + +When selecting a database service, it should run a standard, performant, and [supported version](../../install/requirements.md#postgresql-requirements) of PostgreSQL with the following features: + +- Read Replicas for [Database Load Balancing](../postgresql/database_load_balancing.md). +- Cross Region replication for [GitLab Geo](../geo/index.md). + +Several cloud provider services are known not to support the above or have been found to have other issues and aren't recommended: + +- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible and not supported. See [14.4.0](../../update/index.md#1440) for more details. +- [Azure Database for PostgreSQL Single Server](https://azure.microsoft.com/en-gb/services/postgresql/#overview) (Single / Flexible) is **strongly not recommended** for use due to notable performance / stability issues or missing functionality. See [Recommendation Notes for Azure](#recommendation-notes-for-azure) for more details. +- [Google AlloyDB](https://cloud.google.com/alloydb) and [Amazon RDS Multi-AZ DB clusters](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/multi-az-db-clusters-concepts.html) have not been tested and are not recommended. Both solutions are specifically not expected to work with GitLab Geo. + +### Recommendation notes for Azure + +Due to performance issues that we found with several key Azure services, we only recommend smaller architectures (up to 2k) to be deployed to Azure. For larger architectures, we recommend using another cloud provider. + +In addition to the above, you should be aware of the additional specific guidance for Azure: + +- **We outright strongly do not recommend [Azure Database for PostgreSQL Single Server](https://learn.microsoft.com/en-us/azure/postgresql/single-server/overview-single-server)** specifically due to significant performance and stability issues found. **For GitLab 14.0 and higher the service is not supported** due to it only supporting up to PostgreSQL 11. + - A new service, [Azure Database for Postgres Flexible Server](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/) has been released but due to it missing some functionality we don't recommend it at this time. +- [Azure Blob Storage](https://azure.microsoft.com/en-gb/services/storage/blobs/) has been found to have performance limits that can impact production use at certain times. However, this has only been seen in larger architectures. ## Validation and test results @@ -97,7 +249,7 @@ Network latency on the test environments between components on all Cloud Provide We aim to have a "test smart" approach where architectures tested have a good range that can also apply to others. Testing focuses on 10k Omnibus on GCP as the testing has shown this is a good bellwether for the other architectures and cloud providers as well as Cloud Native Hybrids. -The Standard Reference Architectures are designed to be platform agnostic, with everything being run on VMs via [Omnibus GitLab](https://docs.gitlab.com/omnibus/). While testing occurs primarily on GCP, ad-hoc testing has shown that they perform similarly on equivalently specced hardware on other Cloud Providers or if run on premises (bare-metal). +The Standard Reference Architectures are designed to be platform-agnostic, with everything being run on VMs via [Omnibus GitLab](https://docs.gitlab.com/omnibus/). While testing occurs primarily on GCP, ad-hoc testing has shown that they perform similarly on equivalently specced hardware on other Cloud Providers or if run on premises (bare-metal). Testing on these reference architectures is performed with the [GitLab Performance Tool](https://gitlab.com/gitlab-org/quality/performance) @@ -111,14 +263,14 @@ per 1,000 users: - API: 20 RPS - Web: 2 RPS - Git (Pull): 2 RPS -- Git (Push): 0.4 RPS (rounded to nearest integer) +- Git (Push): 0.4 RPS (rounded to the nearest integer) ### How to interpret the results NOTE: Read our blog post on [how our QA team leverages GitLab performance testing tool](https://about.gitlab.com/blog/2020/02/18/how-were-building-up-performance-testing-of-gitlab/). -Testing is done publicly and all results are shared. +Testing is done publicly, and all results are shared. The following table details the testing done against the reference architectures along with the frequency and results. Additional testing is continuously evaluated, and the table is updated accordingly. @@ -292,170 +444,6 @@ The following table details the cost to run the different reference architecture </tr> </table> -## Recommended cloud providers and services - -NOTE: -The following lists are non exhaustive. Generally, other cloud providers not listed -here likely work with the same specs, but this hasn't been validated. -Additionally, when it comes to other cloud provider services not listed here, -it's advised to be cautious as each implementation can be notably different -and should be tested thoroughly before production use. - -Through testing and real life usage, the Reference Architectures are validated and supported on the following cloud providers: - -<table> -<thead> - <tr> - <th>Reference Architecture</th> - <th>GCP</th> - <th>AWS</th> - <th>Azure</th> - <th>Bare Metal</th> - </tr> -</thead> -<tbody> - <tr> - <td>Omnibus</td> - <td>✅</td> - <td>✅</td> - <td>✅</td> - <td>✅</td> - </tr> - <tr> - <td>Cloud Native Hybrid</td> - <td>✅</td> - <td>✅</td> - <td></td> - <td></td> - </tr> -</tbody> -</table> - -Additionally, the following cloud provider services are validated and supported for use as part of the Reference Architectures: - -<table> -<thead> - <tr> - <th>Cloud Service</th> - <th>GCP</th> - <th>AWS</th> - <th>Bare Metal</th> - </tr> -</thead> -<tbody> - <tr> - <td>Object Storage</td> - <td>✅ <a href="https://cloud.google.com/storage" target="_blank">Cloud Storage</a></td> - <td>✅ <a href="https://aws.amazon.com/s3/" target="_blank">S3</a></td> - <td>✅ <a href="https://min.io/" target="_blank">MinIO</a></td> - </tr> - <tr> - <td>Database</td> - <td>✅ <a href="https://cloud.google.com/sql" target="_blank" rel="noopener noreferrer">Cloud SQL</a></td> - <td>✅ <a href="https://aws.amazon.com/rds/" target="_blank" rel="noopener noreferrer">RDS</a></td> - <td></td> - </tr> - <tr> - <td>Redis</td> - <td></td> - <td>✅ <a href="https://aws.amazon.com/elasticache/" target="_blank" rel="noopener noreferrer">ElastiCache</a></td> - <td></td> - </tr> -</tbody> -</table> - -The following specific cloud provider services have been found to have issues in terms of either functionality or performance. As such, they either have caveats that should be considered or are not recommended: - -- [Amazon Aurora](https://aws.amazon.com/rds/aurora/) is incompatible. See [14.4.0](../../update/index.md#1440) for more details. -- [Azure Blob Storage](https://azure.microsoft.com/en-gb/services/storage/blobs/) has been found to have performance limits that can impact production use at certain times. For larger Reference Architectures the service may not be sufficient for production use and an alternative is recommended for use instead. -- [Azure Database for PostgreSQL Server](https://azure.microsoft.com/en-gb/services/postgresql/#overview) (Single / Flexible) is not recommended for use due to notable performance issues or missing functionality. - -NOTE: -As a general rule we unfortunately don't recommend Azure Services at this time. -If required, we advise thorough testing is done at your intended scale -over a sustained period to validate if the service is suitable. - -## Availability Components - -GitLab comes with the following components for your use, listed from least to -most complex: - -- [Automated backups](#automated-backups) -- [Traffic load balancer](#traffic-load-balancer) -- [Zero downtime updates](#zero-downtime-updates) -- [Automated database failover](#automated-database-failover) -- [Instance level replication with GitLab Geo](#instance-level-replication-with-gitlab-geo) - -As you implement these components, begin with a single server and then do -backups. Only after completing the first server should you proceed to the next. - -Also, not implementing extra servers for GitLab doesn't necessarily mean that you have -more downtime. Depending on your needs and experience level, single servers can -have more actual perceived uptime for your users. - -### Automated backups - -> - Level of complexity: **Low** -> - Required domain knowledge: PostgreSQL, GitLab configurations, Git - -This solution is appropriate for many teams that have the default GitLab installation. -With automatic backups of the GitLab repositories, configuration, and the database, -this can be an optimal solution if you don't have strict requirements. -[Automated backups](../../raketasks/backup_gitlab.md#configuring-cron-to-make-daily-backups) -is the least complex to setup. This provides a point-in-time recovery of a predetermined schedule. - -### Traffic load balancer **(PREMIUM SELF)** - -> - Level of complexity: **Medium** -> - Required domain knowledge: HAProxy, shared storage, distributed systems - -This requires separating out GitLab into multiple application nodes with an added -[load balancer](../load_balancer.md). The load balancer distributes traffic -across GitLab application nodes. Meanwhile, each application node connects to a -shared file server and database systems on the back end. This way, if one of the -application servers fails, the workflow is not interrupted. -[HAProxy](https://www.haproxy.org/) is recommended as the load balancer. - -With this added component you have a number of advantages compared -to the default installation: - -- Increase the number of users. -- Enable zero-downtime upgrades. -- Increase availability. - -For more details on how to configure a traffic load balancer with GitLab, you can refer -to any of the [available reference architectures](#available-reference-architectures) with more than 1,000 users. - -### Zero downtime updates **(PREMIUM SELF)** - -> - Level of complexity: **Medium** -> - Required domain knowledge: PostgreSQL, HAProxy, shared storage, distributed systems - -GitLab supports [zero-downtime upgrades](../../update/zero_downtime.md). -Single GitLab nodes can be updated with only a [few minutes of downtime](../../update/index.md#upgrade-based-on-installation-method). -To avoid this, we recommend to separate GitLab into several application nodes. -As long as at least one of each component is online and capable of handling the instance's usage load, your team's productivity is not interrupted during the update. - -### Automated database failover **(PREMIUM SELF)** - -> - Level of complexity: **High** -> - Required domain knowledge: PgBouncer, Patroni, shared storage, distributed systems - -By adding automatic failover for database systems, you can enable higher uptime -with additional database nodes. This extends the default database with -cluster management and failover policies. -[PgBouncer in conjunction with Patroni](../postgresql/replication_and_failover.md) -is recommended. - -### Instance level replication with GitLab Geo **(PREMIUM SELF)** - -> - Level of complexity: **Very High** -> - Required domain knowledge: Storage replication - -[GitLab Geo](../geo/index.md) allows you to replicate your GitLab -instance to other geographical locations as a read-only fully operational instance -that can also be promoted in case of disaster. - ## Deviating from the suggested reference architectures As a general guideline, the further away you move from the Reference Architectures, @@ -475,11 +463,3 @@ However, it is still an additional layer and may still add some support complexi Other technologies, like [Docker swarm](https://docs.docker.com/engine/swarm/) are not officially supported, but can be implemented at your own risk. In that case, GitLab Support is not able to help you. - -## Supported modifications for lower user count HA reference architectures - -The reference architectures for user counts [3,000](3k_users.md) and up support High Availability (HA). - -In the specific case you have the requirement to achieve HA but have a lower user count, select modifications to the [3,000 user](3k_users.md) architecture are supported. - -For more details, [refer to this section in the architecture's documentation](3k_users.md#supported-modifications-for-lower-user-counts-ha). diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index 13fa8450996..6e97ffc3b47 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -1,7 +1,7 @@ --- stage: Plan group: Certify -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reply by email **(FREE SELF)** @@ -54,4 +54,4 @@ If it finds a reply key, it leaves your reply as a comment on the entity the notification was about (issue, merge request, commit...). For more details about the `Message-ID`, `In-Reply-To`, and `References headers`, -see [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4). +see [RFC 5322](https://www.rfc-editor.org/rfc/rfc5322#section-3.6.4). diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index 0fbb4562995..ef6fd82a460 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up Postfix for incoming email **(FREE SELF)** diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 4615499d6fa..08c1df3d5eb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository checks **(FREE SELF)** diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 482cbd97e37..492c5306b26 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository storage **(FREE SELF)** diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 865daba9e89..77a5eae3747 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository storage types **(FREE SELF)** @@ -167,6 +167,10 @@ For example: "@groups/#{hash[0..1]}/#{hash[2..3]}/#{hash}.wiki.git" ``` +### Gitaly Cluster storage + +If Gitaly Cluster is used, Praefect manages storage locations. For more information, see [Praefect-generated replica paths](gitaly/index.md#praefect-generated-replica-paths-gitlab-150-and-later). + ### Object storage support This table shows which storable objects are storable in each storage type: diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index e5ec12054b8..1a1194e16a9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to restart GitLab **(FREE SELF)** @@ -119,7 +119,7 @@ This should restart Puma, Sidekiq, GitLab Workhorse, and [Mailroom](reply_by_ema ## Helm chart installations There is no single command to restart the entire GitLab application installed via -the [cloud native Helm Chart](https://docs.gitlab.com/charts/). Usually, it should be +the [cloud-native Helm chart](https://docs.gitlab.com/charts/). Usually, it should be enough to restart a specific component separately (for example, `gitaly`, `puma`, `workhorse`, or `gitlab-shell`) by deleting all the pods related to it: diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 4148abf1bdc..6ab4f476e5e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/administration/custom_hooks.html' --- diff --git a/doc/administration/sidekiq/extra_sidekiq_processes.md b/doc/administration/sidekiq/extra_sidekiq_processes.md index b774b0d3e14..feaaa55aa59 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Run multiple Sidekiq processes **(FREE SELF)** @@ -75,6 +75,9 @@ To start multiple processes: ] ``` + `*` which matches all workers. + As a result, the wildcard query must stay at the end of the list or the rules after it are ignored. + `*` cannot be combined with concrete queue names - `*, mailers` just handles the `mailers` queue. diff --git a/doc/administration/sidekiq/extra_sidekiq_routing.md b/doc/administration/sidekiq/extra_sidekiq_routing.md index ebbf4059290..56c51beb758 100644 --- a/doc/administration/sidekiq/extra_sidekiq_routing.md +++ b/doc/administration/sidekiq/extra_sidekiq_routing.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Queue routing rules **(FREE SELF)** @@ -161,20 +161,3 @@ After the Sidekiq routing rules are changed, administrators must take care with the migration to avoid losing jobs entirely, especially in a system with long queues of jobs. The migration can be done by following the migration steps mentioned in [Sidekiq job migration](sidekiq_job_migration.md) - -### Workers that cannot be migrated - -Some workers cannot share a queue with other workers - typically because -they check the size of their own queue - and so must be excluded from -this process. We recommend excluding these from any further worker -routing by adding a rule to keep them in their own queue, for example: - -```ruby -sidekiq['routing_rules'] = [ - ['tags=needs_own_queue', nil], - # ... -] -``` - -These queues must also be included in at least one -[Sidekiq queue group](extra_sidekiq_processes.md#start-multiple-processes). diff --git a/doc/administration/sidekiq/index.md b/doc/administration/sidekiq/index.md index f4e67fcb6dd..f17c248e60e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure an external Sidekiq instance **(FREE SELF)** @@ -377,6 +377,10 @@ To enable LDAP with the synchronization worker for Sidekiq: sudo gitlab-ctl reconfigure ``` +## Configure SAML Groups for SAML Group Sync + +If you use [SAML Group Sync](../../user/group/saml_sso/group_sync.md), you must configure [SAML Groups](../../integration/saml.md#saml-groups) on all your Sidekiq nodes. + ## Disable Rugged Calls into Rugged, Ruby bindings for `libgit2`, [lock the Sidekiq processes's GVL](https://silverhammermba.github.io/emberb/c/#c-in-ruby-threads), diff --git a/doc/administration/sidekiq/sidekiq_health_check.md b/doc/administration/sidekiq/sidekiq_health_check.md index 3477320a2ac..74b478c1913 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 a3bc8b2959a..f61021ad4e7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq job migration **(FREE SELF)** diff --git a/doc/administration/sidekiq/sidekiq_memory_killer.md b/doc/administration/sidekiq/sidekiq_memory_killer.md index 12381808523..bbf95bc45ce 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: Memory -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +group: Application Performance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq MemoryKiller **(FREE SELF)** @@ -32,26 +32,12 @@ run as a process group leader (for example, using `chpst -P`). If using Omnibus The MemoryKiller is controlled using environment variables. -- `SIDEKIQ_DAEMON_MEMORY_KILLER`: defaults to 1. When set to 0, the MemoryKiller - works in _legacy_ mode. Otherwise, the MemoryKiller works in _daemon_ mode. - - In _legacy_ mode, the MemoryKiller checks the Sidekiq process RSS - ([Resident Set Size](https://github.com/mperham/sidekiq/wiki/Memory#rss)) - after each job. - - In _daemon_ mode, the MemoryKiller checks the Sidekiq process RSS every 3 seconds - (defined by `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL`). - - `SIDEKIQ_MEMORY_KILLER_MAX_RSS` (KB): if this variable is set, and its value is greater than 0, the MemoryKiller is enabled. Otherwise the MemoryKiller is disabled. `SIDEKIQ_MEMORY_KILLER_MAX_RSS` defines the Sidekiq process allowed RSS. - In _legacy_ mode, if the Sidekiq process exceeds the allowed RSS then an irreversible - delayed graceful restart is triggered. The restart of Sidekiq happens - after `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` seconds. - - In _daemon_ mode, if the Sidekiq process exceeds the allowed RSS for longer than + If the Sidekiq process exceeds the allowed RSS for longer than `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` the graceful restart is triggered. If the Sidekiq process go below the allowed RSS within `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`, the restart is aborted. @@ -59,11 +45,11 @@ The MemoryKiller is controlled using environment variables. The default value for Omnibus packages is set [in the Omnibus GitLab repository](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb). -- `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` (KB): is used by _daemon_ mode. If the Sidekiq +- `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` (KB): If the Sidekiq process RSS (expressed in kilobytes) exceeds `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS`, an immediate graceful restart of Sidekiq is triggered. -- `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL`: used in _daemon_ mode to define how +- `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL`: Define how often to check process RSS, default to 3 seconds. - `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`: defaults to 900 seconds (15 minutes). diff --git a/doc/administration/sidekiq/sidekiq_troubleshooting.md b/doc/administration/sidekiq/sidekiq_troubleshooting.md index 9bc8e473409..d2afe171e9c 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/engineering/ux/technical-writing/#assignments +info: To 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 Sidekiq **(FREE SELF)** @@ -306,7 +306,7 @@ end ### Remove Sidekiq jobs for given parameters (destructive) The general method to kill jobs conditionally is the following command, which -removes jobs that are queued but not started. Running jobs can not be killed. +removes jobs that are queued but not started. Running jobs cannot be killed. ```ruby queue = Sidekiq::Queue.new('<queue name>') diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md index c9647129104..4e49eef44df 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 61d0b1ec50a..89a571946af 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Snippets settings **(FREE SELF)** diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index a288b19f164..ef89e38be6f 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/administration/system_hooks.md b/doc/administration/system_hooks.md index 0d70744e942..56e73150616 100644 --- a/doc/administration/system_hooks.md +++ b/doc/administration/system_hooks.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index 5a272025987..61fda91ba71 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform state administration **(FREE)** diff --git a/doc/administration/timezone.md b/doc/administration/timezone.md index 93419751251..b0dc995c684 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Changing your time zone **(FREE SELF)** @@ -27,7 +27,7 @@ This Rake task does not list time zones in TZInfo format required by Omnibus Git GitLab defaults its time zone to UTC. It has a global time zone configuration parameter in `/etc/gitlab/gitlab.rb`. -To obtain a list of time zones, log in to your GitLab application server and run a command that generates a list of time zones in TZInfo format for the server. For example, install `timedatectl` and run `timedatectl list-timezones`. +To obtain a list of time zones, sign in to your GitLab application server and run a command that generates a list of time zones in TZInfo format for the server. For example, install `timedatectl` and run `timedatectl list-timezones`. To update, add the time zone that best applies to your location. For example: diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md index faddf12b97d..32b07d8c4af 100644 --- a/doc/administration/troubleshooting/diagnostics_tools.md +++ b/doc/administration/troubleshooting/diagnostics_tools.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -26,4 +26,4 @@ and summarize raw `strace` data. ## `kubesos` -The [`kubesos`](https://gitlab.com/gitlab-com/support/toolbox/kubesos/) utility retrieves GitLab cluster configuration and logs from GitLab Cloud Native chart deployments. +The [`kubesos`](https://gitlab.com/gitlab-com/support/toolbox/kubesos/) utility retrieves GitLab cluster configuration and logs from GitLab Helm chart deployments. diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 40bb15ecb70..20ce52a9094 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Rails Console Cheat Sheet **(FREE SELF)** @@ -62,308 +62,6 @@ Notify.test_email(e, "Test email for #{n}", 'Test email').deliver_now Notify.test_email(u.email, "Test email for #{u.name}", 'Test email').deliver_now ``` -## Open object in `irb` - -Sometimes it is easier to go through a method if you are in the context of the object. You can shim into the namespace of `Object` to let you open `irb` in the context of any object: - -```ruby -Object.define_method(:irb) { binding.irb } - -project = Project.last -# => #<Project id:2537 root/discard>> -project.irb -# Notice new context -irb(#<Project>)> web_url -# => "https://gitlab-example/root/discard" -``` - -## View all keys in cache - -```ruby -Rails.cache.instance_variable_get(:@data).keys -``` - -## Profile a page - -```ruby -url = '<url/of/the/page>' - -# Before 11.6.0 -logger = Logger.new($stdout) -admin_token = User.find_by_username('<admin-username>').personal_access_tokens.first.token -app.get("#{url}/?private_token=#{admin_token}") - -# From 11.6.0 -admin = User.find_by_username('<admin-username>') -Gitlab::Profiler.with_user(admin) { app.get(url) } -``` - -## Using the GitLab profiler inside console (used as of 10.5) - -```ruby -logger = Logger.new($stdout) -admin = User.find_by_username('<admin-username>') -Gitlab::Profiler.profile('<url/of/the/page>', logger: logger, user: admin) -``` - -## Time an operation - -```ruby -# A single operation -Benchmark.measure { <operation> } - -# A breakdown of multiple operations -Benchmark.bm do |x| - x.report(:label1) { <operation_1> } - x.report(:label2) { <operation_2> } -end -``` - -## Projects - -### Clear a project's cache - -```ruby -ProjectCacheWorker.perform_async(project.id) -``` - -### Expire the .exists? cache - -```ruby -project.repository.expire_exists_cache -``` - -### Make all projects private - -```ruby -Project.update_all(visibility_level: 0) -``` - -### Find projects that are pending deletion - -```ruby -# -# This section lists all the projects which are pending deletion -# -projects = Project.where(pending_delete: true) -projects.each do |p| - puts "Project ID: #{p.id}" - puts "Project name: #{p.name}" - puts "Repository path: #{p.repository.full_path}" -end - -# -# Assign a user (the root user does) -# -user = User.find_by_username('root') - -# -# For each project listed repeat these two commands -# - -# Find the project, update the xxx-changeme values from above -project = Project.find_by_full_path('group-changeme/project-changeme') - -# Immediately delete the project -::Projects::DestroyService.new(project, user, {}).execute -``` - -### Destroy a project - -```ruby -project = Project.find_by_full_path('<project_path>') -user = User.find_by_username('<username>') -ProjectDestroyWorker.perform_async(project.id, user.id, {}) -# or ProjectDestroyWorker.new.perform(project.id, user.id, {}) -# or Projects::DestroyService.new(project, user).execute -``` - -If this fails, display why it doesn't work with: - -```ruby -project = Project.find_by_full_path('<project_path>') -project.delete_error -``` - -### Remove fork relationship manually - -```ruby -p = Project.find_by_full_path('<project_path>') -u = User.find_by_username('<username>') -::Projects::UnlinkForkService.new(p, u).execute -``` - -### Make a project read-only (can only be done in the console) - -```ruby -# Make a project read-only -project.repository_read_only = true; project.save - -# OR -project.update!(repository_read_only: true) -``` - -### Transfer project from one namespace to another - -```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) -``` - -### Bulk update service integration password for _all_ projects - -For example, change the Jira user's password for all projects that have the Jira -integration active: - -```ruby -p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN services s ON p.id = s.project_id WHERE s.type = 'JiraService' AND s.active = true") - -p.each do |project| - project.jira_integration.update_attribute(:password, '<your-new-password>') -end -``` - -### Bulk update push rules for _all_ projects - -For example, enable **Check whether the commit author is a GitLab user** and **Do not allow users to remove Git tags with `git push`** checkboxes, and create a filter for allowing commits from a specific email domain only: - -``` ruby -Project.find_each do |p| - pr = p.push_rule || PushRule.new(project: p) - # Check whether the commit author is a GitLab user - pr.member_check = true - # Do not allow users to remove Git tags with `git push` - pr.deny_delete_tag = true - # Commit author's email - pr.author_email_regex = '@domain\.com$' - pr.save! -end -``` - -### Bulk update to change all the Jira integrations to Jira instance-level values - -To change all Jira project to use the instance-level integration settings: - -1. In a Rails console: - - ```ruby - jira_integration_instance_id = Integrations::Jira.find_by(instance: true).id - Integrations::Jira.where(active: true, instance: false, template: false, inherit_from_id: nil).find_each do |integration| - integration.update_attribute(:inherit_from_id, jira_integration_instance_id) - end - ``` - -1. Modify and save again the instance-level integration from the UI to propagate the changes to all the group-level and project-level integrations. - -### Check if Jira Cloud is linked to a namespace - -```ruby -JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup')) -``` - -### Check if Jira Cloud is linked to a project - -```ruby -Project.find_by_full_path('path/to/project').jira_subscription_exists? -``` - -### Check if Jira Cloud URL is linked to any namespace - -```ruby -installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net") -installation.subscriptions -``` - -### Bulk update to disable the Slack Notification service - -To disable notifications for all projects that have Slack service enabled, do: - -```ruby -# Grab all projects that have the Slack notifications enabled -p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN services s ON p.id = s.project_id WHERE s.type = 'SlackService' AND s.active = true") - -# Disable the service on each of the projects that were found. -p.each do |project| - project.slack_service.update_attribute(:active, false) -end -``` - -### Incorrect repository statistics shown in the GUI - -After [reducing a repository size with third-party tools](../../user/project/repository/reducing_the_repo_size_using_git.md) -the displayed size may still show old sizes or commit numbers. To force an update, do: - -```ruby -p = Project.find_by_full_path('<namespace>/<project>') -pp p.statistics -p.statistics.refresh! -pp p.statistics -# compare with earlier values - -# check the total artifact storage space separately -builds_with_artifacts = p.builds.with_downloadable_artifacts.all - -artifact_storage = 0 -builds_with_artifacts.find_each do |build| - artifact_storage += build.artifacts_size -end - -puts "#{artifact_storage} bytes" -``` - -### Identify deploy keys associated with blocked and non-member users - -When the user who created a deploy key is blocked or removed from the project, the key -can no longer be used to push to protected branches in a private project (see [issue #329742](https://gitlab.com/gitlab-org/gitlab/-/issues/329742)). -The following script identifies unusable deploy keys: - -```ruby -ghost_user_id = User.ghost.id - -DeployKeysProject.with_write_access.find_each do |deploy_key_mapping| - project = deploy_key_mapping.project - deploy_key = deploy_key_mapping.deploy_key - user = deploy_key.user - - access_checker = Gitlab::DeployKeyAccess.new(deploy_key, container: project) - - # can_push_for_ref? tests if deploy_key can push to default branch, which is likely to be protected - can_push = access_checker.can_do_action?(:push_code) - can_push_to_default = access_checker.can_push_for_ref?(project.repository.root_ref) - - next if access_checker.allowed? && can_push && can_push_to_default - - if user.nil? || user.id == ghost_user_id - username = 'none' - state = '-' - else - username = user.username - user_state = user.state - end - - puts "Deploy key: #{deploy_key.id}, Project: #{project.full_path}, Can push?: " + (can_push ? 'YES' : 'NO') + - ", Can push to default branch #{project.repository.root_ref}?: " + (can_push_to_default ? 'YES' : 'NO') + - ", User: #{username}, User state: #{user_state}" -end -``` - -### Find projects using an SQL query - -Find and store an array of projects based on an SQL query: - -```ruby -# Finds projects that end with '%ject' -projects = Project.find_by_sql("SELECT * FROM projects WHERE name LIKE '%ject'") -=> [#<Project id:12 root/my-first-project>>, #<Project id:13 root/my-second-project>>] -``` - ## Imports and exports ### Import a project @@ -435,37 +133,6 @@ repeat the above procedure after, and report the output to [GitLab Support](https://about.gitlab.com/support/). -## Repository - -### Search sequence of pushes to a repository - -If it seems that a commit has gone "missing", search the sequence of pushes to a repository. -[This StackOverflow article](https://stackoverflow.com/questions/13468027/the-mystery-of-the-missing-commit-across-merges) -describes how you can end up in this state without a force push. Another cause can be a misconfigured [server hook](../server_hooks.md) that changes a HEAD ref via a `git reset` operation. - -If you look at the output from the sample code below for the target branch, you -see a discontinuity in the from/to commits as you step through the output. The `commit_from` of each new push should equal the `commit_to` of the previous push. A break in that sequence indicates one or more commits have been "lost" from the repository history. - -The following example checks the last 100 pushes and prints the `commit_from` and `commit_to` entries: - -```ruby -p = Project.find_by_full_path('u/p') -p.events.pushed_action.last(100).each do |e| - printf "%-20.20s %8s...%8s (%s) -", e.push_event_payload[:ref], e.push_event_payload[:commit_from], e.push_event_payload[:commit_to], e.author.try(:username) -end -``` - -Example output showing break in sequence at line 4: - -```plaintext -master f21b07713251e04575908149bdc8ac1f105aabc3...6bc56c1f46244792222f6c85b11606933af171de (root) -master 6bc56c1f46244792222f6c85b11606933af171de...132da6064f5d3453d445fd7cb452b148705bdc1b (root) -master 132da6064f5d3453d445fd7cb452b148705bdc1b...a62e1e693150a2e46ace0ce696cd4a52856dfa65 (root) -master 58b07b719a4b0039fec810efa52f479ba1b84756...f05321a5b5728bd8a89b7bf530aa44043c951dce (root) -master f05321a5b5728bd8a89b7bf530aa44043c951dce...7d02e575fd790e76a3284ee435368279a5eb3773 (root) -``` - ## Mirrors ### Find mirrors with "bad decrypt" errors @@ -474,36 +141,7 @@ This content has been converted to a Rake task, see [verify database values can ### Transfer mirror users and tokens to a single service account -Use case: If you have multiple users using their own GitHub credentials to set up -repository mirroring, mirroring breaks when people leave the company. Use this -script to migrate disparate mirroring users and tokens into a single service account: - -```ruby -svc_user = User.find_by(username: 'ourServiceUser') -token = 'githubAccessToken' - -Project.where(mirror: true).each do |project| - import_url = project.import_url - - # The url we want is https://token@project/path.git - repo_url = if import_url.include?('@') - # Case 1: The url is something like https://23423432@project/path.git - import_url.split('@').last - elsif import_url.include?('//') - # Case 2: The url is something like https://project/path.git - import_url.split('//').last - end - - next unless repo_url - - final_url = "https://#{token}@#{repo_url}" - - project.mirror_user = svc_user - project.import_url = final_url - project.username_only_import_url = final_url - project.save -end -``` +This content has been moved to [Troubleshooting Repository mirroring](../../user/project/repository/mirror/index.md#transfer-mirror-users-and-tokens-to-a-single-service-account-in-rails-console). ## Users @@ -627,147 +265,6 @@ group = Group.find_by_full_path 'group' user.max_member_access_for_group group.id ``` -## Groups - -### Transfer group to another location - -```ruby -user = User.find_by_username('<username>') -group = Group.find_by_name("<group_name>") -parent_group = Group.find_by(id: "<group_id>") -service = ::Groups::TransferService.new(group, user) -service.execute(parent_group) -``` - -### Count unique users in a group and subgroups - -```ruby -group = Group.find_by_path_or_name("groupname") -members = [] -for member in group.members_with_descendants - members.push(member.user_name) -end - -members.uniq.length -``` - -```ruby -group = Group.find_by_path_or_name("groupname") - -# Count users from subgroup and up (inherited) -group.members_with_parents.count - -# Count users from the parent group and down (specific grants) -parent.members_with_descendants.count -``` - -### Find groups that are pending deletion - -```ruby -# -# This section lists all the groups which are pending deletion -# -Group.all.each do |g| - if g.marked_for_deletion? - puts "Group ID: #{g.id}" - puts "Group name: #{g.name}" - puts "Group path: #{g.full_path}" - end -end -``` - -### Delete a group - -```ruby -GroupDestroyWorker.perform_async(group_id, user_id) -``` - -### Modify group project creation - -```ruby -# Project creation levels: 0 - No one, 1 - Maintainers, 2 - Developers + Maintainers -group = Group.find_by_path_or_name('group-name') -group.project_creation_level=0 -``` - -### Modify group - disable 2FA requirement - -WARNING: -When disabling the 2FA Requirement on a subgroup, the whole parent group (including all subgroups) is affected by this change. - -```ruby -group = Group.find_by_path_or_name('group-name') -group.require_two_factor_authentication=false -group.save -``` - -### Check and toggle a feature for all projects in a group - -```ruby -projects = Group.find_by_name('_group_name').projects -projects.each do |p| - state = p.<feature-name>? - - if state - puts "#{p.name} has <feature-name> already enabled. Skipping..." - else - puts "#{p.name} didn't have <feature-name> enabled. Enabling..." - p.project_feature.update!(builds_access_level: ProjectFeature::PRIVATE) - end -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). - -### Get all error messages associated with groups, subgroups, members, and requesters - -Collect error messages associated with groups, subgroups, members, and requesters. This -captures error messages that may not appear in the Web interface. This can be especially helpful -for troubleshooting issues with [LDAP group sync](../auth/ldap/ldap_synchronization.md#group-sync) -and unexpected behavior with users and their membership in groups and subgroups. - -```ruby -# Find the group and subgroup -group = Group.find_by_full_path("parent_group") -subgroup = Group.find_by_full_path("parent_group/child_group") - -# Group and subgroup errors -group.valid? -group.errors.map(&:full_messages) - -subgroup.valid? -subgroup.errors.map(&:full_messages) - -# Group and subgroup errors for the members AND requesters -group.requesters.map(&:valid?) -group.requesters.map(&:errors).map(&:full_messages) -group.members.map(&:valid?) -group.members.map(&:errors).map(&:full_messages) -group.members_and_requesters.map(&:errors).map(&:full_messages) - -subgroup.requesters.map(&:valid?) -subgroup.requesters.map(&:errors).map(&:full_messages) -subgroup.members.map(&:valid?) -subgroup.members.map(&:errors).map(&:full_messages) -subgroup.members_and_requesters.map(&:errors).map(&:full_messages) -``` - -## Routes - -### Remove redirecting routes - -See <https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41758#note_54828133>. - -```ruby -path = 'foo' -conflicting_permanent_redirects = RedirectRoute.matching_path_and_descendants(path) - -# Check that conflicting_permanent_redirects is as expected -conflicting_permanent_redirects.destroy_all -``` - ## Merge requests ### Close a merge request @@ -972,37 +469,7 @@ License.select(&TYPE).each(&:destroy!) ### Registry Disk Space Usage by Project -As a GitLab administrator, you may want to reduce disk space consumption. -A common culprit is Docker Registry images that are no longer in use. To find -the storage broken down by each project, run the following in the -[GitLab Rails console](../operations/rails_console.md): - -```ruby -projects_and_size = [["project_id", "creator_id", "registry_size_bytes", "project path"]] -# You need to specify the projects that you want to look through. You can get these in any manner. -projects = Project.last(100) - -projects.each do |p| - project_total_size = 0 - container_repositories = p.container_repositories - - container_repositories.each do |c| - c.tags.each do |t| - project_total_size = project_total_size + t.total_size unless t.total_size.nil? - end - end - - if project_total_size > 0 - projects_and_size << [p.project_id, p.creator.id, project_total_size, p.full_path] - end -end - -# projects_and_size is filled out now -# maybe print it as comma separated output? -projects_and_size.each do |ps| - puts "%s,%s,%s,%s" % ps -end -``` +Find this content in the [Container Registry troubleshooting documentation](../packages/container_registry.md#registry-disk-space-usage-by-project). ### Run the Cleanup policy now @@ -1012,14 +479,6 @@ Find this content in the [Container Registry troubleshooting documentation](../p This content has been moved to [Troubleshooting Sidekiq](sidekiq.md). -## Redis - -### Connect to Redis (omnibus) - -```shell -/opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket -``` - ## LFS ### Get information about LFS objects and associated project @@ -1124,152 +583,19 @@ There is an [issue to implement this functionality in the Admin UI](https://gitl ### Artifacts -#### Find failed artifacts - -```ruby -Geo::JobArtifactRegistry.failed -``` - -#### Get a count of the synced artifacts - -```ruby -Geo::JobArtifactRegistry.synced.count -``` - -#### Find `ID` of synced artifacts that are missing on primary - -```ruby -Geo::JobArtifactRegistry.synced.missing_on_primary.pluck(:artifact_id) -``` +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#find-failed-artifacts). ### Repository verification failures -#### Get the number of verification failed repositories - -```ruby -Geo::ProjectRegistry.verification_failed('repository').count -``` - -#### Find the verification failed repositories - -```ruby -Geo::ProjectRegistry.verification_failed('repository') -``` - -### Find repositories that failed to sync - -```ruby -Geo::ProjectRegistry.sync_failed('repository') -``` +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#repository-verification-failures). ### Resync repositories -#### Queue up all repositories for resync. Sidekiq handles each sync - -```ruby -Geo::ProjectRegistry.update_all(resync_repository: true, resync_wiki: true) -``` - -#### Sync individual repository now - -```ruby -project = Project.find_by_full_path('<group/project>') - -Geo::RepositorySyncService.new(project).execute -``` +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#resync-repositories). ### Blob types -- `Ci::JobArtifact` -- `Ci::PipelineArtifact` -- `LfsObject` -- `MergeRequestDiff` -- `Packages::PackageFile` -- `PagesDeployment` -- `Terraform::StateVersion` -- `Upload` - -`Packages::PackageFile` is used in the following examples, but things generally work the same for the other Blob types. - -#### The Replicator - -The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it): - -```ruby -model_record = Packages::PackageFile.last -model_record.replicator.registry.replicator.model_record # just showing that these methods exist -``` - -#### Replicate a package file, synchronously, given an ID - -```ruby -model_record = Packages::PackageFile.find(id) -model_record.replicator.send(:download) -``` - -#### Replicate a package file, synchronously, given a registry ID - -```ruby -registry = Geo::PackageFileRegistry.find(registry_id) -registry.replicator.send(:download) -``` - -#### Verify package files on the secondary manually - -This iterates over all package files on the secondary, looking at the -`verification_checksum` stored in the database (which came from the primary) -and then calculate this value on the secondary to check if they match. This -does not change anything in the UI: - -```ruby -# Run on secondary -status = {} - -Packages::PackageFile.find_each do |package_file| - primary_checksum = package_file.verification_checksum - secondary_checksum = Packages::PackageFile.hexdigest(package_file.file.path) - verification_status = (primary_checksum == secondary_checksum) - - status[verification_status.to_s] ||= [] - status[verification_status.to_s] << package_file.id -end - -# Count how many of each value we get -status.keys.each {|key| puts "#{key} count: #{status[key].count}"} - -# See the output in its entirety -status -``` - -### Repository types newer than project/wiki repositories - -- `SnippetRepository` -- `GroupWikiRepository` - -`SnippetRepository` is used in the examples below, but things generally work the same for the other Repository types. - -#### The Replicator - -The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it). - -```ruby -model_record = SnippetRepository.last -model_record.replicator.registry.replicator.model_record # just showing that these methods exist -``` - -#### Replicate a snippet repository, synchronously, given an ID - -```ruby -model_record = SnippetRepository.find(id) -model_record.replicator.send(:sync_repository) -``` - -#### Replicate a snippet repository, synchronously, given a registry ID - -```ruby -registry = Geo::SnippetRepositoryRegistry.find(registry_id) -registry.replicator.send(:sync_repository) -``` +Moved to [Geo replication troubleshooting](../geo/replication/troubleshooting.md#blob-types). ## Generate Service Ping @@ -1311,3 +637,24 @@ Prints the metrics saved in `conversational_development_index_metrics`. ```shell rake gitlab:usage_data:generate_and_send ``` + +## GraphQL + +Call a [GraphQL](../../api/graphql/getting_started.md) endpoint through the Rails console: + +```ruby +query = <<~EOQ +query securityGetProjects($search: String!) { + projects(search: $search) { + nodes { + path + } + } +} +EOQ + +variables = { "search": "gitlab" } + +result = GitlabSchema.execute(query, variables: variables, context: { current_user: current_user }) +result.to_h +``` diff --git a/doc/administration/troubleshooting/index.md b/doc/administration/troubleshooting/index.md index 429dc79e95f..ce548f9e100 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/engineering/ux/technical-writing/#assignments +info: To 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 a GitLab installation **(FREE SELF)** diff --git a/doc/administration/troubleshooting/linux_cheat_sheet.md b/doc/administration/troubleshooting/linux_cheat_sheet.md index c1a428018c2..0c6fcd31d1d 100644 --- a/doc/administration/troubleshooting/linux_cheat_sheet.md +++ b/doc/administration/troubleshooting/linux_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index 9e3d3d47a10..8a76d4f88ab 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PostgreSQL **(FREE SELF)** @@ -109,7 +109,7 @@ This section is for links to information elsewhere in the GitLab documentation. - Deploying PostgreSQL on Azure Database for PostgreSQL - Flexible Server may result in an error stating `extension "btree_gist" is not allow-listed for "azure_pg_admin" users in Azure Database for PostgreSQL` - To resolve the above error, [allow-list the extension](https://docs.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions) prior to install. + To resolve the above error, [allow-list the extension](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-extensions#how-to-use-postgresql-extensions) prior to install. ## Support topics diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md index c5f3f0ed8d1..245ff9f4982 100644 --- a/doc/administration/troubleshooting/ssl.md +++ b/doc/administration/troubleshooting/ssl.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -50,7 +50,7 @@ following issues: - `openssl` works when specifying the path to the certificate: ```shell - /opt/gitlab/embedded/bin/openssl s_client -CAfile /root/my-cert.crt -connect gitlab.domain.tld:443 + /opt/gitlab/embedded/bin/openssl s_client -CAfile /root/my-cert.crt -connect gitlab.domain.tld:443 -servername gitlab.domain.tld ``` If you have the previously described issues, add your certificate to diff --git a/doc/administration/troubleshooting/test_environments.md b/doc/administration/troubleshooting/test_environments.md index d240103a51c..a249d5bd133 100644 --- a/doc/administration/troubleshooting/test_environments.md +++ b/doc/administration/troubleshooting/test_environments.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 2dd8f1ed819..f0def7320cc 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads administration **(FREE SELF)** diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index 0a3f351c695..a767132db0f 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.md @@ -1,17 +1,24 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Modify global user settings **(FREE SELF)** GitLab administrators can modify user settings for the entire GitLab instance. -## Prevent new users from creating top-level groups +## Use configuration files to prevent new users from creating top-level groups By default, new users can create top-level groups. To disable new users' -ability to create top-level groups (does not affect existing users' setting): +ability to create top-level groups (does not affect existing users' setting), GitLab administrators can modify this setting: + +- In GitLab 15.5 and later, using either: + - The [GitLab UI](../user/admin_area/settings/account_and_limit_settings.md#prevent-users-from-creating-top-level-groups). + - The [application setting API](../api/settings.md#change-application-settings). +- In GitLab 15.4 and earlier, in a configuration file by following the steps in this section. + +To disable new users' ability to create top-level groups using the configuation file: **Omnibus GitLab installations** diff --git a/doc/administration/whats-new.md b/doc/administration/whats-new.md index d8003d579ac..d9c8a991577 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/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +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. --- # What's new **(FREE)** diff --git a/doc/administration/wikis/index.md b/doc/administration/wikis/index.md index 01c175e014e..f3442e23160 100644 --- a/doc/administration/wikis/index.md +++ b/doc/administration/wikis/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 adaae78f1b5..9eab35a32d8 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Group and project access requests API **(FREE)** diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index 2b3cce80257..e5d60587dea 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 2323cecfd6a..bf3d6287341 100644 --- a/doc/api/alert_management_alerts.md +++ b/doc/api/alert_management_alerts.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Alert Management alerts API **(FREE)** @@ -79,7 +79,7 @@ Example response: ## Update metric image ```plaintext -PUT /projects/:id/alert_management_alerts/:alert_iid/metric_image/:image_id +PUT /projects/:id/alert_management_alerts/:alert_iid/metric_images/:image_id ``` | Attribute | Type | Required | Description | diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 7d613852d23..531d679a34d 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # REST API resources **(FREE)** @@ -99,7 +99,7 @@ The following API resources are available in the project context: | [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | | [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | | [Tags](tags.md) | `/projects/:id/repository/tags` | -| [Terraform modules](packages/terraform-modules.md) | `/projects/:id/packages/terraform/mdoules` (also available standalone) | +| [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)** | `/projects/:id/merge_requests/:merge_request_id/visual_review_discussions` | | [Vulnerabilities](vulnerabilities.md) **(ULTIMATE)** | `/vulnerabilities/:id` | diff --git a/doc/api/appearance.md b/doc/api/appearance.md index 7ad79fd66fe..f8926f8a91d 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 aeb6a0452c5..f7b646d2351 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Applications API **(FREE)** diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md index 5bff3cf49fc..db89262c84f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit Events API **(PREMIUM)** diff --git a/doc/api/avatar.md b/doc/api/avatar.md index bc47d3a4d9e..d6b9c9f70b7 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Avatar API **(FREE)** diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 5b350dd88c6..ca6761ed6be 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Award emoji API **(FREE)** diff --git a/doc/api/boards.md b/doc/api/boards.md index ab9bd4ea3f1..79f5cca4a0d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project issue boards API **(FREE)** diff --git a/doc/api/branches.md b/doc/api/branches.md index 4e2a0306845..0c9df88cf85 100644 --- a/doc/api/branches.md +++ b/doc/api/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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -84,7 +84,7 @@ Parameters: | Attribute | Type | Required | Description | |:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `branch` | string | yes | Name of the branch. | +| `branch` | string | yes | [URL-encoded name](index.md#namespaced-path-encoding) of the branch. | Example request: diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index 6c95bf2fda5..cc777a8bf53 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 913dc6ce4f1..e18a77df6df 100644 --- a/doc/api/bulk_imports.md +++ b/doc/api/bulk_imports.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Migrations (Bulk Imports) API **(FREE)** @@ -150,11 +150,14 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab "updated_at": "2021-06-24T10:40:46.590Z", "failures": [ { - "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline", - "pipeline_step": "extractor", + "relation": "group", + "step": "extractor", + "exception_message": "Error!", "exception_class": "Exception", "correlation_id_value": "dfcf583058ed4508e4c7c617bd7f0edd", - "created_at": "2021-06-24T10:40:46.495Z" + "created_at": "2021-06-24T10:40:46.495Z", + "pipeline_class": "BulkImports::Groups::Pipelines::GroupPipeline", + "pipeline_step": "extractor" } ] } diff --git a/doc/api/cluster_agents.md b/doc/api/cluster_agents.md index 16eed70fd48..718871884fb 100644 --- a/doc/api/cluster_agents.md +++ b/doc/api/cluster_agents.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Agents API **(FREE)** diff --git a/doc/api/commits.md b/doc/api/commits.md index 3b9a72e1568..f08fe5ba881 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Commits API **(FREE)** diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index f23641abb4f..6e8911df098 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Container Registry API **(FREE)** diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index e15ed4bceee..5ce2aa34744 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom Attributes API **(FREE SELF)** diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 85ad6085fb2..dce928046bc 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependencies API **(ULTIMATE)** @@ -49,18 +49,34 @@ Example response: "version": "5.0.1", "package_manager": "bundler", "dependency_file_path": "Gemfile.lock", - "vulnerabilities": [{ - "name": "DDoS", - "severity": "unknown" - }] + "vulnerabilities": [ + { + "name": "DDoS", + "severity": "unknown", + "id": 144827, + "url": "https://gitlab.example.com/group/project/-/security/vulnerabilities/144827" + } + ], + "licenses": [ + { + "name": "MIT", + "url": "https://opensource.org/licenses/MIT" + } + ] }, { - "name": "hanami", - "version": "1.3.1", - "package_manager": "bundler", - "dependency_file_path": "Gemfile.lock", - "vulnerabilities": [] - } + "name": "hanami", + "version": "1.3.1", + "package_manager": "bundler", + "dependency_file_path": "Gemfile.lock", + "vulnerabilities": [], + "licenses": [ + { + "name": "MIT", + "url": "https://opensource.org/licenses/MIT" + } + ] + } ] ``` diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index 028584e69ff..05e144f5810 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Proxy API **(FREE)** diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 40641c6e2f7..bc5852db457 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy keys API **(FREE)** diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index ace7e55f882..5c4c99f3ba3 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy Tokens API **(FREE)** diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 8b99c21a385..9618d57013f 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 60ce10590e1..e82f6927e0b 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 543b6583fde..d902f5eb91f 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/environments.md b/doc/api/environments.md index 3f5f711e10b..0f969ea4fd3 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -342,6 +342,7 @@ It schedules for deletion multiple environments that have already been [stopped](../ci/environments/index.md#stop-an-environment) and are [in the review app folder](../ci/review_apps/index.md). The actual deletion is performed after 1 week from the time of execution. +By default, it only deletes environments 30 days or older. You can change this default using the `before` parameter. ```plaintext DELETE /projects/:id/environments/review_apps diff --git a/doc/api/epic_issues.md b/doc/api/epic_issues.md index dfc54cd81aa..4bbd0b21136 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epic Issues API **(PREMIUM)** diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index d87b44f43a7..91560512ffc 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epic Links API **(ULTIMATE)** diff --git a/doc/api/epics.md b/doc/api/epics.md index de20af08915..85a127696f6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epics API **(PREMIUM)** diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index dbf832b301f..c8f795ed88c 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Error Tracking settings API **(FREE)** diff --git a/doc/api/events.md b/doc/api/events.md index e4490459030..632f573be47 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Events API **(FREE)** diff --git a/doc/api/experiments.md b/doc/api/experiments.md index 6393a358e51..8e34868b282 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Experiments API (GitLab team only) **(FREE SAAS)** diff --git a/doc/api/feature_flag_specs.md b/doc/api/feature_flag_specs.md index f2853efc5f2..b549c790aaa 100644 --- a/doc/api/feature_flag_specs.md +++ b/doc/api/feature_flag_specs.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Feature Flag Specs API **(PREMIUM)** diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index 46ed44d8808..ef65da64668 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Feature flag user lists API **(FREE)** diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index b00917674b0..c4d766a6319 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -1,19 +1,19 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Feature Flags API **(FREE)** +# Feature flags API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in GitLab Premium 12.5. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Free in 13.5. -API for accessing resources of [GitLab Feature Flags](../operations/feature_flags.md). +API for accessing resources of [GitLab feature flags](../operations/feature_flags.md). -Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag API. +Users with Developer or higher [permissions](../user/permissions.md) can access the feature flag API. -## Feature Flags pagination +## Feature flags pagination By default, `GET` requests return 20 results at a time because the API results are [paginated](index.md#pagination). @@ -144,7 +144,7 @@ POST /projects/:id/feature_flags | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `name` | string | yes | The name of the feature flag. | -| `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit or set to `legacy_flag` to create a Legacy Feature Flag. | +| `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit or set to `legacy_flag` to create a Legacy feature flag. | | `description` | string | no | The description of the feature flag. | | `active` | boolean | no | The active state of the flag. Defaults to true. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | | `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). | diff --git a/doc/api/features.md b/doc/api/features.md index f006fa07188..6f3af683020 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 6dc4e8745d6..36d069df607 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index b5b920ec0cd..fe25b6661a0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo Nodes API **(PREMIUM SELF)** @@ -339,10 +339,6 @@ Example response: "job_artifacts_failed_count": null, "job_artifacts_synced_missing_on_primary_count": 0, "job_artifacts_synced_in_percentage": "0.00%", - "container_repositories_count": 3, - "container_repositories_synced_count": null, - "container_repositories_failed_count": null, - "container_repositories_synced_in_percentage": "0.00%", "design_repositories_count": 3, "design_repositories_synced_count": null, "design_repositories_failed_count": null, @@ -507,7 +503,13 @@ Example response: "ci_secure_files_verification_failed_count": 0, "ci_secure_files_synced_in_percentage": "100.00%", "ci_secure_files_verified_in_percentage": "100.00%", - "ci_secure_files_synced_missing_on_primary_count": 0, + "ci_secure_files_synced_missing_on_primary_count": 0, + "container_repositories_count": 5, + "container_repositories_synced_count": 5, + "container_repositories_failed_count": 0, + "container_repositories_registry_count": 5, + "container_repositories_synced_in_percentage": "100.00%", + "container_repositories_synced_missing_on_primary_count": 0, }, { "geo_node_id": 2, @@ -533,10 +535,6 @@ Example response: "job_artifacts_failed_count": 1, "job_artifacts_synced_missing_on_primary_count": 0, "job_artifacts_synced_in_percentage": "50.00%", - "container_repositories_count": 3, - "container_repositories_synced_count": null, - "container_repositories_failed_count": null, - "container_repositories_synced_in_percentage": "0.00%", "design_repositories_count": 3, "design_repositories_synced_count": null, "design_repositories_failed_count": null, @@ -677,6 +675,12 @@ Example response: "job_artifacts_synced_in_percentage": "100.00%", "job_artifacts_verified_in_percentage": "100.00%", "job_artifacts_synced_missing_on_primary_count": 0, + "container_repositories_count": 5, + "container_repositories_synced_count": 5, + "container_repositories_failed_count": 0, + "container_repositories_registry_count": 5, + "container_repositories_synced_in_percentage": "100.00%", + "container_repositories_synced_missing_on_primary_count": 0, } ] ``` @@ -718,10 +722,6 @@ Example response: "job_artifacts_failed_count": 1, "job_artifacts_synced_missing_on_primary_count": 0, "job_artifacts_synced_in_percentage": "50.00%", - "container_repositories_count": 3, - "container_repositories_synced_count": null, - "container_repositories_failed_count": null, - "container_repositories_synced_in_percentage": "0.00%", "design_repositories_count": 3, "design_repositories_synced_count": null, "design_repositories_failed_count": null, @@ -856,6 +856,12 @@ Example response: "ci_secure_files_synced_in_percentage": "100.00%", "ci_secure_files_verified_in_percentage": "100.00%", "ci_secure_files_synced_missing_on_primary_count": 0, + "container_repositories_count": 5, + "container_repositories_synced_count": 5, + "container_repositories_failed_count": 0, + "container_repositories_registry_count": 5, + "container_repositories_synced_in_percentage": "100.00%", + "container_repositories_synced_missing_on_primary_count": 0, } ``` diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md index dc7eb10b810..2f96bc5ecdd 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up an Audit Report with GraphQL **(FREE)** diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md index e7fd9837b0f..ea90b02a069 100644 --- a/doc/api/graphql/custom_emoji.md +++ b/doc/api/graphql/custom_emoji.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use custom emojis with GraphQL **(FREE)** diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index 386ef6c403b..20fb2f030f2 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Get started with GitLab GraphQL API **(FREE)** diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index eab48d65742..40e1ed115a3 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL API **(FREE)** diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index cf218d6e2d7..11a60671008 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!--- @@ -226,6 +226,22 @@ Returns [`Iteration`](#iteration). | ---- | ---- | ----------- | | <a id="queryiterationid"></a>`id` | [`IterationID!`](#iterationid) | Find an iteration by its ID. | +### `Query.jobs` + +All jobs on this GitLab instance. + +Returns [`CiJobConnection`](#cijobconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="queryjobsstatuses"></a>`statuses` | [`[CiJobStatus!]`](#cijobstatus) | Filter jobs by status. | + ### `Query.licenseHistoryEntries` Fields related to entries in the license history. @@ -320,7 +336,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="queryprojectsmembership"></a>`membership` | [`Boolean`](#boolean) | Return only projects that the current user is a member of. | | <a id="queryprojectssearch"></a>`search` | [`String`](#string) | Search query, which can be for the project name, a path, or a description. | | <a id="queryprojectssearchnamespaces"></a>`searchNamespaces` | [`Boolean`](#boolean) | Include namespace in project search. | -| <a id="queryprojectssort"></a>`sort` | [`String`](#string) | Sort order of results. Format: '<field_name>_<sort_direction>', for example: 'id_desc' or 'name_asc'. | +| <a id="queryprojectssort"></a>`sort` | [`String`](#string) | Sort order of results. Format: `<field_name>_<sort_direction>`, for example: `id_desc` or `name_asc`. | | <a id="queryprojectstopics"></a>`topics` | [`[String!]`](#string) | Filter projects by topics. | ### `Query.queryComplexity` @@ -640,6 +656,7 @@ Input type: `AdminSidekiqQueuesDeleteJobsInput` | Name | Type | Description | | ---- | ---- | ----------- | | <a id="mutationadminsidekiqqueuesdeletejobsartifactsize"></a>`artifactSize` | [`String`](#string) | Delete jobs matching artifact_size in the context metadata. | +| <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="mutationadminsidekiqqueuesdeletejobscallerid"></a>`callerId` | [`String`](#string) | Delete jobs matching caller_id in the context metadata. | @@ -1011,7 +1028,8 @@ Input type: `CiCdSettingsUpdateInput` | ---- | ---- | ----------- | | <a id="mutationcicdsettingsupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcicdsettingsupdatefullpath"></a>`fullPath` | [`ID!`](#id) | Full Path of the project the settings belong to. | -| <a id="mutationcicdsettingsupdatejobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI job tokens generated in this project have restricted access to resources. | +| <a id="mutationcicdsettingsupdateinboundjobtokenscopeenabled"></a>`inboundJobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in other projects have restricted access to this project. | +| <a id="mutationcicdsettingsupdatejobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in this project have restricted access to other projects. | | <a id="mutationcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for this project. | | <a id="mutationcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | @@ -1989,6 +2007,7 @@ Input type: `DastSiteProfileCreateInput` | <a id="mutationdastsiteprofilecreatefullpath"></a>`fullPath` | [`ID!`](#id) | Project the site profile belongs to. | | <a id="mutationdastsiteprofilecreateprofilename"></a>`profileName` | [`String!`](#string) | Name of the site profile. | | <a id="mutationdastsiteprofilecreaterequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | +| <a id="mutationdastsiteprofilecreatescanfilepath"></a>`scanFilePath` | [`String`](#string) | File Path or URL used as input for the scan method. Will not be saved or updated if `dast_api_scanner` feature flag is disabled. | | <a id="mutationdastsiteprofilecreatescanmethod"></a>`scanMethod` | [`DastScanMethodType`](#dastscanmethodtype) | Scan method by the scanner. Is not saved or updated if `dast_api_scanner` feature flag is disabled. | | <a id="mutationdastsiteprofilecreatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | | <a id="mutationdastsiteprofilecreatetargeturl"></a>`targetUrl` | [`String`](#string) | URL of the target to be scanned. | @@ -2036,6 +2055,7 @@ Input type: `DastSiteProfileUpdateInput` | <a id="mutationdastsiteprofileupdateid"></a>`id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be updated. | | <a id="mutationdastsiteprofileupdateprofilename"></a>`profileName` | [`String!`](#string) | Name of the site profile. | | <a id="mutationdastsiteprofileupdaterequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | +| <a id="mutationdastsiteprofileupdatescanfilepath"></a>`scanFilePath` | [`String`](#string) | File Path or URL used as input for the scan method. Will not be saved or updated if `dast_api_scanner` feature flag is disabled. | | <a id="mutationdastsiteprofileupdatescanmethod"></a>`scanMethod` | [`DastScanMethodType`](#dastscanmethodtype) | Scan method by the scanner. Is not saved or updated if `dast_api_scanner` feature flag is disabled. | | <a id="mutationdastsiteprofileupdatetargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | | <a id="mutationdastsiteprofileupdatetargeturl"></a>`targetUrl` | [`String`](#string) | URL of the target to be scanned. | @@ -2406,6 +2426,24 @@ Input type: `DestroyPackageFilesInput` | <a id="mutationdestroypackagefilesclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationdestroypackagefileserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.destroyPackages` + +Input type: `DestroyPackagesInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdestroypackagesclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdestroypackagesids"></a>`ids` | [`[PackagesPackageID!]!`](#packagespackageid) | Global IDs of the Packages. Max 20. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationdestroypackagesclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationdestroypackageserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.destroySnippet` Input type: `DestroySnippetInput` @@ -2874,6 +2912,7 @@ Input type: `GitlabSubscriptionActivateInput` | ---- | ---- | ----------- | | <a id="mutationgitlabsubscriptionactivateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationgitlabsubscriptionactivateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationgitlabsubscriptionactivatefuturesubscriptions"></a>`futureSubscriptions` | [`[SubscriptionFutureEntry!]`](#subscriptionfutureentry) | Array of future subscriptions. | | <a id="mutationgitlabsubscriptionactivatelicense"></a>`license` | [`CurrentLicense`](#currentlicense) | Current license. | ### `Mutation.groupUpdate` @@ -4141,6 +4180,24 @@ Input type: `PipelineRetryInput` | <a id="mutationpipelineretryerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationpipelineretrypipeline"></a>`pipeline` | [`Pipeline`](#pipeline) | Pipeline after mutation. | +### `Mutation.pipelineScheduleDelete` + +Input type: `PipelineScheduleDeleteInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinescheduledeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinescheduledeleteid"></a>`id` | [`CiPipelineScheduleID!`](#cipipelinescheduleid) | ID of the pipeline schedule to mutate. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationpipelinescheduledeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationpipelinescheduledeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.projectCiCdSettingsUpdate` Input type: `ProjectCiCdSettingsUpdateInput` @@ -4151,7 +4208,8 @@ Input type: `ProjectCiCdSettingsUpdateInput` | ---- | ---- | ----------- | | <a id="mutationprojectcicdsettingsupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationprojectcicdsettingsupdatefullpath"></a>`fullPath` | [`ID!`](#id) | Full Path of the project the settings belong to. | -| <a id="mutationprojectcicdsettingsupdatejobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI job tokens generated in this project have restricted access to resources. | +| <a id="mutationprojectcicdsettingsupdateinboundjobtokenscopeenabled"></a>`inboundJobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in other projects have restricted access to this project. | +| <a id="mutationprojectcicdsettingsupdatejobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in this project have restricted access to other projects. | | <a id="mutationprojectcicdsettingsupdatekeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Indicates if the latest artifact should be kept for this project. | | <a id="mutationprojectcicdsettingsupdatemergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Indicates if merge pipelines are enabled for the project. | | <a id="mutationprojectcicdsettingsupdatemergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Indicates if merge trains are enabled for the project. | @@ -5350,9 +5408,15 @@ Input type: `UpdateNamespacePackageSettingsInput` | <a id="mutationupdatenamespacepackagesettingsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationupdatenamespacepackagesettingsgenericduplicateexceptionregex"></a>`genericDuplicateExceptionRegex` | [`UntrustedRegexp`](#untrustedregexp) | When generic_duplicates_allowed is false, you can publish duplicate packages with names that match this regex. Otherwise, this setting has no effect. | | <a id="mutationupdatenamespacepackagesettingsgenericduplicatesallowed"></a>`genericDuplicatesAllowed` | [`Boolean`](#boolean) | Indicates whether duplicate generic packages are allowed for this namespace. | +| <a id="mutationupdatenamespacepackagesettingslockmavenpackagerequestsforwarding"></a>`lockMavenPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether Maven package forwarding is locked for all descendent namespaces. | +| <a id="mutationupdatenamespacepackagesettingslocknpmpackagerequestsforwarding"></a>`lockNpmPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether npm package forwarding is locked for all descendent namespaces. | +| <a id="mutationupdatenamespacepackagesettingslockpypipackagerequestsforwarding"></a>`lockPypiPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether PyPI package forwarding is locked for all descendent namespaces. | | <a id="mutationupdatenamespacepackagesettingsmavenduplicateexceptionregex"></a>`mavenDuplicateExceptionRegex` | [`UntrustedRegexp`](#untrustedregexp) | When maven_duplicates_allowed is false, you can publish duplicate packages with names that match this regex. Otherwise, this setting has no effect. | | <a id="mutationupdatenamespacepackagesettingsmavenduplicatesallowed"></a>`mavenDuplicatesAllowed` | [`Boolean`](#boolean) | Indicates whether duplicate Maven packages are allowed for this namespace. | +| <a id="mutationupdatenamespacepackagesettingsmavenpackagerequestsforwarding"></a>`mavenPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether Maven package forwarding is allowed for this namespace. | | <a id="mutationupdatenamespacepackagesettingsnamespacepath"></a>`namespacePath` | [`ID!`](#id) | Namespace path where the namespace package setting is located. | +| <a id="mutationupdatenamespacepackagesettingsnpmpackagerequestsforwarding"></a>`npmPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether npm package forwarding is allowed for this namespace. | +| <a id="mutationupdatenamespacepackagesettingspypipackagerequestsforwarding"></a>`pypiPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether PyPI package forwarding is allowed for this namespace. | #### Fields @@ -5630,6 +5694,10 @@ Input type: `VulnerabilityExternalIssueLinkDestroyInput` ### `Mutation.vulnerabilityFindingDismiss` +WARNING: +**Deprecated** in 15.5. +Use VulnerabilityDismiss for vulnerabilities or SecurityFindingDismiss for pipeline findings. + Input type: `VulnerabilityFindingDismissInput` #### Arguments @@ -5818,8 +5886,10 @@ Input type: `WorkItemUpdateInput` | <a id="mutationworkitemupdatehierarchywidget"></a>`hierarchyWidget` | [`WorkItemWidgetHierarchyUpdateInput`](#workitemwidgethierarchyupdateinput) | Input for hierarchy widget. | | <a id="mutationworkitemupdateid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | | <a id="mutationworkitemupdateiterationwidget"></a>`iterationWidget` | [`WorkItemWidgetIterationInput`](#workitemwidgetiterationinput) | Input for iteration widget. | +| <a id="mutationworkitemupdatelabelswidget"></a>`labelsWidget` | [`WorkItemWidgetLabelsUpdateInput`](#workitemwidgetlabelsupdateinput) | Input for labels widget. | | <a id="mutationworkitemupdatestartandduedatewidget"></a>`startAndDueDateWidget` | [`WorkItemWidgetStartAndDueDateUpdateInput`](#workitemwidgetstartandduedateupdateinput) | Input for start and due date widget. | | <a id="mutationworkitemupdatestateevent"></a>`stateEvent` | [`WorkItemStateEvent`](#workitemstateevent) | Close or reopen a work item. | +| <a id="mutationworkitemupdatestatuswidget"></a>`statusWidget` | [`StatusInput`](#statusinput) | Input for status widget. | | <a id="mutationworkitemupdatetitle"></a>`title` | [`String`](#string) | Title of the work item. | | <a id="mutationworkitemupdateweightwidget"></a>`weightWidget` | [`WorkItemWidgetWeightInput`](#workitemwidgetweightinput) | Input for weight widget. | @@ -5858,32 +5928,6 @@ Input type: `WorkItemUpdateTaskInput` | <a id="mutationworkitemupdatetasktask"></a>`task` | [`WorkItem`](#workitem) | Updated task. | | <a id="mutationworkitemupdatetaskworkitem"></a>`workItem` | [`WorkItem`](#workitem) | Updated work item. | -### `Mutation.workItemUpdateWidgets` - -Updates the attributes of a work item's widgets by global ID. Available only when feature flag `work_items` is enabled. - -WARNING: -**Introduced** in 15.1. -This feature is in Alpha. It can be changed or removed at any time. - -Input type: `WorkItemUpdateWidgetsInput` - -#### Arguments - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationworkitemupdatewidgetsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationworkitemupdatewidgetsdescriptionwidget"></a>`descriptionWidget` | [`WorkItemWidgetDescriptionInput`](#workitemwidgetdescriptioninput) | Input for description widget. | -| <a id="mutationworkitemupdatewidgetsid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | - -#### Fields - -| Name | Type | Description | -| ---- | ---- | ----------- | -| <a id="mutationworkitemupdatewidgetsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| <a id="mutationworkitemupdatewidgetserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| <a id="mutationworkitemupdatewidgetsworkitem"></a>`workItem` | [`WorkItem`](#workitem) | Updated work item. | - ## Connections Some types in our schema are `Connection` types - they represent a paginated @@ -6015,6 +6059,29 @@ The edge type for [`AlertManagementIntegration`](#alertmanagementintegration). | <a id="alertmanagementintegrationedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="alertmanagementintegrationedgenode"></a>`node` | [`AlertManagementIntegration`](#alertmanagementintegration) | The item at the end of the edge. | +#### `ApprovalProjectRuleConnection` + +The connection type for [`ApprovalProjectRule`](#approvalprojectrule). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="approvalprojectruleconnectionedges"></a>`edges` | [`[ApprovalProjectRuleEdge]`](#approvalprojectruleedge) | A list of edges. | +| <a id="approvalprojectruleconnectionnodes"></a>`nodes` | [`[ApprovalProjectRule]`](#approvalprojectrule) | A list of nodes. | +| <a id="approvalprojectruleconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ApprovalProjectRuleEdge` + +The edge type for [`ApprovalProjectRule`](#approvalprojectrule). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="approvalprojectruleedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="approvalprojectruleedgenode"></a>`node` | [`ApprovalProjectRule`](#approvalprojectrule) | The item at the end of the edge. | + #### `AuditEventStreamingHeaderConnection` The connection type for [`AuditEventStreamingHeader`](#auditeventstreamingheader). @@ -6821,6 +6888,29 @@ The edge type for [`ContainerRepository`](#containerrepository). | <a id="containerrepositoryedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="containerrepositoryedgenode"></a>`node` | [`ContainerRepository`](#containerrepository) | The item at the end of the edge. | +#### `ContainerRepositoryRegistryConnection` + +The connection type for [`ContainerRepositoryRegistry`](#containerrepositoryregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="containerrepositoryregistryconnectionedges"></a>`edges` | [`[ContainerRepositoryRegistryEdge]`](#containerrepositoryregistryedge) | A list of edges. | +| <a id="containerrepositoryregistryconnectionnodes"></a>`nodes` | [`[ContainerRepositoryRegistry]`](#containerrepositoryregistry) | A list of nodes. | +| <a id="containerrepositoryregistryconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ContainerRepositoryRegistryEdge` + +The edge type for [`ContainerRepositoryRegistry`](#containerrepositoryregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="containerrepositoryregistryedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="containerrepositoryregistryedgenode"></a>`node` | [`ContainerRepositoryRegistry`](#containerrepositoryregistry) | The item at the end of the edge. | + #### `ContainerRepositoryTagConnection` The connection type for [`ContainerRepositoryTag`](#containerrepositorytag). @@ -8351,6 +8441,30 @@ The edge type for [`Pipeline`](#pipeline). | <a id="pipelineedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="pipelineedgenode"></a>`node` | [`Pipeline`](#pipeline) | The item at the end of the edge. | +#### `PipelineScheduleConnection` + +The connection type for [`PipelineSchedule`](#pipelineschedule). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelinescheduleconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | +| <a id="pipelinescheduleconnectionedges"></a>`edges` | [`[PipelineScheduleEdge]`](#pipelinescheduleedge) | A list of edges. | +| <a id="pipelinescheduleconnectionnodes"></a>`nodes` | [`[PipelineSchedule]`](#pipelineschedule) | A list of nodes. | +| <a id="pipelinescheduleconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `PipelineScheduleEdge` + +The edge type for [`PipelineSchedule`](#pipelineschedule). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelinescheduleedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="pipelinescheduleedgenode"></a>`node` | [`PipelineSchedule`](#pipelineschedule) | The item at the end of the edge. | + #### `PipelineSecurityReportFindingConnection` The connection type for [`PipelineSecurityReportFinding`](#pipelinesecurityreportfinding). @@ -8421,6 +8535,75 @@ The edge type for [`ProjectMember`](#projectmember). | <a id="projectmemberedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="projectmemberedgenode"></a>`node` | [`ProjectMember`](#projectmember) | The item at the end of the edge. | +#### `ProtectedEnvironmentApprovalRuleConnection` + +The connection type for [`ProtectedEnvironmentApprovalRule`](#protectedenvironmentapprovalrule). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentapprovalruleconnectionedges"></a>`edges` | [`[ProtectedEnvironmentApprovalRuleEdge]`](#protectedenvironmentapprovalruleedge) | A list of edges. | +| <a id="protectedenvironmentapprovalruleconnectionnodes"></a>`nodes` | [`[ProtectedEnvironmentApprovalRule]`](#protectedenvironmentapprovalrule) | A list of nodes. | +| <a id="protectedenvironmentapprovalruleconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ProtectedEnvironmentApprovalRuleEdge` + +The edge type for [`ProtectedEnvironmentApprovalRule`](#protectedenvironmentapprovalrule). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentapprovalruleedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="protectedenvironmentapprovalruleedgenode"></a>`node` | [`ProtectedEnvironmentApprovalRule`](#protectedenvironmentapprovalrule) | The item at the end of the edge. | + +#### `ProtectedEnvironmentConnection` + +The connection type for [`ProtectedEnvironment`](#protectedenvironment). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentconnectionedges"></a>`edges` | [`[ProtectedEnvironmentEdge]`](#protectedenvironmentedge) | A list of edges. | +| <a id="protectedenvironmentconnectionnodes"></a>`nodes` | [`[ProtectedEnvironment]`](#protectedenvironment) | A list of nodes. | +| <a id="protectedenvironmentconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ProtectedEnvironmentDeployAccessLevelConnection` + +The connection type for [`ProtectedEnvironmentDeployAccessLevel`](#protectedenvironmentdeployaccesslevel). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentdeployaccesslevelconnectionedges"></a>`edges` | [`[ProtectedEnvironmentDeployAccessLevelEdge]`](#protectedenvironmentdeployaccessleveledge) | A list of edges. | +| <a id="protectedenvironmentdeployaccesslevelconnectionnodes"></a>`nodes` | [`[ProtectedEnvironmentDeployAccessLevel]`](#protectedenvironmentdeployaccesslevel) | A list of nodes. | +| <a id="protectedenvironmentdeployaccesslevelconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ProtectedEnvironmentDeployAccessLevelEdge` + +The edge type for [`ProtectedEnvironmentDeployAccessLevel`](#protectedenvironmentdeployaccesslevel). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentdeployaccessleveledgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="protectedenvironmentdeployaccessleveledgenode"></a>`node` | [`ProtectedEnvironmentDeployAccessLevel`](#protectedenvironmentdeployaccesslevel) | The item at the end of the edge. | + +#### `ProtectedEnvironmentEdge` + +The edge type for [`ProtectedEnvironment`](#protectedenvironment). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="protectedenvironmentedgenode"></a>`node` | [`ProtectedEnvironment`](#protectedenvironment) | The item at the end of the edge. | + #### `PushAccessLevelConnection` The connection type for [`PushAccessLevel`](#pushaccesslevel). @@ -9732,6 +9915,20 @@ An API Fuzzing scan profile. | <a id="apifuzzingscanprofilename"></a>`name` | [`String`](#string) | Unique name of the profile. | | <a id="apifuzzingscanprofileyaml"></a>`yaml` | [`String`](#string) | Syntax highlighted HTML representation of the YAML. | +### `ApprovalProjectRule` + +Describes a project approval rule regarding who can approve merge requests. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="approvalprojectruleapprovalsrequired"></a>`approvalsRequired` | [`Int`](#int) | Number of required approvals. | +| <a id="approvalprojectruleeligibleapprovers"></a>`eligibleApprovers` | [`UserCoreConnection`](#usercoreconnection) | List of users eligible to approve merge requests for this approval rule. (see [Connections](#connections)) | +| <a id="approvalprojectruleid"></a>`id` | [`GlobalID!`](#globalid) | ID of the rule. | +| <a id="approvalprojectrulename"></a>`name` | [`String`](#string) | Name of the rule. | +| <a id="approvalprojectruletype"></a>`type` | [`ApprovalRuleType`](#approvalruletype) | Type of the rule. | + ### `ApprovalRule` Describes a rule for who can approve merge requests. @@ -10145,8 +10342,10 @@ List of branch rules for a project, grouped by branch name. | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="branchruleapprovalrules"></a>`approvalRules` | [`ApprovalProjectRuleConnection`](#approvalprojectruleconnection) | Merge request approval rules configured for this branch rule. (see [Connections](#connections)) | | <a id="branchrulebranchprotection"></a>`branchProtection` | [`BranchProtection!`](#branchprotection) | Branch protections configured for this branch rule. | | <a id="branchrulecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the branch rule was created. | +| <a id="branchruleisdefault"></a>`isDefault` | [`Boolean!`](#boolean) | Check if this branch rule protects the project's default branch. | | <a id="branchrulename"></a>`name` | [`String!`](#string) | Branch name, with wildcards, for the branch rules. | | <a id="branchruleupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the branch rule was last updated. | @@ -10274,6 +10473,7 @@ CI/CD config variables. | <a id="ciconfigvariabledescription"></a>`description` | [`String`](#string) | Description for the CI/CD config variable. | | <a id="ciconfigvariablekey"></a>`key` | [`String`](#string) | Name of the variable. | | <a id="ciconfigvariablevalue"></a>`value` | [`String`](#string) | Value of the variable. | +| <a id="ciconfigvariablevalueoptions"></a>`valueOptions` | [`[String!]`](#string) | Value options for the variable. | ### `CiGroup` @@ -10330,6 +10530,7 @@ CI/CD variables for a GitLab instance. | <a id="cijobactive"></a>`active` | [`Boolean!`](#boolean) | Indicates the job is active. | | <a id="cijoballowfailure"></a>`allowFailure` | [`Boolean!`](#boolean) | Whether the job is allowed to fail. | | <a id="cijobartifacts"></a>`artifacts` | [`CiJobArtifactConnection`](#cijobartifactconnection) | Artifacts generated by the job. (see [Connections](#connections)) | +| <a id="cijobbrowseartifactspath"></a>`browseArtifactsPath` | [`String`](#string) | URL for browsing the artifact's archive. | | <a id="cijobcancelable"></a>`cancelable` | [`Boolean!`](#boolean) | Indicates the job can be canceled. | | <a id="cijobcommitpath"></a>`commitPath` | [`String`](#string) | Path to the commit that triggered the job. | | <a id="cijobcoverage"></a>`coverage` | [`Float`](#float) | Coverage level of the job. | @@ -10903,6 +11104,25 @@ 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. | +### `ContainerRepositoryRegistry` + +Represents the Geo replication and verification state of an Container Repository. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="containerrepositoryregistrycontainerrepositoryid"></a>`containerRepositoryId` | [`ID!`](#id) | ID of the ContainerRepository. | +| <a id="containerrepositoryregistrycreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp when the ContainerRepositoryRegistry was created. | +| <a id="containerrepositoryregistryid"></a>`id` | [`ID!`](#id) | ID of the ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistrylastsyncfailure"></a>`lastSyncFailure` | [`String`](#string) | Error message during sync of the ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistrylastsyncedat"></a>`lastSyncedAt` | [`Time`](#time) | Timestamp of the most recent successful sync of the ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistryretryat"></a>`retryAt` | [`Time`](#time) | Timestamp after which the ContainerRepositoryRegistry is resynced. | +| <a id="containerrepositoryregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the ContainerRepositoryRegistry. | +| <a id="containerrepositoryregistryverificationretryat"></a>`verificationRetryAt` | [`Time`](#time) | Timestamp after which the ContainerRepositoryRegistry is reverified. | +| <a id="containerrepositoryregistryverifiedat"></a>`verifiedAt` | [`Time`](#time) | Timestamp of the most recent successful verification of the ContainerRepositoryRegistry. | + ### `ContainerRepositoryTag` A tag from a container repository. @@ -11090,6 +11310,7 @@ Represents a DAST Site Profile. | <a id="dastsiteprofileprofilename"></a>`profileName` | [`String`](#string) | Name of the site profile. | | <a id="dastsiteprofilereferencedinsecuritypolicies"></a>`referencedInSecurityPolicies` | [`[String!]`](#string) | List of security policy names that are referencing given project. | | <a id="dastsiteprofilerequestheaders"></a>`requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | +| <a id="dastsiteprofilescanfilepath"></a>`scanFilePath` | [`String`](#string) | Scan File Path used as input for the scanner. Will always return `null` if `dast_api_scanner` feature flag is disabled. | | <a id="dastsiteprofilescanmethod"></a>`scanMethod` | [`DastScanMethodType`](#dastscanmethodtype) | Scan method used by the scanner. Always returns `null` if `dast_api_scanner` feature flag is disabled. | | <a id="dastsiteprofiletargettype"></a>`targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | | <a id="dastsiteprofiletargeturl"></a>`targetUrl` | [`String`](#string) | URL of the target to be scanned. | @@ -11133,6 +11354,7 @@ Represents a DAST Site Validation. | <a id="dastsitevalidationid"></a>`id` | [`DastSiteValidationID!`](#dastsitevalidationid) | Global ID of the site validation. | | <a id="dastsitevalidationnormalizedtargeturl"></a>`normalizedTargetUrl` | [`String`](#string) | Normalized URL of the target to be validated. | | <a id="dastsitevalidationstatus"></a>`status` | [`DastSiteProfileValidationStatusEnum!`](#dastsiteprofilevalidationstatusenum) | Status of the site validation. | +| <a id="dastsitevalidationvalidationstartedat"></a>`validationStartedAt` | [`Time`](#time) | Timestamp of when the validation started. | ### `DeleteJobsResponse` @@ -11685,6 +11907,7 @@ Describes where code is deployed for a project. | <a id="environmentlatestopenedmostseverealert"></a>`latestOpenedMostSevereAlert` | [`AlertManagementAlert`](#alertmanagementalert) | Most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. | | <a id="environmentname"></a>`name` | [`String!`](#string) | Human-readable name of the environment. | | <a id="environmentpath"></a>`path` | [`String!`](#string) | Path to the environment. | +| <a id="environmentprotectedenvironments"></a>`protectedEnvironments` | [`ProtectedEnvironmentConnection`](#protectedenvironmentconnection) | Protected Environments for the environment. (see [Connections](#connections)) | | <a id="environmentslug"></a>`slug` | [`String`](#string) | Slug of the environment. | | <a id="environmentstate"></a>`state` | [`String!`](#string) | State of the environment, for example: available/stopped. | | <a id="environmenttier"></a>`tier` | [`DeploymentTier`](#deploymenttier) | Deployment tier of the environment. | @@ -11694,7 +11917,7 @@ Describes where code is deployed for a project. ##### `Environment.deployments` -Deployments of the environment. This field can only be resolved for one project in any single request. +Deployments of the environment. This field can only be resolved for one environment in any single request. Returns [`DeploymentConnection`](#deploymentconnection). @@ -12279,6 +12502,28 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="geonodecisecurefileregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | | <a id="geonodecisecurefileregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | +##### `GeoNode.containerRepositoryRegistries` + +Find Container Repository registries on this Geo node. Ignored if `geo_container_repository_replication` feature flag is disabled. + +WARNING: +**Introduced** in 15.5. +This feature is in Alpha. It can be changed or removed at any time. + +Returns [`ContainerRepositoryRegistryConnection`](#containerrepositoryregistryconnection). + +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="geonodecontainerrepositoryregistriesids"></a>`ids` | [`[ID!]`](#id) | Filters registries by their ID. | +| <a id="geonodecontainerrepositoryregistriesreplicationstate"></a>`replicationState` | [`ReplicationStateEnum`](#replicationstateenum) | Filters registries by their replication state. | +| <a id="geonodecontainerrepositoryregistriesverificationstate"></a>`verificationState` | [`VerificationStateEnum`](#verificationstateenum) | Filters registries by their verification state. | + ##### `GeoNode.groupWikiRepositoryRegistries` Find group wiki repository registries on this Geo node. @@ -12775,6 +13020,21 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupepicsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Epics updated after this date. | | <a id="groupepicsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Epics updated before this date. | +##### `Group.gitlabSubscriptionsPreviewBillableUserChange` + +Preview Billable User Changes. + +Returns [`PreviewBillableUserChange`](#previewbillableuserchange). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <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="groupgitlabsubscriptionspreviewbillableuserchangerole"></a>`role` | [`GitlabSubscriptionsUserRole!`](#gitlabsubscriptionsuserrole) | Role of users being added to group. | + ##### `Group.groupMembers` A membership of a user within this group. @@ -12820,7 +13080,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupissuescrmcontactid"></a>`crmContactId` | [`String`](#string) | ID of a contact assigned to the issues. | | <a id="groupissuescrmorganizationid"></a>`crmOrganizationId` | [`String`](#string) | ID of an organization assigned to the issues. | | <a id="groupissuesepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | -| <a id="groupissueshealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Health status of the issue. | +| <a id="groupissueshealthstatus"></a>`healthStatus` **{warning-solid}** | [`HealthStatus`](#healthstatus) | **Deprecated** in 15.4. Use `healthStatusFilter`. | +| <a id="groupissueshealthstatusfilter"></a>`healthStatusFilter` | [`HealthStatusFilter`](#healthstatusfilter) | Health status of the issue, "none" and "any" values are supported. | | <a id="groupissuesiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | | <a id="groupissuesiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | | <a id="groupissuesin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument.'. | @@ -13653,7 +13914,7 @@ Represents an iteration object. | <a id="iterationsequence"></a>`sequence` | [`Int!`](#int) | Sequence number for the iteration when you sort the containing cadence's iterations by the start and end date. The earliest starting and ending iteration is assigned 1. | | <a id="iterationstartdate"></a>`startDate` | [`Time`](#time) | Timestamp of the iteration start date. | | <a id="iterationstate"></a>`state` | [`IterationState!`](#iterationstate) | State of the iteration. | -| <a id="iterationtitle"></a>`title` | [`String`](#string) | Title of the iteration. Title must be specified unless iteration_cadences feature flag is enabled. | +| <a id="iterationtitle"></a>`title` | [`String`](#string) | Title of the iteration. | | <a id="iterationupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of last iteration update. | | <a id="iterationwebpath"></a>`webPath` | [`String!`](#string) | Web path of the iteration. | | <a id="iterationweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the iteration. | @@ -15253,7 +15514,7 @@ Represents the network policy. | <a id="noteauthor"></a>`author` | [`UserCore!`](#usercore) | User who wrote this note. | | <a id="notebody"></a>`body` | [`String!`](#string) | Content of the note. | | <a id="notebodyhtml"></a>`bodyHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `note`. | -| <a id="noteconfidential"></a>`confidential` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.3. This was renamed. Use: `internal`. | +| <a id="noteconfidential"></a>`confidential` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated** in 15.5. This was renamed. Use: `internal`. | | <a id="notecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of the note creation. | | <a id="notediscussion"></a>`discussion` | [`Discussion`](#discussion) | Discussion this note is a part of. | | <a id="noteid"></a>`id` | [`NoteID!`](#noteid) | ID of the note. | @@ -15558,8 +15819,17 @@ Namespace-level Package Registry settings. | ---- | ---- | ----------- | | <a id="packagesettingsgenericduplicateexceptionregex"></a>`genericDuplicateExceptionRegex` | [`UntrustedRegexp`](#untrustedregexp) | When generic_duplicates_allowed is false, you can publish duplicate packages with names that match this regex. Otherwise, this setting has no effect. | | <a id="packagesettingsgenericduplicatesallowed"></a>`genericDuplicatesAllowed` | [`Boolean!`](#boolean) | Indicates whether duplicate generic packages are allowed for this namespace. | +| <a id="packagesettingslockmavenpackagerequestsforwarding"></a>`lockMavenPackageRequestsForwarding` | [`Boolean!`](#boolean) | Indicates whether Maven package forwarding is locked for all descendent namespaces. | +| <a id="packagesettingslocknpmpackagerequestsforwarding"></a>`lockNpmPackageRequestsForwarding` | [`Boolean!`](#boolean) | Indicates whether npm package forwarding is locked for all descendent namespaces. | +| <a id="packagesettingslockpypipackagerequestsforwarding"></a>`lockPypiPackageRequestsForwarding` | [`Boolean!`](#boolean) | Indicates whether PyPI package forwarding is locked for all descendent namespaces. | | <a id="packagesettingsmavenduplicateexceptionregex"></a>`mavenDuplicateExceptionRegex` | [`UntrustedRegexp`](#untrustedregexp) | When maven_duplicates_allowed is false, you can publish duplicate packages with names that match this regex. Otherwise, this setting has no effect. | | <a id="packagesettingsmavenduplicatesallowed"></a>`mavenDuplicatesAllowed` | [`Boolean!`](#boolean) | Indicates whether duplicate Maven packages are allowed for this namespace. | +| <a id="packagesettingsmavenpackagerequestsforwarding"></a>`mavenPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether Maven package forwarding is allowed for this namespace. | +| <a id="packagesettingsmavenpackagerequestsforwardinglocked"></a>`mavenPackageRequestsForwardingLocked` | [`Boolean!`](#boolean) | Indicates whether Maven package forwarding settings are locked by a parent namespace. | +| <a id="packagesettingsnpmpackagerequestsforwarding"></a>`npmPackageRequestsForwarding` | [`Boolean`](#boolean) | Indicates whether npm package forwarding is allowed for this namespace. | +| <a id="packagesettingsnpmpackagerequestsforwardinglocked"></a>`npmPackageRequestsForwardingLocked` | [`Boolean!`](#boolean) | Indicates whether npm package forwarding settings are locked by a parent 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. | ### `PackageTag` @@ -15820,6 +16090,37 @@ Represents pipeline counts for the project. | <a id="pipelinepermissionsdestroypipeline"></a>`destroyPipeline` | [`Boolean!`](#boolean) | Indicates the user can perform `destroy_pipeline` on this resource. | | <a id="pipelinepermissionsupdatepipeline"></a>`updatePipeline` | [`Boolean!`](#boolean) | Indicates the user can perform `update_pipeline` on this resource. | +### `PipelineSchedule` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelinescheduleactive"></a>`active` | [`Boolean!`](#boolean) | Indicates if a pipeline schedule is active. | +| <a id="pipelineschedulecron"></a>`cron` | [`String!`](#string) | Cron notation for the schedule. | +| <a id="pipelineschedulecrontimezone"></a>`cronTimezone` | [`String!`](#string) | Timezone for the pipeline schedule. | +| <a id="pipelinescheduledescription"></a>`description` | [`String`](#string) | Description of the pipeline schedule. | +| <a id="pipelineschedulefortag"></a>`forTag` | [`Boolean!`](#boolean) | Indicates if a pipelines schedule belongs to a tag. | +| <a id="pipelinescheduleid"></a>`id` | [`ID!`](#id) | ID of the pipeline schedule. | +| <a id="pipelineschedulelastpipeline"></a>`lastPipeline` | [`Pipeline`](#pipeline) | Last pipeline object. | +| <a id="pipelineschedulenextrunat"></a>`nextRunAt` | [`Time!`](#time) | Time when the next pipeline will run. | +| <a id="pipelinescheduleowner"></a>`owner` | [`UserCore!`](#usercore) | Owner of the pipeline schedule. | +| <a id="pipelineschedulerealnextrun"></a>`realNextRun` | [`Time!`](#time) | Time when the next pipeline will run. | +| <a id="pipelineschedulereffordisplay"></a>`refForDisplay` | [`String`](#string) | Git ref for the pipeline schedule. | +| <a id="pipelineschedulerefpath"></a>`refPath` | [`String`](#string) | Path to the ref that triggered the pipeline. | +| <a id="pipelinescheduleuserpermissions"></a>`userPermissions` | [`PipelineSchedulePermissions!`](#pipelineschedulepermissions) | Permissions for the current user on the resource. | + +### `PipelineSchedulePermissions` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelineschedulepermissionsadminpipelineschedule"></a>`adminPipelineSchedule` | [`Boolean!`](#boolean) | Indicates the user can perform `admin_pipeline_schedule` on this resource. | +| <a id="pipelineschedulepermissionsplaypipelineschedule"></a>`playPipelineSchedule` | [`Boolean!`](#boolean) | Indicates the user can perform `play_pipeline_schedule` on this resource. | +| <a id="pipelineschedulepermissionstakeownershippipelineschedule"></a>`takeOwnershipPipelineSchedule` | [`Boolean!`](#boolean) | Indicates the user can perform `take_ownership_pipeline_schedule` on this resource. | +| <a id="pipelineschedulepermissionsupdatepipelineschedule"></a>`updatePipelineSchedule` | [`Boolean!`](#boolean) | Indicates the user can perform `update_pipeline_schedule` on this resource. | + ### `PipelineSecurityReportFinding` Represents vulnerability finding of a security report on the pipeline. @@ -15848,6 +16149,16 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="pipelinesecurityreportfindingtitle"></a>`title` | [`String`](#string) | Title of the vulnerability finding. | | <a id="pipelinesecurityreportfindinguuid"></a>`uuid` | [`String`](#string) | Name of the vulnerability finding. | +### `PreviewBillableUserChange` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="previewbillableuserchangehasoverage"></a>`hasOverage` | [`Boolean`](#boolean) | If the group has an overage after change. | +| <a id="previewbillableuserchangenewbillableusercount"></a>`newBillableUserCount` | [`Int`](#int) | Total number of billable users after change. | +| <a id="previewbillableuserchangeseatsinsubscription"></a>`seatsInSubscription` | [`Int`](#int) | Number of seats in subscription. | + ### `Project` #### Fields @@ -15898,6 +16209,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectnamewithnamespace"></a>`nameWithNamespace` | [`String!`](#string) | Full name of the project with its namespace. | | <a id="projectnamespace"></a>`namespace` | [`Namespace`](#namespace) | Namespace of the project. | | <a id="projectonlyallowmergeifalldiscussionsareresolved"></a>`onlyAllowMergeIfAllDiscussionsAreResolved` | [`Boolean`](#boolean) | Indicates if merge requests of the project can only be merged when all the discussions are resolved. | +| <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="projectpackagescleanuppolicy"></a>`packagesCleanupPolicy` | [`PackagesCleanupPolicy`](#packagescleanuppolicy) | Packages cleanup policy for the project. | @@ -16256,6 +16568,21 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="projectforktargetssearch"></a>`search` | [`String`](#string) | Search query for path or name. | +##### `Project.gitlabSubscriptionsPreviewBillableUserChange` + +Preview Billable User Changes. + +Returns [`PreviewBillableUserChange`](#previewbillableuserchange). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <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="projectgitlabsubscriptionspreviewbillableuserchangerole"></a>`role` | [`GitlabSubscriptionsUserRole!`](#gitlabsubscriptionsuserrole) | Role of users being added to group. | + ##### `Project.incidentManagementEscalationPolicies` Incident Management escalation policies of the project. @@ -16352,7 +16679,8 @@ Returns [`Issue`](#issue). | <a id="projectissuecrmcontactid"></a>`crmContactId` | [`String`](#string) | ID of a contact assigned to the issues. | | <a id="projectissuecrmorganizationid"></a>`crmOrganizationId` | [`String`](#string) | ID of an organization assigned to the issues. | | <a id="projectissueepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | -| <a id="projectissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Health status of the issue. | +| <a id="projectissuehealthstatus"></a>`healthStatus` **{warning-solid}** | [`HealthStatus`](#healthstatus) | **Deprecated** in 15.4. Use `healthStatusFilter`. | +| <a id="projectissuehealthstatusfilter"></a>`healthStatusFilter` | [`HealthStatusFilter`](#healthstatusfilter) | Health status of the issue, "none" and "any" values are supported. | | <a id="projectissueiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | | <a id="projectissueiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | | <a id="projectissuein"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument.'. | @@ -16436,7 +16764,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectissuescrmcontactid"></a>`crmContactId` | [`String`](#string) | ID of a contact assigned to the issues. | | <a id="projectissuescrmorganizationid"></a>`crmOrganizationId` | [`String`](#string) | ID of an organization assigned to the issues. | | <a id="projectissuesepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | -| <a id="projectissueshealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Health status of the issue. | +| <a id="projectissueshealthstatus"></a>`healthStatus` **{warning-solid}** | [`HealthStatus`](#healthstatus) | **Deprecated** in 15.4. Use `healthStatusFilter`. | +| <a id="projectissueshealthstatusfilter"></a>`healthStatusFilter` | [`HealthStatusFilter`](#healthstatusfilter) | Health status of the issue, "none" and "any" values are supported. | | <a id="projectissuesiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | | <a id="projectissuesiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | | <a id="projectissuesin"></a>`in` | [`[IssuableSearchableField!]`](#issuablesearchablefield) | Specify the fields to perform the search in. Defaults to `[TITLE, DESCRIPTION]`. Requires the `search` argument.'. | @@ -16700,6 +17029,22 @@ Returns [`PipelineCounts`](#pipelinecounts). | <a id="projectpipelinecountssha"></a>`sha` | [`String`](#string) | Filter pipelines by the SHA of the commit they are run for. | | <a id="projectpipelinecountssource"></a>`source` | [`String`](#string) | Filter pipelines by their source. | +##### `Project.pipelineSchedules` + +Pipeline schedules of the project. This field can only be resolved for one project per request. + +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`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectpipelineschedulesstatus"></a>`status` | [`PipelineScheduleStatus`](#pipelineschedulestatus) | Filter pipeline schedules by active status. | + ##### `Project.pipelines` Build pipelines of the project. @@ -17044,7 +17389,8 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectcicdsettingjobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI job tokens generated in this project have restricted access to resources. | +| <a id="projectcicdsettinginboundjobtokenscopeenabled"></a>`inboundJobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in other projects have restricted access to this project. | +| <a id="projectcicdsettingjobtokenscopeenabled"></a>`jobTokenScopeEnabled` | [`Boolean`](#boolean) | Indicates CI/CD job tokens generated in this project have restricted access to other projects. | | <a id="projectcicdsettingkeeplatestartifact"></a>`keepLatestArtifact` | [`Boolean`](#boolean) | Whether to keep the latest builds artifacts. | | <a id="projectcicdsettingmergepipelinesenabled"></a>`mergePipelinesEnabled` | [`Boolean`](#boolean) | Whether merge pipelines are enabled. | | <a id="projectcicdsettingmergetrainsenabled"></a>`mergeTrainsEnabled` | [`Boolean`](#boolean) | Whether merge trains are enabled. | @@ -17185,6 +17531,45 @@ The alert condition for Prometheus. | <a id="prometheusalerthumanizedtext"></a>`humanizedText` | [`String!`](#string) | Human-readable text of the alert condition. | | <a id="prometheusalertid"></a>`id` | [`ID!`](#id) | ID of the alert condition. | +### `ProtectedEnvironment` + +Protected Environments of the environment. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentapprovalrules"></a>`approvalRules` | [`ProtectedEnvironmentApprovalRuleConnection`](#protectedenvironmentapprovalruleconnection) | Which group, user or role is allowed to approve deployments to the environment. (see [Connections](#connections)) | +| <a id="protectedenvironmentdeployaccesslevels"></a>`deployAccessLevels` | [`ProtectedEnvironmentDeployAccessLevelConnection`](#protectedenvironmentdeployaccesslevelconnection) | Which group, user or role is allowed to execute deployments to the environment. (see [Connections](#connections)) | +| <a id="protectedenvironmentgroup"></a>`group` | [`Group`](#group) | Group details. Present if it's group-level protected environment. | +| <a id="protectedenvironmentname"></a>`name` | [`String`](#string) | Name of the environment if it's a project-level protected environment. Tier of the environment if it's a group-level protected environment. | +| <a id="protectedenvironmentproject"></a>`project` | [`Project`](#project) | Project details. Present if it's project-level protected environment. | + +### `ProtectedEnvironmentApprovalRule` + +Which group, user or role is allowed to approve deployments to the environment. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentapprovalruleaccesslevel"></a>`accessLevel` | [`AccessLevel`](#accesslevel) | Role details. Present if it's role specific access control. | +| <a id="protectedenvironmentapprovalrulegroup"></a>`group` | [`Group`](#group) | Group details. Present if it's group specific access control. | +| <a id="protectedenvironmentapprovalrulerequiredapprovals"></a>`requiredApprovals` | [`Int`](#int) | Number of required approvals. | +| <a id="protectedenvironmentapprovalruleuser"></a>`user` | [`UserCore`](#usercore) | User details. Present if it's user specific access control. | + +### `ProtectedEnvironmentDeployAccessLevel` + +Which group, user or role is allowed to execute deployments to the environment. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="protectedenvironmentdeployaccesslevelaccesslevel"></a>`accessLevel` | [`AccessLevel`](#accesslevel) | Role details. Present if it's role specific access control. | +| <a id="protectedenvironmentdeployaccesslevelgroup"></a>`group` | [`Group`](#group) | Group details. Present if it's group specific access control. | +| <a id="protectedenvironmentdeployaccessleveluser"></a>`user` | [`UserCore`](#usercore) | User details. Present if it's user specific access control. | + ### `PushAccessLevel` Represents the push access level of a branch protection. @@ -17464,7 +17849,7 @@ Represents a requirement. | <a id="requirementauthor"></a>`author` | [`UserCore!`](#usercore) | Author of the requirement. | | <a id="requirementcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the requirement was created. | | <a id="requirementdescription"></a>`description` | [`String`](#string) | Description of the requirement. | -| <a id="requirementdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="requirementdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `description`. | | <a id="requirementid"></a>`id` | [`ID!`](#id) | ID of the requirement. | | <a id="requirementiid"></a>`iid` | [`ID!`](#id) | Internal ID of the requirement. | | <a id="requirementlasttestreportmanuallycreated"></a>`lastTestReportManuallyCreated` | [`Boolean`](#boolean) | Indicates if latest test report was created by user. | @@ -17472,7 +17857,7 @@ Represents a requirement. | <a id="requirementproject"></a>`project` | [`Project!`](#project) | Project to which the requirement belongs. | | <a id="requirementstate"></a>`state` | [`RequirementState!`](#requirementstate) | State of the requirement. | | <a id="requirementtitle"></a>`title` | [`String`](#string) | Title of the requirement. | -| <a id="requirementtitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="requirementtitlehtml"></a>`titleHtml` | [`String`](#string) | GitLab Flavored Markdown rendering of `title`. | | <a id="requirementupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the requirement was last updated. | | <a id="requirementuserpermissions"></a>`userPermissions` | [`RequirementPermissions!`](#requirementpermissions) | Permissions for the current user on the resource. | @@ -19439,16 +19824,16 @@ Represents a start and due date widget. | <a id="workitemwidgetstartandduedatestartdate"></a>`startDate` | [`Date`](#date) | Start date of the work item. | | <a id="workitemwidgetstartandduedatetype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | -### `WorkItemWidgetVerificationStatus` +### `WorkItemWidgetStatus` -Represents a verification status widget. +Represents a status widget. #### Fields | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="workitemwidgetverificationstatustype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | -| <a id="workitemwidgetverificationstatusverificationstatus"></a>`verificationStatus` | [`String`](#string) | Verification status of the work item. | +| <a id="workitemwidgetstatusstatus"></a>`status` | [`String`](#string) | Status of the work item. | +| <a id="workitemwidgetstatustype"></a>`type` | [`WorkItemWidgetType`](#workitemwidgettype) | Widget type. | ### `WorkItemWidgetWeight` @@ -19696,6 +20081,7 @@ Values for filtering runners in namespaces. The previous type name `RunnerMember | Value | Description | | ----- | ----------- | +| <a id="cirunnermembershipfilterall_available"></a>`ALL_AVAILABLE` **{warning-solid}** | **Introduced** in 15.5. This feature is in Alpha. It can be changed or removed at any time. Include all runners. This list includes runners for all projects in the group and subgroups, as well as for the parent groups and instance. | | <a id="cirunnermembershipfilterdescendants"></a>`DESCENDANTS` | Include runners that have either a direct or inherited relationship. These runners can be specific to a project or a group. | | <a id="cirunnermembershipfilterdirect"></a>`DIRECT` | Include runners that have a direct relationship. | @@ -20105,6 +20491,7 @@ Detailed representation of whether a GitLab merge request can be merged. | <a id="detailedmergestatusci_still_running"></a>`CI_STILL_RUNNING` | Pipeline is still running. | | <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="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. | @@ -20228,6 +20615,18 @@ Event action. | <a id="eventactionreopened"></a>`REOPENED` | Reopened action. | | <a id="eventactionupdated"></a>`UPDATED` | Updated action. | +### `GitlabSubscriptionsUserRole` + +Role of User. + +| Value | Description | +| ----- | ----------- | +| <a id="gitlabsubscriptionsuserroledeveloper"></a>`DEVELOPER` | Developer. | +| <a id="gitlabsubscriptionsuserroleguest"></a>`GUEST` | Guest. | +| <a id="gitlabsubscriptionsuserrolemaintainer"></a>`MAINTAINER` | Maintainer. | +| <a id="gitlabsubscriptionsuserroleowner"></a>`OWNER` | Owner. | +| <a id="gitlabsubscriptionsuserrolereporter"></a>`REPORTER` | Reporter. | + ### `GroupMemberRelation` Group member relation. @@ -20258,6 +20657,18 @@ Health status of an issue or epic. | <a id="healthstatusneedsattention"></a>`needsAttention` | Needs attention. | | <a id="healthstatusontrack"></a>`onTrack` | On track. | +### `HealthStatusFilter` + +Health status of an issue or epic for filtering. + +| Value | Description | +| ----- | ----------- | +| <a id="healthstatusfilterany"></a>`ANY` | Any health status is assigned. | +| <a id="healthstatusfilternone"></a>`NONE` | No health status is assigned. | +| <a id="healthstatusfilteratrisk"></a>`atRisk` | At risk. | +| <a id="healthstatusfilterneedsattention"></a>`needsAttention` | Needs attention. | +| <a id="healthstatusfilterontrack"></a>`onTrack` | On track. | + ### `IssuableResourceLinkType` Issuable resource link type enum. @@ -20408,7 +20819,8 @@ Iteration sort values. | Value | Description | | ----- | ----------- | -| <a id="iterationsortcadence_and_due_date_asc"></a>`CADENCE_AND_DUE_DATE_ASC` | Sort by cadence id and due date in ascending order. | +| <a id="iterationsortcadence_and_due_date_asc"></a>`CADENCE_AND_DUE_DATE_ASC` | Sort by cadence id in ascending and due date in ascending order. | +| <a id="iterationsortcadence_and_due_date_desc"></a>`CADENCE_AND_DUE_DATE_DESC` | Sort by cadence id in ascending and due date in descending order. | ### `IterationState` @@ -20818,6 +21230,13 @@ Event type of the pipeline associated with a merge request. | <a id="pipelinemergerequesteventtypemerged_result"></a>`MERGED_RESULT` | Pipeline run on the changes from the source branch combined with the target branch. | | <a id="pipelinemergerequesteventtypemerge_train"></a>`MERGE_TRAIN` | Pipeline ran as part of a merge train. | +### `PipelineScheduleStatus` + +| Value | Description | +| ----- | ----------- | +| <a id="pipelineschedulestatusactive"></a>`ACTIVE` | Active pipeline schedules. | +| <a id="pipelineschedulestatusinactive"></a>`INACTIVE` | Inactive pipeline schedules. | + ### `PipelineScopeEnum` | Value | Description | @@ -21211,6 +21630,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumnamespace_storage_limit_banner_error_threshold"></a>`NAMESPACE_STORAGE_LIMIT_BANNER_ERROR_THRESHOLD` | Callout feature name for namespace_storage_limit_banner_error_threshold. | | <a id="usercalloutfeaturenameenumnamespace_storage_limit_banner_info_threshold"></a>`NAMESPACE_STORAGE_LIMIT_BANNER_INFO_THRESHOLD` | Callout feature name for namespace_storage_limit_banner_info_threshold. | | <a id="usercalloutfeaturenameenumnamespace_storage_limit_banner_warning_threshold"></a>`NAMESPACE_STORAGE_LIMIT_BANNER_WARNING_THRESHOLD` | Callout feature name for namespace_storage_limit_banner_warning_threshold. | +| <a id="usercalloutfeaturenameenumnew_top_level_group_alert"></a>`NEW_TOP_LEVEL_GROUP_ALERT` | Callout feature name for new_top_level_group_alert. | | <a id="usercalloutfeaturenameenumnew_user_signups_cap_reached"></a>`NEW_USER_SIGNUPS_CAP_REACHED` | Callout feature name for new_user_signups_cap_reached. | | <a id="usercalloutfeaturenameenumpersonal_access_token_expiry"></a>`PERSONAL_ACCESS_TOKEN_EXPIRY` | Callout feature name for personal_access_token_expiry. | | <a id="usercalloutfeaturenameenumpersonal_project_limitations_banner"></a>`PERSONAL_PROJECT_LIMITATIONS_BANNER` | Callout feature name for personal_project_limitations_banner. | @@ -21450,7 +21870,7 @@ Type of a work item widget. | <a id="workitemwidgettypeiteration"></a>`ITERATION` | Iteration widget. | | <a id="workitemwidgettypelabels"></a>`LABELS` | Labels widget. | | <a id="workitemwidgettypestart_and_due_date"></a>`START_AND_DUE_DATE` | Start And Due Date widget. | -| <a id="workitemwidgettypeverification_status"></a>`VERIFICATION_STATUS` | Verification Status widget. | +| <a id="workitemwidgettypestatus"></a>`STATUS` | Status widget. | | <a id="workitemwidgettypeweight"></a>`WEIGHT` | Weight widget. | ## Scalar types @@ -21544,6 +21964,12 @@ A `CiPipelineID` is a global ID. It is encoded as a string. An example `CiPipelineID` is: `"gid://gitlab/Ci::Pipeline/1"`. +### `CiPipelineScheduleID` + +A `CiPipelineScheduleID` is a global ID. It is encoded as a string. + +An example `CiPipelineScheduleID` is: `"gid://gitlab/Ci::PipelineSchedule/1"`. + ### `CiRunnerID` A `CiRunnerID` is a global ID. It is encoded as a string. @@ -22714,7 +23140,7 @@ Implementations: - [`WorkItemWidgetIteration`](#workitemwidgetiteration) - [`WorkItemWidgetLabels`](#workitemwidgetlabels) - [`WorkItemWidgetStartAndDueDate`](#workitemwidgetstartandduedate) -- [`WorkItemWidgetVerificationStatus`](#workitemwidgetverificationstatus) +- [`WorkItemWidgetStatus`](#workitemwidgetstatus) - [`WorkItemWidgetWeight`](#workitemwidgetweight) ##### Fields @@ -22756,6 +23182,7 @@ Field that are available while modifying the custom mapping attributes for an HT | <a id="boardissueinputconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter by confidentiality. | | <a id="boardissueinputepicid"></a>`epicId` | [`EpicID`](#epicid) | Filter by epic ID. Incompatible with epicWildcardId. | | <a id="boardissueinputepicwildcardid"></a>`epicWildcardId` | [`EpicWildcardId`](#epicwildcardid) | Filter by epic ID wildcard. Incompatible with epicId. | +| <a id="boardissueinputhealthstatusfilter"></a>`healthStatusFilter` | [`HealthStatusFilter`](#healthstatusfilter) | Health status of the issue, "none" and "any" values are supported. | | <a id="boardissueinputiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example `["1", "2"]`. | | <a id="boardissueinputiterationcadenceid"></a>`iterationCadenceId` | [`[IterationsCadenceID!]`](#iterationscadenceid) | Filter by a list of iteration cadence IDs. | | <a id="boardissueinputiterationid"></a>`iterationId` | [`[IterationID!]`](#iterationid) | Filter by a list of iteration IDs. Incompatible with iterationWildcardId. | @@ -23142,6 +23569,14 @@ Represents an action to perform over a snippet file. | <a id="snippetblobactioninputtypefilepath"></a>`filePath` | [`String!`](#string) | Path of the snippet file. | | <a id="snippetblobactioninputtypepreviouspath"></a>`previousPath` | [`String`](#string) | Previous path of the snippet file. | +### `StatusInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="statusinputstatus"></a>`status` | [`TestReportState!`](#testreportstate) | Status to assign to the work item. | + ### `Timeframe` A time-frame defined as a closed inclusive range of two dates. @@ -23228,6 +23663,7 @@ A time-frame defined as a closed inclusive range of two dates. | <a id="workitemupdatedtaskinputdescriptionwidget"></a>`descriptionWidget` | [`WorkItemWidgetDescriptionInput`](#workitemwidgetdescriptioninput) | Input for description widget. | | <a id="workitemupdatedtaskinputhierarchywidget"></a>`hierarchyWidget` | [`WorkItemWidgetHierarchyUpdateInput`](#workitemwidgethierarchyupdateinput) | Input for hierarchy widget. | | <a id="workitemupdatedtaskinputid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | +| <a id="workitemupdatedtaskinputlabelswidget"></a>`labelsWidget` | [`WorkItemWidgetLabelsUpdateInput`](#workitemwidgetlabelsupdateinput) | Input for labels widget. | | <a id="workitemupdatedtaskinputstartandduedatewidget"></a>`startAndDueDateWidget` | [`WorkItemWidgetStartAndDueDateUpdateInput`](#workitemwidgetstartandduedateupdateinput) | Input for start and due date widget. | | <a id="workitemupdatedtaskinputstateevent"></a>`stateEvent` | [`WorkItemStateEvent`](#workitemstateevent) | Close or reopen a work item. | | <a id="workitemupdatedtaskinputtitle"></a>`title` | [`String`](#string) | Title of the work item. | @@ -23273,6 +23709,15 @@ A time-frame defined as a closed inclusive range of two dates. | ---- | ---- | ----------- | | <a id="workitemwidgetiterationinputiterationid"></a>`iterationId` | [`IterationID`](#iterationid) | Iteration to assign to the work item. | +### `WorkItemWidgetLabelsUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemwidgetlabelsupdateinputaddlabelids"></a>`addLabelIds` | [`[LabelID!]`](#labelid) | Global IDs of labels to be added to the work item. | +| <a id="workitemwidgetlabelsupdateinputremovelabelids"></a>`removeLabelIds` | [`[LabelID!]`](#labelid) | Global IDs of labels to be removed from the work item. | + ### `WorkItemWidgetStartAndDueDateUpdateInput` #### Arguments diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index 6778a0c2aab..57f1c49290f 100644 --- a/doc/api/graphql/removed_items.md +++ b/doc/api/graphql/removed_items.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL API removed items **(FREE)** diff --git a/doc/api/graphql/sample_issue_boards.md b/doc/api/graphql/sample_issue_boards.md index 7fe8046b27d..1a189914b28 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Identify issue boards with GraphQL **(FREE)** diff --git a/doc/api/graphql/users_example.md b/doc/api/graphql/users_example.md index 1c366587e5f..96bbeeb2d06 100644 --- a/doc/api/graphql/users_example.md +++ b/doc/api/graphql/users_example.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Query users with GraphQL **(FREE)** diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md index 1c707f92ebd..2f3459a6121 100644 --- a/doc/api/group_access_tokens.md +++ b/doc/api/group_access_tokens.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group access tokens API **(FREE)** diff --git a/doc/api/group_activity_analytics.md b/doc/api/group_activity_analytics.md index 9206b0a1bd6..6d1c1ec155a 100644 --- a/doc/api/group_activity_analytics.md +++ b/doc/api/group_activity_analytics.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group Activity Analytics API **(PREMIUM)** diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index b1166ba5b54..cc99c137a47 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group badges API **(FREE)** diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 6178a3fdc04..d08a84aea61 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group issue boards API **(FREE)** diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index dfb6e7e4778..ed50594c73a 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group clusters API (certificate-based) (DEPRECATED) **(FREE)** diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index dbdc2c3669e..1efed80699b 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group import/export API **(FREE)** diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index 7f663515fee..92333de701c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group iterations API **(PREMIUM)** diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index e0f1b451231..f33f181336f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group labels API **(FREE)** diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index 7c51de47bc7..cdda15d9610 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group-level Variables API **(FREE)** diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 8b9c09ef1a0..824c4eb4678 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group milestones API **(FREE)** diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index 3f1d932e0c8..4cf87cb4305 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -112,7 +112,7 @@ POST /groups/:id/protected_environments | `approval_rules` | array | no | Array of access levels allowed to approve, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. You can also specify the number of required approvals from the specified entity with `required_approvals` field. See [Multiple approval rules](../ci/environments/deployment_approvals.md#multiple-approval-rules) for more information. | The assignable `user_id` are the users who belong to the given group with the Maintainer role (or above). -The assignable `group_id` are the sub-groups under the given group. +The assignable `group_id` are the subgroups under the given group. ```shell curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_environments" @@ -157,7 +157,7 @@ PUT /groups/:id/protected_environments/:name To update: - **`user_id`**: Ensure the updated user belongs to the given group with the Maintainer role (or above). You must also pass the `id` of either a `deploy_access_level` or `approval_rule` in the respective hash. -- **`group_id`**: Ensure the updated group is a sub-group of the group this protected environment belongs to. You must also pass the `id` of either a `deploy_access_level` or `approval_rule` in the respective hash. +- **`group_id`**: Ensure the updated group is a subgroup of the group this protected environment belongs to. You must also pass the `id` of either a `deploy_access_level` or `approval_rule` in the respective hash. To delete: diff --git a/doc/api/group_relations_export.md b/doc/api/group_relations_export.md index 4dbf0f6d54c..065ae03259a 100644 --- a/doc/api/group_relations_export.md +++ b/doc/api/group_relations_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group Relations Export API **(FREE)** diff --git a/doc/api/group_releases.md b/doc/api/group_releases.md index 06ce55b7d48..1918d0a54b9 100644 --- a/doc/api/group_releases.md +++ b/doc/api/group_releases.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group releases API **(FREE)** diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index f1ad7f51ea0..a4baf7936dd 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index 50bb67b8173..cba64269942 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/groups.md b/doc/api/groups.md index d3c0d659d08..c1effc78a4d 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Groups API **(FREE)** @@ -125,13 +125,16 @@ GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_valu ## List a group's subgroups -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15142) in GitLab 10.3. - Get a list of visible direct subgroups in this group. -When accessed without authentication, only public groups are returned. By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +If you request this list as: + +- An unauthenticated user, the response returns only public groups. +- An authenticated user, the response returns only the groups you're +a member of and does not include public groups. + Parameters: | Attribute | Type | Required | Description | @@ -284,7 +287,7 @@ Parameters: | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity` (1), or `last_activity_at` fields. Default is `created_at` | | `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Return list of authorized projects matching the search criteria | -| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | +| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned. | | `owned` | boolean | no | Limit by projects owned by the current user | | `starred` | boolean | no | Limit by projects starred by the current user | | `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | @@ -367,7 +370,7 @@ Parameters: | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | | `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Return list of authorized projects matching the search criteria | -| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | +| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned. | | `starred` | boolean | no | Limit by projects starred by the current user | | `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | | `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | diff --git a/doc/api/import.md b/doc/api/import.md index 1baea5d1500..78b9beb1815 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import API **(FREE)** @@ -14,13 +14,14 @@ Import your projects from GitHub to GitLab via the API. POST /import/github ``` -| Attribute | Type | Required | Description | -|------------|---------|----------|---------------------| -| `personal_access_token` | string | yes | GitHub personal access token | -| `repo_id` | integer | yes | GitHub repository ID | -| `new_name` | string | no | New repository name | -| `target_namespace` | string | yes | Namespace to import repository into. Supports subgroups like `/namespace/subgroup`. | -| `github_hostname` | string | no | Custom GitHub Enterprise hostname. Do not set for GitHub.com. | +| Attribute | Type | Required | Description | +|-------------------------|---------|----------|-------------------------------------------------------------------------------------| +| `personal_access_token` | string | yes | GitHub personal access token | +| `repo_id` | integer | yes | GitHub repository ID | +| `new_name` | string | no | New repository name | +| `target_namespace` | string | yes | Namespace to import repository into. Supports subgroups like `/namespace/subgroup` | +| `github_hostname` | string | no | Custom GitHub Enterprise hostname. Do not set for GitHub.com. | +| `optional_stages` | object | no | [Additional items to import](../user/project/import/github.md#select-additional-items-to-import). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5 | ```shell curl --request POST \ @@ -32,10 +33,23 @@ curl --request POST \ "repo_id": "12345", "target_namespace": "group/subgroup", "new_name": "NEW-NAME", - "github_hostname": "https://github.example.com" + "github_hostname": "https://github.example.com", + "optional_stages": { + "single_endpoint_issue_events_import": true, + "single_endpoint_notes_import": true, + "attachments_import": true + } }' ``` +The following keys are available for `optional_stages`: + +- `single_endpoint_issue_events_import`, for issue and pull request events import. +- `single_endpoint_notes_import`, for an alternative and more thorough comments import. +- `attachments_import`, for Markdown attachments import. + +For more information, see [Select additional items to import](../user/project/import/github.md#select-additional-items-to-import). + Example response: ```json @@ -47,6 +61,51 @@ Example response: } ``` +## Cancel GitHub project import + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364783) in GitLab 15.5. + +Cancel an in-progress GitHub project import using the API. + +```plaintext +POST /import/github/cancel +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `project_id` | integer | yes | GitLab project ID | + +```shell +curl --request POST \ + --url "https://gitlab.example.com/api/v4/import/github/cancel" \ + --header "content-type: application/json" \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --data '{ + "project_id": 12345 +}' +``` + +Example response: + +```json +{ + "id": 160, + "name": "my-repo", + "full_path": "/root/my-repo", + "full_name": "Administrator / my-repo", + "import_source": "source/source-repo", + "import_status": "canceled", + "human_import_status_name": "canceled", + "provider_link": "/source/source-repo" +} +``` + +Returns the following status codes: + +- `200 OK`: the project import is being canceled. +- `400 Bad Request`: the project import cannot be canceled. +- `404 Not Found`: the project associated with `project_id` does not exist. + ## Import repository from Bitbucket Server Import your projects from Bitbucket Server to GitLab via the API. diff --git a/doc/api/index.md b/doc/api/index.md index 15d0b0fd65f..7e14137b0fe 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # API Docs **(FREE)** @@ -29,7 +29,7 @@ For an introduction and basic steps, see ## SCIM API **(PREMIUM SAAS)** GitLab provides a [SCIM API](scim.md) that both implements -[the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides the +[the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644) and provides the `/Users` endpoint. The base URL is `/api/scim/v2/groups/:group_path/Users/`. ## GraphQL API diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index 3d2c35a0ab0..45243003004 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 2b2579425b5..776b1000651 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 Authoring -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 b7e110a7eef..176ed931d38 100644 --- a/doc/api/integrations.md +++ b/doc/api/integrations.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrations API **(FREE)** @@ -276,7 +276,7 @@ Parameters: | Parameter | Type | Required | Description | |---------------|---------|----------|---------------------------------------------------------------------------------------------| -| `token` | string | true | Campfire API token. To find it, log into Campfire and select **My info**. | +| `token` | string | true | Campfire API token. To find it, sign in to Campfire and select **My info**. | | `subdomain` | string | false | Campfire subdomain. Text between `https://` and `.campfirenow.com` when you're logged in. | | `room` | string | false | Campfire room. The last part of the URL when you're in a room. | diff --git a/doc/api/invitations.md b/doc/api/invitations.md index 96c820536de..94362b097af 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Invitations API **(FREE)** diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index eb9e8e8adc0..253be9109c7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue links API **(FREE)** diff --git a/doc/api/issues.md b/doc/api/issues.md index 6e8aaa3d489..a0eb518f23e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues API **(FREE)** @@ -54,37 +54,38 @@ GET /issues?state=closed GET /issues?state=opened ``` -| 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)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ -| `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | -| `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | -| `iteration_title` **(PREMIUM)** | 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)** | 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| +| 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)** | 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)** | 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)** | 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)** | 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)** | 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| ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues" diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 7687124fb3a..cb08dc26b64 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues statistics API **(FREE)** diff --git a/doc/api/iterations.md b/doc/api/iterations.md index c39c397f27e..5704bcd3418 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project iterations API **(PREMIUM)** diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index d1bd40b91b9..2a40f7c15ef 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Job Artifacts API **(FREE)** diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 1548045d7c2..fc2de00c3d2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs API **(FREE)** @@ -76,6 +76,9 @@ Example of response "failure_reason": "script_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/7", + "project": { + "ci_job_token_scope_enabled": false + }, "user": { "id": 1, "name": "Administrator", @@ -132,6 +135,9 @@ Example of response "failure_reason": "stuck_or_timeout_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/6", + "project": { + "ci_job_token_scope_enabled": false + }, "user": { "id": 1, "name": "Administrator", @@ -216,6 +222,9 @@ Example of response "failure_reason": "stuck_or_timeout_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/6", + "project": { + "ci_job_token_scope_enabled": false + }, "user": { "id": 1, "name": "Administrator", @@ -281,6 +290,9 @@ Example of response "failure_reason": "script_failure", "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/7", + "project": { + "ci_job_token_scope_enabled": false + }, "user": { "id": 1, "name": "Administrator", diff --git a/doc/api/keys.md b/doc/api/keys.md index 99c9745d8f2..74d8bc4383f 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/labels.md b/doc/api/labels.md index 5de227c8e1f..5851138a3a3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Labels API **(FREE)** diff --git a/doc/api/license.md b/doc/api/license.md index eb576117d4a..72589710590 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 0d2176dfc61..77540f37054 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked epics API **(ULTIMATE)** diff --git a/doc/api/lint.md b/doc/api/lint.md index ff7aa2f1fb9..c1d95f65a86 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI Lint API **(FREE)** diff --git a/doc/api/managed_licenses.md b/doc/api/managed_licenses.md index 1a9be725b88..e9cab7f878a 100644 --- a/doc/api/managed_licenses.md +++ b/doc/api/managed_licenses.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managed Licenses API **(ULTIMATE)** diff --git a/doc/api/markdown.md b/doc/api/markdown.md index b66a07dc1d5..b4b700d24d6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Markdown API **(FREE)** diff --git a/doc/api/members.md b/doc/api/members.md index aff601ba33f..52bc3f6f468 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group and project members API **(FREE)** @@ -365,7 +365,8 @@ Example response: "last_activity_on": "2021-01-27", "membership_type": "group_member", "removable": true, - "created_at": "2021-01-03T12:16:02.000Z" + "created_at": "2021-01-03T12:16:02.000Z", + "last_login_at": "2022-10-09T01:33:06.000Z" }, { "id": 2, @@ -378,7 +379,8 @@ Example response: "last_activity_on": "2021-01-25", "membership_type": "group_member", "removable": true, - "created_at": "2021-01-04T18:46:42.000Z" + "created_at": "2021-01-04T18:46:42.000Z", + "last_login_at": "2022-09-29T22:18:46.000Z" }, { "id": 3, @@ -390,7 +392,8 @@ Example response: "last_activity_on": "2021-01-20", "membership_type": "group_invite", "removable": false, - "created_at": "2021-01-09T07:12:31.000Z" + "created_at": "2021-01-09T07:12:31.000Z", + "last_login_at": "2022-10-10T07:28:56.000Z" } ] ``` diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 1fcce40a5b0..e65263030b1 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/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Merge request approvals API **(PREMIUM)** diff --git a/doc/api/merge_request_context_commits.md b/doc/api/merge_request_context_commits.md index 08020e5a613..f5e22c469a3 100644 --- a/doc/api/merge_request_context_commits.md +++ b/doc/api/merge_request_context_commits.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 82125aec366..4667e48f233 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests API **(FREE)** diff --git a/doc/api/merge_trains.md b/doc/api/merge_trains.md index 1a4dfdbac2c..64ca2bf9b97 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge Trains API **(PREMIUM)** diff --git a/doc/api/metadata.md b/doc/api/metadata.md index 0f27960937d..3803173b0b8 100644 --- a/doc/api/metadata.md +++ b/doc/api/metadata.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metadata API **(FREE)** diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index 7732bf61d77..99d7b01d1a0 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 4f5fe1c909a..dbc6f64044f 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 48b6143a020..df09e374395 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project milestones API **(FREE)** diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 50c97d55f45..f75ebe5a881 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Namespaces API **(FREE)** diff --git a/doc/api/notes.md b/doc/api/notes.md index e0799cdd380..188d2697e6d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Notes API **(FREE)** diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 4b70a643263..d3e4a058b11 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Notification settings API **(FREE)** diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 0b7e0ba08eb..aca6ee74b15 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OAuth 2.0 identity provider API **(FREE)** @@ -37,7 +37,7 @@ For example, the `X-Requested-With` header can't be used for preflight requests. GitLab supports the following authorization flows: -- **Authorization code with [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636):** +- **Authorization code with [Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636):** Most secure. Without PKCE, you'd have to include client secrets on mobile clients, and is recommended for both client and server apps. - **Authorization code:** Secure and common flow. Recommended option for secure @@ -48,7 +48,7 @@ GitLab supports the following authorization flows: The draft specification for [OAuth 2.1](https://oauth.net/2.1/) specifically omits both the Implicit grant and Resource Owner Password Credentials flows. -Refer to the [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out +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 @@ -75,15 +75,15 @@ For production, please 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 -URIs. For more information, see the [OAuth 2.0 RFC](https://tools.ietf.org/html/rfc6749#section-3.1.2.1) -and the [OAuth 2.0 Threat Model RFC](https://tools.ietf.org/html/rfc6819#section-4.4.2.1). +URIs. For more information, see the [OAuth 2.0 RFC](https://www.rfc-editor.org/rfc/rfc6749#section-3.1.2.1) +and the [OAuth 2.0 Threat Model RFC](https://www.rfc-editor.org/rfc/rfc6819#section-4.4.2.1). In the following sections you can find detailed instructions on how to obtain authorization with each flow. ### Authorization code with Proof Key for Code Exchange (PKCE) -The [PKCE RFC](https://tools.ietf.org/html/rfc7636#section-1.1) includes a +The [PKCE RFC](https://www.rfc-editor.org/rfc/rfc7636#section-1.1) includes a detailed flow description, from authorization request through access token. The following steps describe our implementation of the flow. @@ -177,7 +177,7 @@ You can now make requests to the API with the access token. ### Authorization code flow NOTE: -Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.1) for a +Check the [RFC spec](https://www.rfc-editor.org/rfc/rfc6749#section-4.1) for a detailed flow description. The authorization code flow is essentially the same as @@ -257,7 +257,7 @@ You can now make requests to the API with the access token returned. ### Resource owner password credentials flow NOTE: -Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.3) for a +Check the [RFC spec](https://www.rfc-editor.org/rfc/rfc6749#section-4.3) for a detailed flow description. NOTE: diff --git a/doc/api/openapi/openapi_interactive.md b/doc/api/openapi/openapi_interactive.md index f83ac985131..1cf6ba6482c 100644 --- a/doc/api/openapi/openapi_interactive.md +++ b/doc/api/openapi/openapi_interactive.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Interactive API documentation diff --git a/doc/api/openapi/openapi_v2.yaml b/doc/api/openapi/openapi_v2.yaml new file mode 100644 index 00000000000..59b21ecd048 --- /dev/null +++ b/doc/api/openapi/openapi_v2.yaml @@ -0,0 +1,90 @@ +--- +info: + title: GitLab API + version: v4 +swagger: '2.0' +produces: +- application/json +securityDefinitions: + access_token_header: + type: apiKey + name: PRIVATE-TOKEN + in: header + access_token_query: + type: apiKey + name: private_token + in: query +host: gitlab.com +tags: +- name: metadata + description: Operations related to metadata of the GitLab instance +paths: + "/api/v4/metadata": + get: + summary: Retrieve metadata information for this GitLab instance. + description: This feature was introduced in GitLab 15.2. + produces: + - application/json + responses: + '200': + description: successful operation + schema: + "$ref": "#/definitions/API_Entities_Metadata" + examples: + successful_response: + value: + version: 15.0-pre + revision: c401a659d0c + kas: + enabled: true + externalUrl: grpc://gitlab.example.com:8150 + version: 15.0.0 + '401': + description: unauthorized operation + tags: + - metadata + operationId: getApiV4Metadata + "/api/v4/version": + get: + summary: Get the version information of the GitLab instance. + description: This feature was introduced in GitLab 8.13 and deprecated in 15.5. + We recommend you instead use the Metadata API. + produces: + - application/json + responses: + '200': + description: successful operation + schema: + "$ref": "#/definitions/API_Entities_Metadata" + examples: + Example: + value: + version: 15.0-pre + revision: c401a659d0c + kas: + enabled: true + externalUrl: grpc://gitlab.example.com:8150 + version: 15.0.0 + '401': + description: unauthorized operation + tags: + - metadata + operationId: getApiV4Version +definitions: + API_Entities_Metadata: + type: object + properties: + version: + type: string + revision: + type: string + kas: + type: object + properties: + enabled: + type: boolean + externalUrl: + type: string + version: + type: string + description: API_Entities_Metadata model diff --git a/doc/api/packages.md b/doc/api/packages.md index d91f4f0de7b..4fd21a43a92 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Packages API **(FREE)** diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md index ea2e917bbba..913831776d9 100644 --- a/doc/api/packages/composer.md +++ b/doc/api/packages/composer.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Composer API **(FREE)** diff --git a/doc/api/packages/conan.md b/doc/api/packages/conan.md index 637c3d27d75..d0077d18c11 100644 --- a/doc/api/packages/conan.md +++ b/doc/api/packages/conan.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Conan API **(FREE)** diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md index 598124ba2b9..0e85e554f01 100644 --- a/doc/api/packages/debian.md +++ b/doc/api/packages/debian.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Debian API **(FREE SELF)** diff --git a/doc/api/packages/debian_group_distributions.md b/doc/api/packages/debian_group_distributions.md index 0d0a4cb2cde..e3fabd92c51 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 -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 4f3ac62f576..f8ad7259866 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 -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 ffafc387951..3a98c5acd2f 100644 --- a/doc/api/packages/go_proxy.md +++ b/doc/api/packages/go_proxy.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 82b3f5225b0..b9888f2eed7 100644 --- a/doc/api/packages/helm.md +++ b/doc/api/packages/helm.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Helm API **(FREE)** diff --git a/doc/api/packages/maven.md b/doc/api/packages/maven.md index 27bc4da07a1..6eb343dc7ab 100644 --- a/doc/api/packages/maven.md +++ b/doc/api/packages/maven.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maven API **(FREE)** diff --git a/doc/api/packages/npm.md b/doc/api/packages/npm.md index 846271015cc..a35fe630075 100644 --- a/doc/api/packages/npm.md +++ b/doc/api/packages/npm.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.example/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.example/handbook/product/ux/technical-writing/#assignments --- # npm API **(FREE)** diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index f25a3a25754..4c63524291b 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about..example/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about..example/handbook/product/ux/technical-writing/#assignments --- # NuGet API **(FREE)** diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index e6204d87e1f..061de5bb9dd 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PyPI API **(FREE)** diff --git a/doc/api/packages/rubygems.md b/doc/api/packages/rubygems.md index 10dcaafda42..a87df17ab43 100644 --- a/doc/api/packages/rubygems.md +++ b/doc/api/packages/rubygems.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 daafe0579e7..4c32e3f7cb4 100644 --- a/doc/api/packages/terraform-modules.md +++ b/doc/api/packages/terraform-modules.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform Registry API **(FREE)** @@ -25,12 +25,12 @@ GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/ | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `module_namespace` | string | yes | The group to which Terraform module's project belongs. | +| `module_namespace` | string | yes | The top-level group (namespace) to which Terraform module's project or subgroup belongs.| | `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). | ```shell -curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/versions" +curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/versions" ``` Example response: @@ -88,7 +88,7 @@ GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system | `module_system` | string | yes | The name of the module system or [provider](https://www.terraform.io/registry/providers). | ```shell -curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local" +curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local" ``` Example response: @@ -127,7 +127,7 @@ GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/ | `module_system` | string | yes | The name of the module system or [provider](https://www.terraform.io/registry/providers). | ```shell -curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0" +curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0" ``` Example response: @@ -166,7 +166,7 @@ GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/ | `module_system` | string | yes | The name of the module system or [provider](https://www.terraform.io/registry/providers). | ```shell -curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/download" +curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/download" ``` Example response: @@ -195,7 +195,7 @@ GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/ | `module_version` | string | yes | Specific module version to download. | ```shell -curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/download" +curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/download" ``` Example response: @@ -220,11 +220,11 @@ GET packages/terraform/modules/v1/:module_namespace/:module_name/:module_system/ | `module_version` | string | yes | Specific module version to download. | ```shell -curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/file" +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" ``` To write the output to file: ```shell -curl --header "Private-Token: <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 +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 ``` diff --git a/doc/api/pages.md b/doc/api/pages.md index 57982188858..1855eaf153f 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pages API **(FREE)** diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 1c2cfef8e1b..511098fa380 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pages domains API **(FREE)** diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 849b5c75684..717e995f510 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Personal access tokens API **(FREE)** @@ -12,24 +12,56 @@ You can read more about [personal access tokens](../user/profile/personal_access > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in GitLab 13.3. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) from GitLab Ultimate to GitLab Free in 13.6. +> - `created_after`, `created_before`, `last_used_after`, `last_used_before`, `revoked`, `search` and `state` filters were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362248) in GitLab 15.5. -Get a list of personal access tokens. +Get all personal access tokens the authenticated user has access to. By default, returns an unfiltered list of: + +- Only personal access tokens created by the current user to a non-administrator. +- All personal access tokens to an administrator. + +Administrators: + +- Can use the `user_id` parameter to filter by a user. +- Can use other filters on all personal access tokens (GitLab 15.5 and later). + +Non-administrators: + +- Cannot use the `user_id` parameter to filter on any user except themselves, otherwise they receive a `401 Unauthorized` response. +- Can only filter on their own personal access tokens (GitLab 15.5 and later). ```plaintext GET /personal_access_tokens +GET /personal_access_tokens?created_after=2022-01-01T00:00:00 +GET /personal_access_tokens?created_before=2022-01-01T00:00:00 +GET /personal_access_tokens?last_used_after=2022-01-01T00:00:00 +GET /personal_access_tokens?last_used_before=2022-01-01T00:00:00 +GET /personal_access_tokens?revoked=true +GET /personal_access_tokens?search=name +GET /personal_access_tokens?state=inactive +GET /personal_access_tokens?user_id=1 ``` -| Attribute | Type | required | Description | -|-----------|---------|----------|---------------------| -| `user_id` | integer/string | no | The ID of the user to filter by | +Supported attributes: -NOTE: -Administrators can use the `user_id` parameter to filter by a user. Non-administrators cannot filter by any user except themselves. Attempting to do so will result in a `401 Unauthorized` response. +| Attribute | Type | Required | Description | +|---------------------|----------------|----------|---------------------| +| `created_after` | datetime (ISO 8601) | **{dotted-circle}** No | Limit results to PATs created after specified time. | +| `created_before` | datetime (ISO 8601) | **{dotted-circle}** No | Limit results to PATs created before specified time. | +| `last_used_after` | datetime (ISO 8601) | **{dotted-circle}** No | Limit results to PATs last used after specified time. | +| `last_used_before` | datetime (ISO 8601) | **{dotted-circle}** No | Limit results to PATs last used before specified time. | +| `revoked` | boolean | **{dotted-circle}** No | Limit results to PATs with specified revoked state. Valid values are `true` and `false`. | +| `search` | string | **{dotted-circle}** No | Limit results to PATs with name containing search string. | +| `state` | string | **{dotted-circle}** No | Limit results to PATs with specified state. Valid values are `active` and `inactive`. | +| `user_id` | integer or string | **{dotted-circle}** No | Limit results to PATs owned by specified user. | + +Example request: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens" ``` +Example response: + ```json [ { @@ -48,10 +80,14 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ] ``` +Example request: + ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?user_id=3" ``` +Example response: + ```json [ { @@ -70,7 +106,46 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ] ``` -## Get single personal access token by ID +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens?revoked=true" +``` + +Example response: + +```json +[ + { + "id": 41, + "name": "Revoked Test Token", + "revoked": true, + "created_at": "2022-01-01T14:31:47.729Z", + "scopes": [ + "api" + ], + "user_id": 8, + "last_used_at": "2022-05-18T17:58:37.550Z", + "active": false, + "expires_at": null + } +] +``` + +You can filter by merged attributes with: + +```plaintext +GET /personal_access_tokens?revoked=true&created_before=2022-01-01 +``` + +## Get single personal access token + +Get a personal access token by either: + +- Using the ID of the personal access token. +- Passing it to the API in a header. + +### Using a personal access token ID > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362239) in GitLab 15.1. @@ -81,7 +156,7 @@ Administrators can get any token. GET /personal_access_tokens/:id ``` -| Attribute | Type | required | Description | +| Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| | `id` | integer/string | yes | ID of personal access token | @@ -89,7 +164,7 @@ GET /personal_access_tokens/:id curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/<id>" ``` -### Responses +#### Responses > `404` HTTP status code [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93650) in GitLab 15.3. @@ -98,6 +173,38 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab - The token with the specified ID doesn't exist. - `404: Not Found` if the user is an administrator but the token with the specified ID doesn't exist. +### Using a request header + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373999) in GitLab 15.5 + +Get a single personal access token by using passing the token in a header. + +```plaintext +GET /personal_access_tokens/self +``` + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/personal_access_tokens/self" +``` + +Example response: + +```json +{ + "id": 4, + "name": "Test Token", + "revoked": false, + "created_at": "2020-07-23T14:31:47.729Z", + "scopes": [ + "api" + ], + "user_id": 3, + "last_used_at": "2021-10-06T17:58:37.550Z", + "active": true, + "expires_at": null +} +``` + ## Revoke a personal access token Revoke a personal access token by either: @@ -116,7 +223,7 @@ Revoke a personal access token using its ID. DELETE /personal_access_tokens/:id ``` -| Attribute | Type | required | Description | +| Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| | `id` | integer/string | yes | ID of personal access token | diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index bbaf38aaaae..edab87f3478 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline schedules API **(FREE)** diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index 9f3120bd5d7..1fc29d2a654 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline trigger tokens API **(FREE)** @@ -153,7 +153,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git Trigger a pipeline by using a pipeline [trigger token](../ci/triggers/index.md#create-a-trigger-token) or a [CI/CD job token](../ci/jobs/ci_job_token.md) for authentication. -With a CI/CD job token, the [triggered pipeline is a multi-project pipeline](../ci/jobs/ci_job_token.md#trigger-a-multi-project-pipeline-by-using-a-cicd-job-token). +With a CI/CD job token, the [triggered pipeline is a multi-project pipeline](../ci/pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api). The job that authenticates the request becomes associated with the upstream pipeline, which is visible on the [pipeline graph](../ci/pipelines/downstream_pipelines.md#view-multi-project-pipelines-in-pipeline-graphs). @@ -170,7 +170,7 @@ Supported attributes: | `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `ref` | string | **{check-circle}** Yes | The branch or tag to run the pipeline on. | | `token` | string | **{check-circle}** Yes | The trigger token or CI/CD job token. | -| `variables` | array | **{dotted-circle}** No | An array containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. | +| `variables` | array | **{dotted-circle}** No | An [array of hashes](index.md#array-of-hashes) containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. | Example request: diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 23c55cfb177..a44d02982c0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipelines API **(FREE)** diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md index 0b6f89675d0..8f6a7ae3e8d 100644 --- a/doc/api/plan_limits.md +++ b/doc/api/plan_limits.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 c3114baff8a..4653a52732a 100644 --- a/doc/api/product_analytics.md +++ b/doc/api/product_analytics.md @@ -1,7 +1,7 @@ --- stage: Analyze group: Product Analytics -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Product analytics API @@ -21,7 +21,7 @@ Make sure to define the `cube_api_base_url` and `cube_api_key` application setti Generate an access token that can be used to query the Cube API. For example: ```plaintext -POST /projects/:id/product_analytics/request +POST /projects/:id/product_analytics/request/load ``` | Attribute | Type | Required | Description | @@ -62,6 +62,7 @@ The body of the request should be a valid Cube query. "Jitsu.docPath" ], "limit": 23 - } + }, + "queryType": "multi" } ``` diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md index f76795f424e..4b74dacb996 100644 --- a/doc/api/project_access_tokens.md +++ b/doc/api/project_access_tokens.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project access tokens API **(FREE)** diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index 0d130f6f484..6bad94f48b3 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -1,14 +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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- # Project Aliases API **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab 12.1. - All methods require administrator authorization. ## List all project aliases @@ -50,7 +48,7 @@ GET /project_aliases/:name | Attribute | Type | Required | Description | |-----------|--------|----------|-----------------------| -| `name` | string | yes | The name of the alias | +| `name` | string | **{check-circle}** Yes | The name of the alias. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases/gitlab" @@ -77,8 +75,8 @@ POST /project_aliases | Attribute | Type | Required | Description | |--------------|----------------|----------|----------------------------------------| -| `project_id` | integer/string | yes | The ID or path of the project. | -| `name` | string | yes | The name of the alias. Must be unique. | +| `name` | string | **{check-circle}** Yes | The name of the alias. Must be unique. | +| `project_id` | integer or string | **{check-circle}** Yes | The ID or path of the project. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -113,7 +111,7 @@ DELETE /project_aliases/:name | Attribute | Type | Required | Description | |-----------|--------|----------|-----------------------| -| `name` | string | yes | The name of the alias | +| `name` | string | **{check-circle}** Yes | The name of the alias. | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases/gitlab" diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index 846c0241dd1..d83aa370808 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project badges API **(FREE)** diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 87a629372d5..48fc669fe59 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project clusters API (certificate-based) (DEPRECATED) **(FREE)** diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 49a9b68227d..83d8746e1d0 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project import/export API **(FREE)** diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 39e7f441b42..d900e1da78c 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/project_relations_export.md b/doc/api/project_relations_export.md index 74fdc91e420..fa6bdfa2900 100644 --- a/doc/api/project_relations_export.md +++ b/doc/api/project_relations_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project Relations Export API **(FREE)** diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index 48c22ff2d93..429cb97c404 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 0429c8abe3c..29d3b38f977 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project snippets **(FREE)** diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index c0a1227b295..7d8cc19457a 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index 14dd0761487..ae366e35f91 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project templates API **(FREE)** diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index 1267f748633..b1eb1b958ee 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/projects.md b/doc/api/projects.md index 26733801b45..470b3721b23 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Projects API **(FREE)** @@ -61,7 +61,7 @@ GET /projects | `repository_storage` | string | **{dotted-circle}** No | Limit results to projects stored on `repository_storage`. _(administrators only)_ | | `search_namespaces` | boolean | **{dotted-circle}** No | Include ancestor namespaces when matching search criteria. Default is `false`. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | -| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | @@ -336,7 +336,7 @@ GET /users/:user_id/projects | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | -| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | @@ -591,7 +591,7 @@ GET /users/:user_id/starred_projects | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | -| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | @@ -1014,6 +1014,19 @@ can also see the `approvals_before_merge` parameter: } ``` +Users of [GitLab Ultimate](https://about.gitlab.com/pricing/) +can also see the `only_allow_merge_if_all_status_checks_passed` +parameters using GitLab 15.5 and later: + +```json +{ + "id": 1, + "project_id": 3, + "only_allow_merge_if_all_status_checks_passed": false, + ... +} +``` + If the project is a fork, the `forked_from_project` field appears in the response. For this field, if the upstream project is private, a valid token for authentication must be provided. The field `mr_default_target_self` appears as well. If this value is `false`, then all merge requests @@ -1188,6 +1201,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `name` | string | **{check-circle}** Yes (if path isn't provided) | The name of the new project. Equals path if not provided. | | `path` | string | **{check-circle}** Yes (if name isn't provided) | Repository name for new project. Generated based on name if not provided (generated as lowercase with dashes). Starting with GitLab 14.9, path must not start or end with a special character and must not contain consecutive special characters. | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | +| `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | | `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | @@ -1229,6 +1243,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your-token>" \ | `pages_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, `enabled`, or `public`. | | `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | +| `releases_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrator only)_ | @@ -1266,6 +1281,7 @@ POST /projects/user/:user_id | `user_id` | integer | **{check-circle}** Yes | The user ID of the project owner. | | `name` | string | **{check-circle}** Yes | The name of the new project. | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | +| `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | | `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge requests by default. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | @@ -1307,6 +1323,7 @@ POST /projects/user/:user_id | `path` | string | **{dotted-circle}** No | Custom repository name for new project. By default generated based on name. | | `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project-members. | +| `releases_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrators only)_ | @@ -1355,6 +1372,7 @@ Supported attributes: |-------------------------------------------------------------|----------------|------------------------|-------------| | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `allow_merge_on_skipped_pipeline` | boolean | **{dotted-circle}** No | Set whether or not merge requests can be merged with skipped jobs. | +| `only_allow_merge_if_all_status_checks_passed` **(ULTIMATE)** | boolean | **{dotted-circle}** No | Indicates that merges of merge requests should be blocked unless all status checks have passed. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 with feature flag `only_allow_merge_if_all_status_checks_passed` disabled by default. | | `analytics_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private` or `enabled` | | `approvals_before_merge` **(PREMIUM)** | integer | **{dotted-circle}** No | How many approvers should approve merge request by default. To configure approval rules, see [Merge request approvals API](merge_request_approvals.md). | | `auto_cancel_pending_pipelines` | string | **{dotted-circle}** No | Auto-cancel pending pipelines. This isn't a boolean, but enabled/disabled. | @@ -1408,6 +1426,7 @@ Supported attributes: | `path` | string | **{dotted-circle}** No | Custom repository name for the project. By default generated based on name. | | `printing_merge_request_link_enabled` | boolean | **{dotted-circle}** No | Show link to create/view merge request when pushing from the command line. | | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | +| `releases_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | | `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrators only)_ | @@ -1473,7 +1492,7 @@ GET /projects/:id/forks | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | -| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | +| `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned. | | `sort` | string | **{dotted-circle}** No | Return projects sorted in `asc` or `desc` order. Default is `desc`. | | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index ea2412515a0..620cb0e0bae 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected branches API **(FREE)** diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 5b52d11feda..9ff3c34d2d7 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index b2ab3227a7e..c8e7117e5a9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected tags API **(FREE)** diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index e286fefc462..e3b1d9230f6 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Releases API **(FREE)** diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index f9e07991948..050d7cabdf9 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release links API **(FREE)** diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index 351706e8514..1013ffb49fb 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 7d94edc0872..751bbd75c7a 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -9,16 +9,19 @@ type: reference, api ## List repository tree +> Iterating pages of results with a number (`?page=2`) [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67509) in GitLab 14.3. + Get a list of repository files and directories in a project. This endpoint can be accessed without authentication if the repository is publicly accessible. -This command provides essentially the same functionality as the `git ls-tree` command. For more information, see the section _Tree Objects_ in the [Git internals documentation](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects/#_tree_objects). +This command provides essentially the same features as the `git ls-tree` +command. For more information, refer to the section +[Tree Objects](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects/#_tree_objects) +in the Git internals documentation. WARNING: -This endpoint is changing to keyset-based pagination. Iterating pages of results -with a number (`?page=2`) [is deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67509). -Support for iterating with a number became supported in GitLab 15.0. Use -the new [keyset pagination system](index.md#keyset-based-pagination) instead. +This endpoint changed to [keyset-based pagination](index.md#keyset-based-pagination) +in GitLab 15.0. Iterating pages of results with a number (`?page=2`) is unsupported. ```plaintext GET /projects/:id/repository/tree @@ -29,12 +32,12 @@ Supported attributes: | Attribute | Type | Required | Description | | :---------- | :------------- | :------- | :---------- | | `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `path` | string | no | The path inside repository. Used to get content of subdirectories. | -| `ref` | string | no | The name of a repository branch or tag or if not given the default branch. | -| `recursive` | boolean | no | Boolean value used to get a recursive tree (false by default). | -| `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](index.md#pagination). | -| `pagination` | string | no | If set to `keyset`, use the new keyset pagination method. | | `page_token` | string | no | The tree record ID at which to fetch the next page. Used only with keyset pagination. | +| `pagination` | string | no | If `keyset`, use the [keyset-based pagination method](index.md#keyset-based-pagination). | +| `path` | string | no | The path inside the repository. Used to get content of subdirectories. | +| `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](index.md#pagination). | +| `recursive` | boolean | no | Boolean value used to get a recursive tree. Default is `false`. | +| `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch. | ```json [ @@ -92,9 +95,9 @@ Supported attributes: ## Get a blob from repository -Allows you to receive information about blob in repository like size and -content. Blob content is Base64 encoded. This endpoint can be accessed -without authentication if the repository is publicly accessible. +Allows you to receive information, such as size and content, about blobs in a repository. +Blob content is Base64 encoded. This endpoint can be accessed without authentication, +if the repository is publicly accessible. ```plaintext GET /projects/:id/repository/blobs/:sha @@ -109,7 +112,7 @@ Supported attributes: ## Raw blob content -Get the raw file contents for a blob by blob SHA. This endpoint can be accessed +Get the raw file contents for a blob, by blob SHA. This endpoint can be accessed without authentication if the repository is publicly accessible. ```plaintext @@ -131,24 +134,32 @@ Supported attributes: Get an archive of the repository. This endpoint can be accessed without authentication if the repository is publicly accessible. -This endpoint has a rate limit threshold of 5 requests per minute for GitLab.com users. +For GitLab.com users, this endpoint has a rate limit threshold of 5 requests per minute. ```plaintext GET /projects/:id/repository/archive[.format] ``` -`format` is an optional suffix for the archive format. Default is -`tar.gz`. Options are `tar.gz`, `tar.bz2`, `tbz`, `tbz2`, `tb2`, -`bz2`, `tar`, and `zip`. For example, specifying `archive.zip` -would send an archive in ZIP format. +`format` is an optional suffix for the archive format, and defaults to +`tar.gz`. For example, specifying `archive.zip` sends an archive in ZIP format. +Available options are: + +- `bz2` +- `tar` +- `tar.bz2` +- `tar.gz` +- `tb2` +- `tbz` +- `tbz2` +- `zip` Supported attributes: | Attribute | Type | Required | Description | |:------------|:---------------|:---------|:----------------------| | `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. | -| `path` | string | no | The subpath of the repository to download. This defaults to the whole repository (empty string). | +| `path` | string | no | The subpath of the repository to download. If an empty string, defaults to the whole repository. | +| `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. If not specified, defaults to the tip of the default branch. | Example request: @@ -159,7 +170,8 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.com/api/v4/pr ## Compare branches, tags or commits This endpoint can be accessed without authentication if the repository is -publicly accessible. Diffs can have an empty diff string if [diff limits](../development/diffs.md#diff-limits) are reached. +publicly accessible. Diffs can have an empty diff string if +[diff limits](../development/diffs.md#diff-limits) are reached. ```plaintext GET /projects/:id/repository/compare @@ -172,8 +184,8 @@ Supported attributes: | `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `from` | string | yes | The commit SHA or branch name. | | `to` | string | yes | The commit SHA or branch name. | -| `from_project_id` | integer | no | The ID to compare from | -| `straight` | boolean | no | Comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`. | +| `from_project_id` | integer | no | The ID to compare from. | +| `straight` | boolean | no | Comparison method: `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`...`to`)'. Default is `false`. | ```plaintext GET /projects/:id/repository/compare?from=master&to=feature @@ -217,6 +229,9 @@ Example response: ## Contributors +> - Attributes `additions` and `deletions` [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653) in GitLab 13.4, because they [always returned `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). +> - Attributes `additions` and `deletions` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38920) in GitLab 14.0. + Get repository contributors list. This endpoint can be accessed without authentication if the repository is publicly accessible. @@ -224,9 +239,6 @@ authentication if the repository is publicly accessible. GET /projects/:id/repository/contributors ``` -WARNING: -The `additions` and `deletions` attributes are [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653) as of GitLab 13.4, because they [always return `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). - Supported attributes: | Attribute | Type | Required | Description | @@ -255,16 +267,16 @@ Example response: ## Merge Base -Get the common ancestor for 2 or more refs (commit SHAs, branch names or tags). +Get the common ancestor for 2 or more refs, such as commit SHAs, branch names, or tags. ```plaintext GET /projects/:id/repository/merge_base ``` | Attribute | Type | Required | Description | -| --------- | -------------- | -------- | ------------------------------------------------------------------------------- | -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | -| `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed | +| --------- | -------------- | -------- | ---------------------------------------------------------------------------------- | +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | +| `refs` | array | yes | The refs to find the common ancestor of. Accepts multiple refs. | Example request: @@ -293,17 +305,16 @@ Example response: ## Add changelog data to a changelog file -> [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/351) in GitLab 13.9. +> - [Introduced](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/351) in GitLab 13.9. +> - Commit range limits [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89032) in GitLab 15.1 [with a flag](../administration/feature_flags.md) named `changelog_commits_limitation`. Enabled by default. Generate changelog data based on commits in a repository. -Given a version (using [semantic versioning](https://semver.org/)) and a range +Given a [semantic version](https://semver.org/) and a range of commits, GitLab generates a changelog for all commits that use a particular -[Git trailer](https://git-scm.com/docs/git-interpret-trailers). - -The output of this process is a new section in a changelog file in the Git -repository of the given project. The output format is in Markdown, and can be -customized. +[Git trailer](https://git-scm.com/docs/git-interpret-trailers). GitLab adds +a new Markdown-formatted section to a changelog file in the Git repository of +the project. The output format can be customized. ```plaintext POST /projects/:id/repository/changelog @@ -314,30 +325,21 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------- | :--------- | :---------- | | `version` | string | yes | The version to generate the changelog for. The format must follow [semantic versioning](https://semver.org/). | -| `from` | string | no | The start of the range of commits (as a SHA) to use for generating the changelog. This commit itself isn't included in the list. | -| `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the branch specified in the `branch` attribute. | -| `date` | datetime | no | The date and time of the release, defaults to the current time. | -| `branch` | string | no | The branch to commit the changelog changes to, defaults to the project's default branch. | -| `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | +| `branch` | string | no | The branch to commit the changelog changes to. Defaults to the project's default branch. | | `config_file` | string | no | Path to the changelog configuration file in the project's Git repository. Defaults to `.gitlab/changelog_config.yml`. | -| `file` | string | no | The file to commit the changes to, defaults to `CHANGELOG.md`. | -| `message` | string | no | The commit message to produce when committing the changes, defaults to `Add changelog for version X` where X is the value of the `version` argument. | +| `date` | datetime | no | The date and time of the release. Defaults to the current time. | +| `file` | string | no | The file to commit the changes to. Defaults to `CHANGELOG.md`. | +| `from` | string | no | The SHA of the commit that marks the beginning of the range of commits to include in the changelog. This commit isn't included in the changelog. | +| `message` | string | no | The commit message to use when committing the changes. Defaults to `Add changelog for version X`, where `X` is the value of the `version` argument. | +| `to` | string | no | The SHA of the commit that marks the end of the range of commits to include in the changelog. This commit _is_ included in the changelog. Defaults to the branch specified in the `branch` attribute. Limited to 15000 commits unless the feature flag `changelog_commits_limitation` is disabled. | +| `trailer` | string | no | The Git trailer to use for including commits. Defaults to `Changelog`. Case-sensitive: `Example` does not match `example` or `eXaMpLE`. | -WARNING: -GitLab treats trailers case-sensitively. If you set the `trailer` field to -`Example`, GitLab _won't_ include commits that use the trailer `example`, -`eXaMpLE`, or anything else that isn't _exactly_ `Example`. - -WARNING: -The allowed commits range between `from` and `to` is limited to 15000 commits. To disable -this restriction, [turn off the feature flag](../administration/feature_flags.md) -`changelog_commits_limitation`. +### Requirements for `from` attribute If the `from` attribute is unspecified, GitLab uses the Git tag of the last stable version that came before the version specified in the `version` -attribute. This requires that Git tag names follow a specific format, allowing -GitLab to extract a version from the tag names. By default, GitLab considers -tags using these formats: +attribute. For GitLab to extract version numbers from tag names, Git tag names +must follow a specific format. By default, GitLab considers tags using these formats: - `vX.Y.Z` - `X.Y.Z` @@ -350,7 +352,7 @@ For example, consider a project with the following tags: - v1.1.0 - v2.0.0 -If the `version` attribute is `2.1.0`, GitLab uses tag v2.0.0. And when the +If the `version` attribute is `2.1.0`, GitLab uses tag `v2.0.0`. And when the version is `1.1.1`, or `1.2.0`, GitLab uses tag v1.1.0. The tag `v1.0.0-pre1` is never used, because pre-release tags are ignored. @@ -372,7 +374,8 @@ This command generates a changelog for version `1.0.0`. The commit range: - Starts with the tag of the last release. -- Ends with the last commit on the target branch. The default target branch is the project's default branch. +- Ends with the last commit on the target branch. The default target branch is + the project's default branch. If the last tag is `v0.9.0` and the default branch is `main`, the range of commits included in this example is `v0.9.0..main`: @@ -638,28 +641,28 @@ At the top level, the following variable is available: In a category, the following variables are available: -- `title`: the title of the category (after it has been remapped). - `count`: the number of entries in this category. +- `entries`: the entries that belong to this category. - `single_change`: a boolean that indicates if there is only one change (`true`), or multiple changes (`false`). -- `entries`: the entries that belong to this category. +- `title`: the title of the category (after it has been remapped). In an entry, the following variables are available (here `foo.bar` means that `bar` is a sub-field of `foo`): -- `title`: the title of the changelog entry (this is the commit title). -- `commit.reference`: a reference to the commit, for example, - `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. -- `commit.trailers`: an object containing all the Git trailers that were present - in the commit body. -- `author.reference`: a reference to the commit author (for example, `@alice`). - `author.contributor`: a boolean set to `true` when the author is not a project member, otherwise `false`. - `author.credit`: a boolean set to `true` when `author.contributor` is `true` or when `include_groups` is configured, and the author is a member of one of the groups. +- `author.reference`: a reference to the commit author (for example, `@alice`). +- `commit.reference`: a reference to the commit, for example, + `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. +- `commit.trailers`: an object containing all the Git trailers that were present + in the commit body. - `merge_request.reference`: a reference to the merge request that first introduced the change (for example, `gitlab-org/gitlab!50063`). +- `title`: the title of the changelog entry (this is the commit title). The `author` and `merge_request` objects might not be present if the data couldn't be determined. For example, when a commit is created without a @@ -732,11 +735,11 @@ Supported attributes: | Attribute | Type | Required | Description | | :-------- | :------- | :--------- | :---------- | | `version` | string | yes | The version to generate the changelog for. The format must follow [semantic versioning](https://semver.org/). | +| `config_file` | string | no | The path of changelog configuration file in the project's Git repository, defaults to `.gitlab/changelog_config.yml`. | +| `date` | datetime | no | The date and time of the release, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z`. Defaults to the current time. | | `from` | string | no | The start of the range of commits (as a SHA) to use for generating the changelog. This commit itself isn't included in the list. | | `to` | string | no | The end of the range of commits (as a SHA) to use for the changelog. This commit _is_ included in the list. Defaults to the branch specified in the `branch` attribute. | -| `date` | datetime | no | The date and time of the release, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z`. Defaults to the current time. | | `trailer` | string | no | The Git trailer to use for including commits, defaults to `Changelog`. | -| `config_file` | string | no | The path of changelog configuration file in the project's Git repository, defaults to `.gitlab/changelog_config.yml`. | ```shell curl --header "PRIVATE-TOKEN: token" "https://gitlab.com/api/v4/projects/42/repository/changelog?version=1.0.0" diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 8097fecea87..9f06467964b 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index cbd6a369e97..1dd65ed60b8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository submodules API **(FREE)** diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md index f70ad2f09e7..114dc4e383e 100644 --- a/doc/api/resource_groups.md +++ b/doc/api/resource_groups.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource group API **(FREE)** @@ -63,6 +63,101 @@ Example of response } ``` +## List upcoming jobs for a specific resource group + +```plaintext +GET /projects/:id/resource_groups/:key/upcoming_jobs +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The key of the resource group | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/50/resource_groups/production/upcoming_jobs" +``` + +Example of response + +```json +[ + { + "id": 1154, + "status": "waiting_for_resource", + "stage": "deploy", + "name": "deploy_to_production", + "ref": "main", + "tag": false, + "coverage": null, + "allow_failure": false, + "created_at": "2022-09-28T09:57:04.590Z", + "started_at": null, + "finished_at": null, + "duration": null, + "queued_duration": null, + "user": { + "id": 1, + "username": "john_smith", + "name": "John Smith", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/2d691a4d0427ca8db6efc3924a6408ba?s=80\u0026d=identicon", + "web_url": "http://localhost:3000/john_smith", + "created_at": "2022-05-27T19:19:17.526Z", + "bio": "", + "location": null, + "public_email": null, + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": null, + "job_title": "", + "pronouns": null, + "bot": false, + "work_information": null, + "followers": 0, + "following": 0, + "local_time": null + }, + "commit": { + "id": "3177f39064891bbbf5124b27850c339da331f02f", + "short_id": "3177f390", + "created_at": "2022-09-27T17:55:31.000+02:00", + "parent_ids": [ + "18059e45a16eaaeaddf6fc0daf061481549a89df" + ], + "title": "List upcoming jobs", + "message": "List upcoming jobs", + "author_name": "Example User", + "author_email": "user@example.com", + "authored_date": "2022-09-27T17:55:31.000+02:00", + "committer_name": "Example User", + "committer_email": "user@example.com", + "committed_date": "2022-09-27T17:55:31.000+02:00", + "trailers": {}, + "web_url": "https://gitlab.example.com/test/gitlab/-/commit/3177f39064891bbbf5124b27850c339da331f02f" + }, + "pipeline": { + "id": 274, + "iid": 9, + "project_id": 50, + "sha": "3177f39064891bbbf5124b27850c339da331f02f", + "ref": "main", + "status": "waiting_for_resource", + "source": "web", + "created_at": "2022-09-28T09:57:04.538Z", + "updated_at": "2022-09-28T09:57:13.537Z", + "web_url": "https://gitlab.example.com/test/gitlab/-/pipelines/274" + }, + "web_url": "https://gitlab.example.com/test/gitlab/-/jobs/1154", + "project": { + "ci_job_token_scope_enabled": false + } + } +] +``` + ## Edit an existing resource group Updates an existing resource group's properties. diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md index 37a945b140e..41e1ddd725b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource iteration events API **(PREMIUM)** diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index da265972f28..62a37806459 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource label events API **(FREE)** diff --git a/doc/api/resource_milestone_events.md b/doc/api/resource_milestone_events.md index 448ec6e2c1d..d1e0b4fe053 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource milestone events API **(FREE)** diff --git a/doc/api/resource_state_events.md b/doc/api/resource_state_events.md index 8e957df8145..5ea588167a0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource state events API **(FREE)** diff --git a/doc/api/resource_weight_events.md b/doc/api/resource_weight_events.md index faa2d543c50..14596556b7b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource weight events API **(FREE)** diff --git a/doc/api/runners.md b/doc/api/runners.md index 8af388a2b74..657eb4d470c 100644 --- a/doc/api/runners.md +++ b/doc/api/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Runners API **(FREE)** diff --git a/doc/api/saml.md b/doc/api/saml.md new file mode 100644 index 00000000000..810ed382d49 --- /dev/null +++ b/doc/api/saml.md @@ -0,0 +1,78 @@ +--- +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# SAML API **(PREMIUM SAAS)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5. + +API for accessing SAML features. + +## Get SAML identities for a group + +```plaintext +GET /groups/:id/saml/identities +``` + +Fetch SAML identities for a group. + +Supported attributes: + +| Attribute | Type | Required | Description | +|:------------------|:--------|:---------|:----------------------| +| `id` | integer | Yes | Group ID for the group to return SAML identities. | + +If successful, returns [`200`](index.md#status-codes) and the following +response attributes: + +| Attribute | Type | Description | +| ------------ | ------ | ------------------------- | +| `extern_uid` | string | External UID for the user | +| `user_id` | string | ID for the user | + +Example request: + +```shell +curl --location --request GET "https://gdk.test:3443/api/v4/groups/33/saml/identities" \ +--header "<PRIVATE-TOKEN>" \ +--form "extern_uid=<ID_TO_BE_UPDATED>" \ +``` + +Example response: + +```json +[ + { + "extern_uid": "4", + "user_id": 48 + } +] +``` + +## Update `extern_uid` field for a SAML identity + +Update `extern_uid` field for a SAML identity. Field that can be updated are: + +| SAML IdP attribute | GitLab field | +| ------------------ | ------------ | +| `id/externalId` | `extern_uid` | + +```plaintext +PATCH groups/:groups_id/saml/:uid +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ------------------------- | +| `uid` | string | yes | External UID of the user. | + +Example request: + +```shell +curl --location --request PATCH "https://gdk.test:3443/api/v4/groups/33/saml/sydney_jones" \ +--header "<PRIVATE TOKEN>" \ +--form "extern_uid=sydney_jones_new" \ +``` diff --git a/doc/api/scim.md b/doc/api/scim.md index 9c88997b94c..b1763a44fc4 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -2,253 +2,82 @@ type: reference, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- +# SCIM API **(PREMIUM SAAS)** -# SCIM API (SYSTEM ONLY) **(PREMIUM SAAS)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10. - -The SCIM API implements the [RFC7644 protocol](https://tools.ietf.org/html/rfc7644). As this API is for -**system** use for SCIM provider integration, it is subject to change without notice. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98354) in GitLab 15.5. To use this API, [Group SSO](../user/group/saml_sso/index.md) must be enabled for the group. This API is only in use where [SCIM for Group SSO](../user/group/saml_sso/scim_setup.md) is enabled. It's a prerequisite to the creation of SCIM identities. -## 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. - -```plaintext -GET /api/scim/v2/groups/:group_path/Users -``` - -Parameters: - -| Attribute | Type | Required | Description | -|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| -| `filter` | string | no | A [filter](#available-filters) expression. | -| `group_path` | string | yes | Full path to the group. | -| `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one will be interpreted as 1. | -| `count` | integer | no | Desired maximum number of query results. | - -NOTE: -Pagination follows the [SCIM spec](https://tools.ietf.org/html/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: - -```shell -curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \ - --header "Authorization: Bearer <your_scim_token>" \ - --header "Content-Type: application/scim+json" -``` - -Example response: +Not to be confused with the [internal SCIM API](../development/internal_api/index.md#scim-api). -```json -{ - "schemas": [ - "urn:ietf:params:scim:api:messages:2.0:ListResponse" - ], - "totalResults": 1, - "itemsPerPage": 20, - "startIndex": 1, - "Resources": [ - { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], - "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", - "active": true, - "name.formatted": "Test User", - "userName": "username", - "meta": { "resourceType":"User" }, - "emails": [ - { - "type": "work", - "value": "name@example.com", - "primary": true - } - ] - } - ] -} -``` +## Get SCIM identities for a group -## Get a single SCIM provisioned user +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5. ```plaintext -GET /api/scim/v2/groups/:group_path/Users/:id +GET /groups/:id/scim/identities ``` -Parameters: +Supported attributes: -| Attribute | Type | Required | Description | -|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| -| `id` | string | yes | External UID of the user. | -| `group_path` | string | yes | Full path to the group. | +| Attribute | Type | Required | Description | +|:------------------|:--------|:---------|:----------------------| +| `id` | integer | Yes | Return SAML identities for the given group ID. | -Example request: +If successful, returns [`200`](index.md#status-codes) and the following +response attributes: -```shell -curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ - --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" -``` +| Attribute | Type | Description | +| ------------ | ------ | ------------------------- | +| `extern_uid` | string | External UID for the user | +| `user_id` | string | ID for the user | Example response: ```json -{ - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], - "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", - "active": true, - "name.formatted": "Test User", - "userName": "username", - "meta": { "resourceType":"User" }, - "emails": [ +[ { - "type": "work", - "value": "name@example.com", - "primary": true + "extern_uid": "4", + "user_id": 48 } - ] -} +] ``` -## Create a SCIM provisioned user - -```plaintext -POST /api/scim/v2/groups/:group_path/Users/ -``` - -Parameters: - -| Attribute | Type | Required | Description | -|:---------------|:----------|:----|:--------------------------| -| `externalId` | string | yes | External UID of the user. | -| `userName` | string | yes | Username of the user. | -| `emails` | JSON string | yes | Work email. | -| `name` | JSON string | yes | Name of the user. | -| `meta` | string | no | Resource type (`User`). | - Example request: ```shell -curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/groups/test_group/Users" \ - --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \ - --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" -``` - -Example response: - -```json -{ - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], - "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", - "active": true, - "name.formatted": "Test User", - "userName": "username", - "meta": { "resourceType":"User" }, - "emails": [ - { - "type": "work", - "value": "name@example.com", - "primary": true - } - ] -} +curl --location --request GET "https://gdk.test:3443/api/v4/groups/33/scim/identities" \ +--header "<PRIVATE-TOKEN>" \ +--form "extern_uid=<ID_TO_BE_UPDATED>" \ ``` -Returns a `201` status code if successful. +## Update extern_uid field for a SCIM identity -## Update a single SCIM provisioned user +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5. Fields that can be updated are: -| SCIM/IdP field | GitLab field | -|:---------------------------------|:-----------------------------------------------------------------------------| -| `id/externalId` | `extern_uid` | -| `name.formatted` | `name` ([Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/363058)) | -| `emails\[type eq "work"\].value` | `email` ([Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/363058)) | -| `active` | Identity removal if `active` = `false` | -| `userName` | `username` ([Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/363058)) | - -```plaintext -PATCH /api/scim/v2/groups/:group_path/Users/:id -``` - -Parameters: - -| Attribute | Type | Required | Description | -|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| -| `id` | string | yes | External UID of the user. | -| `group_path` | string | yes | Full path to the group. | -| `Operations` | JSON string | yes | An [operations](#available-operations) expression. | - -Example request: - -```shell -curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ - --data '{ "Operations": [{"op":"Add","path":"name.formatted","value":"New Name"}] }' \ - --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. +| SCIM/IdP field | GitLab field | +| --------------- | ------------ | +| `id/externalId` | `extern_uid` | ```plaintext -DELETE /api/scim/v2/groups/:group_path/Users/:id +PATCH groups/:groups_id/scim/:uid ``` Parameters: -| Attribute | Type | Required | Description | -|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| -| `id` | string | yes | External UID of the user. | -| `group_path` | string | yes | Full path to the group. | +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ------------------------- | +| `uid` | string | yes | External UID of the user. | Example request: ```shell -curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ - --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" -``` - -Returns an empty response with a `204` status code if successful. - -## Available filters - -They match an expression as specified in [the RFC7644 filtering section](https://tools.ietf.org/html/rfc7644#section-3.4.2.2). - -| Filter | Description | -| ----- | ----------- | -| `eq` | The attribute matches exactly the specified value. | - -Example: - -```plaintext -id eq a-b-c-d -``` - -## Available operations - -They perform an operation as specified in [the RFC7644 update section](https://tools.ietf.org/html/rfc7644#section-3.5.2). - -| Operator | Description | -| ----- | ----------- | -| `Replace` | The attribute's value is updated. | -| `Add` | The attribute has a new value. | - -Example: - -```json -{ "op": "Add", "path": "name.formatted", "value": "New Name" } +curl --location --request PATCH "https://gdk.test:3443/api/v4/groups/33/scim/sydney_jones" \ +--header "<PRIVATE TOKEN>" \ +--form "extern_uid=sydney_jones_new" \ ``` diff --git a/doc/api/search.md b/doc/api/search.md index 4e644a6c087..a59f943319c 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +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/engineering/ux/technical-writing/#assignments --- @@ -10,28 +10,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w Every API call to search must be authenticated. +## Additional scopes **(PREMIUM)** + +Additional scopes are available for the [Advanced Search API](#advanced-search-api) +and [Group Search API](#group-search-api) if +[Elasticsearch is enabled](../integration/advanced_search/elasticsearch.md): +`blobs`, `commits`, `notes`, `wiki_blobs`. + ## Advanced Search API -Search globally across the GitLab instance. +Search for an expression globally across the GitLab instance, in a specified scope. +The response depends on the requested scope. ```plaintext GET /search ``` -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `scope` | string | yes | The scope to search in | -| `search` | string | yes | The search query | -| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | -| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | -| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| -| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| - -Search the expression in the specified scope. These scopes are supported: `projects`, `issues`, `merge_requests`, `milestones`, `snippet_titles`, `users`. - -If Elasticsearch is enabled additional scopes available are `blobs`, `wiki_blobs`, `notes`, and `commits`. Find more about [the feature](../integration/advanced_search/elasticsearch.md). **(PREMIUM)** - -The response depends on the requested scope. +| Attribute | Type | Required | Description | +| ------------- | -------- | ---------- | ------------| +| `scope` | string | Yes | The scope to search in. Values include `projects`, `issues`, `merge_requests`, `milestones`, `snippet_titles`, `users`. [Additional scopes](#additional-scopes): `blobs`, `commits`, `notes`, `wiki_blobs`. | +| `search` | string | Yes | The search query. | +| `confidential` | boolean | No | Filter by confidentiality. Supports `issues` scope; other scopes are ignored. | +| `order_by` | string | No | Allowed values are `created_at` only. If not set, results are sorted by `created_at` in descending order for basic search, or by the most relevant documents for Advanced Search.| +| `sort` | string | No | Allowed values are `asc` or `desc` only. If not set, results are sorted by `created_at` in descending order for basic search, or by the most relevant documents for Advanced Search.| +| `state` | string | No | Filter by state. Supports `issues` and `merge_requests` scopes; other scopes are ignored. | ### Scope: `projects` @@ -129,7 +131,7 @@ Example response: ``` NOTE: -`assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +The `assignee` column is deprecated. It is shown as a single-sized array `assignees` to conform to the GitLab EE API. ### Scope: `merge_requests` @@ -432,27 +434,23 @@ Example response: ## Group Search API -Search in the specified group. +Search for an expression in the specified group. -If a user is not a member of a group and the group is private, a `GET` request on that group results in a `404` status code. +If a user is not a member of a group and the group is private, a `GET` request on that group results in a `404 Not Found` status code. ```plaintext GET /groups/:id/search ``` -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | -| `scope` | string | yes | The scope to search in | -| `search` | string | yes | The search query | -| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | -| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | -| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| -| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| - -Search the expression in the specified scope. These scopes are supported: `projects`, `issues`, `merge_requests`, `milestones`, `users`. - -If Elasticsearch is enabled additional scopes available are `blobs`, `wiki_blobs`, `notes`, and `commits`. Find more about [the feature](../integration/advanced_search/elasticsearch.md). **(PREMIUM)** +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | -------------| +| `id` | integer or string | Yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `scope` | string | Yes | The scope to search in. Values include `issues`, `merge_requests`, `milestones`, `projects`, `users`. [Additional scopes](#additional-scopes): `blobs`, `commits`, `notes`, `wiki_blobs`. | +| `search` | string | Yes | The search query. | +| `confidential` | boolean | No | Filter by confidentiality. Supports only `issues` scope; other scopes are ignored. | +| `order_by` | string | No | Allowed values are `created_at` only. If not set, results are sorted by `created_at` in descending order for basic search, or by the most relevant documents for Advanced Search.| +| `sort` | string | No | Allowed values are `asc` or `desc` only. If not set, results are sorted by `created_at` in descending order for basic search, or by the most relevant documents for Advanced Search.| +| `state` | string | No | Filter by state. Supports `issues` and `merge_requests` only; other scopes are ignored. | The response depends on the requested scope. @@ -824,7 +822,7 @@ Example response: ## Project Search API -Search in the specified project. +Search for an expression in the specified project. If a user is not a member of a project and the project is private, a `GET` request on that project results in a `404` status code. @@ -832,18 +830,16 @@ If a user is not a member of a project and the project is private, a `GET` reque GET /projects/:id/search ``` -| Attribute | Type | Required | Description | -| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `scope` | string | yes | The scope to search in | -| `search` | string | yes | The search query | -| `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: `commits`, `blobs`, and `wiki_blobs`. | -| `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | -| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. | -| `order_by` | string | no | Allowed values are `created_at` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| -| `sort` | string | no | Allowed values are `asc` or `desc` only. If this is not set, the results are either sorted by `created_at` in descending order for basic search, or by the most relevant documents when using advanced search.| - -Search the expression in the specified scope. These scopes are supported: `issues`, `merge_requests`, `milestones`, `notes`, `wiki_blobs`, `commits`, `blobs`, `users`. +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ------------| +| `id` | integer or string | Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `scope` | string | Yes | The scope to search in. Values include `blobs`, `commits`, `issues`, `merge_requests`, `milestones`, `notes`, `users`, and `wiki_blobs`. | +| `search` | string | Yes | The search query. | +| `confidential` | boolean | No | Filter by confidentiality. Supports `issues` scope; other scopes are ignored. | +| `ref` | string | No | The name of a repository branch or tag to search on. The project's default branch is used by default. Applicable only for scopes `blobs`, `commits`, and `wiki_blobs`. | +| `order_by` | string | No | Allowed values are `created_at` only. If not set, results are sorted by `created_at` in descending order for basic search, or by the most relevant documents for Advanced Search.| +| `sort` | string | No | Allowed values are `asc` or `desc` only. If not set, results are sorted by `created_at` in descending order for basic search, or by the most relevant documents for Advanced Search.| +| `state` | string | No | Filter by state. Supports the `issues` and `merge_requests` scopes; other scopes are ignored. | The response depends on the requested scope. @@ -1144,9 +1140,9 @@ This scope is available only if [Elasticsearch](../integration/advanced_search/e Filters are available for this scope: -- filename -- path -- extension +- Filename +- Path +- Extension To use a filter, include it in your query. For example: `a query filename:some_name*`. You may use wildcards (`*`) to use glob matching. diff --git a/doc/api/secure_files.md b/doc/api/secure_files.md index b4fe7bb6dd8..0c34dd30cdf 100644 --- a/doc/api/secure_files.md +++ b/doc/api/secure_files.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -127,7 +127,7 @@ Example response: Download the contents of a project's secure file. ```plaintext -GET /projects/:project_id/download/:id +GET /projects/:project_id/secure_files/:id/download ``` Supported attributes: diff --git a/doc/api/settings.md b/doc/api/settings.md index 467fa6bfc37..3d8d02b8429 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application settings API **(FREE SELF)** @@ -216,7 +216,8 @@ Example response: "admin_mode": false, "external_pipeline_validation_service_timeout": null, "external_pipeline_validation_service_token": null, - "external_pipeline_validation_service_url": null + "external_pipeline_validation_service_url": null, + "can_create_group": false } ``` @@ -266,6 +267,7 @@ listed in the descriptions of the relevant settings. | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It automatically builds, tests, and deploys applications based on a predefined CI/CD configuration. | | `automatic_purchased_storage_allocation` | boolean | no | Enabling this permits automatic allocation of purchased storage in a namespace. | +| `can_create_group` | boolean | no | Indicates whether users can create top-level groups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. Defaults to `true`. | | `check_namespace_plan` **(PREMIUM)** | boolean | no | Enabling this makes only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | | `container_expiration_policies_enable_historic_entries` | boolean | no | Enable [cleanup policies](../user/packages/container_registry/reduce_container_registry_storage.md#enable-the-cleanup-policy) for all projects. | @@ -352,7 +354,7 @@ listed in the descriptions of the relevant settings. | `gravatar_enabled` | boolean | no | Enable Gravatar. | | `hashed_storage_enabled` | boolean | no | Create new projects using hashed storage paths: Enable immutable, hash-based paths and repository names to store repositories on disk. This prevents repositories from having to be moved or renamed when the Project URL changes and may improve disk I/O performance. (Always enabled in GitLab versions 13.0 and later, configuration is scheduled for removal in 14.0) | | `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help. | -| `help_page_support_url` | string | no | Alternate support URL for help page and help dropdown. | +| `help_page_support_url` | string | no | Alternate support URL for help page and help dropdown list. | | `help_page_text` | string | no | Custom text displayed on the help page. | | `help_text` **(PREMIUM)** | string | no | GitLab server administrator information. | | `hide_third_party_offers` | boolean | no | Do not display offers from third parties in GitLab. | diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index dedd28d6cf6..a6422d8545a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 a73542c8505..1ef5299668d 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/snippets.md b/doc/api/snippets.md index e3bc3573ed7..593985b5d5f 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Snippets API **(FREE)** diff --git a/doc/api/statistics.md b/doc/api/statistics.md index 17daf2fc71f..691b03505a7 100644 --- a/doc/api/statistics.md +++ b/doc/api/statistics.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application statistics API **(FREE SELF)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Get current application statistics List the current statistics of the GitLab instance. You have to be an -administrator in order to perform this action. +administrator to perform this action. NOTE: These statistics are approximate. diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md index 1cedd2d3730..a30bfbd4dfb 100644 --- a/doc/api/status_checks.md +++ b/doc/api/status_checks.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md index c174c0f5264..9771225ad31 100644 --- a/doc/api/suggestions.md +++ b/doc/api/suggestions.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 14339460270..1b72ef1da53 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # System hooks API **(FREE SELF)** diff --git a/doc/api/tags.md b/doc/api/tags.md index 45c621f534e..35085baf93f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tags API **(FREE)** diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index 5f862201571..9636393dfe9 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index 71b791de16a..7c68daa5c48 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index ab97823fe07..152f3373ad6 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index adba4f75255..e676da2e999 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/api/todos.md b/doc/api/todos.md index 98f254f6620..8fd76864f1c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab To-Do List API **(FREE)** diff --git a/doc/api/topics.md b/doc/api/topics.md index 38d99244bb6..13a5eabf8f9 100644 --- a/doc/api/topics.md +++ b/doc/api/topics.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Topics API **(FREE)** diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md index a01ed3e83a5..33126521901 100644 --- a/doc/api/usage_data.md +++ b/doc/api/usage_data.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine 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 --- diff --git a/doc/api/users.md b/doc/api/users.md index c30bac3c542..4a924f3b5f3 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Users API **(FREE)** @@ -106,7 +106,8 @@ GET /users?without_project_bots=true ### For administrators **(FREE SELF)** -> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. +> - 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. ```plaintext GET /users @@ -161,7 +162,8 @@ GET /users "private_profile": false, "current_sign_in_ip": "196.165.1.102", "last_sign_in_ip": "172.127.2.22", - "namespace_id": 1 + "namespace_id": 1, + "created_by": null }, { "id": 2, @@ -196,7 +198,8 @@ GET /users "private_profile": false, "current_sign_in_ip": "10.165.1.102", "last_sign_in_ip": "172.127.2.22", - "namespace_id": 2 + "namespace_id": 2, + "created_by": null } ] ``` @@ -269,6 +272,13 @@ You can include the users' [custom attributes](custom_attributes.md) in the resp GET /users?with_custom_attributes=true ``` +You can use the `created_by` parameter to see if a user account was created: + +- [Manually by an administrator](../user/profile/account/create_accounts.md#create-users-in-admin-area). +- As a [project bot user](../user/project/settings/project_access_tokens.md#bot-users-for-projects). + +If the returned value is `null`, the account was created by a user who registered an account themselves. + ## Single user Get a single user. @@ -315,7 +325,8 @@ Parameters: ### For administrators **(FREE SELF)** -> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. +> - 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. ```plaintext GET /users/:id @@ -378,7 +389,8 @@ Example Responses: "plan": "gold", "trial": true, "sign_in_count": 1337, - "namespace_id": 1 + "namespace_id": 1, + "created_by": null } ``` @@ -419,6 +431,13 @@ see the `group_saml` option and `provisioned_by_group_id` parameter: } ``` +Administrators can use the `created_by` parameter to see if a user account was created: + +- [Manually by an administrator](../user/profile/account/create_accounts.md#create-users-in-admin-area). +- As a [project bot user](../user/project/settings/project_access_tokens.md#bot-users-for-projects). + +If the returned value is `null`, the account was created by a user who registered an account themselves. + You can include the user's [custom attributes](custom_attributes.md) in the response with: ```plaintext @@ -505,6 +524,7 @@ Parameters: | `bio` | No | User's biography | | `can_create_group` | No | User can create groups - true or false | | `color_scheme_id` | No | User's color scheme for the file viewer (see [the user preference docs](../user/profile/preferences.md#syntax-highlighting-theme) for more information) | +| `commit_email` | No | User's commit email. Set to `_private` to use the private commit email. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375148) in GitLab 15.5. | | `email` | No | Email | | `extern_uid` | No | External UID | | `external` | No | Flags the user as external - true or false (default) | @@ -519,6 +539,7 @@ Parameters: | `password` | No | Password | | `private_profile` | No | User's profile is private - true, false (default), or null (is converted to false) | | `projects_limit` | No | Limit projects each user can create | +| `pronouns` | No | Pronouns | | `provider` | No | External provider name | | `public_email` | No | Public email of the user (must be already verified) | | `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0`. | @@ -628,7 +649,8 @@ Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see ### For administrators **(FREE SELF)** -> The `namespace_id` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82045) in GitLab 14.10. +> - 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. ```plaintext GET /user @@ -681,6 +703,7 @@ Parameters: "current_sign_in_ip": "196.165.1.102", "last_sign_in_ip": "172.127.2.22", "namespace_id": 1, + "created_by": null, "note": null } ``` diff --git a/doc/api/version.md b/doc/api/version.md index efdf2b8b626..0ceab92b9d6 100644 --- a/doc/api/version.md +++ b/doc/api/version.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Version API **(FREE)** @@ -9,8 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: We recommend you use the [Metadata API](metadata.md) instead of the Version API. It contains additional information and is aligned with the GraphQL metadata endpoint. +As of GitLab 15.5, the Version API is a mirror of the Metadata API. -Retrieve version information for this GitLab instance. Responds `200 OK` for +Retrieves version information for the GitLab instance. Responds with `200 OK` for authenticated users. ```plaintext @@ -21,7 +22,13 @@ GET /version curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/version" ``` -Example response: +## Example responses + +### GitLab 15.5 and later + +See [Metadata API](metadata.md) for the response. + +### GitLab 15.4 and earlier ```json { diff --git a/doc/api/visual_review_discussions.md b/doc/api/visual_review_discussions.md index 7f91b829061..4b9a7d4f88a 100644 --- a/doc/api/visual_review_discussions.md +++ b/doc/api/visual_review_discussions.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Visual Review discussions API **(PREMIUM)** diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index c90dc226661..b82e2b6cbdd 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerabilities API **(ULTIMATE)** diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 59943ede3e6..14966d2e925 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability export API **(ULTIMATE)** diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index fcfef848f14..a236960bc68 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability Findings API **(ULTIMATE)** diff --git a/doc/api/wikis.md b/doc/api/wikis.md index ebdaa700aa7..b092338aaa5 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project wikis API **(FREE)** diff --git a/doc/architecture/blueprints/_template.md b/doc/architecture/blueprints/_template.md index e99ce61970a..7637c3bf5fa 100644 --- a/doc/architecture/blueprints/_template.md +++ b/doc/architecture/blueprints/_template.md @@ -1,4 +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 status: proposed creation-date: yyyy-mm-dd authors: [ "@username" ] @@ -52,7 +55,10 @@ good title can help communicate what the blueprint is and should be considered as part of any review. --> -[[_TOC_]] +<!-- +For long pages, consider creating a table of contents. +The `[_TOC_]` function is not supported on docs.gitlab.com. +--> ## Summary diff --git a/doc/architecture/blueprints/ci_data_decay/index.md b/doc/architecture/blueprints/ci_data_decay/index.md index 23c8e9df1bb..221c2364f79 100644 --- a/doc/architecture/blueprints/ci_data_decay/index.md +++ b/doc/architecture/blueprints/ci_data_decay/index.md @@ -102,9 +102,9 @@ Epic: [Reduce the rate of builds metadata table growth](https://gitlab.com/group ### Partition CI/CD pipelines database tables -After we move CI/CD metadata to a different store, or reduce the rate of +Even if we move CI/CD metadata to a different store, or reduce the rate of metadata growth in a different way, the problem of having billions of rows -describing pipelines, builds and artifacts, remains. We still need to keep +describing pipelines, builds and artifacts, remains. We still may need to keep reference to the metadata we might store in object storage and we still do need to be able to retrieve this information reliably in bulk (or search through it). @@ -123,12 +123,12 @@ multiple smaller ones, using PostgreSQL partitioning features. There are a few approaches we can take to partition CI/CD data. A promising one is using list-based partitioning where a partition number is assigned a pipeline, and gets propagated to all resources that are related to this -pipeline. We assign the partition number based on when the pipeline was created -or when we observed the last processing activity in it. This is very flexible -because we can extend this partitioning strategy at will; for example with this -strategy we can assign an arbitrary partition number based on multiple -partitioning keys, combining time-decay-based partitioning with tenant-based -partitioning on the application level. +pipeline. We will assign a partition number using a +[uniform logical partition ID](pipeline_partitioning.md#why-do-we-want-to-use-explicit-logical-partition-ids) +This is very flexible because we can extend this partitioning strategy at will; +for example with this strategy we can assign an arbitrary partition number +based on multiple partitioning keys, combining time-decay-based partitioning +with tenant-based partitioning on the application level if desired. Partitioning rarely accessed data should also follow the policy defined for builds archival, to make it consistent and reliable. @@ -177,7 +177,7 @@ everyone to understand the vision described in this architectural blueprint. ### Removing pipeline data -While it might be tempting to simply remove old or archived data from our +While it might be tempting to remove old or archived data from our databases this should be avoided. It is usually not desired to permanently remove user data unless consent is given to do so. We can, however, move data to a different data store, like object storage. @@ -245,6 +245,7 @@ In progress. - 2022-04-15: Partitioned pipeline data associations PoC [shipped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84071). - 2022-04-30: Additional [benchmarking started](https://gitlab.com/gitlab-org/gitlab/-/issues/361019) to evaluate impact. - 2022-06-31: [Pipeline partitioning design](pipeline_partitioning.md) document [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87683) merged. +- 2022-09-01: Engineering effort started to implement partitioning. ## Who @@ -273,6 +274,7 @@ Domain experts: |------------------------------|------------------------| | Verify / Pipeline execution | Fabio Pitino | | Verify / Pipeline execution | Marius Bobin | +| Verify / Pipeline insights | Maxime Orefice | | PostgreSQL Database | Andreas Brandl | <!-- vale gitlab.Spelling = YES --> diff --git a/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md b/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md index baec14e3f0f..5f907ecdaa4 100644 --- a/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md +++ b/doc/architecture/blueprints/ci_data_decay/pipeline_partitioning.md @@ -60,7 +60,7 @@ out of a database to a different place when data is no longer relevant or needed. Our dataset is extremely large (tens of terabytes), so moving such a high volume of data is challenging. When time-decay is implemented using partitioning, we can archive the entire partition (or set of partitions) by -simply updating a single record in one of our database tables. It is one of the +updating a single record in one of our database tables. It is one of the least expensive ways to implement time-decay patterns at a database level.  @@ -87,6 +87,7 @@ incidents, over the last couple of months, for example: - S2: 2022-04-12 [Transactions detected that have been running for more than 10m](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/6821) - S2: 2022-04-06 [Database contention plausibly caused by excessive `ci_builds` reads](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/6773) - S2: 2022-03-18 [Unable to remove a foreign key on `ci_builds`](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/6642) +- S2: 2022-10-10 [The queuing_queries_duration SLI apdex violating SLO](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/7852#note_1130123525) We have approximately 50 `ci_*` prefixed database tables, and some of them would benefit from partitioning. @@ -259,7 +260,7 @@ smart enough to move rows between partitions on its own. A partitioned table is called a **routing** table and it will use the `p_` prefix which should help us with building automated tooling for query analysis. -A table partition will be simply called **partition** and it can use the a +A table partition will be called **partition** and it can use the a physical partition ID as suffix, leaded by a `p` letter, for example `ci_builds_p101`. Existing CI tables will become **zero partitions** of the new routing tables. Depending on the chosen @@ -278,6 +279,20 @@ also find information about which logical partitions are "active" or "archived", which will help us to implement a time-decay pattern using database declarative partitioning. +Doing that will also allow us to use a Unified Resource Identifier for +partitioned resources, that will contain a pointer to a pipeline ID, we could +then use to efficiently lookup a partition the resource is stored in. It might +be important when a resources can be directly referenced by an URL, in UI or +API. We could use an ID like `1e240-5ba0` for pipeline `123456`, build `23456`. +Using a dash `-` can prevent an identifier from being highlighted and copied +with a mouse double-click. If we want to avoid this problem, we can use any +character of written representation that is not present in base-16 numeral +system - any letter from `g` to `z` in Latin alphabet, for example `x`. In that +case an example of an URI would look like `1e240x5ba0`. If we decide to update +the primary identifier of a partitioned resource (today it is just a big +integer) it is important to design a system that is resilient to migrating data +between partitions, to avoid changing idenfiers when rebalancing happens. + `ci_partitions` table will store information about a partition identifier, pipeline ids range it is valid for and whether the partitions have been archived or not. Additional columns with timestamps may be helpful too. @@ -304,7 +319,7 @@ of storing archived data in PostgreSQL will be reduced significantly this way. There are some technical details here that are out of the scope of this description, but by using this strategy we can "archive" data, and make it much -less expensive to reside in our PostgreSQL cluster by simply toggling a boolean +less expensive to reside in our PostgreSQL cluster by toggling a boolean column value. ## Accessing partitioned data @@ -317,7 +332,7 @@ with its `partition_id`, and we will be able to find the partition that the pipeline data is stored in. We will need to constrain access to searching through pipelines, builds, -artifacts etc. Search can not be done through all partitions, as it would not +artifacts etc. Search cannot be done through all partitions, as it would not be efficient enough, hence we will need to find a better way of searching through archived pipelines data. It will be necessary to have different access patterns to access archived data in the UI and API. @@ -343,7 +358,7 @@ has_many :builds, -> (pipeline) { where(partition_id: pipeline.partition_id) } ``` The problem with this approach is that it makes preloading much more difficult -as instance dependent associations can not be used with preloads: +as instance dependent associations cannot be used with preloads: ```plaintext ArgumentError: The association scope 'builds' is instance dependent (the @@ -351,6 +366,33 @@ scope block takes an argument). Preloading instance dependent scopes is not supported. ``` +### Primary key + +Primary key must include the partitioning key column to partition the table. + +We first create a unique index including the `(id, partition_id)`. +Then, we drop the primary key constraint and use the new index created to set +the new primary key constraint. + +`ActiveRecord` [does not support](https://github.com/rails/rails/blob/6-1-stable/activerecord/lib/active_record/attribute_methods/primary_key.rb#L126) +composite primary keys, so we must force it to treat the `id` column as a primary key: + +```ruby +class Model < ApplicationRecord + self.primary_key = 'id' +end +``` + +The application layer is now ignorant of the database structure and all of the +existing queries from `ActiveRecord` continue to use the `id` column to access +the data. There is some risk to this approach because it is possible to +construct application code that results in duplicate models with the same `id` +value, but on a different `partition_id`. To mitigate this risk we must ensure +that all inserts use the database sequence to populate the `id` since they are +[guaranteed](https://www.postgresql.org/docs/12/sql-createsequence.html#id-1.9.3.81.7) +to allocate distinct values and rewrite the access patterns to include the +`partition_id` value. Manually assigning the ids during inserts must be avoided. + ### Foreign keys Foreign keys must reference columns that either are a primary key or form a @@ -403,7 +445,7 @@ partition, `auto_canceled_by_partition_id`, and the FK becomes: ```sql ALTER TABLE ONLY p_ci_pipelines - ADD CONSTRAINT fk_cancel_redundant_pieplines + ADD CONSTRAINT fk_cancel_redundant_pipelines FOREIGN KEY (auto_canceled_by_id, auto_canceled_by_partition_id) REFERENCES p_ci_pipelines(id, partition_id) ON DELETE SET NULL; ``` @@ -610,6 +652,40 @@ application-wide outage. 1. Make it possible to create partitions in an automatic way. 1. Deliver the new architecture to self-managed instances. +The diagram below visualizes this plan on Gantt chart. Please note that dates +on the chart below are just estimates to visualize the plan better, these are +not deadlines and can change at any time. + +```mermaid +gantt + title CI Data Partitioning Timeline + dateFormat YYYY-MM-DD + axisFormat %m-%y + + section Phase 0 + Build data partitioning strategy :done, 0_1, 2022-06-01, 90d + section Phase 1 + Partition biggest CI tables :1_1, after 0_1, 140d + Biggest table partitioned :milestone, metadata, 2022-12-01, 1min + Tables larger than 100GB partitioned :milestone, 100gb, after 1_1, 1min + section Phase 2 + Add paritioning keys to SQL queries :2_1, after 1_1, 120d + Emergency partition detachment possible :milestone, detachment, 2023-04-01, 1min + All SQL queries are routed to partitions :milestone, routing, after 2_1, 1min + section Phase 3 + Build new data access patterns :3_1, 2023-03-01, 120d + New API endpoint created for inactive data :milestone, api1, 2023-05-01, 1min + Filtering added to existing API endpoints :milestone, api2, 2023-07-01, 1min + section Phase 4 + Introduce time-decay mechanisms :4_1, 2023-06-01, 120d + Inactive partitions are not being read :milestone, part1, 2023-08-01, 1min + Performance of the database cluster improves :milestone, part2, 2023-09-01, 1min + section Phase 5 + Introduce auto-partitioning mechanisms :5_1, 2023-07-01, 120d + New partitions are being created automatically :milestone, part3, 2023-10-01, 1min + Partitioning is made available on self-managed :milestone, part4, 2023-11-01, 1min +``` + ## Conclusions We want to build a solid strategy for partitioning CI/CD data. We are aware of @@ -637,8 +713,8 @@ Authors: Recommenders: -| Role | Who | -|------------------------|-----------------| -| Distingiushed Engineer | Kamil Trzciński | +| Role | Who | +|-------------------------------|-----------------| +| Senior Distingiushed Engineer | Kamil Trzciński | <!-- vale gitlab.Spelling = YES --> diff --git a/doc/architecture/blueprints/ci_pipeline_components/index.md b/doc/architecture/blueprints/ci_pipeline_components/index.md index 94ec3e2f894..115f6909d2d 100644 --- a/doc/architecture/blueprints/ci_pipeline_components/index.md +++ b/doc/architecture/blueprints/ci_pipeline_components/index.md @@ -1,7 +1,7 @@ --- stage: Stage group: Pipeline Authoring -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Create a catalog of shareable pipeline constructs' --- @@ -107,7 +107,18 @@ identifying abstract concepts and are subject to changes as we refine the design - **Catalog** is the collection of projects that are set to contain components. - **Version** is the release name of a tag in the project, which allows components to be pinned to a specific revision. -## Characteristics of a component +## Definition of pipeline 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. +It can optionally take input parameters and set output data to be adaptable and reusable in different pipeline contexts, +while encapsulating and isolating implementation details. + +Components allow a pipeline to be assembled by using abstractions instead of having all the details defined in one place. +When using a component in a pipeline, a user shouldn't need to know the implementation details of the component and should +only rely on the provided interface. The interface will have a version / revision, so that users understand which revision they are interfacing with. + +A pipeline component defines its type which indicates in which context of the pipeline configuration the component can be used. +For example, a component of type X can only be used according to the type X use-case. For best experience with any systems made of components it's fundamental that components are single purpose, isolated, reusable and resolvable. @@ -118,7 +129,7 @@ isolated, reusable and resolvable. - **Reusability:** a component is designed to be used in different pipelines. Depending on the assumptions it's built on a component can be more or less generic. Generic components are more reusable but may require more customization. -- **Resolvable:** When a component depends on another component, this dependency needs to be explicit and trackable. Hidden dependencies can lead to myriads of problems. +- **Resolvable:** When a component depends on another component, this dependency must be explicit and trackable. ## Proposal diff --git a/doc/architecture/blueprints/ci_scale/index.md b/doc/architecture/blueprints/ci_scale/index.md index 75c4d05c334..c02fb35974b 100644 --- a/doc/architecture/blueprints/ci_scale/index.md +++ b/doc/architecture/blueprints/ci_scale/index.md @@ -17,11 +17,15 @@ and has become [one of the most beloved CI/CD solutions](https://about.gitlab.co GitLab CI/CD has come a long way since the initial release, but the design of the data storage for pipeline builds remains almost the same since 2012. We store all the builds in PostgreSQL in `ci_builds` table, and because we are -creating more than [2 million builds each day on GitLab.com](https://docs.google.com/spreadsheets/d/17ZdTWQMnTHWbyERlvj1GA7qhw_uIfCoI5Zfrrsh95zU), -we are reaching database limits that are slowing our development velocity down. +creating more than 5 million builds each day on GitLab.com we are reaching +database limits that are slowing our development velocity down. -On February 1st, 2021, GitLab.com surpassed 1 billion CI/CD builds created and the number of -builds continues to grow exponentially. +On February 1st, 2021, GitLab.com surpassed 1 billion CI/CD builds created. In +February 2022 we reached 2 billion of CI/CD build stored in the database. The +number of builds continues to grow exponentially. + +The screenshot below shows our forecast created at the beginning of 2021, that +turned out to be quite accurate.  @@ -34,9 +38,9 @@ builds continues to grow exponentially. The current state of CI/CD product architecture needs to be updated if we want to sustain future growth. -### We are running out of the capacity to store primary keys +### We were running out of the capacity to store primary keys: DONE -The primary key in `ci_builds` table is an integer generated in a sequence. +The primary key in `ci_builds` table is an integer value, generated in a sequence. Historically, Rails used to use [integer](https://www.postgresql.org/docs/14/datatype-numeric.html) type when creating primary keys for a table. We did use the default when we [created the `ci_builds` table in 2012](https://gitlab.com/gitlab-org/gitlab/-/blob/046b28312704f3131e72dcd2dbdacc5264d4aa62/db/ci/migrate/20121004165038_create_builds.rb). @@ -45,34 +49,32 @@ since the release of Rails 5. The framework is now using `bigint` type that is 8 bytes long, however we have not migrated primary keys for `ci_builds` table to `bigint` yet. -We will run out of the capacity of the integer type to store primary keys in -`ci_builds` table before December 2021. When it happens without a viable -workaround or an emergency plan, GitLab.com will go down. - -`ci_builds` is just one of the tables that are running out of the primary keys -available in Int4 sequence. There are multiple other tables storing CI/CD data -that have the same problem. +In early 2021 we had estimated that would run out of the capacity of the integer +type to store primary keys in `ci_builds` table before December 2021. If it had +happened without a viable workaround or an emergency plan, GitLab.com would go +down. `ci_builds` was just one of many tables that were running out of the +primary keys available in Int4 sequence. -Primary keys problem will be tackled by our Database Team. +Before October 2021, our Database team had managed to migrate all the risky +tables' primary keys to big integers. -**Status**: In October 2021, the primary keys in CI tables were migrated -to big integers. See the [related Epic](https://gitlab.com/groups/gitlab-org/-/epics/5657) for more details. +See the [related Epic](https://gitlab.com/groups/gitlab-org/-/epics/5657) for more details. -### The table is too large +### Some CI/CD database tables are too large: IN PROGRESS -There is more than a billion rows in `ci_builds` table. We store more than 2 -terabytes of data in that table, and the total size of indexes is more than 1 -terabyte (as of February 2021). +There is more than two billion rows in `ci_builds` table. We store many +terabytes of data in that table, and the total size of indexes is measured in +terabytes as well. -This amount of data contributes to a significant performance problems we -experience on our primary PostgreSQL database. +This amount of data contributes to a significant number of performance +problems we experience on our CI PostgreSQL database. -Most of the problem are related to how PostgreSQL database works internally, +Most of the problems are related to how PostgreSQL database works internally, and how it is making use of resources on a node the database runs on. We are at -the limits of vertical scaling of the primary database nodes and we frequently -see a negative impact of the `ci_builds` table on the overall performance, -stability, scalability and predictability of the database GitLab.com depends -on. +the limits of vertical scaling of the CI primary database nodes and we +frequently see a negative impact of the `ci_builds` table on the overall +performance, stability, scalability and predictability of the CI database +GitLab.com depends on. The size of the table also hinders development velocity because queries that seem fine in the development environment may not work on GitLab.com. The @@ -90,41 +92,40 @@ environment. We also expect a significant, exponential growth in the upcoming years. One of the forecasts done using [Facebook's Prophet](https://facebook.github.io/prophet/) -shows that in the first half of -2024 we expect seeing 20M builds created on GitLab.com each day. In comparison -to around 2M we see created today, this is 10x growth our product might need to -sustain in upcoming years. +shows that in the first half of 2024 we expect seeing 20M builds created on +GitLab.com each day. In comparison to around 5M we see created today. This is +10x growth from numbers we saw in 2021.  **Status**: As of October 2021 we reduced the growth rate of `ci_builds` table -by writing build options and variables to `ci_builds_metadata` table. We plan -to ship further improvements that will be described in a separate blueprint. +by writing build options and variables to `ci_builds_metadata` table. We are +also working on partitioning the largest CI/CD database tables using +[time decay pattern](../ci_data_decay/index.md). -### Queuing mechanisms are using the large table +### Queuing mechanisms were using the large table: DONE -Because of how large the table is, mechanisms that we use to build queues of -pending builds (there is more than one queue), are not very efficient. Pending -builds represent a small fraction of what we store in the `ci_builds` table, -yet we need to find them in this big dataset to determine an order in which we -want to process them. +Because of how large the table is, mechanisms that we used to build queues of +pending builds (there is more than one queue), were not very efficient. Pending +builds represented a small fraction of what we store in the `ci_builds` table, +yet we needed to find them in this big dataset to determine an order in which we +wanted to process them. -This mechanism is very inefficient, and it has been causing problems on the -production environment frequently. This usually results in a significant drop -of the CI/CD Apdex score, and sometimes even causes a significant performance +This mechanism was very inefficient, and it had been causing problems on the +production environment frequently. This usually resulted in a significant drop +of the CI/CD Apdex score, and sometimes even caused a significant performance degradation in the production environment. -There are multiple other strategies that can improve performance and -reliability. We can use [Redis queuing](https://gitlab.com/gitlab-org/gitlab/-/issues/322972), or -[a separate table that will accelerate SQL queries used to build queues](https://gitlab.com/gitlab-org/gitlab/-/issues/322766) -and we want to explore them. +There were multiple other strategies that we considered to improve performance and +reliability. We evaluated using [Redis queuing](https://gitlab.com/gitlab-org/gitlab/-/issues/322972), or +[a separate table that would accelerate SQL queries used to build queues](https://gitlab.com/gitlab-org/gitlab/-/issues/322766). +We decided to proceed with the latter. -**Status**: As of October 2021 the new architecture -[has been implemented on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/5909#note_680407908). -The following epic tracks making it generally available: -[Make the new pending builds architecture generally available](https://gitlab.com/groups/gitlab-org/-/epics/6954). +In October 2021 we finished shipping the new architecture of builds queuing +[on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/5909#note_680407908). +We then made the new architecture [generally available](https://gitlab.com/groups/gitlab-org/-/epics/6954). -### Moving big amounts of data is challenging +### Moving big amounts of data is challenging: IN PROGRESS We store a significant amount of data in `ci_builds` table. Some of the columns in that table store a serialized user-provided data. Column `ci_builds.options` @@ -144,24 +145,27 @@ described in a separate architectural blueprint. ## Proposal -Making GitLab CI/CD product ready for the scale we expect to see in the -upcoming years is a multi-phase effort. - -First, we want to focus on things that are urgently needed right now. We need -to fix primary keys overflow risk and unblock other teams that are working on -database partitioning and sharding. - -We want to improve known bottlenecks, like -builds queuing mechanisms that is using the large table, and other things that -are holding other teams back. - -Extending CI/CD metrics is important to get a better sense of how the system -performs and to what growth should we expect. This will make it easier for us -to identify bottlenecks and perform more advanced capacity planning. - -Next step is to better understand how we can leverage strong time-decay -characteristic of CI/CD data. This might help us to partition CI/CD dataset to -reduce the size of CI/CD database tables. +Below you can find the original proposal made in early 2021 about how we want +to move forward with CI Scaling effort: + +> Making GitLab CI/CD product ready for the scale we expect to see in the +> upcoming years is a multi-phase effort. +> +> First, we want to focus on things that are urgently needed right now. We need +> to fix primary keys overflow risk and unblock other teams that are working on +> database partitioning and sharding. +> +> We want to improve known bottlenecks, like +> builds queuing mechanisms that is using the large table, and other things that +> are holding other teams back. +> +> Extending CI/CD metrics is important to get a better sense of how the system +> performs and to what growth should we expect. This will make it easier for us +> to identify bottlenecks and perform more advanced capacity planning. +> +> Next step is to better understand how we can leverage strong time-decay +> characteristic of CI/CD data. This might help us to partition CI/CD dataset to +> reduce the size of CI/CD database tables. ## Iterations @@ -170,15 +174,12 @@ Work required to achieve our next CI/CD scaling target is tracked in the 1. ✓ Migrate primary keys to big integers on GitLab.com. 1. ✓ Implement the new architecture of builds queuing on GitLab.com. -1. [Make the new builds queuing architecture generally available](https://gitlab.com/groups/gitlab-org/-/epics/6954). +1. ✓ [Make the new builds queuing architecture generally available](https://gitlab.com/groups/gitlab-org/-/epics/6954). 1. [Partition CI/CD data using time-decay pattern](../ci_data_decay/index.md). ## Status -|-------------|--------------| -| Created at | 21.01.2021 | -| Approved at | 26.04.2021 | -| Updated at | 28.02.2022 | +Created at 21.01.2021, approved at 26.04.2021. Status: In progress. diff --git a/doc/architecture/blueprints/cloud_native_build_logs/index.md b/doc/architecture/blueprints/cloud_native_build_logs/index.md index 3a06d73141b..b77d7998fc8 100644 --- a/doc/architecture/blueprints/cloud_native_build_logs/index.md +++ b/doc/architecture/blueprints/cloud_native_build_logs/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Next iteration of build logs architecture at GitLab' --- diff --git a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md index 431bc19ad84..127badabb71 100644 --- a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md +++ b/doc/architecture/blueprints/cloud_native_gitlab_pages/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Making GitLab Pages a Cloud Native application - architecture blueprint.' --- @@ -20,7 +20,7 @@ company behind the project. This effort is described in more detail [in the infrastructure team handbook page](https://about.gitlab.com/handbook/engineering/infrastructure/production/kubernetes/gitlab-com/). -GitLab Pages is tightly coupled with NFS and in order to unblock Kubernetes +GitLab Pages is tightly coupled with NFS and to unblock Kubernetes migration a significant change to GitLab Pages' architecture is required. This is an ongoing work that we have started more than a year ago. This blueprint might be useful to understand why it is important, and what is the roadmap. 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 5f0f0a7aa63..4111e2ef056 100644 --- a/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md +++ b/doc/architecture/blueprints/composable_codebase_using_rails_engines/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Making a GitLab codebase composable - allowing to run parts of the application' --- @@ -50,7 +50,7 @@ codebase without clear boundaries results in a number of problems and inefficien we usually need to run a whole test suite to confidently know which parts are affected. This to some extent can be improved by building a heuristic to aid this process, but it is prone to errors and hard to keep accurate at all times -- All components need to be loaded at all times in order to run only parts of the application +- All components need to be loaded at all times to run only parts of the application - Increased resource usage, as we load parts of the application that are rarely used in a given context - The high memory usage results in slowing the whole application as it increases GC cycles duration creating significantly longer latency for processing requests or worse cache usage of CPUs @@ -208,7 +208,7 @@ graph LR ### Application Layers on GitLab.com -Due to its scale, GitLab.com requires much more attention to run. This is needed in order to better manage resources +Due to its scale, GitLab.com requires much more attention to run. This is needed to better manage resources and provide SLAs for different functional parts. The chart below provides a simplistic view of GitLab.com application layers. It does not include all components, like Object Storage nor Gitaly nodes, but shows the GitLab Rails dependencies between different components and how they are configured on GitLab.com today: @@ -543,7 +543,7 @@ Controllers, Serializers, some presenters and some of the Grape:Entities are als Potential challenges with moving Controllers: -- We needed to extend `Gitlab::Patch::DrawRoute` in order to support `engines/web_engine/config/routes` and `engines/web_engine/ee/config/routes` in case when `web_engine` is loaded. Here is potential [solution](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53720#note_506957398). +- We needed to extend `Gitlab::Patch::DrawRoute` to support `engines/web_engine/config/routes` and `engines/web_engine/ee/config/routes` in case when `web_engine` is loaded. Here is potential [solution](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53720#note_506957398). - `Gitlab::Routing.url_helpers` paths are used in models and services, that could be used by Sidekiq (for example `Gitlab::Routing.url_helpers.project_pipelines_path` is used by [ExpirePipelineCacheService](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/expire_pipeline_cache_service.rb#L20) in [ExpirePipelineCacheWorker](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/workers/expire_pipeline_cache_worker.rb#L18))) ### Packwerk diff --git a/doc/architecture/blueprints/consolidating_groups_and_projects/index.md b/doc/architecture/blueprints/consolidating_groups_and_projects/index.md index df8686ed0aa..433c23bf188 100644 --- a/doc/architecture/blueprints/consolidating_groups_and_projects/index.md +++ b/doc/architecture/blueprints/consolidating_groups_and_projects/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: Consolidating groups and projects --- diff --git a/doc/architecture/blueprints/container_registry_metadata_database/index.md b/doc/architecture/blueprints/container_registry_metadata_database/index.md index 9d40593d7ce..58d59fe5737 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Container Registry metadata database' --- diff --git a/doc/architecture/blueprints/database/scalability/patterns/index.md b/doc/architecture/blueprints/database/scalability/patterns/index.md index 4a9bb003763..ec00d757377 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false 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 0780ae3c4d5..6cf8e17edeb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false 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 7a64f0cb7c6..ff5f7c25ea1 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Learn how to operate on large time-decay data' --- @@ -27,7 +27,7 @@ application. Let's first consider entities with no inherent time-related bias for their data. A record for a user or a project may be equally important and frequently accessed, irrelevant to when -it was created. We can not predict by using a user's `id` or `created_at` how often the related +it was created. We cannot predict by using a user's `id` or `created_at` how often the related record is accessed or updated. On the other hand, a good example for datasets with extreme time-decay effects are logs and time @@ -91,7 +91,7 @@ a maximum of a month of events, restricted to 6 months in the past. ### Immutability The third characteristic of time-decay data is that their **time-decay status does not change**. -Once they are considered "old", they can not switch back to "new" or relevant again. +Once they are considered "old", they cannot switch back to "new" or relevant again. This definition may sound trivial, but we have to be able to make operations over "old" data **more** expensive (for example, by archiving or moving them to less expensive storage) without having to worry about diff --git a/doc/architecture/blueprints/database_testing/index.md b/doc/architecture/blueprints/database_testing/index.md index 5bc9528d568..3f8041ea416 100644 --- a/doc/architecture/blueprints/database_testing/index.md +++ b/doc/architecture/blueprints/database_testing/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Database Testing' --- @@ -84,7 +84,7 @@ The short-term focus is on testing regular migrations (typically schema changes) In order to secure this process and meet compliance goals, the runner environment is treated as a *production* environment and similarly locked down, monitored and audited. Only Database Maintainers have access to the CI pipeline and its job output. Everyone else can only see the results and statistics posted back on the merge request. -We implement a secured CI pipeline on <https://ops.gitlab.net> that adds the execution steps outlined above. The goal is to secure this pipeline in order to solve the following problem: +We implement a secured CI pipeline on <https://ops.gitlab.net> that adds the execution steps outlined above. The goal is to secure this pipeline to solve the following problem: Make sure we strongly protect production data, even though we allow everyone (GitLab team/developers) to execute arbitrary code on the thin-clone which contains production data. diff --git a/doc/architecture/blueprints/feature_flags_development/index.md b/doc/architecture/blueprints/feature_flags_development/index.md index 08253ac883c..866be9d8a70 100644 --- a/doc/architecture/blueprints/feature_flags_development/index.md +++ b/doc/architecture/blueprints/feature_flags_development/index.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Internal usage of Feature Flags for GitLab development' --- -# Usage of Feature Flags for GitLab development +# Architectural discussion of feature flags Usage of feature flags become crucial for the development of GitLab. The feature flags are a convenient way to ship changes early, and safely rollout diff --git a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md index b22636ac1d9..19fd995bead 100644 --- a/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md +++ b/doc/architecture/blueprints/gitlab_to_kubernetes_communication/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'GitLab to Kubernetes communication' --- diff --git a/doc/architecture/blueprints/image_resizing/index.md b/doc/architecture/blueprints/image_resizing/index.md index f2fd7543b90..dd7ce27f459 100644 --- a/doc/architecture/blueprints/image_resizing/index.md +++ b/doc/architecture/blueprints/image_resizing/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Image Resizing' --- diff --git a/doc/architecture/blueprints/pods/index.md b/doc/architecture/blueprints/pods/index.md index fc33a4f441b..01d56c483ea 100644 --- a/doc/architecture/blueprints/pods/index.md +++ b/doc/architecture/blueprints/pods/index.md @@ -22,12 +22,14 @@ We use the following terms to describe components and properties of the Pods arc ### Pod -A Pod is a set of infrastructure components that contains multiple workspaces that belong to different organizations. The components include both datastores (PostgreSQL, Redis etc.) and stateless services (web etc.). The infrastructure components provided within a Pod are shared among workspaces but not shared with other Pods. This isolation of infrastructure components means that Pods are independent from each other. +A Pod is a set of infrastructure components that contains multiple top-level namespaces that belong to different organizations. The components include both datastores (PostgreSQL, Redis etc.) and stateless services (web etc.). The infrastructure components provided within a Pod are shared among organizations and their top-level namespaces but not shared with other Pods. This isolation of infrastructure components means that Pods are independent from each other. + + #### Pod properties - Each pod is independent from the others -- Infrastructure components are shared by workspaces within a Pod +- Infrastructure components are shared by organizations and their top-level namespaces within a Pod - More Pods can be provisioned to provide horizontal scalability - A failing Pod does not lead to failure of other Pods - Noisy neighbor effects are limited to within a Pod @@ -36,23 +38,50 @@ A Pod is a set of infrastructure components that contains multiple workspaces th Discouraged synonyms: GitLab instance, cluster, shard -### Workspace +### Cluster + +A cluster is a collection of Pods. + + + +#### Cluster properties + +- A cluster holds cluster-wide metadata, for example Users, Routes, Settings. + +Discouraged synonyms: whale + +### Organizations + +GitLab references [Organizations in the initial set up](../../../topics/set_up_organization.md) and users can add a (free text) organization to their profile. There is no Organization entity established in the GitLab codebase. + +As part of delivering Pods, we propose the introduction of an `organization` entity. Organizations would represent billable entities or customers. + +Organizations are a known concept, present for example in [AWS](https://docs.aws.amazon.com/whitepapers/latest/organizing-your-aws-environment/core-concepts.html) and [GCP](https://cloud.google.com/resource-manager/docs/cloud-platform-resource-hierarchy#organizations). + +Organizations work under the following assumptions: + +1. Users care about what happens within their organizations. +1. Features need to work within an organization. +1. Only few features need to work across organizations. +1. Users understand that the majority of pages they view are only scoped to a single organization at a time. +1. Organizations are located on a single pod. -A [workspace](../../../user/workspace/index.md) is the name for the top-level namespace that is used by organizations to manage everything GitLab. It will provide similar administrative capabilities to a self-managed instance. + -See more in the [workspace group overview](https://about.gitlab.com/direction/manage/workspace/#overview). +#### Organization properties -#### Workspace properties +- Top-level namespaces belong to organizations +- Users can be members of different organizations +- Organizations are isolated from each other by default meaning that cross-namespace features will only work for namespaces that exist within a single organization +- User namespaces must not belong to an organization -- Workspaces are isolated from each other by default -- A workspace is located on a single Pod -- Workspaces share the resources provided by a Pod +Discouraged synonyms: Billable entities, customers ### Top-Level namespace A top-level namespace is the logical object container in the code that represents all groups, subgroups and projects that belong to an organization. -A top-level namespace is the root of nested collection namespaces and projects. The namespace and its related entities form a tree-like hierarchy: Namespaces are the nodes of the tree, projects are the leaves. An organization usually contains a single top-level namespace, called a workspace. +A top-level namespace is the root of nested collection namespaces and projects. The namespace and its related entities form a tree-like hierarchy: Namespaces are the nodes of the tree, projects are the leaves. Example: @@ -61,21 +90,30 @@ Example: - `gitlab-org` is a `top-level namespace`; the root for all groups and projects of an organization - `gitlab` is a `project`; a project of the organization. +Top-level namespaces may [be replaced by workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/368237#high-level-goals). This proposal only uses the term top-level namespaces as the workspace definition is ongoing. + Discouraged synonyms: Root-level namespace + + #### Top-level namespace properties -Same as workspaces. +- Top-level namespaces belonging to an organization are located on the same Pod +- Top-level namespaces can interact with other top-level namespaces that belong to the same organization ### Users -Users are available globally and not restricted to a single Pod. Users can create multiple workspaces and they may be members of several workspaces and contribute to them. Because users' activity is not limited to an individual Pod, their activity needs to be aggregated across Pods to reflect all their contributions (for example TODOs). This means, the Pods architecture may need to provide a central dashboard. +Users are available globally and not restricted to a single Pod. Users can be members of many different organizations with varying permissions. Inside organizations, users can create multiple top-level namespaces. User activity is not limited to a single organization but their contributions (for example TODOs) are only aggregated within an organization. This avoids the need for aggregating across pods. #### User properties - Users are shared globally across all Pods -- Users can create multiple workspaces -- Users can be a member of multiple workspaces +- Users can create multiple top-level namespaces +- Users can be a member of multiple top-level namespaces +- Users can be a member of multiple organizations +- Users can administrate organizations +- User activity is aggregated within an organization +- Every user has one personal namespace ## Goals @@ -87,7 +125,7 @@ Pods provide a horizontally scalable solution because additional Pods can be cre ### Increased availability -A major challenge for shared-infrastructure architectures is a lack of isolation between workspaces. This can lead to noisy neighbor effects. A organization's behavior inside a workspace can impact all other workspaces. This is highly undesirable. Pods provide isolation at the pod level. A group of organizations is fully isolated from other organizations located on a different Pod. This minimizes noisy neighbor effects while still benefiting from the cost-efficiency of shared infrastructure. +A major challenge for shared-infrastructure architectures is a lack of isolation between top-level namespaces. This can lead to noisy neighbor effects. A organization's behavior inside a top-level namespace can impact all other organizations. This is highly undesirable. Pods provide isolation at the pod level. A group of organizations is fully isolated from other organizations located on a different Pod. This minimizes noisy neighbor effects while still benefiting from the cost-efficiency of shared infrastructure. Additionally, Pods provide a way to implement disaster recovery capabilities. Entire Pods may be replicated to read-only standbys with automatic failover capabilities. @@ -105,35 +143,113 @@ Pods would provide a solution for organizations in the small to medium business (See [segmentation definitions](https://about.gitlab.com/handbook/sales/field-operations/gtm-resources/#segmentation).) Larger organizations may benefit substantially from [GitLab Dedicated](../../../subscriptions/gitlab_dedicated/index.md). +At this moment, GitLab.com has "social-network"-like capabilities that may not fit well into a more isolated organization model. Removing those features, however, possesses some challenges: + +1. How will existing `gitlab-org` contributors contribute to the namespace?? +1. How do we move existing top-level namespaces into the new model (effectively breaking their social features)? + +We should evaluate if the SMB and mid market segment is interested in these features, or if not having them is acceptable in most cases. + ## High-level architecture problems to solve A number of technical issues need to be resolved to implement Pods (in no particular order). This section will be expanded. -1. How are users of an organization routed to the correct Pod containing their workspace? +1. How are users of an organization routed to the correct Pod? 1. How do users authenticate? 1. How are Pods rebalanced? 1. How are Pods provisioned? 1. How can Pods implement disaster recovery capabilities? -## Iteration 1 +## Iteration plan + +We can't ship the entire Pods architecture in one go - it is too large. Instead, we are adopting an iteration plan that provides value along the way. + +1. Introduce organizations +1. Migrate existing top-level namespaces to organizations +1. Create new organizations on `pod_0` +1. Migrate existing organizations from `pod_0` to `pod_n` +1. Add additional Pod capabilities (DR, Regions) + +### Iteration 0: Introduce organizations + +In the first iteration, we introduce the concept of an organization +as a way to group top-level namespaces together. Support for organizations **does not require any Pods work** but having them will make all subsequent iterations of Pods simpler. This is mainly because we can group top-level namespaces for a single organization onto a Pod. Within an organization all interactions work as normal but we eliminate any cross-organizational interactions except in well defined cases (e.g. forking). + +This means that we don't have a large number of cross-pod interactions. + +Introducing organizations allows GitLab to move towards a multi-tenant system that is similar to Discord's with a single user account but many different "servers" - our organizations - that allow users to switch context. This model harmonizes the UX across self-managed and our SaaS Platforms and is a good fit for Pods. + +Organizations solve the following problems: + +1. We can group top-level namespaces by organization. It is very similar to the initial concept of "instance groups". For example these two top-level namespaces would belong to the organization `GitLab`: + 1. `https://gitlab.com/gitlab-org/` + 1. `https://gitlab.com/gitlab-com/` +1. We can isolate organizations from each other. Top-level namespaces of the same organization can interact within organizations but are not allowed to interact with other namespaces in other organizations. This is useful for customers because it means an organization provides clear boundaries - similar to a self-managed instance. This means we don't have to aggregate user dashboards across everything and can locally scope them to organizations. +1. We don't need to define hierarchies inside an organization. It is a container that could be filled with whatever hierarchy / entity set makes sense (workspaces, top-level namespaces etc.) +1. Self-managed instances would set a default organization. +1. Organizations can control user-profiles in a central way. This could be achieved by having an organization specific user-profile. Such a profile makes it possible for the organization administrators to control the user role in a company, enforce user emails, or show a graphical indicator of a user being part of the organization. An example would be a "GitLab Employee stamp" on comments. + + + +#### Why would customers opt-in to Organizations? + +By introducing organizations and Pods we can improve the reliability, performance and availability of our SaaS Platforms. + +The first iteration of organizations would also have some benefits by providing more isolation. A simple example would be that `@` mentions could be scoped to an organization. + +Future iterations would create additional value but are beyond the scope of this blueprint. + +Organizations will likely be required in the future as well. + +#### Initial user experience + +1. We create a default `GitLab.com public` organization and assign all public top-level namespaces to it. This allows existing users to access all the data on GitLab.com, exactly as it does now. +1. Any user wanting to opt-in to the benefits of organizations will need to set a single default organization. Any attempts for these users to load a global page like `/dashboard` will end up redirecting to `/-/organizations/<DEFAULT_ORGANIZATION>/dashboard`. +1. New users that opted in to organizations will only ever see data that is related to a single organization. Upon login, data is shown for the default organization. It will be clear to the user how they can switch to a different organization. Users can still navigate to the `GitLab.com` organization but they won't see TODOs from their new organizations in any such views. Instead they'd need to navigate directly to `/organizations/my-company/-/dashboard`. + +### Migrating to Organizations + +Existing customers could also opt-in to migrate their existing top-level paid namespaces to become part of an organization. In most cases this will be a 1-to-1 mapping. But in some cases it may allow a customer to move multiple top-level namespaces into one organization (for example GitLab). + +Migrating to Organizations would be optional. We could even recruit a few beta testers early on to see if this works for them. GitLab itself could dogfood organizations and we'd surface a lot of issues restricting interactions with other namespaces. + +## Iteration 1 - Introduce Pod US 0 + +### GitLab.com as Pod US0 + +GitLab.com will be treated as the first pod `Pod US 0`. It will be unique and much larger compared to newly created pods. All existing top-level namespaces and organizations will remain on `Pod US 0` in the first iteration. + +### Users are globally available + +Users are globally available and the same for all pods. This means that user data needs to be handled separately, for example via decomposition, see [!95941](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95941). + +### Pod groundwork + +In this iteration, we'll lay all the groundwork to support a second Pod for new organizations. This will be transparent to customers. + +## Iteration 2 - Introduce Pod US 1 + +### Add new organizations to Pod US 1 + +After we are ready to support a second Pod, newly created organizations are located by default on `Pod US 1`. The user experience for organizations is already well established. + +### Migrate existing organizations from Pod US 0 to Pod US 1 -Ultimately, a Pods architecture should offer the same user experience as self-managed and GitLab dedicated. However, at this moment GitLab.com has many more "social-network"-like capabilities that will be difficult to implement with a Pods architecture. We should evaluate if the SMB and mid market segment is interested in these features, or if not having them is acceptable in most cases. +We know that we'll have to move organizations from `Pod US 0` to other pods to reduce its size and ultimately retire the existing GitLab.com architecture. -The first iteration of Pods will still contain some limitations that would break cross-workspace workflows. This means it may only be acceptable for new customers, or for existing customers that are briefed. +By introducing organizations early, we should be able to draw strong "boundaries" across organizations and support migrating existing organizations to a new Pod. -Limitations are: +This is likely going to be GitLab itself - if we can dogfood this, we are likely going to be successful with other organizations as well. -- An organization can create only a single workspace. -- Workspaces are isolated from each other. This means cross-workspace workflows are broken. +## Iteration 3 - Introduce Regions -## Iteration 2 +We can now leverage the Pods architecture to introduce Regions. -Based on user research, we may want to change certain features to work across namespaces to allow organizations to interact with each other in specific circumstances. We may also allow organizations to have more than one workspace. This is particularly relevant for organizations with sub-divisions, or multi-national organizations that want to have workspaces in different regions. +## Iteration 4 - Introduce cross-organizational interactions as needed -Additional features: +Based on user research, we may want to change certain features to work across organizations. Examples include: -- Specific features allow for cross-workspace interactions, for example forking, search. -- An organization can own multiple workspaces on different Pods. +- Specific features allow for cross-organization interactions, for example forking, search. ### Links diff --git a/doc/architecture/blueprints/pods/iteration0-organizations-introduction.png b/doc/architecture/blueprints/pods/iteration0-organizations-introduction.png Binary files differnew file mode 100644 index 00000000000..5f5cad7b169 --- /dev/null +++ b/doc/architecture/blueprints/pods/iteration0-organizations-introduction.png diff --git a/doc/architecture/blueprints/pods/term-cluster.png b/doc/architecture/blueprints/pods/term-cluster.png Binary files differnew file mode 100644 index 00000000000..f52e31b52ad --- /dev/null +++ b/doc/architecture/blueprints/pods/term-cluster.png diff --git a/doc/architecture/blueprints/pods/term-organization.png b/doc/architecture/blueprints/pods/term-organization.png Binary files differnew file mode 100644 index 00000000000..f605adb124d --- /dev/null +++ b/doc/architecture/blueprints/pods/term-organization.png diff --git a/doc/architecture/blueprints/pods/term-pod.png b/doc/architecture/blueprints/pods/term-pod.png Binary files differnew file mode 100644 index 00000000000..d8f79df2f29 --- /dev/null +++ b/doc/architecture/blueprints/pods/term-pod.png diff --git a/doc/architecture/blueprints/pods/term-top-level-namespace.png b/doc/architecture/blueprints/pods/term-top-level-namespace.png Binary files differnew file mode 100644 index 00000000000..c1cd317d878 --- /dev/null +++ b/doc/architecture/blueprints/pods/term-top-level-namespace.png diff --git a/doc/architecture/blueprints/rate_limiting/index.md b/doc/architecture/blueprints/rate_limiting/index.md index 692cef4b11d..2ed66f22b53 100644 --- a/doc/architecture/blueprints/rate_limiting/index.md +++ b/doc/architecture/blueprints/rate_limiting/index.md @@ -65,7 +65,7 @@ Inc._ - There is no way to automatically notify a user when they are approaching thresholds. - There is no single way to change limits for a namespace / project / user / customer. - There is no single way to monitor limits through real-time metrics. -- There is no framework for hierarchical limit configuration (instance / namespace / sub-group / project). +- There is no framework for hierarchical limit configuration (instance / namespace / subgroup / project). - We allow disabling rate-limiting for some marquee SaaS customers, but this increases a risk for those same customers. We should instead be able to set higher limits. @@ -357,7 +357,7 @@ hierarchy. Choosing a proper solution will require a thoughtful research. 1. Build application limits API in a way that it can be easily extracted to a separate service. 1. Build application limits definition in a way that is independent from the Rails application. 1. Build tooling that produce consistent behavior and results across programming languages. -1. Build the new framework in a way that we can extend to allow self-managed admins to customize limits. +1. Build the new framework in a way that we can extend to allow self-managed administrators to customize limits. 1. Maintain consistent features and behavior across SaaS and self-managed codebase. 1. Be mindful about a cognitive load added by the hierarchical limits, aim to reduce it. @@ -388,7 +388,7 @@ Proposal: | Author | Hayley Swimelar | | Engineering Leader | Sam Goldstein | | Product Manager | | -| Architecture Evolution Coach | | +| Architecture Evolution Coach | Andrew Newdigate | | Recommender | | | Recommender | | | Recommender | | diff --git a/doc/architecture/blueprints/runner_scaling/index.md b/doc/architecture/blueprints/runner_scaling/index.md index 8f7062a1148..415884449ed 100644 --- a/doc/architecture/blueprints/runner_scaling/index.md +++ b/doc/architecture/blueprints/runner_scaling/index.md @@ -43,10 +43,10 @@ to be able to keep using this and ship fixes and updates needed for our use case and the documentation for it has been removed from the official page. This means that the original reason to use Docker Machine is no longer valid too. -To keep supporting our customers and the wider community we need to design a -new mechanism for GitLab Runner auto-scaling. It not only needs to support -auto-scaling, but it also needs to do that in the way to enable us to build on -top of it to improve efficiency, reliability and availability. +To keep supporting our customers and the wider community and to improve our SaaS runners +maintenance we need to design a new mechanism for GitLab Runner auto-scaling. It not only +needs to support auto-scaling, but it also needs to do that in the way to enable us to +build on top of it to improve efficiency, reliability and availability. We call this new mechanism the "next GitLab Runner Scaling architecture". @@ -62,6 +62,66 @@ subject to change or delay. The development, release and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc._ +## Continuing building on Docker Machine + +At this moment one of our core products - GitLab Runner - and one of its most +important features - ability to auto-scale job execution environments - depends +on an external product that is abandoned. + +Docker Machine project itself is also hard to maintain. Its design starts to +show its age, which makes it hard to bring new features and fixes. A huge +codebase that it brings with a lack of internal knowledge about it makes it +hard for our maintainers to support and properly handle incoming feature +requests and community contributions. + +Docker Machine and it integrated 20+ drivers for cloud and virtualization +providers creates also another subset of problems, like: + +- Each cloud/virtualization environment brings features that come and go + and we would need to maintain support for them (add new features, fix + bugs). + +- We basically need to become experts for each of the virtualization/cloud + provider to properly support integration with their API, + +- Every single provider that Docker Machine integrates with has its + bugs, security releases, vulnerabilities - to maintain the project properly + we would need to be on top of all of that and handle updates whenever + they are needed. + +Another problem is the fact that Docker Machine, from its beginnings, was +focused on managing Linux based instances only. Despite that at some moment +Docker got official and native integration on Windows, Docker Machine never +followed this step. Nor its designed to make such integration easy. + +There is also no support for MacOS. This one is obvious - Docker Machine is a +tool to maintain hosts for Docker Engine and there is no native Docker Engine +for MacOS. And by native we mean MacOS containers executed within MacOS +operating system. Docker for MacOS product is not a native support - it's just +a tooling and a virtualized Linux instance installed with it that makes it +easier to develop **Linux containers** on MacOS development instances. + +This means that only one of three of our officially supported platforms - +Linux, Windows and MacOS - have a fully-featured support for CI/CD +auto-scaling. For Windows there is a possibility to use Kubernetes (which in +some cases have limitations) and maybe with a lot of effort we could bring +support for Windows into Docker Machine. But for MacOS, there is no +auto-scaling solution provided natively by GitLab Runner. + +This is a huge limitation for our users and a frequently requested feature. +It's also a limitation for our SaaS runners offering. We've maintained to +create some sort of auto-scaling for our SaaS Windows and SaaS MacOS runners +hacking around Custom executor. But experiences from past three years show +that it's not the best way of doing this. And yet, after this time, Windows +and MacOS runners autoscaling lacks a lot of performance and feature support +that we have with our SaaS Linux runners. + +To keep supporting our customers and the wider community and to improve our +SaaS runners maintenance we need to design a new mechanism for GitLab Runner +auto-scaling. It not only needs to support auto-scaling, but it also needs to +do that in the way to enable us to build on top of it to improve efficiency, +reliability and availability. + ## Proposal Currently, GitLab Runner auto-scaling can be configured in a few ways. Some @@ -94,7 +154,7 @@ data that can be shared between job runs. Because there is no viable replacement and we might be unable to support all cloud providers that Docker Machine used to support, the key design requirement is to make it really simple and easy for the wider community to write a custom -GitLab auto-scaling plugin, whatever cloud provider they might be using. We +GitLab plugin for whatever cloud provider they might be using. We want to design a simple abstraction that users will be able to build on top, as will we to support existing workflows on GitLab.com. @@ -129,12 +189,11 @@ the need of rebuilding GitLab Runner whenever it happens. ### 💡 Write a solid documentation about how to build your own plugin -It is important to show users how to build an auto-scaling plugin, so that they +It is important to show users how to build a plugin, so that they can implement support for their own cloud infrastructure. -Building new plugins should be simple, and with the support of great -documentation it should not require advanced skills, like understanding how -gRPC works. We want to design the plugin system in a way that the entry barrier +Building new plugins should be simple and supported with great +documentation. We want to design the plugin system in a way that the entry barrier for contributing new plugins is very low. ### 💡 Build a PoC to run multiple builds on a single machine @@ -171,7 +230,128 @@ configures the Docker daemon there to allow external authenticated requests. It stores credentials to such ephemeral Docker environments on disk. Once a machine has been provisioned and made available for GitLab Runner Manager to run builds, it is using one of the existing executors to run a user-provided -script. In auto-scaling, this is typically done using Docker executor. +script. In auto-scaling, this is typically done using the Docker executor. + +### Separation of concerns + +There are several concerns represented in the current architecture. They are +coupled in the current implementation so we will break them out here to consider +them each separately. + +- **Virtual Machine (VM) shape**. The underlying provider of a VM requires configuration to + know what kind of machine to create. E.g. Cores, memory, failure domain, + etc... This information is very provider specific. +- **VM lifecycle management**. Multiple machines will be created and a + system must keep track of which machines belong to this executor. Typically + a cloud provider will have a way to manage a set of homogenous machines. + E.g. GCE Instance Group. The basic operations are increase, decrease and + usually delete a specific machine. +- **VM autoscaling**. In addition to low-level lifecycle management, + job-aware capacity decisions must be made to the set of machines to provide + capacity when it is needed but not maintain excess capacity for cost reasons. +- **Job to VM mapping (routing)**. Currently the system assigns only one job to a + given a machine. A machine may be reused based on the specific executor + configuration. +- **In-VM job execution**. Within each VM a job must be driven through + various pre-defined stages and results and trace information returned + to the Runner system. These details are highly dependent on the VM + architecture and operating system as well as Executor type. + +The current architecture has several points of coupling between concerns. +Coupling reduces opportunities for abstraction (e.g. community supported +plugins) and increases complexity, making the code harder to understand, +test, maintain and extend. + +A primary design decision will be which concerns to externalize to the plugin +and which should remain with the runner system. The current implementation +has several abstractions internally which could be used as cut points for a +new abstraction. + +For example the [`Build`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/common/build.go#L125) +type uses the [`GetExecutorProvider`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/common/executor.go#L171) +function to get an executor provider based on a dispatching executor string. +Various executor types register with the system by being imported and calling +[`RegisterExecutorProvider`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/common/executor.go#L154) +during initialization. Here the abstractions are the [`ExecutorProvider`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/common/executor.go#L80) +and [`Executor`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/common/executor.go#L59) +interfaces. + +Within the `docker+autoscaling` executor the [`machineExecutor`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/executors/docker/machine/machine.go#L19) +type has a [`Machine`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/helpers/docker/machine.go#L7) +interface which it uses to aquire a VM during the common [`Prepare`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/executors/docker/machine/machine.go#L71) +phase. This abstraction primarily creates, accesses and deletes VMs. + +There is no current abstraction for the VM autoscaling logic. It is tightly +coupled with the VM lifecycle and job routing logic. Creating idle capacity +happens as a side-effect of calling [`Acquire`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/executors/docker/machine/provider.go#L449) on the `machineProvider` while binding a job to a VM. + +There is also no current abstraction for in-VM job execution. VM-specific +commands are generated by the Runner Manager using the [`GenerateShellScript`](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/common/build.go#L336) +function and [injected](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/267f40d871cd260dd063f7fbd36a921fedc62241/common/build.go#L373) +into the VM as the manager drives the job execution stages. + +### Design principles + +Our goal is to design a GitLab Runner plugin system interface that is flexible +and simple for the wider community to consume. As we cannot build plugins for +all cloud platforms, we want to ensure a low entry barrier for anyone who needs +to develop a plugin. We want to allow everyone to contribute. + +To achieve this goal, we will follow a few critical design principles. These +principles will guide our development process for the new plugin system +abstraction. + +#### General high-level principles + +- Design the new auto-scaling architecture aiming for having more choices and + flexibility in the future, instead of imposing new constraints. +- Design the new auto-scaling architecture to experiment with running multiple + jobs in parallel, on a single machine. +- Design the new provisioning architecture to replace Docker Machine in a way + that the wider community can easily build on top of the new abstractions. +- New auto-scaling method should become a core component of GitLab Runner product so that + we can simplify maintenance, use the same tooling, test configuration and Go language + setup as we do in our other main products. +- It should support multiple job execution environments - not only Docker containers + on Linux operating system. + + The best design would be to bring auto-scaling as a feature wrapped around + our current executors like Docker or Shell. + +#### Principles for the new plugin system + +- Make the entry barrier for writing a new plugin low. +- Developing a new plugin should be simple and require only basic knowledge of + a programming language and a cloud provider's API. +- Strive for a balance between the plugin system's simplicity and flexibility. + These are not mutually exclusive. +- Abstract away as many technical details as possible but do not hide them completely. +- Build an abstraction that serves our community well but allows us to ship it quickly. +- Invest in a flexible solution, avoid one-way-door decisions, foster iteration. +- When in doubts err on the side of making things more simple for the wider community. +- Limit coupling between concerns to make the system more simple and extensible. +- Concerns should live on one side of the plug or the other--not both, which + duplicates effort and increases coupling. + +#### The most important technical details + +- Favor gRPC communication between a plugin and GitLab Runner. +- Make it possible to version communication interface and support many versions. +- Make Go a primary language for writing plugins but accept other languages too. +- Autoscaling mechanism should be fully owned by GitLab. + + Cloud provider autoscalers don't know which VM to delete when scaling down so + they make sub-optimal decisions. Rather than teaching all autoscalers about GitLab + jobs, we prefer to have one, GitLab-owned autoscaler (not in the plugin). + + It will also ensure that we can shape the future of the mechanism and make decisions + that fit our needs and requirements. + +## Plugin boundary proposals + +The following are proposals for where to draw the plugin boundary. We will evaluate +these proposals and others by the design principles and technical constraints +listed above. ### Custom provider @@ -204,43 +384,33 @@ document, define requirements and score the solution accordingly. This will allow us to choose a solution that will work best for us and the wider community. -### Design principles - -Our goal is to design a GitLab Runner plugin system interface that is flexible -and simple for the wider community to consume. As we cannot build plugins for -all cloud platforms, we want to ensure a low entry barrier for anyone who needs -to develop a plugin. We want to allow everyone to contribute. +This proposal places VM lifecycle and autoscaling concerns as well as job to +VM mapping (routing) into the plugin. The build need only ask for a VM and +it will get one with all aspects of lifecycle and routing already accounted +for by the plugin. -To achieve this goal, we will follow a few critical design principles. These -principles will guide our development process for the new plugin system -abstraction. +Rationale: [Description of the Custom Executor Provider proposal](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28848#note_823321515) -#### General high-level principles +### Fleeting VM provider -1. Design the new auto-scaling architecture aiming for having more choices and - flexibility in the future, instead of imposing new constraints. -1. Design the new auto-scaling architecture to experiment with running multiple - jobs in parallel, on a single machine. -1. Design the new provisioning architecture to replace Docker Machine in a way - that the wider community can easily build on top of the new abstractions. +We can introduce a more simple version of the `Machine` abstraction in the +form of a "Fleeting" interface. Fleeting provides a low-level interface to +a homogenous VM group which allows increasing and decreasing the set size +as well as consuming a VM from within the set. -#### Principles for the new plugin system +Plugins for cloud providers and other VM sources are implemented via the +Hashicorp go-plugin library. This is in practice gRPC over STDIN/STDOUT +but other wire protocols can be used also. -1. Make the entry barrier for writing a new plugin low. -1. Developing a new plugin should be simple and require only basic knowledge of - a programming language and a cloud provider's API. -1. Strive for a balance between the plugin system's simplicity and flexibility. - These are not mutually exclusive. -1. Abstract away as many technical details as possible but do not hide them completely. -1. Build an abstraction that serves our community well but allows us to ship it quickly. -1. Invest in a flexible solution, avoid one-way-door decisions, foster iteration. -1. When in doubts err on the side of making things more simple for the wider community. +In order to make use of the new interface, the autoscaling logic is pulled +out of the Docker Executor and placed into a new Taskscaler library. -#### The most important technical details +This places the concerns of VM lifecycle, VM shape and job routing within +the plugin. It also places the conern of VM autoscaling into a separate +component so it can be used by multiple Runner Executors (not just `docker+autoscaling`). -1. Favor gRPC communication between a plugin and GitLab Runner. -1. Make it possible to version communication interface and support many versions. -1. Make Go a primary language for writing plugins but accept other languages too. +Rationale: [Description of the InstanceGroup / Fleeting proposal](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28848#note_823430883) +POC: [Merge request](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3315) ## Status @@ -252,26 +422,26 @@ Proposal: <!-- vale gitlab.Spelling = NO --> -| Role | Who -|------------------------------|------------------------------------------| -| Authors | Grzegorz Bizon, Tomasz Maczukin | -| Architecture Evolution Coach | Kamil Trzciński | -| Engineering Leader | Elliot Rushton, Cheryl Li | -| Product Manager | Darren Eastman, Jackie Porter | -| Domain Expert / Runner | Arran Walker | +| Role | Who | +|------------------------------|-------------------------------------------------| +| Authors | Grzegorz Bizon, Tomasz Maczukin, Joseph Burnett | +| Architecture Evolution Coach | Kamil Trzciński | +| Engineering Leader | Elliot Rushton, Cheryl Li | +| Product Manager | Darren Eastman, Jackie Porter | +| Domain Expert / Runner | Arran Walker | DRIs: -| Role | Who -|------------------------------|------------------------| -| Leadership | Elliot Rushton | -| Product | Darren Eastman | -| Engineering | Tomasz Maczukin | +| Role | Who | +|-------------|-----------------| +| Leadership | Elliot Rushton | +| Product | Darren Eastman | +| Engineering | Tomasz Maczukin | Domain experts: -| Area | Who -|------------------------------|------------------------| -| Domain Expert / Runner | Arran Walker | +| Area | Who | +|------------------------|--------------| +| Domain Expert / Runner | Arran Walker | <!-- vale gitlab.Spelling = YES --> diff --git a/doc/architecture/blueprints/work_items/index.md b/doc/architecture/blueprints/work_items/index.md new file mode 100644 index 00000000000..42864e7112e --- /dev/null +++ b/doc/architecture/blueprints/work_items/index.md @@ -0,0 +1,130 @@ +--- +stage: Plan +group: Project Management +comments: false +description: 'Work Items' +--- + +# Work Items + +DISCLAIMER: +This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. + +This document is a work-in-progress. Some aspects are not documented, though we expect to add them in the future. + +## Summary + +Work Items is a new architecture created to support the various types of built and planned entities throughout the product, such as issues, requirements, and incidents. It will make these types easy to extend and customize while sharing the same core functionality. + +## Terminology + +We use the following terms to describe components and properties of the Work items architecture. + +### Work Item + +Base type for issue, requirement, test case, incident and task (this list is planned to extend in the future). Different work items have the same set of base properties but their [widgets](#work-item-widgets) list is different. + +### Work Item types + +A set of predefined types for different categories of work items. Currently, the available types are: + +- Issue +- Incident +- Test case +- Requirement +- Task + +#### Work Item properties + +Every Work Item type has the following common properties: + +- `id` - a unique Work Item global identifier; +- `iid` - internal ID of the Work Item, relative to the parent workspace (currently workspace can only be a project) +- Work Item type; +- properties related to Work Item modification time: `createdAt`, `updatedAt`, `closedAt`; +- title string; +- Work Item confidentiality state; +- Work Item state (can be open or closed); +- lock version, incremented each time the work item is updated; +- permissions for the current user on the resource +- a list of [Work Item widgets](#work-item-widgets) + +### Work Item widgets + +All Work Item types share the same pool of predefined widgets and are customized by which widgets are active on a specific type. The list of widgets for any certain Work Item type is currently predefined and is not customizable. However, in the future we plan to allow users to create new Work Item types and define a set of widgets for them. + +### Work Item widget types (updating) + +- assignees +- description +- hierarchy +- iteration +- labels +- start and due date +- verification status +- weight + +### Work Item view + +The new frontend view that renders Work Items of any type using global Work Item `id` as an identifier. + +### Task + +Task is a special Work Item type. Tasks can be added to issues as child items and can be displayed in the modal on the issue view. + +## Motivation + +Work Items main goal is to enhance the planning toolset to become the most popular collaboration tool for knowledge workers in any industry. + +- Puts all like-items (issues, incidents, epics, test cases etc.) on a standard platform to simplify maintenance and increase consistency in experience +- Enables first-class support of common planning concepts to lower complexity and allow users to plan without learning GitLab-specific nuances. + +## Goals + +### Scalability + +Currently, different entities like issues, epics, merge requests etc share many similar features but these features are implemented separately for every entity type. This makes implementing new features or refactoring existing ones problematic: for example, if we plan to add new feature to issues and incidents, we would need to implement it separately on issue and incident types respectively. With work items, any new feature is implemented via widgets for all existing types which makes the architecture more scalable. + +### Flexibility + +With existing implementation, we have a rigid structure for issuables, merge requests, epics etc. This structure is defined on both backend and frontend, so any change requires a coordinated effort. Also, it would be very hard to make this structure customizable for the user without introducing a set of flags to enable/disable any existing feature. Work Item architecture allows frontend to display Work Item widgets in a flexible way: whatever is present in Work Item widgets, will be rendered on the page. This allows us to make changes fast and makes the structure way more flexible. For example, if we want to stop displaying labels on the Incident page, we remove labels widget from Incident Work Item type on the backend. Also, in the future this will allow users to define the set of widgets they want to see on custom Work Item types. + +### A consistent experience + +As much as we try to have consistent behavior for similar features on different entities, we still have differences in the implementation. For example, updating labels on merge request via GraphQL API can be done with dedicated `setMergeRequestLabels` mutation, while for the issue we call more coarse-grained `updateIssue`. This provides inconsistent experience for both frontend and external API users. As a result, epics, issues, requirements, and others all have similar but just subtle enough differences in common interactions that the user needs to hold a complicated mental model of how they each behave. + +Work Item architecture is designed with making all the features for all the types consistent, implemented as Work Item widgets. + +## High-level architecture problems to solve + +- how can we bypass groups and projects consolidation to migrate epics to Work Item type; +- dealing with parent-child relationships for certain Work Item types: epic > issue > task, and to the same Work Item types: issue > issue. +- [implementing custom Work Item types and custom widgets](https://gitlab.com/gitlab-org/gitlab/-/issues/335110) + +### Links + +- [Work items initiative epic](https://gitlab.com/groups/gitlab-org/-/epics/6033) +- [Tasks roadmap](https://gitlab.com/groups/gitlab-org/-/epics/7103?_gl=1*zqatx*_ga*NzUyOTc3NTc1LjE2NjEzNDcwMDQ.*_ga_ENFH3X7M5Y*MTY2MjU0MDQ0MC43LjEuMTY2MjU0MDc2MC4wLjAuMA..) +- [Work Item "Vision" Prototype](https://gitlab.com/gitlab-org/gitlab/-/issues/368607) +- [Work Item Discussions](https://gitlab.com/groups/gitlab-org/-/epics/7060) + +### Who + +| Role | Who +|------------------------------|-----------------------------| +| Author | Natalia Tepluhina | +| Architecture Evolution Coach | Kamil Trzciński | +| Engineering Leader | TBD | +| Product Manager | Gabe Weaver | +| Domain Expert / Frontend | Natalia Tepluhina | +| Domain Expert / Backend | Heinrich Lee Yu | +| Domain Expert / Backend | Jan Provaznik | +| Domain Expert / Backend | Mario Celi | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Leadership | TBD | +| Product | Gabe Weaver | +| Engineering | TBD | diff --git a/doc/architecture/index.md b/doc/architecture/index.md index 5dee2fd8a80..643f5766b0a 100644 --- a/doc/architecture/index.md +++ b/doc/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: 'Architecture Practice at GitLab' --- diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index d34f44ea9ba..c93d2b6a82a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Caching in GitLab CI/CD **(FREE)** diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index 21b970536bc..3354c94aff2 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- 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 cfe7be064fb..6256f11f1ea 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- 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 a48822fc214..18cc430c225 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 7c0889a329a..7b9145050bf 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- 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 2d1c3f927e2..4a6b96736df 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: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to Amazon Elastic Container Service **(FREE)** diff --git a/doc/ci/cloud_deployment/ecs/quick_start_guide.md b/doc/ci/cloud_deployment/ecs/quick_start_guide.md deleted file mode 100644 index 7522bc80d0d..00000000000 --- a/doc/ci/cloud_deployment/ecs/quick_start_guide.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'deploy_to_aws_ecs.md' -remove_date: '2022-09-18' ---- - -This document was moved to [another location](deploy_to_aws_ecs.md). - -<!-- This redirect file can be deleted after <2022-09-18>. --> -<!-- 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/ci/cloud_deployment/heroku.md b/doc/ci/cloud_deployment/heroku.md index 4e627675b01..541ba89dca8 100644 --- a/doc/ci/cloud_deployment/heroku.md +++ b/doc/ci/cloud_deployment/heroku.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 82d914f0a6a..83774f63566 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -11,7 +11,7 @@ GitLab provides Docker images with the libraries and tools you need to deploy to AWS. You can reference these images in your CI/CD pipeline. If you're using GitLab.com and deploying to the [Amazon Elastic Container Service](https://aws.amazon.com/ecs/) (ECS), -read about [deploying to ECS](ecs/quick_start_guide.md). +read about [deploying to ECS](ecs/deploy_to_aws_ecs.md). ## Authenticate GitLab with AWS diff --git a/doc/ci/cloud_services/aws/index.md b/doc/ci/cloud_services/aws/index.md index 2e1abf83a11..cc4dd53b29f 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 Authoring -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect in AWS to retrieve temporary credentials diff --git a/doc/ci/cloud_services/azure/index.md b/doc/ci/cloud_services/azure/index.md index 901b36afde6..944f95c03e2 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 Authoring -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect in Azure to retrieve temporary credentials @@ -16,7 +16,7 @@ Prerequisites: - Access to an existing Azure Subscription with `Owner` access level. - Access to the corresponding Azure Active Directory Tenant with at least the `Application Developer` access level. -- A local installation of the [Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli). +- A local installation of the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli). Alternatively, you can follow all the steps below with the [Azure Cloud Shell](https://shell.azure.com/). - A GitLab project. @@ -27,11 +27,11 @@ To complete this tutorial: 1. [Grant permissions for the service principal](#grant-permissions-for-the-service-principal). 1. [Retrieve a temporary credential](#retrieve-a-temporary-credential). -For more information, review Azure's documentation on [Workload identity federation](https://docs.microsoft.com/azure/active-directory/develop/workload-identity-federation). +For more information, review Azure's documentation on [Workload identity federation](https://learn.microsoft.com/azure/active-directory/develop/workload-identity-federation). ## Create Azure AD application and service principal -To create an [Azure AD application](https://docs.microsoft.com/cli/azure/ad/app?view=azure-cli-latest#az-ad-app-create) +To create an [Azure AD application](https://learn.microsoft.com/cli/azure/ad/app?view=azure-cli-latest#az-ad-app-create) and service principal: 1. In the Azure CLI, create the AD application: @@ -43,13 +43,13 @@ and service principal: Save the `appId` (Application client ID) output, as you need it later to configure your GitLab CI/CD pipeline. -1. Create a corresponding [Service Principal](https://docs.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create): +1. Create a corresponding [Service Principal](https://learn.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create): ```shell az ad sp create --id $appId --query appId -otsv ``` -Instead of the Azure CLI, you can [use the Azure Portal to create these resources](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal). +Instead of the Azure CLI, you can [use the Azure Portal to create these resources](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal). ## Create Azure AD federated identity credentials @@ -88,7 +88,7 @@ identity credentials from the Azure Portal: ## Grant permissions for the service principal -After you create the credentials, use [`role assignment`](https://docs.microsoft.com/cli/azure/role/assignment?view=azure-cli-latest#az-role-assignment-create) +After you create the credentials, use [`role assignment`](https://learn.microsoft.com/cli/azure/role/assignment?view=azure-cli-latest#az-role-assignment-create) to grant permissions to the above service principal to access to Azure resources: ```shell @@ -97,13 +97,13 @@ az role assignment create --assignee $appId --role Reader --scope /subscriptions You can find your subscription ID in: -- The [Azure Portal](https://docs.microsoft.com/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription). -- The [Azure CLI](https://docs.microsoft.com/cli/azure/manage-azure-subscriptions-azure-cli#get-the-active-subscription). +- The [Azure Portal](https://learn.microsoft.com/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription). +- The [Azure CLI](https://learn.microsoft.com/cli/azure/manage-azure-subscriptions-azure-cli#get-the-active-subscription). ## Retrieve a temporary credential After you configure the Azure AD application and federated identity credentials, -the CI/CD job can retrieve a temporary credential by using the [Azure CLI](https://docs.microsoft.com/cli/azure/reference-index?view=azure-cli-latest#az-login): +the CI/CD job can retrieve a temporary credential by using the [Azure CLI](https://learn.microsoft.com/cli/azure/reference-index?view=azure-cli-latest#az-login): ```yaml default: @@ -123,7 +123,7 @@ The CI/CD variables are: - `AZURE_CLIENT_ID`: The [application client ID you saved earlier](#create-azure-ad-application-and-service-principal). - `AZURE_TENANT_ID`: Your Azure Active Directory. You can - [find it by using the Azure CLI or Azure Portal](https://docs.microsoft.com/azure/active-directory/fundamentals/active-directory-how-to-find-tenant). + [find it by using the Azure CLI or Azure Portal](https://learn.microsoft.com/azure/active-directory/fundamentals/active-directory-how-to-find-tenant). - `CI_JOB_JWT_V2`: The JSON web token is a [predefined CI/CD variable](../../variables/predefined_variables.md). ## Troubleshooting diff --git a/doc/ci/cloud_services/google_cloud/index.md b/doc/ci/cloud_services/google_cloud/index.md index 54265816868..ba6efa4d35c 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 Authoring -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure OpenID Connect with GCP Workload Identity Federation diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md index 93fedb0ffca..b7129d92205 100644 --- a/doc/ci/cloud_services/index.md +++ b/doc/ci/cloud_services/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect to cloud services diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index f63ecc57028..ded91edeff5 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/docker/index.md b/doc/ci/docker/index.md index 4f6da72af12..e976700c160 100644 --- a/doc/ci/docker/index.md +++ b/doc/ci/docker/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index --- diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 4c9cb2923d7..06197d71690 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -608,7 +608,7 @@ build: - docker run my-docker-image /script/to/run/tests ``` -To log in to Docker Hub, leave `$DOCKER_REGISTRY` +To sign in to Docker Hub, leave `$DOCKER_REGISTRY` empty or remove it. ### Option 2: Mount `~/.docker/config.json` on each job diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index f985b02be33..70680a44ed2 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -282,8 +282,8 @@ Use one of the following methods to determine the value for `DOCKER_AUTH_CONFIG` configuration JSON manually. Open a terminal and execute the following command: ```shell - # The use of "-n" - prevents encoding a newline in the password. - echo -n "my_username:my_password" | base64 + # The use of printf (as opposed to echo) prevents encoding a newline in the password. + printf "my_username:my_password" | openssl base64 -A # Example output to copy bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= @@ -402,7 +402,7 @@ pulling from Docker Hub fails. Docker daemon tries to use the same credentials f > Introduced in GitLab Runner 12.0. As an example, let's assume that you want to use the `<aws_account_id>.dkr.ecr.<region>.amazonaws.com/private/image:latest` -image. This image is private and requires you to log in into a private container registry. +image. This image is private and requires you to sign in to a private container registry. To configure access for `<aws_account_id>.dkr.ecr.<region>.amazonaws.com`, follow these steps: diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index ee8d73dd113..37b9ea87d7a 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index bac06972c7b..adb9b5a87d5 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md index 26461d9827f..5f5ec027827 100644 --- a/doc/ci/environments/deployment_approvals.md +++ b/doc/ci/environments/deployment_approvals.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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: Require approvals prior to deploying to a Protected Environment --- @@ -10,9 +10,6 @@ description: Require approvals prior to deploying to a Protected Environment > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 with a flag named `deployment_approvals`. Disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/347342) in GitLab 14.8. -WARNING: -This feature is in a [Beta](../../policy/alpha-beta-support.md#beta-features) stage and subject to change without prior notice. - It may be useful to require additional approvals before deploying to certain protected environments (for example, production). This pre-deployment approval requirement is useful to accommodate testing, security, or compliance processes that must happen before each deployment. When a protected environment requires one or more approvals, all deployments to that environment become blocked and wait for the required approvals from the `Allowed to Deploy` list before running. diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 90efc7ba9ef..665aeb23d28 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deployment safety **(FREE)** diff --git a/doc/ci/environments/environments_dashboard.md b/doc/ci/environments/environments_dashboard.md index 11e9fe90e25..f662c156f55 100644 --- a/doc/ci/environments/environments_dashboard.md +++ b/doc/ci/environments/environments_dashboard.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md index ee2e708f822..af431a9812e 100644 --- a/doc/ci/environments/incremental_rollouts.md +++ b/doc/ci/environments/incremental_rollouts.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index c34a978709b..63641a9b7c3 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 disqus_identifier: 'https://docs.gitlab.com/ee/ci/environments.html' --- @@ -43,6 +43,18 @@ To view a list of environments and deployments: Deployments show up in this list only after a deployment job has created them. +## Search environments + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10754) in GitLab 15.5. + +To search environments by name: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Deployments > Environments**. +1. In the search bar, enter your search term. Matching applies from the + beginning of the environment name. For example, `devel` matches the + environment name `development`, but `elop` does not. + ## Types of environments There are two types of environments: diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index e63777dc0e0..0f943679c07 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected environments **(PREMIUM)** @@ -26,7 +26,7 @@ Maintainer role. Prerequisites: -- When granting the **Allowed to deploy** permission to a group or sub-group, the user configuring the protected environment must be a **direct member** of the group or sub-group to be added. Otherwise, the group or sub-group will not show up in the dropdown. For more information see [issue #345140](https://gitlab.com/gitlab-org/gitlab/-/issues/345140). +- 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 will not show up in the dropdown. For more information see [issue #345140](https://gitlab.com/gitlab-org/gitlab/-/issues/345140). To protect an environment: @@ -133,7 +133,7 @@ they have the following privileges: Users granted access to a protected environment, but not push or merge access to the branch deployed to it, are only granted access to deploy the environment. [Invited groups](../../user/project/members/share_project_with_groups.md#share-a-project-with-a-group-of-users) added -to the project with [Reporter role](../../user/permissions.md#project-members-permissions), appear in the dropdown menu for deployment-only access. +to the project with [Reporter role](../../user/permissions.md#project-members-permissions), appear in the dropdown list for deployment-only access. To add deployment-only access: @@ -146,7 +146,7 @@ To add deployment-only access: Maintainers can: - Update existing protected environments at any time by changing the access in the - **Allowed to Deploy** dropdown menu. + **Allowed to Deploy** dropdown list. - Unprotect a protected environment by clicking the **Unprotect** button for that environment. After an environment is unprotected, all access entries are deleted and must @@ -194,7 +194,7 @@ and are protected at the same time. ### Configure group-level memberships > - Operators are required to have Owner+ role from the original Maintainer+ role and this role change is introduced from GitLab 15.3 [with a flag](https://gitlab.com/gitlab-org/gitlab/-/issues/369873) named `group_level_protected_environment_settings_permission`. Enabled by default. -> - Original behavior where Operators are required to have Maintainer+ role can be achieved by enabling [flag](https://gitlab.com/gitlab-org/gitlab/-/issues/369875) named `override_group_level_protected_environment_settings_permission`. Disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/369873) in GitLab 15.4. To maximize the effectiveness of group-level protected environments, [group-level memberships](../../user/group/index.md) must be correctly @@ -214,8 +214,8 @@ configured: They do *not* have access to the CI/CD configurations in the top-level group, so operators can ensure that the critical configuration won't be accidentally changed by the developers. -- For sub-groups and child projects: - - Regarding [sub-groups](../../user/group/subgroups/index.md), if a higher +- For subgroups and child projects: + - Regarding [subgroups](../../user/group/subgroups/index.md), if a higher group has configured the group-level protected environment, the lower groups cannot override it. - [Project-level protected environments](#protecting-environments) can be @@ -257,14 +257,10 @@ Configure the group-level protected environments by using the [REST API](../../a Protected environments can also be used to require manual approvals before deployments. See [Deployment approvals](deployment_approvals.md) for more information. -<!-- ## Troubleshooting +## 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. +### Reporter can't run a trigger job that deploys to a protected environment in downstream pipeline -Each scenario can be a third-level heading, e.g. `### 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. --> +A user who has [deployment-only access to protected environments](#deployment-only-access-to-protected-environments) might **not** be able to run a job if it's with a [`trigger`](../yaml/index.md#trigger) keyword. This is because the job is missing the [`environment`](../yaml/index.md#environment) keyword definition to associate the job with the protected environment, therefore the job is recognized as a normal job that uses [regular CI/CD permission model](../../user/permissions.md#gitlab-cicd-permissions). + +Please see [this issue](https://gitlab.com/groups/gitlab-org/-/epics/8483) for more information about supporting `environment` keyword with `trigger` keyword. diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index 00025a66936..59e377dbb09 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index aa4055c00ea..f14372757a9 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/examples/deployment/index.md b/doc/ci/examples/deployment/index.md index b097f1fac76..7a20bfc2e0a 100644 --- a/doc/ci/examples/deployment/index.md +++ b/doc/ci/examples/deployment/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -36,7 +36,7 @@ apt-get install ruby-dev ``` The Dpl provides support for vast number of services, including: Heroku, Cloud Foundry, AWS/S3, and more. -To use it simply define provider and any additional parameters required by the provider. +To use it, define provider and any additional parameters required by the provider. For example if you want to use it to deploy your application to Heroku, you need to specify `heroku` as provider, specify `api_key` and `app`. All possible parameters can be found in the [Heroku API section](https://github.com/travis-ci/dpl#heroku-api). 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 5ff99755242..e9f126b0409 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 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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.' @@ -86,7 +86,7 @@ steering the browser. In this case, we can use [`browser.url`](http://v4.webdriver.io/api/protocol/url.html) to visit `/page-that-does-not-exist` to hit our 404 page. We can then use [`browser.getUrl`](http://v4.webdriver.io/api/property/getUrl.html) to verify that the current page is indeed at the location we specified. To interact with the page, -we can simply pass CSS selectors to +we can pass CSS selectors to [`browser.element`](http://v4.webdriver.io/api/protocol/element.html) to get access to elements on the page and to interact with them - for example, to click on the link back to the home page. diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index 77591ad2ca6..361061d0d75 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index --- 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 0735029f0be..80e476f2a87 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/articles/laravel_with_gitlab_and_envoy/index.html' author: Mehran Rasulian author_gitlab: mehranrasulian diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 9b9f87fffbb..2d0c6382dd8 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -189,7 +189,7 @@ phpenv config-add my_config.ini Since this is a pretty bare installation of the PHP environment, you may need some extensions that are not currently present on the build machine. -To install additional extensions simply execute: +To install additional extensions, execute: ```shell pecl install <extension> @@ -272,5 +272,5 @@ We have set up an [Example PHP Project](https://gitlab.com/gitlab-examples/php) that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/index.md). -Want to hack on it? Simply fork it, commit, and push your changes. Within a few +Want to hack on it? Fork it, commit, and push your changes. Within a few moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md index eaa7d8ebcfa..88e63a7f36f 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Publish npm packages to the GitLab Package Registry using semantic-release **(FREE)** diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index fbecb1cd964..ee9d15894fe 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -60,6 +60,14 @@ To make submodules work correctly in CI/CD jobs: GIT_SUBMODULE_STRATEGY: recursive ``` +1. You can filter or exclude specific submodules to control which submodules will be synced using + [`GIT_SUBMODULE_PATHS`](runners/configure_runners.md#git-submodule-paths). + + ```yaml + variables: + GIT_SUBMODULE_PATHS: submoduleA submoduleB + ``` + 1. You can provide additional flags to control advanced checkout behavior using [`GIT_SUBMODULE_UPDATE_FLAGS`](runners/configure_runners.md#git-submodule-update-flags). diff --git a/doc/ci/index.md b/doc/ci/index.md index be7088ab153..ddc9ba5d475 100644 --- a/doc/ci/index.md +++ b/doc/ci/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false 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 diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 03c905184cf..a1df55cfc38 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index add47c95051..ccf7ebccb2c 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/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/engineering/ux/technical-writing/#assignments +info: To 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: "An overview of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD." type: concepts --- diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 812683ef2c1..7282ebb0909 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 Execution -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD job token **(FREE)** @@ -20,7 +20,8 @@ You can use a GitLab CI/CD job token to authenticate with specific API endpoints (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). -- [Pipeline triggers](../../api/pipeline_triggers.md), using the `token=` parameter. +- [Pipeline triggers](../../api/pipeline_triggers.md), using the `token=` parameter + to [trigger a multi-project pipeline](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api). - [Releases](../../api/releases/index.md) and [Release links](../../api/releases/links.md). - [Terraform plan](../../user/infrastructure/index.md). @@ -78,7 +79,7 @@ to be accessed by authenticating with the current project's job token. By defaul the token scope only allows access to the same project where the token comes from. Other projects can be added and removed by maintainers with access to both projects. -This setting is disabled by default for all new projects. It is recommended that project maintainers enable this +This setting is disabled by default for all new projects. It is recommended that project maintainers or owners enable this setting at all times, and configure the allowlist for cross-project access if needed. For example, when the setting is enabled, jobs in a pipeline in project `A` have @@ -99,28 +100,6 @@ The job token scope is only for controlling access to private projects. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve the feature with more strategic control of the access permissions. -## Trigger a multi-project pipeline by using a CI/CD job token - -> `CI_JOB_TOKEN` for multi-project pipelines was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) from GitLab Premium to GitLab Free in 12.4. - -You can use the `CI_JOB_TOKEN` to [trigger multi-project pipelines](../../api/pipeline_triggers.md#trigger-a-pipeline-with-a-token) -from a CI/CD job. - -For example: - -```yaml -trigger_pipeline: - stage: deploy - script: - - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" - rules: - - if: $CI_COMMIT_TAG - environment: production -``` - -If you use the `CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) -in a pipeline triggered this way, [the value is `pipeline` (not `triggered`)](../triggers/index.md#configure-cicd-jobs-to-run-in-triggered-pipelines). - ## Download an artifact from a different pipeline **(PREMIUM)** > `CI_JOB_TOKEN` for artifacts download with the API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in GitLab 9.5. diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index 806837e3dc8..d1a4f1e35bf 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jobs **(FREE)** diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index 5a94c2e9bbc..39ab0998291 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Choose when to run jobs **(FREE)** @@ -624,8 +624,9 @@ by authorized users. Use [`when: delayed`](../yaml/index.md#when) to execute scripts after a waiting period, or if you want to avoid jobs immediately entering the `pending` state. -You can set the period with `start_in` keyword. The value of `start_in` is an elapsed time in seconds, unless a unit is -provided. `start_in` must be less than or equal to one week. Examples of valid values include: +You can set the period with `start_in` keyword. The value of `start_in` is an elapsed time +in seconds, unless a unit is provided. The minimum is one second, and the maximum is one week. +Examples of valid values include: - `'5'` (a value with no unit must be surrounded by single quotes) - `5 seconds` diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index 3904a527a8f..c7ecc25dc44 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -260,3 +260,8 @@ For very active repositories with a large number of references and files, you ca - Optimize your CI/CD jobs by seeding repository data in a pre-clone step with the [`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) of GitLab Runner. See [SaaS runners on Linux](../runners/saas/linux_saas_runner.md#pre-clone-script) for details. + Besides speeding up pipelines in large and active projects, + seeding the repository data also helps avoid + `429 Too many requests` errors from Cloudflare. + This error can occur if you have many runners behind a single, + NAT'ed IP address that pulls from GitLab.com. diff --git a/doc/ci/lint.md b/doc/ci/lint.md index 8c64d968b8b..c297cab1822 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Validate GitLab CI/CD configuration **(FREE)** diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md deleted file mode 100644 index c3ab3392f36..00000000000 --- a/doc/ci/metrics_reports.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'testing/metrics_reports.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](testing/metrics_reports.md). - -<!-- This redirect file can be deleted after <2022-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 --> diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index efe11466674..5354e406e34 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index, howto --- diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 35c5a7e56c8..300de610aa7 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index, howto --- @@ -66,6 +66,9 @@ of transition, by letting you delay the migration of less urgent pipelines for a If you are interested in helping GitLab test the wrapper, join our [public testing issue](https://gitlab.com/gitlab-org/gitlab/-/issues/215675) for instructions and to provide your feedback. +NOTE: +If you have a paid GitLab subscription, note that the JenkinsFile Wrapper is not packaged as part of GitLab, and falls outside of the scope of support. For more information, see the [Statement of Support](https://about.gitlab.com/support/statement-of-support.html). + ## Important product differences There are some high level differences between the products worth mentioning: @@ -208,7 +211,7 @@ For advanced CI/CD teams, project templates can enable the reuse of pipeline con as well as encourage inner sourcing. In self-managed GitLab instances, you can build an [Instance Template Repository](../../user/admin_area/settings/instance_template_repository.md). -Development teams across the whole organization can select templates from a dropdown menu. +Development teams across the whole organization can select templates from a dropdown list. A group maintainer or a group owner is able to set a group to use as the source for the [custom project templates](../../user/admin_area/custom_project_templates.md), which can be used by all projects in the group. An instance administrator can set a group as diff --git a/doc/ci/mobile_devops.md b/doc/ci/mobile_devops.md index 6eb56434a1b..1359191f6a6 100644 --- a/doc/ci/mobile_devops.md +++ b/doc/ci/mobile_devops.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 87c2b3f1c71..c4416d41ab4 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index 02a74883244..a5484fcdf5a 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -139,6 +139,8 @@ Premium license: If you use `13,000` minutes during the month, the next month your additional minutes become `2,000`. If you use `9,000` minutes during the month, your additional minutes remain the same. +If you bought additional CI/CD minutes while on a trial subscription those minutes will be available after the trial ends or you upgrade to a paid plan. + You can find pricing for additional CI/CD minutes on the [GitLab Pricing page](https://about.gitlab.com/pricing/). @@ -205,8 +207,8 @@ The cost factors for jobs running on shared runners on GitLab.com are: - `0.5` for public projects in the [GitLab for Open Source program](../../subscriptions/index.md#gitlab-for-open-source). - `0.008` for public forks of public projects in the [GitLab for Open Source program](../../subscriptions/index.md#gitlab-for-open-source). For every 125 minutes of job execution time, you use 1 CI/CD minute. -- `0.04` for other public projects, after September 1, 2022 (previously `0.008`). - For every 25 minutes of job execution time, you use 1 CI/CD minute. +- `1` for other public projects, after October 1, 2022 (previously `0.04`). + For every 1 minute of job execution time, you use 1 CI/CD minute. - Calculated differently for [community contributions to GitLab projects](#cost-factor-for-community-contributions-to-gitlab-projects). The cost factors on self-managed instances are: @@ -246,7 +248,6 @@ GitLab SaaS runners have different cost factors, depending on the runner type (L | Linux OS + Docker executor| Small |1| | Linux OS + Docker executor| Medium |2| | Linux OS + Docker executor| Large |3| -| macOS + shell executor | Large| 6 | ### Monthly reset of CI/CD minutes diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 6c7ec8e98ec..0b1963e1874 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -1,39 +1,65 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Downstream pipelines **(FREE)** A downstream pipeline is any GitLab CI/CD pipeline triggered by another pipeline. -A downstream pipeline can be either: +Downstream pipelines run independently and concurrently to the upstream pipeline +that triggered them. -- A [parent-child pipeline](downstream_pipelines.md#parent-child-pipelines), which is a downstream pipeline triggered - in the same project as the first pipeline. -- A [multi-project pipeline](#multi-project-pipelines), which is a downstream pipeline triggered - in a different project than the first pipeline. +- A [parent-child pipeline](downstream_pipelines.md#parent-child-pipelines) is a downstream pipeline + triggered in the *same* project as the first pipeline. +- A [multi-project pipeline](#multi-project-pipelines) is a downstream pipeline triggered + in a *different* project than the first pipeline. -Parent-child pipelines and multi-project pipelines can sometimes be used for similar purposes, -but there are some key differences. +You can sometimes use parent-child pipelines and multi-project pipelines for similar purposes, +but there are [key differences](pipeline_architectures.md). -Parent-child pipelines: +## Parent-child pipelines + +A parent pipeline is one that triggers a downstream pipeline in the same project. +The downstream pipeline is called a child pipeline. Child pipelines: - Run under the same project, ref, and commit SHA as the parent pipeline. -- Affect the overall status of the ref the pipeline runs against. For example, +- Do not directly affect the overall status of the ref the pipeline runs against. For example, if a pipeline fails for the main branch, it's common to say that "main is broken". - The status of child pipelines don't directly affect the status of the ref, unless the child + The status of child pipelines only affects the status of the ref if the child pipeline is triggered with [`strategy:depend`](../yaml/index.md#triggerstrategy). - Are automatically canceled if the pipeline is configured with [`interruptible`](../yaml/index.md#interruptible) when a new pipeline is created for the same ref. -- Display only the parent pipelines in the pipeline index page. Child pipelines are - visible when visiting their parent pipeline's page. -- Are limited to 2 levels of nesting. A parent pipeline can trigger multiple child pipelines, - and those child pipeline can trigger multiple child pipelines (`A -> B -> C`). +- Are not displayed in the pipeline index page. You can only view child pipelines on + their parent pipeline's page. + +### Nested child pipelines + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) in GitLab 13.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243747) in GitLab 13.5. + +Parent and child pipelines were introduced with a maximum depth of one level of child +pipelines, which was later increased to two. A parent pipeline can trigger many child +pipelines, and these child pipelines can trigger their own child pipelines. It's not +possible to trigger another level of child pipelines. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Nested Dynamic Pipelines](https://youtu.be/C5j3ju9je2M). + +## Multi-project pipelines + +A pipeline in one project can trigger downstream pipelines in another project, +called multi-project pipelines. The user triggering the upstream pipeline must be able to +start pipelines in the downstream project, otherwise [the downstream pipeline fails to start](#trigger-job-fails-and-does-not-create-multi-project-pipeline). + +For example, you might deploy your web application from three different GitLab projects. +With multi-project pipelines you can trigger a pipeline in each project, where each +has its own build, test, and deploy process. You can visualize the connected pipelines +in one place, including all cross-project interdependencies. Multi-project pipelines: -- Are triggered from another pipeline, but the upstream (triggering) pipeline does +- Are triggered from another project's pipeline, but the upstream (triggering) pipeline does not have much control over the downstream (triggered) pipeline. However, it can choose the ref of the downstream pipeline, and pass CI/CD variables to it. - Affect the overall status of the ref of the project it runs in, but does not @@ -46,75 +72,86 @@ Multi-project pipelines: that happened to be triggered by an external project. They are all visible on the pipeline index page. - Are independent, so there are no nesting limits. -## Multi-project pipelines +Learn more in the "Cross-project Pipeline Triggering and Visualization" demo at +[GitLab@learn](https://about.gitlab.com/learn/), in the Continuous Integration section. -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. +If you use a public project to trigger downstream pipelines in a private project, +make sure there are no confidentiality problems. The upstream project's pipelines page +always displays: -You can set up [GitLab CI/CD](../index.md) across multiple projects, so that a pipeline -in one project can trigger a downstream pipeline in another project. You can visualize the entire pipeline -in one place, including all cross-project interdependencies. - -For example, you might deploy your web application from three different projects in GitLab. -Each project has its own build, test, and deploy process. With multi-project pipelines you can -visualize the entire pipeline, including all build and test stages for all three projects. +- The name of the downstream project. +- The status of the pipeline. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see the [Multi-project pipelines demo](https://www.youtube.com/watch?v=g_PIwBM1J84). +## Trigger a downstream pipeline from a job in the `.gitlab-ci.yml` file -Multi-project pipelines are also useful for larger products that require cross-project interdependencies, like those -with a [microservices architecture](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). -Learn more in the [Cross-project Pipeline Triggering and Visualization demo](https://about.gitlab.com/learn/) -at GitLab@learn, in the Continuous Integration section. +Use the [`trigger`](../yaml/index.md#trigger) keyword in your `.gitlab-ci.yml` file +to create a job that triggers a downstream pipeline. This job is called a trigger job. -If you trigger a pipeline in a downstream private project, on the upstream project's pipelines page, -you can view: +After the trigger job starts, the initial status of the job is `pending` while GitLab +attempts to create the downstream pipeline. If the downstream pipeline is created, +GitLab marks the job as passed, otherwise the job failed. Alternatively, +you can [set the trigger job to show the downstream pipeline's status](#mirror-the-status-of-a-downstream-pipeline-in-the-trigger-job) +instead. -- The name of the project. -- The status of the pipeline. +For example: -If you have a public project that can trigger downstream pipelines in a private project, -make sure there are no confidentiality problems. +::Tabs -### Trigger a multi-project pipeline from a job in your `.gitlab-ci.yml` file +:::TabTitle Multi-project pipeline -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. +```yaml +trigger_job: + trigger: + project: project-group/my-downstream-project +``` -When you use the [`trigger`](../yaml/index.md#trigger) keyword to create a multi-project -pipeline in your `.gitlab-ci.yml` file, you create what is called a *trigger job*. For example: +:::TabTitle Parent-child pipeline ```yaml -rspec: - stage: test - script: bundle exec rspec - -staging: - variables: - ENVIRONMENT: staging - stage: deploy - trigger: my/deployment +trigger_job: + trigger: + include: + - local: path/to/child-pipeline.yml ``` -In this example, after the `rspec` job succeeds in the `test` stage, -the `staging` trigger job starts. The initial status of this -job is `pending`. +::EndTabs -GitLab then creates a downstream pipeline in the -`my/deployment` project and, as soon as the pipeline is created, the -`staging` job succeeds. The full path to the project is `my/deployment`. +### Use `rules` to control downstream pipeline jobs -You can view the status for the pipeline, or you can display -[the downstream pipeline's status instead](#mirror-the-status-of-a-downstream-pipeline-in-the-trigger-job). +You can use CI/CD variables or the [`rules`](../yaml/index.md#rulesif) keyword to +[control job behavior](../jobs/job_control.md) for downstream pipelines. -The user that creates the upstream pipeline must be able to create pipelines in the -downstream project (`my/deployment`) too. If the downstream project is not found, -or the user does not have [permission](../../user/permissions.md) to create a pipeline there, -the `staging` job is marked as _failed_. +When a downstream pipeline is triggered with the [`trigger`](../yaml/index.md#trigger) keyword, +the value of the [`$CI_PIPELINE_SOURCE` predefined variable](../variables/predefined_variables.md) +for all jobs is: -#### Specify a downstream pipeline branch +- `pipeline` for multi-project pipelines. +- `parent` for parent-child pipelines. -You can specify a branch name for the downstream pipeline to use. -GitLab uses the commit on the head of the branch to -create the downstream pipeline. +For example, with a multi-project pipeline: + +```yaml +job1: + rules: + - if: $CI_PIPELINE_SOURCE == "pipeline" + script: echo "This job runs in multi-project pipelines only" + +job2: + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + script: echo "This job runs in merge request pipelines only" + +job3: + rules: + - if: $CI_PIPELINE_SOURCE == "pipeline" + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + script: echo "This job runs in both multi-project and merge request pipelines" +``` + +### Specify a branch for multi-project pipelines + +You can specify a branch name for a multi-project pipeline to use. GitLab uses +the commit on the head of the branch to create the downstream pipeline: ```yaml rspec: @@ -137,100 +174,25 @@ Use: In [GitLab 12.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/10126), variable expansion is supported. -Pipelines triggered on a protected branch in a downstream project use the [role](../../user/permissions.md) -of the user that ran the trigger job in the upstream project. If the user does not -have permission to run CI/CD pipelines against the protected branch, the pipeline fails. See -[pipeline security for protected branches](index.md#pipeline-security-on-protected-branches). - -#### Use `rules` or `only`/`except` with multi-project pipelines - -You can use CI/CD variables or the [`rules`](../yaml/index.md#rulesif) keyword to -[control job behavior](../jobs/job_control.md) for multi-project pipelines. When a -downstream pipeline is triggered with the [`trigger`](../yaml/index.md#trigger) keyword, -the value of the [`$CI_PIPELINE_SOURCE` predefined variable](../variables/predefined_variables.md) -is `pipeline` for all its jobs. - -If you use [`only/except`](../yaml/index.md#only--except) to control job behavior, use the -[`pipelines`](../yaml/index.md#onlyrefs--exceptrefs) keyword. - -### Trigger a multi-project pipeline by using the API - -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) to GitLab Free in 12.4. - -When you use the [`CI_JOB_TOKEN` to trigger pipelines](../jobs/ci_job_token.md), -GitLab recognizes the source of the job token. The pipelines become related, -so you can visualize their relationships on pipeline graphs. - -These relationships are displayed in the pipeline graph by showing inbound and -outbound connections for upstream and downstream pipeline dependencies. - -When using: - -- CI/CD variables or [`rules`](../yaml/index.md#rulesif) to control job behavior, the value of - the [`$CI_PIPELINE_SOURCE` predefined variable](../variables/predefined_variables.md) is - `pipeline` for multi-project pipeline triggered through the API with `CI_JOB_TOKEN`. -- [`only/except`](../yaml/index.md#only--except) to control job behavior, use the - `pipelines` keyword. - -## Parent-child pipelines - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) in GitLab 12.7. - -As pipelines grow more complex, a few related problems start to emerge: - -- The staged structure, where all steps in a stage must be completed before the first - job in next stage begins, causes arbitrary waits, slowing things down. -- Configuration for the single global pipeline becomes very long and complicated, - making it hard to manage. -- Imports with [`include`](../yaml/index.md#include) increase the complexity of the configuration, and create the potential - for namespace collisions where jobs are unintentionally duplicated. -- Pipeline UX can become unwieldy with so many jobs and stages to work with. +### Use a child pipeline configuration file in a different project -Additionally, sometimes the behavior of a pipeline needs to be more dynamic. The ability -to choose to start sub-pipelines (or not) is a powerful ability, especially if the -YAML is dynamically generated. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205157) in GitLab 13.5. - - -Similarly to [multi-project pipelines](#multi-project-pipelines), a pipeline can trigger a -set of concurrently running downstream child pipelines, but in the same project: - -- Child pipelines still execute each of their jobs according to a stage sequence, but - would be free to continue forward through their stages without waiting for unrelated - jobs in the parent pipeline to finish. -- The configuration is split up into smaller child pipeline configurations. Each child pipeline contains only relevant steps which are - easier to understand. This reduces the cognitive load to understand the overall configuration. -- Imports are done at the child pipeline level, reducing the likelihood of collisions. - -Child pipelines work well with other GitLab CI/CD features: - -- Use [`rules: changes`](../yaml/index.md#ruleschanges) to trigger pipelines only when - certain files change. This is useful for monorepos, for example. -- Since the parent pipeline in `.gitlab-ci.yml` and the child pipeline run as normal - pipelines, they can have their own behaviors and sequencing in relation to triggers. - -See the [`trigger`](../yaml/index.md#trigger) keyword documentation for full details on how to -include the child pipeline configuration. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Parent-Child Pipelines feature demo](https://youtu.be/n8KpBSqZNbk). - -NOTE: -The artifact containing the generated YAML file must not be larger than 5MB. - -### Trigger a parent-child pipeline - -The simplest case is [triggering a child pipeline](../yaml/index.md#trigger) using a -local YAML file to define the pipeline configuration. In this case, the parent pipeline -triggers the child pipeline, and continues without waiting: +You can use [`include:file`](../yaml/index.md#includefile) to trigger child pipelines +with a configuration file in a different project: ```yaml microservice_a: trigger: - include: path/to/microservice_a.yml + include: + - project: 'my-group/my-pipeline-library' + ref: 'main' + file: '/path/to/child-pipeline.yml' ``` -You can include multiple files when defining a child pipeline. The child pipeline's +### Combine multiple child pipeline configuration files + +You can include up to three configuration files when defining a child pipeline. The child pipeline's configuration is composed of all configuration files merged together: ```yaml @@ -239,134 +201,139 @@ microservice_a: include: - local: path/to/microservice_a.yml - template: Security/SAST.gitlab-ci.yml -``` - -In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205157), -you can use [`include:file`](../yaml/index.md#includefile) to trigger child pipelines -with a configuration file in a different project: - -```yaml -microservice_a: - trigger: - include: - project: 'my-group/my-pipeline-library' ref: 'main' file: '/path/to/child-pipeline.yml' ``` -The maximum number of entries that are accepted for `trigger:include` is three. +### Dynamic child pipelines -### Merge request child pipelines +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9. -To trigger a child pipeline as a [merge request pipeline](merge_request_pipelines.md) we need to: +You can trigger a child pipeline from a YAML file generated in a job, instead of a +static file saved in your project. This technique can be very powerful for generating pipelines +targeting content that changed or to build a matrix of targets and architectures. -- Set the trigger job to run on merge requests: +The artifact containing the generated YAML file must not be [larger than 5MB](https://gitlab.com/gitlab-org/gitlab/-/issues/249140). -```yaml -# parent .gitlab-ci.yml -microservice_a: - trigger: - include: path/to/microservice_a.yml - rules: - - if: $CI_MERGE_REQUEST_ID -``` +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Create child pipelines using dynamically generated configurations](https://youtu.be/nMdfus2JWHM). -- Configure the child pipeline by either: +For an example project that generates a dynamic child pipeline, see +[Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet). +This project shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. +You can use a similar process for other templating languages like +[Dhall](https://dhall-lang.org/) or [ytt](https://get-ytt.io/). - - Setting all jobs in the child pipeline to evaluate in the context of a merge request: +#### Trigger a dynamic child pipeline - ```yaml - # child path/to/microservice_a.yml - workflow: - rules: - - if: $CI_MERGE_REQUEST_ID +To trigger a child pipeline from a dynamically generated configuration file: - job1: - script: ... +1. Generate the configuration file in a job and save it as an [artifact](../yaml/index.md#artifactspaths): - job2: - script: ... - ``` + ```yaml + generate-config: + stage: build + script: generate-ci-config > generated-config.yml + artifacts: + paths: + - generated-config.yml + ``` - - Alternatively, setting the rule per job. For example, to create only `job1` in - the context of merge request pipelines: +1. Configure the trigger job to run after the job that generated the configuration file, + and set `include: artifact` to the generated artifact: - ```yaml - # child path/to/microservice_a.yml - job1: - script: ... - rules: - - if: $CI_MERGE_REQUEST_ID + ```yaml + child-pipeline: + stage: test + trigger: + include: + - artifact: generated-config.yml + job: generate-config + ``` - job2: - script: ... - ``` +In this example, `generated-config.yml` is extracted from the artifacts and used as the configuration +for triggering the child pipeline. -### Dynamic child pipelines +The artifact path is parsed by GitLab, not the runner, so the path must match the +syntax for the OS running GitLab. If GitLab is running on Linux but using a Windows +runner for testing, the path separator for the trigger job is `/`. Other CI/CD +configuration for jobs that use the Windows runner, like scripts, use `\`. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9. +### Run child pipelines with merge request pipelines -Instead of running a child pipeline from a static YAML file, you can define a job that runs -your own script to generate a YAML file, which is then used to trigger a child pipeline. +To trigger a child pipeline as a [merge request pipeline](merge_request_pipelines.md): -This technique can be very powerful in generating pipelines targeting content that changed or to -build a matrix of targets and architectures. +1. Set the trigger job to run on merge requests: -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Create child pipelines using dynamically generated configurations](https://youtu.be/nMdfus2JWHM). + ```yaml + # parent .gitlab-ci.yml + microservice_a: + trigger: + include: path/to/microservice_a.yml + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + ``` -We also have an example project using -[Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) -which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. -You could use a similar process for other templating languages like -[Dhall](https://dhall-lang.org/) or [ytt](https://get-ytt.io/). +1. Configure the child pipeline jobs to run in merge request pipelines: -The artifact path is parsed by GitLab, not the runner, so the path must match the -syntax for the OS running GitLab. If GitLab is running on Linux but using a Windows -runner for testing, the path separator for the trigger job would be `/`. Other CI/CD -configuration for jobs, like scripts, that use the Windows runner would use `\`. + - With [`workflow:rules`](../yaml/index.md#workflowrules): -For example, to trigger a child pipeline from a dynamically generated configuration file: + ```yaml + # child path/to/microservice_a.yml + workflow: + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" -```yaml -generate-config: - stage: build - script: generate-ci-config > generated-config.yml - artifacts: - paths: - - generated-config.yml - -child-pipeline: - stage: test - trigger: - include: - - artifact: generated-config.yml - job: generate-config -``` + job1: + script: ... -The `generated-config.yml` is extracted from the artifacts and used as the configuration -for triggering the child pipeline. + job2: + script: ... + ``` -In GitLab 12.9, the child pipeline could fail to be created in certain cases, causing the parent pipeline to fail. -This is [resolved](https://gitlab.com/gitlab-org/gitlab/-/issues/209070) in GitLab 12.10. + - By configuring [rules](../yaml/index.md#rules) for each job: -### Nested child pipelines + ```yaml + # child path/to/microservice_a.yml + job1: + script: ... + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) in GitLab 13.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243747) in GitLab 13.5. + job2: + script: ... + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + ``` -Parent and child pipelines were introduced with a maximum depth of one level of child -pipelines, which was later increased to two. A parent pipeline can trigger many child -pipelines, and these child pipelines can trigger their own child pipelines. It's not -possible to trigger another level of child pipelines. +## Trigger a multi-project pipeline by using the API -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Nested Dynamic Pipelines](https://youtu.be/C5j3ju9je2M). +You can use the [CI/CD job token (`CI_JOB_TOKEN`)](../jobs/ci_job_token.md) with the +[pipeline trigger API endpoint](../../api/pipeline_triggers.md#trigger-a-pipeline-with-a-token) +to trigger multi-project pipelines from a CI/CD job. GitLab recognizes the source of the job token +and marks the pipelines as related. In the pipeline graph, the relationships are displayed +as inbound and outbound connections for upstream and downstream pipeline dependencies. + +For example: + +```yaml +trigger_pipeline: + stage: deploy + script: + - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" + rules: + - if: $CI_COMMIT_TAG + environment: production +``` ## View a downstream pipeline +> Hover behavior for pipeline cards [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) in GitLab 13.2. + In the [pipeline graph view](index.md#view-full-pipeline-graph), downstream pipelines display -as a list of cards on the right of the graph. +as a list of cards on the right of the graph. Hover over the pipeline's card to view +which job triggered the downstream pipeline. ### Retry a downstream pipeline @@ -390,9 +357,6 @@ To cancel a downstream pipeline that is still running, select **Cancel** (**{can ### Mirror the status of a downstream pipeline in the trigger job -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11238) in GitLab Premium 12.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. - You can mirror the pipeline status from the triggered pipeline to the source trigger job by using [`strategy: depend`](../yaml/index.md#triggerstrategy): @@ -549,8 +513,9 @@ The `ENVIRONMENT` variable is passed to every job defined in a downstream pipeline. It is available as a variable when GitLab Runner picks a job. In the following configuration, the `MY_VARIABLE` variable is passed to the downstream pipeline -that is created when the `trigger-downstream` job is queued. This is because `trigger-downstream` -job inherits variables declared in global variables blocks, and then we pass these variables to a downstream pipeline. +that is created when the `trigger-downstream` job is queued. This behavior is because `trigger-downstream` +job inherits variables declared in [global `variables`](../yaml/index.md#variables) blocks, +and then GitLab passes these variables to the downstream pipeline. ```yaml variables: @@ -562,7 +527,7 @@ trigger-downstream: trigger: my/project ``` -### Prevent global variables from being passed +#### Prevent global variables from being passed You can stop global variables from reaching the downstream pipeline by using the [`inherit:variables` keyword](../yaml/index.md#inheritvariables). For example, in a [multi-project pipeline](#multi-project-pipelines): @@ -645,3 +610,16 @@ For example, in a [multi-project pipeline](#multi-project-pipelines): ref: master artifacts: true ``` + +## Troubleshooting + +### Trigger job fails and does not create multi-project pipeline + +With multi-project pipelines, the trigger job fails and does not create the downstream pipeline if: + +- The downstream project is not found. +- The user that creates the upstream pipeline does not have [permission](../../user/permissions.md) + to create pipelines in the downstream project. +- The downstream pipeline targets a protected branch and the user does not have permission + to run pipelines against the protected branch. See [pipeline security for protected branches](index.md#pipeline-security-on-protected-branches) + for more information. diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 2696d3adabd..ed0583e0872 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/ci/pipelines.html' type: reference --- @@ -155,26 +155,38 @@ The pipeline now executes the jobs as configured. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. -You can use the [`value` and `description`](../yaml/index.md#variablesdescription) -keywords to define -[pipeline-level (global) variables](../variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) -that are prefilled when running a pipeline manually. +You can use the [`description` and `value`](../yaml/index.md#variablesdescription) +keywords to define [pipeline-level (global) variables](../variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) +that are prefilled when running a pipeline manually. Use the description to explain +what the variable is used for, what the acceptable values are, and so on. -In pipelines triggered manually, the **Run pipelines** page displays all top-level variables -with a `description` and `value` defined in the `.gitlab-ci.yml` file. The values -can then be modified if needed, which overrides the value for that single pipeline run. +Job-level variables cannot be pre-filled. -The description is displayed next to the variable. It can be used to explain what -the variable is used for, what the acceptable values are, and so on: +In manually-triggered pipelines, the **Run pipeline** page displays all pipeline-level variables +with a `description` defined in the `.gitlab-ci.yml` file. The description displays +below the variable. + +You can change the prefilled value, which overrides the value for that single pipeline run. +If you do not define a `value` for the variable in the configuration file, the variable still displays, +but the value field is blank. + +For example: ```yaml variables: + TEST_SUITE: + description: "The test suite that will run. Valid options are: 'default', 'short', 'full'." + value: "default" DEPLOY_ENVIRONMENT: - value: "staging" # Deploy to staging by default - description: "The deployment target. Change this variable to 'canary' or 'production' if needed." + description: "Select the deployment target. Valid options are: 'canary', 'staging', 'production', or a stable branch of your choice." ``` -You cannot set job-level variables to be pre-filled when you run a pipeline manually. +In this example: + +- `TEST_SUITE` is pre-filled in the **Run pipeline** page with `default`, + and the message explains the other options. +- `DEPLOY_ENVIRONMENT` is listed in the **Run pipeline** page, but with no value set. + The user is expected to define the value each time the pipeline is run manually. ### Run a pipeline by using a URL query string diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index f30ae32efb2..33a9069240b 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/job_artifacts.html' --- diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index f6c93356046..714e96d7954 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index 88ab6163f3c..c501d2a7904 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge trains **(PREMIUM)** @@ -91,7 +91,7 @@ In GitLab 13.5 and earlier, there is only one checkbox, named **Enable merge trains and pipelines for merged results**. WARNING: -If you select the check box but don't configure your CI/CD to use +If you select the checkbox but don't configure your CI/CD to use merge request pipelines, your merge requests may become stuck in an unresolved state or your pipelines may be dropped. diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md index 7209a6b9a77..097f6bad87c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merged results pipelines **(PREMIUM)** @@ -33,7 +33,7 @@ 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/fast_forward_merge.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/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md index 824f1445818..25ac9e13185 100644 --- a/doc/ci/pipelines/multi_project_pipelines.md +++ b/doc/ci/pipelines/multi_project_pipelines.md @@ -1,11 +1,11 @@ --- redirect_to: 'downstream_pipelines.md' -remove_date: '2022-11-31' +remove_date: '2022-11-30' --- This document was moved to [another location](downstream_pipelines.md). -<!-- This redirect file can be deleted after <2022-11-31>. --> +<!-- This redirect file can be deleted after <2022-11-30>. --> <!-- 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/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index a02ac7ba067..e36eb24055f 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -10,15 +10,21 @@ type: reference Pipelines are the fundamental building blocks for CI/CD in GitLab. This page documents some of the important concepts related to them. -There are three main ways to structure your pipelines, each with their +You can structure your pipelines with different methods, each with their own advantages. These methods can be mixed and matched if needed: - [Basic](#basic-pipelines): Good for straightforward projects where all the configuration is in one easy to find place. - [Directed Acyclic Graph](#directed-acyclic-graph-pipelines): Good for large, complex projects that need efficient execution. -- [Child/Parent Pipelines](#child--parent-pipelines): Good for monorepos and projects with lots of independently defined components. +- [Parent-child pipelines](#parent-child-pipelines): Good for monorepos and projects with lots of independently defined components. -For more details about -any of the keywords used below, check out our [CI YAML reference](../yaml/index.md) for details. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + For an overview, see the [Parent-Child Pipelines feature demo](https://youtu.be/n8KpBSqZNbk). + +- [Multi-project pipelines](downstream_pipelines.md#multi-project-pipelines): Good for larger products that require cross-project interdependencies, + like those with a [microservices architecture](https://about.gitlab.com/blog/2016/08/16/trends-in-version-control-land-microservices/). + + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + For an overview, see the [Multi-project pipelines demo](https://www.youtube.com/watch?v=g_PIwBM1J84). ## Basic Pipelines @@ -163,12 +169,29 @@ deploy_b: environment: production ``` -## Child / Parent Pipelines +## Parent-child pipelines + +As pipelines grow more complex, a few related problems start to emerge: + +- The staged structure, where all steps in a stage must complete before the first + job in next stage begins, causes waits that slow things down. +- Configuration for the single global pipeline becomes + hard to manage. +- Imports with [`include`](../yaml/index.md#include) increase the complexity of the configuration, and can cause + namespace collisions where jobs are unintentionally duplicated. +- Pipeline UX has too many jobs and stages to work with. + +Additionally, sometimes the behavior of a pipeline needs to be more dynamic. The ability +to choose to start sub-pipelines (or not) is a powerful ability, especially if the +YAML is dynamically generated. + + -In the examples above, it's clear we've got two types of things that could be built independently. -This is an ideal case for using [Child / Parent Pipelines](downstream_pipelines.md#parent-child-pipelines)) via -the [`trigger` keyword](../yaml/index.md#trigger). It separates out the configuration -into multiple files, keeping things very simple. You can also combine this with: +In the [basic pipeline](#basic-pipelines) and [directed acyclic graph](#directed-acyclic-graph-pipelines) +examples above, there are two packages that could be built independently. +These cases are ideal for using [parent-child pipelines](downstream_pipelines.md#parent-child-pipelines). +It separates out the configuration into multiple files, keeping things simpler. +You can combine parent-child pipelines with: - The [`rules` keyword](../yaml/index.md#rules): For example, have the child pipelines triggered only when there are changes to that area. diff --git a/doc/ci/pipelines/pipeline_artifacts.md b/doc/ci/pipelines/pipeline_artifacts.md index 07e1c8a6d99..aacaa110041 100644 --- a/doc/ci/pipelines/pipeline_artifacts.md +++ b/doc/ci/pipelines/pipeline_artifacts.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline artifacts **(FREE)** diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 72711f9b9dd..aa2f074693a 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 897caa340f9..0eeb0eada87 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/schedules.html' type: reference, howto --- @@ -39,6 +39,9 @@ To add a pipeline schedule: These variables are available only when the scheduled pipeline runs, and not in any other pipeline run. +If the project already has the [maximum number of pipeline schedules](../../administration/instance_limits.md#number-of-pipeline-schedules), +you must delete unused schedules before you can add another. + ## Edit a pipeline schedule > Introduced in GitLab 14.8, only a pipeline schedule owner can edit the schedule. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index d663dea7de8..d7155004359 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/settings.html' type: reference, howto --- @@ -159,13 +159,13 @@ If the CI/CD configuration file is in a different project: - The file must exist on its default branch, or specify the branch as refname. - The path must be relative to the root directory in the other project. -- The path must include the group and project name at the end. +- The path must be followed by an `@` symbol and the full group and project path. For example: -- `.gitlab-ci.yml@mygroup/another-project` -- `my/path/.my-custom-file.yml@mygroup/another-project` -- `my/path/.my-custom-file.yml@mygroup/another-project:refname` +- `.gitlab-ci.yml@namespace/another-project` +- `my/path/.my-custom-file.yml@namespace/sub-group/another-project` +- `my/path/.my-custom-file.yml@namespace/sub-group1/sub-group2/another-project:refname` If the configuration file is in a separate project, you can set more granular permissions. For example: @@ -329,7 +329,7 @@ you can view a graph or download a CSV file with this data. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Repository**. -The historic data for each job is listed in the dropdown above the graph. +The historic data for each job is listed in the dropdown list above the graph. To view a CSV file of the data, select **Download raw data (`.csv`)**. diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 2b44cf3b898..ad41e4fa88a 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md index dff52a742a8..2803ddba828 100644 --- a/doc/ci/resource_groups/index.md +++ b/doc/ci/resource_groups/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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: Control the job concurrency in GitLab CI/CD --- diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 9bafb69482b..2f23ebbfd9f 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review Apps **(FREE)** @@ -95,9 +95,14 @@ after a given period of time. The following are example projects that demonstrate Review App configuration: -- [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx). -- [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift). -- [HashiCorp Nomad](https://gitlab.com/gitlab-examples/review-apps-nomad). +| Project | Configuration file | +|-------------------------------------------------------------------------|--------------------| +| [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-examples/review-apps-nginx/-/blob/b9c1f6a8a7a0dfd9c8784cbf233c0a7b6a28ff27/.gitlab-ci.yml#L20) | +| [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-examples/review-apps-openshift/-/blob/82ebd572334793deef2d5ddc379f38942f3488be/.gitlab-ci.yml#L42) | +| [HashiCorp Nomad](https://gitlab.com/gitlab-examples/review-apps-nomad) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-examples/review-apps-nomad/-/blob/ca372c778be7aaed5e82d3be24e98c3f10a465af/.gitlab-ci.yml#L110) | +| [GitLab Documentation](https://gitlab.com/gitlab-org/gitlab-docs/) | [`build-and-deploy.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/a715625496303cbd90ff89f3d3658ea8d36ce0f3/.gitlab/ci/build-and-deploy.gitlab-ci.yml#L59) | +| [`https://about.gitlab.com/`](https://gitlab.com/gitlab-com/www-gitlab-com/) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/6ffcdc3cb9af2abed490cbe5b7417df3e83cd76c/.gitlab-ci.yml#L332) | +| [GitLab Insights](https://gitlab.com/gitlab-org/gitlab-insights/) | [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-insights/-/blob/9e63f44ac2a5a4defc965d0d61d411a768e20546/.gitlab-ci.yml#L234) | Other examples of Review Apps: diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 9d26ec63f96..19e0c1e3c81 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configuring runners **(FREE)** @@ -198,7 +198,7 @@ To make a runner pick untagged jobs: 1. Select **Save changes** for the changes to take effect. NOTE: -The runner tags list can not be empty when it's not allowed to pick untagged jobs. +The runner tags list cannot be empty when it's not allowed to pick untagged jobs. Below are some example scenarios of different variations. @@ -302,6 +302,7 @@ globally or for individual jobs: - [`GIT_CHECKOUT`](#git-checkout) - [`GIT_CLEAN_FLAGS`](#git-clean-flags) - [`GIT_FETCH_EXTRA_FLAGS`](#git-fetch-extra-flags) +- [`GIT_SUBMODULE_PATHS`](#git-submodule-paths) - [`GIT_SUBMODULE_UPDATE_FLAGS`](#git-submodule-update-flags) - [`GIT_DEPTH`](#shallow-cloning) (shallow cloning) - [`GIT_CLONE_PATH`](#custom-build-directories) (custom build directories) @@ -488,6 +489,32 @@ git fetch origin $REFSPECS --depth 50 --prune Where `$REFSPECS` is a value provided to the runner internally by GitLab. +### Git submodule paths + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/2249) in GitLab Runner 14.0. + +Use the `GIT_SUBMODULE_PATHS` variable to control which submodules have to be synced or updated. +You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section. + +This variable can be very useful for projects which have a large number of submodules which not all of them +need to be synced or updated in all CI jobs. + +The path syntax is the same as [`git submodule`](https://git-scm.com/docs/git-submodule#Documentation/git-submodule.txt-ltpathgt82308203): + +- To sync and update specific paths: + + ```yaml + variables: + GIT_SUBMODULE_PATHS: submoduleA submoduleB + ``` + +- To exclude specific paths: + + ```yaml + variables: + GIT_SUBMODULE_PATHS: :(exclude)submoduleA :(exclude)submoduleB + ``` + ### Git submodule update flags > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3192) in GitLab Runner 14.8. @@ -915,12 +942,8 @@ To determine which runners need to be upgraded: ## 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. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to -[enable the feature flag](../../administration/feature_flags.md) named `enforce_runner_token_expires_at`. -On GitLab.com, this feature is not available. +> - [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 [authentication token](../../api/runners.md#registration-and-authentication-tokens) to connect with the GitLab instance. diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 1de24efa8aa..405310fb8ba 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index f8a33ea6861..4be4ed33feb 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -172,8 +172,12 @@ To create a group runner: 1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **CI/CD > Runners**. -1. Note the URL and token. -1. [Register the runner](https://docs.gitlab.com/runner/register/). +1. In the top-right corner, select **Register a group runner**. +1. Select **Show runner installation and registration instructions**. + These instructions include the token, URL, and a command to register a runner. + +Alternately, you can copy the registration token and follow the documentation for +how to [register a runner](https://docs.gitlab.com/runner/register/). ### View and manage group runners @@ -188,6 +192,23 @@ You must have the Owner role for the group. From this page, you can edit, pause, and remove runners from the group, its subgroups, and projects. +#### Filter group runners to show only inherited + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337838/) in GitLab 15.5. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101099) in GitLab 15.5. Feature flag `runners_finder_all_available` removed. + +You can choose to show all runners in the list, or show only +those that are inherited from the instance or other groups. + +By default, only those that are inherited are shown. + +To show all runners available in the instance, including shared runners and +those in other groups: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **CI/CD > Runners**. +1. Above the list, turn off the **Show only inherited** toggle. + ### Pause or remove a group runner You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com. diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index a7d1b8722a5..d1c63ab7291 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Linux diff --git a/doc/ci/runners/saas/macos/codesigning.md b/doc/ci/runners/saas/macos/codesigning.md index 71fdc61f0b6..697f138eec6 100644 --- a/doc/ci/runners/saas/macos/codesigning.md +++ b/doc/ci/runners/saas/macos/codesigning.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code signing for SaaS runners on macOS diff --git a/doc/ci/runners/saas/macos/environment.md b/doc/ci/runners/saas/macos/environment.md index edd897e4c23..1fc7afea7e6 100644 --- a/doc/ci/runners/saas/macos/environment.md +++ b/doc/ci/runners/saas/macos/environment.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # VM instances and images for SaaS runners on macOS **(PREMIUM SAAS)** @@ -57,5 +57,6 @@ Each image is running a specific version of macOS and Xcode. | `macos-10.14-xcode-10` | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/mojave.yml> | | `macos-10.15-xcode-11` | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/catalina.yml> | | `macos-11-xcode-12` | `frozen` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/big-sur.yml> | -| `macos-12-xcode-13` | `maintenance` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/monterey.yml> | +| `macos-12-xcode-13` | `maintenance` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/monterey.yml> | +| `macos-12-xcode-14` | `maintenance` | <https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/macstadium/orka/-/blob/main/toolchain/monterey.yml> | | (none, awaiting macOS 13) | `beta` | | diff --git a/doc/ci/runners/saas/macos_saas_runner.md b/doc/ci/runners/saas/macos_saas_runner.md index 5a2d84b6996..50c24349712 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on macOS (Beta) **(PREMIUM SAAS)** @@ -14,10 +14,6 @@ Use these runners to build, test, and deploy apps for the Apple ecosystem (macOS of all the capabilities of the GitLab single DevOps platform and not have to manage or operate a build environment. -CI/CD minutes used on GitLab SaaS macOS runners are included in your CI/CD minute consumption totals. CI jobs that run on macOS **will** consume CI minutes at a faster rate than CI jobs on the GitLab SaaS runners on Linux. - -Refer to the CI/CD minutes [cost factor](../../../ci/pipelines/cicd_minutes.md#cost-factor) for the cost factor applied to the GitLab SaaS macOS runners. - Jobs handled by macOS shared runners on GitLab.com **time out after 2 hours**, regardless of the timeout configured in a project. ## Access request process diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index f9fe6290220..2c6540833b0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SaaS runners on Windows (beta) **(FREE SAAS)** diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index fb91aeb6240..62350905bd4 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -56,7 +56,7 @@ To configure your Vault server: 1. Ensure your Vault server is running on version 1.2.0 or higher. 1. Enable the authentication method by running these commands. They provide your Vault - server the [JSON Web Key Set](https://tools.ietf.org/html/rfc7517) (JWKS) endpoint for your GitLab instance, so Vault + server the [JSON Web Key Set](https://www.rfc-editor.org/rfc/rfc7517) (JWKS) endpoint for your GitLab instance, so Vault can fetch the public signing key and verify the JSON Web Token (JWT) when authenticating: ```shell diff --git a/doc/ci/secure_files/index.md b/doc/ci/secure_files/index.md index ff5c29cdb06..bba8a3e4c27 100644 --- a/doc/ci/secure_files/index.md +++ b/doc/ci/secure_files/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -13,7 +13,13 @@ FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `ci_secure_files`. Limited to 100 secure files per project. Files must be smaller -than 5 MB. The feature is not ready for production use. +than 5 MB. Project-level Secure Files is an experimental feature developed by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/). + +Project-level Secure Files is still in development, but you can: + +- [Request a feature](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/feedback/-/issues/new?issuable_template=feature_request). +- [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). You can securely store files for use in CI/CD pipelines as "secure files". These files are stored securely outside of your project's repository, and are not version controlled. diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 689ce884ae4..f2ea969f430 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index 9b2bcc39b3e..0f82f2301c7 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index --- @@ -370,8 +370,11 @@ access-service: curlimages/curl:7.74.0 curl "http://tutum-wordpress" ``` -For this solution to work, you must use -[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job). +For this solution to work, you must: + +- Use [the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job). +- [Not use the Docker executor with Docker socket binding](../docker/using_docker_build.md#use-the-docker-executor-with-docker-socket-binding). + If you must, then in the above example, instead of `host`, use the dynamic network name created for this job. ## How Docker integration works diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index d0ac123ba62..ea11719cef1 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index c2ff4c60771..139a4a2f742 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index a3446fc2677..a7a28116aa4 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -69,5 +69,5 @@ We have set up an [Example Redis Project](https://gitlab.com/gitlab-examples/red that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/index.md). -Want to hack on it? Simply fork it, commit and push your changes. Within a few +Want to hack on it? Fork it, commit and push your changes. Within a few moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/ssh_keys/index.md b/doc/ci/ssh_keys/index.md index 30b688c0b96..972e9494126 100644 --- a/doc/ci/ssh_keys/index.md +++ b/doc/ci/ssh_keys/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -10,13 +10,13 @@ type: tutorial GitLab currently doesn't have built-in support for managing SSH keys in a build environment (where the GitLab Runner runs). -Use SSH keys when: +Use SSH keys when you want to: -1. You want to checkout internal submodules -1. You want to download private packages using your package manager (for example, Bundler) -1. You want to deploy your application to your own server, or, for example, Heroku -1. You want to execute SSH commands from the build environment to a remote server -1. You want to rsync files from the build environment to a remote server +- Check out internal submodules. +- Download private packages using your package manager. For example, Bundler. +- Deploy your application to your own server or, for example, Heroku. +- Execute SSH commands from the build environment to a remote server. +- Rsync files from the build environment to a remote server. If anything of the above rings a bell, then you most likely need an SSH key. @@ -115,9 +115,9 @@ SSH key. You can generate the SSH key from the machine that GitLab Runner is installed on, and use that key for all projects that are run on this machine. -1. First, log in to the server that runs your jobs. +1. First, sign in to the server that runs your jobs. -1. Then, from the terminal, log in as the `gitlab-runner` user: +1. Then, from the terminal, sign in as the `gitlab-runner` user: ```shell sudo su - gitlab-runner diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md index 3ef25a4924b..8d2788539d8 100644 --- a/doc/ci/test_cases/index.md +++ b/doc/ci/test_cases/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Certify -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 +info: To 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: Test cases in GitLab can help your teams create testing scenarios in their existing development platform. type: reference --- @@ -36,7 +36,10 @@ issue list with a search query, including labels or the test case's title. Prerequisite: -- You must have at least the Guest role. +Whether you can view an test case depends on the [project visibility level](../../user/public_access.md): + +- Public project: You don't have to be a member of the project. +- Private project: You must have at least the Guest role for the project. To view a test case: diff --git a/doc/ci/testing/accessibility_testing.md b/doc/ci/testing/accessibility_testing.md index 7940b27acf7..fa57371a7d5 100644 --- a/doc/ci/testing/accessibility_testing.md +++ b/doc/ci/testing/accessibility_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Accessibility testing **(FREE)** diff --git a/doc/ci/testing/browser_performance_testing.md b/doc/ci/testing/browser_performance_testing.md index 260ecf6108d..ff013f0037e 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 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Browser Performance Testing **(PREMIUM)** diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index 401279b9601..7345c7ca5eb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Quality **(FREE)** @@ -313,7 +313,7 @@ the nested architecture of container execution, the registry prefix must be specifically configured to be passed down into CodeClimate's subsequent `docker pull` commands for individual engines. -The following two variables can address all of the required image pulls: +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 @@ -322,6 +322,8 @@ The following two variables can address all of the required image pulls: is a configuration option supported by [CodeClimate CLI](https://github.com/codeclimate/codeclimate/pull/948). You must: - Include a trailing slash (`/`). - Not include a protocol prefix, such as `https://`. +- `CODECLIMATE_REGISTRY_USERNAME`: An optional variable to specify the username for the registry domain parsed from `CODECLIMATE_PREFIX`. +- `CODECLIMATE_REGISTRY_PASSWORD`: An optional variable to specify the password for the registry domain parsed from `CODECLIMATE_PREFIX`. ```yaml include: @@ -333,13 +335,49 @@ code_quality: CODECLIMATE_PREFIX: "my-private-registry.local:12345/" ``` -The images in the private container image registry must be available without authentication. -Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/355814) for more information. - This example is specific to GitLab Code Quality. For more general instructions on how to configure DinD with a registry mirror, see the relevant [documentation](../docker/using_docker_build.md#enable-registry-mirror-for-dockerdind-service). +#### Configure Code Quality to use the Dependency Proxy + +Prerequisite: + +- The project must be in a group where the [Dependency Proxy](../../user/packages/dependency_proxy/index.md) is enabled. + +Here is an example of how to configure Code Quality to use the Dependency Proxy: + +```yaml +include: + - template: Jobs/Code-Quality.gitlab-ci.yml + +code_quality: + variables: + CODE_QUALITY_IMAGE: "$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/codequality:0.85.24" + ## You must add a trailing slash to `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`. + CODECLIMATE_PREFIX: $CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX/ + CODECLIMATE_REGISTRY_USERNAME: $CI_DEPENDENCY_PROXY_USER + CODECLIMATE_REGISTRY_PASSWORD: $CI_DEPENDENCY_PROXY_PASSWORD +``` + +#### Configure Code Quality to use Dockerhub with authentication + +Here is an example of how to configure Code Quality to use Dockerhub with authentication: + +```yaml +include: + - template: Jobs/Code-Quality.gitlab-ci.yml + +code_quality: + variables: + CODECLIMATE_PREFIX: "registry-1.docker.io/" + CODECLIMATE_REGISTRY_USERNAME: $DOCKERHUB_USERNAME + CODECLIMATE_REGISTRY_PASSWORD: $DOCKERHUB_PASSWORD +``` + +You should add the username and password as [protected CI/CD variables](../variables/index.md#add-a-cicd-variable-to-a-project) +in the project. + ## Configuring jobs using variables The Code Quality job supports environment variables that users can set to diff --git a/doc/ci/testing/fail_fast_testing.md b/doc/ci/testing/fail_fast_testing.md index 7b95b1ac54a..58471a626da 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 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Fail Fast Testing **(PREMIUM)** diff --git a/doc/ci/testing/index.md b/doc/ci/testing/index.md index a8f06ec695c..41d474f0e60 100644 --- a/doc/ci/testing/index.md +++ b/doc/ci/testing/index.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test with GitLab CI/CD and generate reports in merge requests **(FREE)** diff --git a/doc/ci/testing/load_performance_testing.md b/doc/ci/testing/load_performance_testing.md index e15b3944c2b..6e1b440f252 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 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Load Performance Testing **(PREMIUM)** diff --git a/doc/ci/testing/metrics_reports.md b/doc/ci/testing/metrics_reports.md index e855074ddea..e084e4d3bc7 100644 --- a/doc/ci/testing/metrics_reports.md +++ b/doc/ci/testing/metrics_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metrics Reports **(PREMIUM)** diff --git a/doc/ci/testing/test_coverage_visualization.md b/doc/ci/testing/test_coverage_visualization.md index 472cfca99be..ee6b47e69a5 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 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test coverage visualization **(FREE)** diff --git a/doc/ci/testing/unit_test_report_examples.md b/doc/ci/testing/unit_test_report_examples.md index b49ac29be65..c14e4eedd7c 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 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit test report examples **(FREE)** @@ -183,7 +183,11 @@ the `javascript` job uses Jest to generate the test reports: ```yaml javascript: + image: node:latest stage: test + before_script: + - 'yarn global add jest' + - 'yarn add --dev jest-junit' script: - 'jest --ci --reporters=default --reporters=jest-junit' artifacts: @@ -193,6 +197,9 @@ javascript: - junit.xml ``` +To make the job pass when there are no `.test.js` files with unit tests, add the +`--passWithNoTests` flag to the end of the `jest` command in the `script:` section. + ### Karma The [Karma-junit-reporter](https://github.com/karma-runner/karma-junit-reporter) diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md index 28356a62c99..0fe9b2b6d64 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 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit test reports **(FREE)** diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index 36d136727b0..cafa64c4832 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 8a03ec0b56f..8f78469af18 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/unit_test_reports.md b/doc/ci/unit_test_reports.md deleted file mode 100644 index 7578a1e6009..00000000000 --- a/doc/ci/unit_test_reports.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'testing/unit_test_reports.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](testing/unit_test_reports.md). - -<!-- This redirect file can be deleted after <2022-08-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 (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/variables/index.md b/doc/ci/variables/index.md index 25178903c9a..7ad42aaf96b 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -193,7 +193,7 @@ The output is: > Support for environment scopes [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) in GitLab Premium 13.11 -To make a CI/CD variable available to all projects in a group, define a group CI/CD variable. +To make a CI/CD variable available to all projects in a group, define a group CI/CD variable. Only group owners can add or update group-level CI/CD variables. Use group variables to store secrets like passwords, SSH keys, and credentials, if you: @@ -682,7 +682,10 @@ The order of precedence for variables is (from highest to lowest): - [Manual pipeline run variables](#override-a-variable-when-running-a-pipeline-manually). - Variables added when [creating a pipeline with the API](../../api/pipelines.md#create-a-new-pipeline). 1. Project [variables](#custom-cicd-variables). -1. Group [variables](#add-a-cicd-variable-to-a-group). +1. Group [variables](#add-a-cicd-variable-to-a-group). If the same variable name exists in a + group and its subgroups, the job uses the value from the closest subgroup. For example, if + you have `Group > Subgroup 1 > Subgroup 2 > Project`, the variable defined in + `Subgroup 2` takes precedence. 1. Instance [variables](#add-a-cicd-variable-to-an-instance). 1. [Inherited variables](#pass-an-environment-variable-to-another-job). 1. Variables defined in jobs in the `.gitlab-ci.yml` file. @@ -768,7 +771,7 @@ for [deployment jobs](../environments/index.md). For example, the [Kubernetes integration](../../user/project/clusters/deploy_to_cluster.md#deployment-variables) defines deployment variables that you can use with the integration. -The [documentation for each integration](../../user/project/integrations/overview.md) +The [documentation for each integration](../../user/project/integrations/index.md) explains if the integration has any deployment variables available. ## Auto DevOps environment variables diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 77005e1cec4..606847ee756 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -39,6 +39,7 @@ as it can cause the pipeline to behave unexpectedly. | `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 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. | @@ -60,6 +61,7 @@ as it can cause the pipeline to behave unexpectedly. | `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 | The configuration setting for whether FIPS mode is enabled in the GitLab instance. | | `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. | @@ -69,11 +71,12 @@ as it can cause the pipeline to behave unexpectedly. | `CI_JOB_JWT_V2` | 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. Format is subject to change. Be aware, 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). **Note:** The `CI_JOB_JWT_V2` variable is available for testing, but the full feature is planned to be generally available when [issue 360657](https://gitlab.com/gitlab-org/gitlab/-/issues/360657) is complete.| | `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_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://tools.ietf.org/html/rfc3339#appendix-A) format. | +| `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). | @@ -85,7 +88,7 @@ as it can cause the pipeline to behave unexpectedly. | `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://tools.ietf.org/html/rfc3339#appendix-A) format. | +| `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_PROJECT_CONFIG_PATH` | 13.8 to 13.12 | all | [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/322807) in GitLab 14.0. Use `CI_CONFIG_PATH`. | | `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. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 6c1737f7c65..7e5451658f2 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index 56a9da7cb84..67cbe989f74 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.md @@ -1,7 +1,7 @@ --- stage: Verify group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD artifacts reports types **(FREE)** diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md index f3773fbf143..7b4834b3719 100644 --- a/doc/ci/yaml/gitlab_ci_yaml.md +++ b/doc/ci/yaml/gitlab_ci_yaml.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 5158f80ea64..2b9f42e1c75 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 8aa3ebd4759..e06abe1dc69 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -379,7 +379,7 @@ start. Jobs in the current stage are not stopped and continue to run. - If a job does not specify a [`stage`](#stage), the job is assigned the `test` stage. - If a stage is defined but no jobs use it, the stage is not visible in the pipeline, - which can help [compliance pipeline configurations](../../user/project/settings/index.md#compliance-pipeline-configuration): + which can help [compliance pipeline configurations](../../user/group/manage.md#configure-a-compliance-pipeline): - Stages can be defined in the compliance configuration but remain hidden if not used. - The defined stages become visible when developers use them in job definitions. @@ -398,6 +398,30 @@ Use [`workflow`](workflow.md) to control pipeline behavior. - [`workflow: rules` examples](workflow.md#workflow-rules-examples) - [Switch between branch pipelines and merge request pipelines](workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines) +#### `workflow:name` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372538) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `pipeline_name`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `pipeline_name`. +The feature is not ready for production use. + +You can use `name` in `workflow:` to define a name for pipelines. + +All pipelines are assigned the defined name. Any leading or trailing spaces in the name are removed. + +**Possible inputs**: + +- A string. + +**Example of `workflow:name`**: + +```yaml +workflow: + name: 'Pipeline name' +``` + #### `workflow:rules` The `rules` keyword in `workflow` is similar to [`rules` defined in jobs](#rules), @@ -1238,7 +1262,11 @@ is not found, the prefix is added to `default`, so the key in the example would #### `cache:untracked` -Use `untracked: true` to cache all files that are untracked in your Git repository: +Use `untracked: true` to cache all files that are untracked in your Git repository. +Untracked files include files that are: + +- Ignored due to [`.gitignore` configuration](https://git-scm.com/docs/gitignore). +- Created, but not added to the checkout with [`git add`](https://git-scm.com/docs/git-add). **Keyword type**: Job keyword. You can use it only as part of a job or in the [`default` section](#default). @@ -1259,7 +1287,7 @@ rspec: **Additional details**: - You can combine `cache:untracked` with `cache:paths` to cache all untracked files - as well as files in the configured paths. For example: + as well as files in the configured paths. This is useful for including files that are not tracked because of a `.gitignore` configuration. For example: ```yaml rspec: @@ -2161,7 +2189,7 @@ This example creates four paths of execution: explicitly defined for all jobs that use the `needs` keyword, or are referenced in a job's `needs` section. - In GitLab 13.9 and older, if `needs` refers to a job that might not be added to - a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. + a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. In GitLab 13.10 and later, use the [`needs:optional`](#needsoptional) keyword to resolve a failed pipeline creation. #### `needs:artifacts` @@ -3260,8 +3288,19 @@ branch or merge request pipelines. **Possible inputs**: -- An array of file paths. In GitLab 13.6 and later, [file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges). -- Alternatively, the array of file paths can be in [`rules:changes:paths`](#ruleschangespaths). +An array including any number of: + +- Paths to files. In GitLab 13.6 and later, [file paths can include variables](../jobs/job_control.md#variables-in-ruleschanges). + A file path array can also be in [`rules:changes:paths`](#ruleschangespaths). +- 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}`. + 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"`. **Example of `rules:changes`**: @@ -3332,7 +3371,8 @@ In this example, both jobs have the same behavior. ##### `rules:changes:compare_to` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293645) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `ci_rules_changes_compare`. Enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293645) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `ci_rules_changes_compare`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/366412) in GitLab 15.5. Feature flag `ci_rules_changes_compare` removed. Use `rules:changes:compare_to` to specify which ref to compare against for changes to the files listed under [`rules:changes:paths`](#ruleschangespaths). @@ -3938,7 +3978,7 @@ trigger-multi-project-pipeline: **Related topics**: -- [Multi-project pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-from-a-job-in-your-gitlab-ciyml-file). +- [Multi-project pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-downstream-pipeline-from-a-job-in-the-gitlab-ciyml-file). - To run a pipeline for a specific branch, tag, or commit, you can use a [trigger token](../triggers/index.md) to authenticate with the [pipeline triggers API](../../api/pipeline_triggers.md). The trigger token is different than the `trigger` keyword. @@ -3966,7 +4006,7 @@ trigger-child-pipeline: **Related topics**: -- [Child pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-parent-child-pipeline). +- [Child pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-downstream-pipeline-from-a-job-in-the-gitlab-ciyml-file). #### `trigger:project` @@ -4002,7 +4042,7 @@ trigger-multi-project-pipeline: **Related topics**: -- [Multi-project pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-from-a-job-in-your-gitlab-ciyml-file). +- [Multi-project pipeline configuration examples](../pipelines/downstream_pipelines.md#trigger-a-downstream-pipeline-from-a-job-in-the-gitlab-ciyml-file). - To run a pipeline for a specific branch, tag, or commit, you can also use a [trigger token](../triggers/index.md) to authenticate with the [pipeline triggers API](../../api/pipeline_triggers.md). The trigger token is different than the `trigger` keyword. @@ -4160,9 +4200,9 @@ deploy_review_job: Use the `description` keyword to define a [pipeline-level (global) variable that is prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually). -Must be used with `value`, for the variable value. +If used with `value`, the variable value is also prefilled when running a pipeline manually. -**Keyword type**: Global keyword. You cannot set job-level variables to be pre-filled when you run a pipeline manually. +**Keyword type**: Global keyword. You cannot use it for job-level variables. **Possible inputs**: @@ -4173,10 +4213,15 @@ Must be used with `value`, for the variable value. ```yaml variables: DEPLOY_ENVIRONMENT: - value: "staging" description: "The deployment target. Change this variable to 'canary' or 'production' if needed." + value: "staging" ``` +**Additional details**: + +- A global variable defined with `value` but no `description` behaves the same as + [`variables`](#variables). + ### `when` Use `when` to configure the conditions for when jobs run. If not defined in a job, diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index bd8d7f02a17..1d3186a4047 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Format scripts and job logs **(FREE)** diff --git a/doc/ci/yaml/workflow.md b/doc/ci/yaml/workflow.md index d3e815c742d..3d6314c8e03 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab CI/CD `workflow` keyword **(FREE)** diff --git a/doc/ci/yaml/yaml_optimization.md b/doc/ci/yaml/yaml_optimization.md index e5d9e011230..f4774619713 100644 --- a/doc/ci/yaml/yaml_optimization.md +++ b/doc/ci/yaml/yaml_optimization.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -220,7 +220,7 @@ multiple jobs. It is similar to [YAML anchors](#anchors), but simpler and you ca [use `extends` with `includes`](#use-extends-and-include-together). `extends` supports multi-level inheritance. You should avoid using more than three levels, -but you can use as many as eleven. The following example has two levels of inheritance: +due to the additional complexity, but you can use as many as eleven. The following example has two levels of inheritance: ```yaml .tests: diff --git a/doc/cloud_seed/index.md b/doc/cloud_seed/index.md index 4c56b6c4aaa..bf51da88cb4 100644 --- a/doc/cloud_seed/index.md +++ b/doc/cloud_seed/index.md @@ -4,17 +4,15 @@ group: Incubation info: Cloud Seed (formerly 5mp) is a GitLab Incubation Engineering program. No technical writer assigned to this group. --- -# Cloud Seed +# Cloud Seed **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371332) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `google_cloud`. Disabled by default. +> - [Enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100545) in GitLab 15.5. Cloud Seed is an open-source program led by [GitLab Incubation Engineering](https://about.gitlab.com/handbook/engineering/incubation/) in collaboration with [Google Cloud](https://cloud.google.com/). -Cloud Seed is in `private-testing` mode and is available to a select group of users. If you are interested in joining -this group, please fill in -the [Cloud Seed Trusted Testers invitation form](https://docs.google.com/forms/d/e/1FAIpQLSeJPtFE8Vpqs_YTAKkFK42p5mO9zIYA2jr_PiP2h32cs8R39Q/viewform) -and we will reach out to you. - ## Purpose We believe that it should be **trivial** to deploy web applications (and other workloads) from GitLab to major cloud diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index c00d9da5d16..0048b10c9da 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Adding a new Service Component to GitLab diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 673ec692bf4..d3053a1ca5f 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL API style guide @@ -436,7 +436,7 @@ By default, fields add `1` to a query's complexity score. This can be overridden [providing a custom `complexity`](https://graphql-ruby.org/queries/complexity_and_depth.html) value for a field. Developers should specify higher complexity for fields that cause more _work_ to be performed -by the server in order to return data. Fields that represent data that can be returned +by the server to return data. Fields that represent data that can be returned with little-to-no _work_, for example in most cases; `id` or `title`, can be given a complexity of `0`. ### `calls_gitaly` diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 7f7d78bb58e..f74ed8db50f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # API style guide diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index ceb3c124d1a..edf159a116a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application limits development diff --git a/doc/development/application_secrets.md b/doc/development/application_secrets.md index 93e43856b34..526cc6c3f61 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application secrets diff --git a/doc/development/application_slis/index.md b/doc/development/application_slis/index.md index cb2eb9b8d90..75dd066680e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Application Service Level Indicators (SLIs) @@ -26,6 +26,8 @@ to be emitted from the rails application: 1. [`rails_request_apdex`](rails_request_apdex.md) 1. `global_search_apdex` +1. `global_search_error_rate` +1. `global_search_indexing_apdex` ## Defining a new SLI diff --git a/doc/development/application_slis/rails_request_apdex.md b/doc/development/application_slis/rails_request_apdex.md index 033bffbf608..2fa9f5f4869 100644 --- a/doc/development/application_slis/rails_request_apdex.md +++ b/doc/development/application_slis/rails_request_apdex.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rails request Apdex SLI diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index 922a0cd46a2..ce774b1e8f9 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Approval Rules development guide **(FREE)** diff --git a/doc/development/appsec/index.md b/doc/development/appsec/index.md deleted file mode 100644 index 8361170c3d2..00000000000 --- a/doc/development/appsec/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../index.md' -remove_date: '2022-09-23' ---- - -This document was moved to [another location](../index.md). - -<!-- This redirect file can be deleted after <2022-09-23>. --> -<!-- 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/architecture.md b/doc/development/architecture.md index a813072a976..a731e661a80 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab architecture overview diff --git a/doc/development/audit_event_guide/index.md b/doc/development/audit_event_guide/index.md index 50d7eeed107..5c8938aa46a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Audit Event Guide @@ -19,7 +19,7 @@ actions performed across the application. While any events could trigger an Audit Event, not all events should. In general, events that are not good candidates for audit events are: - Not attributable to one specific user. -- Not of specific interest to an admin or owner persona. +- Not of specific interest to an administrator or owner persona. - 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/manage/compliance/audit-events/#what-is-not-planned-right-now). diff --git a/doc/development/auto_devops.md b/doc/development/auto_devops.md index b9b8770207e..7a684f64d64 100644 --- a/doc/development/auto_devops.md +++ b/doc/development/auto_devops.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auto DevOps development guide **(FREE)** diff --git a/doc/development/avoiding_downtime_in_migrations.md b/doc/development/avoiding_downtime_in_migrations.md deleted file mode 100644 index d4c225b62c5..00000000000 --- a/doc/development/avoiding_downtime_in_migrations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'database/avoiding_downtime_in_migrations.md' -remove_date: '2022-07-08' ---- - -This document was moved to [another location](database/avoiding_downtime_in_migrations.md). - -<!-- This redirect file can be deleted after <2022-07-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 (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/backend/create_source_code_be/gitaly_touch_points.md b/doc/development/backend/create_source_code_be/gitaly_touch_points.md index 5ac362e709f..6ee2c7f0e51 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 a1322b3fa25..8a1a541fac9 100644 --- a/doc/development/backend/create_source_code_be/index.md +++ b/doc/development/backend/create_source_code_be/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create: Source Code Backend 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 dd43bb914c9..2130d76d014 100644 --- a/doc/development/backend/create_source_code_be/rest_endpoints.md +++ b/doc/development/backend/create_source_code_be/rest_endpoints.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Source Code REST endpoints diff --git a/doc/development/backend/ruby_style_guide.md b/doc/development/backend/ruby_style_guide.md index 6ba5b8dd2c5..9b5a68e4292 100644 --- a/doc/development/backend/ruby_style_guide.md +++ b/doc/development/backend/ruby_style_guide.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Ruby style guide diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md deleted file mode 100644 index 3c9c34bccf8..00000000000 --- a/doc/development/background_migrations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'database/background_migrations.md' -remove_date: '2022-07-08' ---- - -This document was moved to [another location](database/background_migrations.md). - -<!-- This redirect file can be deleted after <2022-07-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 (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/batched_background_migrations.md b/doc/development/batched_background_migrations.md deleted file mode 100644 index f5f3655944b..00000000000 --- a/doc/development/batched_background_migrations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'database/batched_background_migrations.md' -remove_date: '2022-07-26' ---- - -This document was moved to [another location](database/batched_background_migrations.md). - -<!-- This redirect file can be deleted after <2022-07-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 (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/build_test_package.md b/doc/development/build_test_package.md index 97dd24fc522..70aa328bf8a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Building a package for testing diff --git a/doc/development/bulk_import.md b/doc/development/bulk_import.md index a2620faed35..92236594f8e 100644 --- a/doc/development/bulk_import.md +++ b/doc/development/bulk_import.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Group Migration diff --git a/doc/development/cached_queries.md b/doc/development/cached_queries.md index 7af4c302e93..fbb857106be 100644 --- a/doc/development/cached_queries.md +++ b/doc/development/cached_queries.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Application Performance -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cached queries guidelines diff --git a/doc/development/caching.md b/doc/development/caching.md index 5ae6484436e..36fbfc7010e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Caching guidelines diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md index 56699ff5ffc..22f146c3f5a 100644 --- a/doc/development/cascading_settings.md +++ b/doc/development/cascading_settings.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cascading Settings diff --git a/doc/development/changelog.md b/doc/development/changelog.md index c0296a6d75e..7dc3ae0a80b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Changelog entries @@ -114,7 +114,7 @@ making it both concise and descriptive, err on the side of descriptive. - **Bad:** Go to a project order. - **Good:** Show a user's starred projects at the top of the "Go to project" - dropdown. + dropdown list. The first example provides no context of where the change was made, or why, or how it benefits the user. @@ -126,9 +126,9 @@ how it benefits the user. Again, the first example is too vague and provides no context. - **Bad:** Fixes and Improves CSS and HTML problems in mini pipeline graph and - builds dropdown. + builds dropdown list. - **Good:** Fix tooltips and hover states in mini pipeline graph and builds - dropdown. + dropdown list. The first example is too focused on implementation details. The user doesn't care that we changed CSS and HTML, they care about the _end result_ of those diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md index 838235fd795..008c3700253 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Generating chaos in a test GitLab instance @@ -77,7 +77,7 @@ curl "http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10&token=s ## CPU spin -This endpoint attempts to fully utilise a single core, at 100%, for the given period. +This endpoint attempts to fully use a single core, at 100%, for the given period. Depending on your rack server setup, your request may timeout after a predetermined period (normally 60 seconds). @@ -100,7 +100,7 @@ curl "http://localhost:3000/-/chaos/cpu_spin?duration_s=60&token=secret" ## DB spin -This endpoint attempts to fully utilise a single core, and interleave it with DB request, for the given period. +This endpoint attempts to fully use a single core, and interleave it with DB request, for the given period. This endpoint can be used to model yielding execution to another threads when running concurrently. Depending on your rack server setup, your request may timeout after a predetermined period (normally 60 seconds). diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md index 7309b92c702..16dc17dd229 100644 --- a/doc/development/chatops_on_gitlabcom.md +++ b/doc/development/chatops_on_gitlabcom.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 0da1717f53c..8c75e66c33a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Documenting the `.gitlab-ci.yml` keywords **(FREE)** diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 7a2dfa01d1e..cd31038ddd1 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -96,6 +96,9 @@ when transitioning to the `pending` state. This job is responsible for creating a multi-project or child pipeline. The workflow loop starts again from the `CreatePipelineService` every time a downstream pipeline is triggered. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +You can watch a walkthrough of the architecture in [CI Backend Architectural Walkthrough](https://www.youtube.com/watch?v=ew4BwohS5OY). + ## Job scheduling When a Pipeline is created all its jobs are created at once for all stages, with an initial state of `created`. This makes it possible to visualize the full content of a pipeline. diff --git a/doc/development/cicd/pipeline_wizard.md b/doc/development/cicd/pipeline_wizard.md index 227a49d85db..eb6d1c60bb1 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline Wizard diff --git a/doc/development/cicd/schema.md b/doc/development/cicd/schema.md index ee5b5e4359a..22896594443 100644 --- a/doc/development/cicd/schema.md +++ b/doc/development/cicd/schema.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index d0c56fb18bc..85ac58e749d 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -1,13 +1,13 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- # Development guide for GitLab CI/CD templates **(FREE)** -This document explains how to develop [GitLab CI/CD templates](../../ci/examples/index.md). +This document explains how to develop [GitLab CI/CD templates](../../ci/examples/index.md#cicd-templates). ## Requirements for CI/CD templates @@ -391,7 +391,7 @@ This is useful information for reviewers to make sure the template is safe to be ### Make sure the new template can be selected in UI Templates located under some directories are also [selectable in the **New file** UI](#template-directories). -When you add a template into one of those directories, make sure that it correctly appears in the dropdown: +When you add a template into one of those directories, make sure that it correctly appears in the dropdown list:  diff --git a/doc/development/code_comments.md b/doc/development/code_comments.md index b1db781b9ee..306f371f306 100644 --- a/doc/development/code_comments.md +++ b/doc/development/code_comments.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code comments diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index 87697a5e252..f8fb794053d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Intelligence **(FREE)** diff --git a/doc/development/code_review.md b/doc/development/code_review.md index c320540401f..5b745f06d22 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Review Guidelines @@ -57,7 +57,7 @@ We make the following assumption with regards to automatically being considered - Team members working on a specific feature (for example, search) are considered domain experts for that feature. We default to assigning reviews to team members with domain expertise. -When a suitable [domain expert](#domain-experts) isn't available, you can choose any team member to review the MR, or simply follow the [Reviewer roulette](#reviewer-roulette) recommendation. +When a suitable [domain expert](#domain-experts) isn't available, you can choose any team member to review the MR, or follow the [Reviewer roulette](#reviewer-roulette) recommendation. To find a domain expert: @@ -75,9 +75,9 @@ NOTE: Reviewer roulette is an internal tool for use on GitLab.com, and not available for use on customer installations. The [Danger bot](dangerbot.md) randomly picks a reviewer and a maintainer for -each area of the codebase that your merge request seems to touch. It only makes -**recommendations** and you should override it if you think someone else is a better -fit! +each area of the codebase that your merge request seems to touch. It makes +**recommendations** for developer reviewers and you should override it if you think someone else is a better +fit. User-facing changes are required to have a UX review, too. Default to the recommended UX reviewer suggested. It picks reviewers and maintainers from the list at the [engineering projects](https://about.gitlab.com/handbook/engineering/projects/) @@ -149,7 +149,7 @@ with [domain expertise](#domain-experts). | `~UX` user-facing changes (*3*) | [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 (*1*) | - [Frontend foundations member](https://about.gitlab.com/direction/ecosystem/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` changes | [Technical writer](https://about.gitlab.com/handbook/engineering/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://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). | | 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 (*4*) | [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors). | | Only End-to-end changes (*4*) **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). | @@ -208,7 +208,7 @@ See the [test engineering process](https://about.gitlab.com/handbook/engineering 1. I have included changelog trailers, or I have decided that they are not needed. - [Does this MR need a changelog?](changelog.md#what-warrants-a-changelog-entry) 1. I have added/updated documentation or decided that documentation changes are unnecessary for this MR. - - [Is documentation required?](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#when-documentation-is-required) + - [Is documentation required?](https://about.gitlab.com/handbook/product/ux/technical-writing/workflow/#when-documentation-is-required) ##### Security @@ -442,8 +442,7 @@ first time. ### Requesting a review When you are ready to have your merge request reviewed, -you should [request an initial review](../user/project/merge_requests/getting_started.md#reviewer) by selecting a reviewer from your group or team. -However, you can also assign it to any reviewer. The list of reviewers can be found on [Engineering projects](https://about.gitlab.com/handbook/engineering/projects/) page. +you should [request an initial review](../user/project/merge_requests/getting_started.md#reviewer) by selecting a reviewer based on the [approval guidelines](#approval-guidelines). When a merge request has multiple areas for review, it is recommended you specify which area a reviewer should be reviewing, and at which stage (first or second). This will help team members who qualify as a reviewer for multiple areas to know which area they're being requested to review. @@ -662,9 +661,10 @@ Enterprise Edition instance. This has some implications: - Regular migrations run before the new code is running on the instance. - [Post-deployment migrations](database/post_deployment_migrations.md) run _after_ the new code is deployed, when the instance is configured to do that. - - [Background migrations](database/background_migrations.md) run in Sidekiq, and - should only be done for migrations that would take an extreme amount of - time at GitLab.com scale. + - [Batched background migrations](database/batched_background_migrations.md) run in Sidekiq, and + should be used for migrations that + [exceed the post-deployment migration time limit](migration_style_guide.md#how-long-a-migration-should-take) + GitLab.com scale. 1. **Sidekiq workers** [cannot change in a backwards-incompatible way](sidekiq/compatibility_across_updates.md): 1. Sidekiq queues are not drained before a deploy happens, so there are workers in the queue from the previous version of GitLab. diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index 37c3c24a7d1..8aa219d72a1 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -1,7 +1,7 @@ --- stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Community members & roles @@ -12,7 +12,7 @@ GitLab community members and their privileges/responsibilities. |-------|------------------|--------------| | Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/company/team/). An expert on code reviews and knows the product/codebase | | Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/company/team/) | -| Developer |Has access to GitLab internal infrastructure & issues (for example, HR-related) | GitLab employee or a Core Team member (with an NDA) | +| Developer | Has access to GitLab internal infrastructure & issues (for example, HR-related) | GitLab employee or a Core Team member (with an NDA) | | Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | -[List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce). +[List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab). diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 04915985dc8..9e54b92337a 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Design and user interface changes @@ -17,11 +17,15 @@ with additions and improvements. ## Merge request reviews -As a merge request (MR) author, you must include _Before_ and _After_ +As a merge request (MR) author, you must: + +- Include _Before_ and _After_ screenshots (or videos) of your changes in the description, as explained in our [MR workflow](merge_request_workflow.md). These screenshots/videos are very helpful for all reviewers and can speed up the review process, especially if the changes are small. +- Attach the ~UX label to any merge request that impacts the user experience. This will enable Product Designers to [review](https://about.gitlab.com/handbook/engineering/ux/product-designer/mr-reviews/#stage-group-mrs/) any user facing changes. +- Assign the Product Designer suggested by Reviewer Roulette as the reviewer of your merge request. The reviewer does not have to be the domain expert unless this is a community contribution. ## Checklist @@ -35,7 +39,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/helping-users/). -- Request review from the [appropriate Technical Writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments), +- Request review from the [appropriate Technical Writer](https://about.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. @@ -100,7 +104,7 @@ When the design is ready, _before_ starting its implementation: - Share design specifications in the related issue, preferably through a [Figma link](https://help.figma.com/hc/en-us/articles/360040531773-Share-Files-with-anyone-using-Link-Sharing#copy-link) link or [GitLab Designs feature](../../user/project/issues/design_management.md). - See [when you should use each tool](https://about.gitlab.com/handbook/engineering/ux/product-designer/#deliver). + See [when you should use each tool](https://about.gitlab.com/handbook/product/ux/product-designer/#deliver). - Document user flow and states (for example, using [Mermaid flowcharts in Markdown](../../user/markdown.md#mermaid)). - Document animations and transitions. - Document responsive behaviors. diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 2ff51e765a3..cbccd832d78 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Contribute to GitLab @@ -26,11 +26,6 @@ Throughout this guide you will see references to CE and EE for abbreviation. To get an overview of GitLab community membership, including those that would review or merge your contributions, visit [the community roles page](community_roles.md). -If you want to know how the GitLab [core team](https://about.gitlab.com/community/core-team/) -operates, see [the GitLab contributing process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md). - -GitLab Inc engineers should refer to the [engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/). - ## Security vulnerability disclosure Report suspected security vulnerabilities by following the diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index d557319b41f..df337bb2809 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues workflow @@ -373,7 +373,7 @@ below will make it easy to manage this, without unnecessary overhead. which might lead to many hard problems to solve. Changing some text in GitLab is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. 1. If something is very large, it should probably be split up in multiple - issues or chunks. You can simply not set the weight of a parent issue and set + issues or chunks. You can not set the weight of a parent issue and set weights to children issues. ## Regression issues @@ -432,7 +432,7 @@ original merge request - or not tracked at all! The overheads of scheduling, and rate of change in the GitLab codebase, mean that the cost of a trivial technical debt issue can quickly exceed the value of tracking it. This generally means we should resolve these in the original merge -request - or simply not create a follow-up issue at all. +request - or not create a follow-up issue at all. For example, a typo in a comment that is being copied between files is worth fixing in the same MR, but not worth creating a follow-up issue for. Renaming a diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 0e9ac569558..b40df01cbe9 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests workflow @@ -14,7 +14,7 @@ label, but you are free to contribute to any issue you want. If an issue is marked for the current milestone at any time, even when you are working on it, a GitLab Inc. team member may take over the merge request -in order to ensure the work is finished before the release date. +to ensure the work is finished before the release date. If you want to add a new feature that is not labeled, it is best to first create an issue (if there isn't one already) and leave a comment asking for it diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 2e696cf517b..9d04e1590d0 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Style guides @@ -41,13 +41,13 @@ We were using Overcommit prior to Lefthook, so you may want to uninstall it firs bundle exec lefthook install ``` -1. Test Lefthook is working by running the Lefthook `prepare-commit-msg` Git hook: +1. Test Lefthook is working by running the Lefthook `pre-push` Git hook: ```shell - bundle exec lefthook run prepare-commit-msg + bundle exec lefthook run pre-push ``` -This should return a fully qualified path command with no other output. +This should return the lefthook version and the list of executable commands with output. ### Lefthook configuration @@ -153,11 +153,37 @@ to add it to our [GitLab Styles](https://gitlab.com/gitlab-org/gitlab-styles) ge If the Cop targets rules that only apply to the main GitLab application, it should be added to [GitLab](https://gitlab.com/gitlab-org/gitlab) instead. +### Cop grace period + +A cop is in a "grace period" if it is enabled and has `Details: grace period` defined in its TODO YAML configuration. + +On the default branch, all of the offenses from cops in the ["grace period"](../rake_tasks.md#run-rubocop-in-graceful-mode) will not fail the RuboCop CI job. The job will notify Slack in the `#f_rubocop` channel when offenses have been silenced in the scheduled pipeline. However, on merge request pipelines, the RuboCop job will fail. + +A grace period can safely be lifted as soon as there are no warnings for 2 weeks in the `#f_rubocop` channel on Slack. + +### Enabling a new cop + +1. Enable the new cop in `.rubocop.yml` (if not already done via [`gitlab-styles`](https://gitlab.com/gitlab-org/ruby/gems/gitlab-styles)). +1. [Generate TODOs for the new cop](../rake_tasks.md#generate-initial-rubocop-todo-list). +1. [Set the new cop to "grace period"](#cop-grace-period). +1. Create an issue to fix TODOs and encourage Community contributions (via ~"good for new contributors" and/or ~"Seeking community contributions"). [See some examples](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=created_date&state=opened&label_name%5B%5D=good%20for%20new%20contributors&label_name%5B%5D=static%20code%20analysis&first_page_size=20). +1. Create an issue to remove "grace period" after 2 weeks silence in `#f_rubocop` Slack channel. ([See an example](https://gitlab.com/gitlab-org/gitlab/-/issues/374903).) + +### Silenced offenses + +When offenses are silenced for cops in ["grace period"](#cop-grace-period), +the `#f_rubocop` Slack channel receives a notification message every two hours. + +To fix this issue: + +1. Find cops with silenced offenses in the linked CI job. +1. [Generate TODOs](../rake_tasks.md#generate-initial-rubocop-todo-list) for these cops. + #### RuboCop node pattern When creating [node patterns](https://docs.rubocop.org/rubocop-ast/node_pattern.html) to match Ruby's AST, you can use [`scripts/rubocop-parse`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/rubocop-parse) -to display the AST of a Ruby expression, in order to help you create the matcher. +to display the AST of a Ruby expression, to help you create the matcher. See also [!97024](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97024). ### Resolving RuboCop exceptions diff --git a/doc/development/contributing/verify/index.md b/doc/development/contributing/verify/index.md index 09b206d59aa..e94b7583904 100644 --- a/doc/development/contributing/verify/index.md +++ b/doc/development/contributing/verify/index.md @@ -52,7 +52,7 @@ and they serve us and our users well. Some examples of these principles are that - The feedback delivered by GitLab CI/CD and data produced by the platform should be accurate. If a job fails and we notify a user that it was successful, it can have severe negative consequences. -- Feedback needs to be available when a user needs it and data can not disappear unexpectedly when engineers need it. +- Feedback needs to be available when a user needs it and data cannot disappear unexpectedly when engineers need it. - It all doesn't matter if the platform is not secure and we are leaking credentials or secrets. - When a user provides a set of preconditions in a form of CI/CD configuration, the result should be deterministic each time a pipeline runs, because otherwise the platform might not be trustworthy. @@ -62,7 +62,7 @@ are leaking credentials or secrets. ### Measure before you optimize, and make data-informed decisions -It is very difficult to optimize something that you can not measure. How would you +It is very difficult to optimize something that you cannot measure. How would you know if you succeeded, or how significant the success was? If you are working on a performance or reliability improvement, make sure that you measure things before you optimize them. diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index d2b231ebc7c..52503f2d9c8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Danger bot @@ -13,7 +13,7 @@ Danger is a gem that runs in the CI environment, like any other analysis tool. What sets it apart from (for example, RuboCop) is that it's designed to allow you to easily write arbitrary code to test properties of your code or changes. To this end, it provides a set of common helpers and access to information about what -has actually changed in your environment, then simply runs your code! +has actually changed in your environment, then runs your code! If Danger is asking you to change something about your merge request, it's best just to make the change. If you want to learn how Danger works, or make changes 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 4be3296b2bb..1609e00531e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Add a foreign key constraint to an existing column @@ -126,7 +126,7 @@ Validating the foreign key scans the whole table and makes sure that each relati Fortunately, this does not lock the source table (`users`) while running. NOTE: -When using [background migrations](background_migrations.md), foreign key validation should happen in the next GitLab release. +When using [batched background migrations](batched_background_migrations.md), foreign key validation should happen in the next GitLab release. Migration file for validating the foreign key: diff --git a/doc/development/database/adding_database_indexes.md b/doc/development/database/adding_database_indexes.md index 774703bd54f..040c6780316 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Adding Database Indexes diff --git a/doc/development/database/avoiding_downtime_in_migrations.md b/doc/development/database/avoiding_downtime_in_migrations.md index 79c76b351c8..57f5a66a9ee 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Avoiding downtime in migrations @@ -296,7 +296,7 @@ when migrating a column in a large table (for example, `issues`). Background migrations spread the work / load over a longer time period, without slowing down deployments. -For more information, see [the documentation on cleaning up background migrations](background_migrations.md#cleaning-up). +For more information, see [the documentation on cleaning up batched background migrations](batched_background_migrations.md#cleaning-up). ## Adding Indexes diff --git a/doc/development/database/background_migrations.md b/doc/development/database/background_migrations.md index 9b596eb7379..8e6f29b9eb8 100644 --- a/doc/development/database/background_migrations.md +++ b/doc/development/database/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Background migrations @@ -44,7 +44,7 @@ into this category. ## Isolation -Background migrations must be isolated and can not use application code (for example, +Background migrations must be isolated and cannot use application code (for example, models defined in `app/models` except the `ApplicationRecord` classes). Since these migrations can take a long time to run it's possible for new versions to be deployed while they are still running. @@ -86,7 +86,7 @@ migration classes must be defined in the namespace Scheduling a background migration should be done in a post-deployment migration that includes `Gitlab::Database::MigrationHelpers` -To do so, simply use the following code while +To do so, use the following code while replacing the class name and arguments with whatever values are necessary for your migration: @@ -110,7 +110,7 @@ You also need to make sure that newly created data is either migrated, or saved in both the old and new version upon creation. For complex and time consuming migrations it's best to schedule a background job using an `after_create` hook so this doesn't affect response timings. The same applies to -updates. Removals in turn can be handled by simply defining foreign keys with +updates. Removals in turn can be handled by defining foreign keys with cascading deletes. ### Rescheduling background migrations diff --git a/doc/development/database/batched_background_migrations.md b/doc/development/database/batched_background_migrations.md index 192cd0d3e49..a48a9c42e27 100644 --- a/doc/development/database/batched_background_migrations.md +++ b/doc/development/database/batched_background_migrations.md @@ -2,7 +2,7 @@ type: reference, dev stage: Data Stores group: Database -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Batched background migrations @@ -41,7 +41,7 @@ into this category. ## Isolation -Batched background migrations must be isolated and can not use application code (for example, +Batched background migrations must be isolated and cannot use application code (for example, models defined in `app/models` except the `ApplicationRecord` classes). Because these migrations can take a long time to run, it's possible for new versions to deploy while the migrations are still running. @@ -532,6 +532,119 @@ for more details. ## Additional tips and strategies +### ChatOps integration + +The batched background migrations framework has ChatOps support. Using ChatOps, GitLab engineers can interact with the batched background migrations present in the system. + +#### List batched background migrations + +To list the batched background migrations in the system, run this command: + +`/chatops run batched_background_migrations list` + +This command supports the following options: + +- Database selection: + - `--database DATABASE_NAME`: Connects to the given database: + - `main`: Uses the main database (default). + - `ci`: Uses the CI database. +- Environment selection: + - `--dev`: Uses the `dev` environment. + - `--staging`: Uses the `staging` environment. + - `--staging_ref`: Uses the `staging_ref` environment. + - `--production` : Uses the `production` environment (default). + +Output example: + + + +NOTE: +ChatOps returns 20 batched background migrations order by `created_at` (DESC). + +#### Monitor the progress and status of a batched background migration + +To see the status and progress of a specific batched background migration, run this command: + +`/chatops run batched_background_migrations status MIGRATION_ID` + +This command supports the following options: + +- Database selection: + - `--database DATABASE_NAME`: Connects to the given database: + - `main`: Uses the main database (default) + - `ci`: Uses the CI database +- Environment selection: + - `--dev`: Uses the `dev` environment. + - `--staging`: Uses the `staging` environment. + - `--staging_ref`: Uses the `staging_ref` environment. + - `--production` : Uses the `production` environment (default). + +Output example: + + + +`Progress` represents the percentage of the background migration that has been completed. + +Definitions of the batched background migration states: + +- **Active:** Either: + - Ready to be picked by the runner. + - Running batched jobs. +- **Finalizing:** Running batched jobs. +- **Failed:** Failed batched background migration. +- **Finished:** Completed batched background migration. +- **Paused:** Not visible to the runner. + +#### Pause a batched background migration + +If you want to pause a batched background migration, you need to run the following command: + +`/chatops run batched_background_migrations pause MIGRATION_ID` + +This command supports the following options: + +- Database selection: + - `--database DATABASE_NAME`: Connects to the given database: + - `main`: Uses the main database (default). + - `ci`: Uses the CI database. +- Environment selection: + - `--dev`: Uses the `dev` environment. + - `--staging`: Uses the `staging` environment. + - `--staging_ref`: Uses the `staging_ref` environment. + - `--production` : Uses the `production` environment (default). + +Output example: + + + +NOTE: +You can pause only `active` batched background migrations. + +#### Resume a batched background migration + +If you want to resume a batched background migration, you need to run the following command: + +`/chatops run batched_background_migrations resume MIGRATION_ID` + +This command supports the following options: + +- Database selection: + - `--database DATABASE_NAME`: Connects to the given database: + - `main`: Uses the main database (default). + - `ci`: Uses the CI database. +- Environment selection: + - `--dev`: Uses the `dev` environment. + - `--staging`: Uses the `staging` environment. + - `--staging_ref`: Uses the `staging_ref` environment. + - `--production` : Uses the `production` environment (default). + +Output example: + + + +NOTE: +You can resume only `active` batched background migrations + ### Viewing failure error logs You can view failures in two ways: @@ -565,3 +678,8 @@ You can view failures in two ways: ON transition_logs.batched_background_migration_job_id = jobs.id WHERE transition_logs.next_status = '2' AND migration.job_class_name = "CLASS_NAME"; ``` + +## Legacy background migrations + +Batched background migrations replaced the [legacy background migrations framework](background_migrations.md). +Check that documentation in reference to any changes involving that framework. diff --git a/doc/development/database/ci_mirrored_tables.md b/doc/development/database/ci_mirrored_tables.md index 1d285e607fa..bf3a744b936 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI mirrored tables diff --git a/doc/development/database/client_side_connection_pool.md b/doc/development/database/client_side_connection_pool.md index 3143391a553..3c9f8e76d89 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Client-side connection-pool diff --git a/doc/development/database/constraint_naming_convention.md b/doc/development/database/constraint_naming_convention.md index 2f0b8bf0463..e9e130495e6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Constraints naming conventions diff --git a/doc/development/database/creating_enums.md b/doc/development/database/creating_enums.md index 450cb97d978..73c3f546728 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Creating enums @@ -103,7 +103,7 @@ This looks working as a workaround, however, this approach has some downsides th Therefore, you need to be careful of that the offset doesn't exceed the maximum value of 2 bytes integer. As a conclusion, you should define all of the key/value pairs in FOSS. -For example, you can simply write the following code in the above case: +For example, you can write the following code in the above case: ```ruby class Pipeline < ApplicationRecord diff --git a/doc/development/database/database_debugging.md b/doc/development/database/database_debugging.md index 591e526cc96..4dc6a3bdcfa 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/engineering/ux/technical-writing/#assignments +info: To 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 and debugging the database diff --git a/doc/development/database/database_dictionary.md b/doc/development/database/database_dictionary.md index c330c5e67bd..bd6dbc54316 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database Dictionary diff --git a/doc/development/database/database_lab.md b/doc/development/database/database_lab.md index 1d584a4ec6f..b60091fa37c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database Lab and Postgres.ai diff --git a/doc/development/database/database_migration_pipeline.md b/doc/development/database/database_migration_pipeline.md index 496bd09bf1d..148dc1e94a0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database migration pipeline diff --git a/doc/development/database/database_query_comments.md b/doc/development/database/database_query_comments.md index 2798071bc06..946947db502 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database query comments with Marginalia diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index a85f399a447..aa92134018d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database Reviewer Guidelines diff --git a/doc/development/database/db_dump.md b/doc/development/database/db_dump.md index f2076cbc410..b09c601537c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 49f8b183272..4ebfb40cd03 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # db:check-migrations job diff --git a/doc/development/database/deleting_migrations.md b/doc/development/database/deleting_migrations.md index 8354cb62d0c..bd03e6c11ae 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Delete existing migrations diff --git a/doc/development/database/efficient_in_operator_queries.md b/doc/development/database/efficient_in_operator_queries.md index a2481577e8c..fb7ff3c1cc2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Efficient `IN` operator queries @@ -670,6 +670,64 @@ records_by_id.each do |id, _| end ``` +#### Ordering by `JOIN` columns + +Ordering records by mixed columns where one or more columns are coming from `JOIN` tables +works with limitations. It requires extra configuration (CTE). The trick is to use a +non-materialized CTE to act as a "fake" table which exposes all required columns. + +NOTE: +The query performance might not improve compared to the standard `IN` query. Always +check the query plan. + +Example: order issues by `projects.name, issues.id` within the group hierarchy + +The first step is to create a CTE, where all required columns are collected in the `SELECT` +clause. + +```ruby +cte_query = Issue + .select('issues.id AS id', 'issues.project_id AS project_id', 'projects.name AS projects_name') + .joins(:project) + +cte = Gitlab::SQL::CTE.new(:issue_with_projects, cte_query, materialized: false) +``` + +Custom order object configuration: + +```ruby +order = Gitlab::Pagination::Keyset::Order.build([ + Gitlab::Pagination::Keyset::ColumnOrderDefinition.new( + attribute_name: 'projects_name', + order_expression: Issue.arel_table[:projects_name].asc, + sql_type: 'character varying', + nullable: :nulls_last, + distinct: false + ), + Gitlab::Pagination::Keyset::ColumnOrderDefinition.new( + attribute_name: :id, + order_expression: Issue.arel_table[:id].asc + ) + ]) +``` + +Generate the query: + +```ruby +scope = cte.apply_to(Issue.where({}).reorder(order)) + +opts = { + scope: scope, + array_scope: Project.where(namespace_id: top_level_group.self_and_descendants.select(:id)).select(:id), + array_mapping_scope: -> (id_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)) } +} + +records = Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder + .new(**opts) + .execute + .limit(20) +``` + #### Batch iteration Batch iteration over the records is possible via the keyset `Iterator` class. @@ -1052,6 +1110,6 @@ Performance comparison for the `gitlab-org` group: | Optimized `IN` query | 9783 | 450ms | 22ms | NOTE: -Before taking measurements, the group lookup query was executed separately in order to make +Before taking measurements, the group lookup query was executed separately to make the group data available in the buffer cache. Since it's a frequently called query, it hits many shared buffers during the query execution in the production environment. diff --git a/doc/development/database/filtering_by_label.md b/doc/development/database/filtering_by_label.md index 29b0c75298e..a30322176ba 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Filtering by label diff --git a/doc/development/database/foreign_keys.md b/doc/development/database/foreign_keys.md index 7834e7d53c3..d9506ae614a 100644 --- a/doc/development/database/foreign_keys.md +++ b/doc/development/database/foreign_keys.md @@ -1,10 +1,10 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Foreign Keys & Associations +# Foreign keys and associations When adding an association to a model you must also add a foreign key. For example, say you have the following model: @@ -20,7 +20,7 @@ that data consistency is enforced on database level. Foreign keys also mean that the database can very quickly remove associated data (for example, when removing a user), instead of Rails having to do this. -## Adding Foreign Keys In Migrations +## Adding foreign keys in migrations Foreign keys can be added concurrently using `add_concurrent_foreign_key` as defined in `Gitlab::Database::MigrationHelpers`. See the @@ -31,7 +31,7 @@ you have removed any orphaned rows. The method `add_concurrent_foreign_key` does not take care of this so you must do so manually. See [adding foreign key constraint to an existing column](add_foreign_key_to_existing_column.md). -## Updating Foreign Keys In Migrations +## Updating foreign keys in migrations Sometimes a foreign key constraint must be changed, preserving the column but updating the constraint condition. For example, moving from @@ -45,64 +45,64 @@ To replace a foreign key: 1. [Add the new foreign key without validation](add_foreign_key_to_existing_column.md#prevent-invalid-records) - The name of the foreign key constraint must be changed to add a new - foreign key before removing the old one. + The name of the foreign key constraint must be changed to add a new + foreign key before removing the old one. - ```ruby - class ReplaceFkOnPackagesPackagesProjectId < Gitlab::Database::Migration[2.0] - disable_ddl_transaction! + ```ruby + class ReplaceFkOnPackagesPackagesProjectId < Gitlab::Database::Migration[2.0] + disable_ddl_transaction! - NEW_CONSTRAINT_NAME = 'fk_new' + NEW_CONSTRAINT_NAME = 'fk_new' - def up - add_concurrent_foreign_key(:packages_packages, :projects, column: :project_id, on_delete: :nullify, validate: false, name: NEW_CONSTRAINT_NAME) - end + def up + add_concurrent_foreign_key(:packages_packages, :projects, column: :project_id, on_delete: :nullify, validate: false, name: NEW_CONSTRAINT_NAME) + end - def down - with_lock_retries do - remove_foreign_key_if_exists(:packages_packages, column: :project_id, on_delete: :nullify, name: NEW_CONSTRAINT_NAME) - end - end - end - ``` + def down + with_lock_retries do + remove_foreign_key_if_exists(:packages_packages, column: :project_id, on_delete: :nullify, name: NEW_CONSTRAINT_NAME) + end + end + end + ``` 1. [Validate the new foreign key](add_foreign_key_to_existing_column.md#validate-the-foreign-key) - ```ruby - class ValidateFkNew < Gitlab::Database::Migration[2.0] - NEW_CONSTRAINT_NAME = 'fk_new' + ```ruby + class ValidateFkNew < Gitlab::Database::Migration[2.0] + NEW_CONSTRAINT_NAME = 'fk_new' - # foreign key added in <link to MR or path to migration adding new FK> - def up - validate_foreign_key(:packages_packages, name: NEW_CONSTRAINT_NAME) - end + # foreign key added in <link to MR or path to migration adding new FK> + def up + validate_foreign_key(:packages_packages, name: NEW_CONSTRAINT_NAME) + end - def down - # no-op - end - end - ``` + def down + # no-op + end + end + ``` 1. Remove the old foreign key: - ```ruby - class RemoveFkOld < Gitlab::Database::Migration[2.0] - OLD_CONSTRAINT_NAME = 'fk_old' + ```ruby + class RemoveFkOld < Gitlab::Database::Migration[2.0] + OLD_CONSTRAINT_NAME = 'fk_old' - # new foreign key added in <link to MR or path to migration adding new FK> - # and validated in <link to MR or path to migration validating new FK> - def up - remove_foreign_key_if_exists(:packages_packages, column: :project_id, on_delete: :cascade, name: OLD_CONSTRAINT_NAME) - end + # new foreign key added in <link to MR or path to migration adding new FK> + # and validated in <link to MR or path to migration validating new FK> + def up + remove_foreign_key_if_exists(:packages_packages, column: :project_id, on_delete: :cascade, name: OLD_CONSTRAINT_NAME) + end - def down - # Validation is skipped here, so if rolled back, this will need to be revalidated in a separate migration - add_concurrent_foreign_key(:packages_packages, :projects, column: :project_id, on_delete: :cascade, validate: false, name: OLD_CONSTRAINT_NAME) - end - end - ``` + def down + # Validation is skipped here, so if rolled back, this will need to be revalidated in a separate migration + add_concurrent_foreign_key(:packages_packages, :projects, column: :project_id, on_delete: :cascade, validate: false, name: OLD_CONSTRAINT_NAME) + end + end + ``` -## Cascading Deletes +## Cascading deletes Every foreign key must define an `ON DELETE` clause, and in 99% of the cases this should be set to `CASCADE`. @@ -124,7 +124,7 @@ have a foreign key constraint. So if that spec fails, don't add the column to `IGNORED_FK_COLUMNS`, but instead add the FK constraint, or consider naming it differently. -## Dependent Removals +## Dependent removals Don't define options such as `dependent: :destroy` or `dependent: :delete` when defining an association. Defining these options means Rails handles the @@ -182,9 +182,9 @@ create_table :user_configs, id: false do |t| end ``` -Setting `default: nil` ensures a primary key sequence is not created, and since the primary key +Setting `default: nil` ensures a primary key sequence is not created, and because the primary key automatically gets an index, we set `index: false` to avoid creating a duplicate. -You also need to add the new primary key to the model: +You must also add the new primary key to the model: ```ruby class UserConfig < ActiveRecord::Base diff --git a/doc/development/database/hash_indexes.md b/doc/development/database/hash_indexes.md index 731639b6f06..aba23dbea70 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Hash Indexes diff --git a/doc/development/database/img/list_v15_4.png b/doc/development/database/img/list_v15_4.png Binary files differnew file mode 100644 index 00000000000..f5c478321c1 --- /dev/null +++ b/doc/development/database/img/list_v15_4.png diff --git a/doc/development/database/img/pause_v15_4.png b/doc/development/database/img/pause_v15_4.png Binary files differnew file mode 100644 index 00000000000..744a2f13243 --- /dev/null +++ b/doc/development/database/img/pause_v15_4.png diff --git a/doc/development/database/img/resume_v15_4.png b/doc/development/database/img/resume_v15_4.png Binary files differnew file mode 100644 index 00000000000..919fd337595 --- /dev/null +++ b/doc/development/database/img/resume_v15_4.png diff --git a/doc/development/database/img/status_v15_4.png b/doc/development/database/img/status_v15_4.png Binary files differnew file mode 100644 index 00000000000..01396649094 --- /dev/null +++ b/doc/development/database/img/status_v15_4.png diff --git a/doc/development/database/index.md b/doc/development/database/index.md index 8cf9a2eec04..87b1b4a9d87 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database guides @@ -26,7 +26,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [Different types of migrations](../migration_style_guide.md#choose-an-appropriate-migration-type) - [Create a regular migration](../migration_style_guide.md#create-a-regular-schema-migration), including creating new models - [Post-deployment migrations guidelines](post_deployment_migrations.md) and [how to create one](post_deployment_migrations.md#creating-migrations) -- [Background migrations guidelines](background_migrations.md) +- [Legacy Background migrations guidelines](background_migrations.md) - [Batched background migrations guidelines](batched_background_migrations.md) - [Deleting migrations](deleting_migrations.md) - [Running database migrations](database_debugging.md#migration-wrangling) @@ -36,7 +36,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [Migrations style guide](../migration_style_guide.md) for creating safe SQL migrations - [Testing Rails migrations](../testing_guide/testing_migrations_guide.md) guide - [Post deployment migrations](post_deployment_migrations.md) -- [Background migrations](background_migrations.md) - [Swapping tables](swapping_tables.md) - [Deleting migrations](deleting_migrations.md) - [SQL guidelines](../sql.md) for working with SQL queries diff --git a/doc/development/database/insert_into_tables_in_batches.md b/doc/development/database/insert_into_tables_in_batches.md index ebed3d16319..78aa793f28b 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/engineering/ux/technical-writing/#assignments +info: To 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: "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 @@ -181,7 +181,7 @@ end ``` You can still save relations that are not `BulkInsertSafe` in this block; they -simply are treated as if you had invoked `save` from outside the block. +are treated as if you had invoked `save` from outside the block. ## Known limitations diff --git a/doc/development/database/iterating_tables_in_batches.md b/doc/development/database/iterating_tables_in_batches.md index 6d7a57ecacb..6357bed8b00 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Iterating tables in batches @@ -114,7 +114,7 @@ falling into an endless loop as described in following When dealing with data migrations the preferred way to iterate over a large volume of data is using `EachBatch`. -A special case of data migration is a [background migration](background_migrations.md#scheduling) +A special case of data migration is a [batched background migration](batched_background_migrations.md) where the actual data modification is executed in a background job. The migration code that determines the data ranges (slices) and schedules the background jobs uses `each_batch`. @@ -196,7 +196,7 @@ value is "excluded". The query looks at the index to get the location of the fiv rows on the disk and read the rows from the table. The returned array is processed in Ruby. The first iteration is done. For the next iteration, the last `id` value is reused from the -previous iteration in order to find out the next end `id` value. +previous iteration to find out the next end `id` value. ```sql SELECT "users"."id" FROM "users" WHERE "users"."id" >= 302 ORDER BY "users"."id" ASC LIMIT 1 OFFSET 5 diff --git a/doc/development/database/keyset_pagination.md b/doc/development/database/keyset_pagination.md index 4aec64b8cce..21bce41012e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Keyset pagination diff --git a/doc/development/database/layout_and_access_patterns.md b/doc/development/database/layout_and_access_patterns.md index 99a50b503aa..06ac24c284c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Best practices for data layout and access patterns diff --git a/doc/development/database/loose_foreign_keys.md b/doc/development/database/loose_foreign_keys.md index 0af12939629..abf66368548 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Loose foreign keys @@ -311,7 +311,7 @@ end The "`it has loose foreign keys`" shared example can be used to test the presence of the `ON DELETE` trigger and the loose foreign key definitions. -Simply add to the model test file: +Add to the model test file: ```ruby it_behaves_like 'it has loose foreign keys' do diff --git a/doc/development/database/maintenance_operations.md b/doc/development/database/maintenance_operations.md index 85df185c024..bfe18068aab 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maintenance operations diff --git a/doc/development/database/migrations_for_multiple_databases.md b/doc/development/database/migrations_for_multiple_databases.md index df9607f5672..b4d2656121b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrations for Multiple databases diff --git a/doc/development/database/multiple_databases.md b/doc/development/database/multiple_databases.md index 034a2c2e438..e5b6cfb8866 100644 --- a/doc/development/database/multiple_databases.md +++ b/doc/development/database/multiple_databases.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Pods -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple Databases diff --git a/doc/development/database/namespaces_storage_statistics.md b/doc/development/database/namespaces_storage_statistics.md index 702129b9ddb..c653cfb145d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database case study: Namespaces storage statistics diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md index cd2adc3ca28..dccaff2df00 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # `NOT NULL` constraints @@ -93,7 +93,7 @@ We only want to enforce the `NOT NULL` constraint without setting a default, as that all epics should have a user-generated description. After checking our production database, we know that there are `epics` with `NULL` descriptions, -so we can not add and validate the constraint in one step. +so we cannot add and validate the constraint in one step. NOTE: Even if we did not have any epic with a `NULL` description, another instance of GitLab could have @@ -202,7 +202,7 @@ end If you have to clean up a nullable column for a [high-traffic table](../migration_style_guide.md#high-traffic-tables) (for example, the `artifacts` in `ci_builds`), your background migration goes on for a while and -it needs an additional [background migration cleaning up](background_migrations.md#cleaning-up) +it needs an additional [batched background migration cleaning up](batched_background_migrations.md#cleaning-up) in the release after adding the data migration. In that rare case you need 3 releases end-to-end: diff --git a/doc/development/database/ordering_table_columns.md b/doc/development/database/ordering_table_columns.md index a16df6a4499..286313fb3ce 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Ordering Table Columns in PostgreSQL diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md index fe2e3b46939..54b315b9dd9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pagination guidelines @@ -50,9 +50,9 @@ When we list records on the page we often provide additional filters and differe For the MVC version, consider the following: - Reduce the number of sort options to the minimum. -- Reduce the number of filters (dropdown, search bar) to the minimum. +- Reduce the number of filters (dropdown list, search bar) to the minimum. -To make sorting and pagination efficient, for each sort option we need at least two database indexes (ascending, descending order). If we add filter options (by state or by author), we might need more indexes to maintain good performance. Note that indexes are not free, they can significantly affect the `UPDATE` query timings. +To make sorting and pagination efficient, for each sort option we need at least two database indexes (ascending, descending order). If we add filter options (by state or by author), we might need more indexes to maintain good performance. Indexes are not free, they can significantly affect the `UPDATE` query timings. It's not possible to make all filter and sort combinations performant, so we should try optimizing the performance by usage patterns. @@ -154,7 +154,7 @@ Here we're leveraging the ordered property of the b-tree database index. Values ##### `COUNT(*)` on a large dataset -Kaminari by default executes a count query to determine the number of pages for rendering the page links. Count queries can be quite expensive for a large table. In an unfortunate scenario the queries simply time out. +Kaminari by default executes a count query to determine the number of pages for rendering the page links. Count queries can be quite expensive for a large table. In an unfortunate scenario the queries time out. To work around this, we can run Kaminari without invoking the count SQL query. @@ -264,7 +264,7 @@ Looking at the query execution plan, we can see that this query read only 5 rows ##### No page numbers -Offset pagination provides an easy way to request a specific page. We can simply edit the URL and modify the `page=` URL parameter. Keyset pagination cannot provide page numbers because the paging logic might depend on different columns. +Offset pagination provides an easy way to request a specific page. We can edit the URL and modify the `page=` URL parameter. Keyset pagination cannot provide page numbers because the paging logic might depend on different columns. In the previous example, the column is the `id`, so we might see something like this in the `URL`: diff --git a/doc/development/database/pagination_performance_guidelines.md b/doc/development/database/pagination_performance_guidelines.md index 0fef246f133..0f98b50d95c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pagination performance guidelines diff --git a/doc/development/database/polymorphic_associations.md b/doc/development/database/polymorphic_associations.md index ac4dc7720a5..f3c9bf1276f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Polymorphic Associations diff --git a/doc/development/database/post_deployment_migrations.md b/doc/development/database/post_deployment_migrations.md index 8166fcc8905..0d0047531f9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Post Deployment Migrations diff --git a/doc/development/database/query_count_limits.md b/doc/development/database/query_count_limits.md index a888bbfc6e7..b5fd4395b36 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Query Count Limits diff --git a/doc/development/database/query_performance.md b/doc/development/database/query_performance.md index 41dbd08d726..61fd80338fe 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Query performance guidelines diff --git a/doc/development/database/query_recorder.md b/doc/development/database/query_recorder.md index da5c6c8e6cb..3fc38c10d68 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # QueryRecorder diff --git a/doc/development/database/rename_database_tables.md b/doc/development/database/rename_database_tables.md index d6827cb9e03..641bba1f131 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rename table without downtime diff --git a/doc/development/database/serializing_data.md b/doc/development/database/serializing_data.md index 97e6f665484..b25c8d49b64 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Serializing Data diff --git a/doc/development/database/setting_multiple_values.md b/doc/development/database/setting_multiple_values.md index cba15a73430..fb85386785d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Update multiple database objects diff --git a/doc/development/database/sha1_as_binary.md b/doc/development/database/sha1_as_binary.md index dab9b0fe72e..5ad9d106086 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Storing SHA1 Hashes As Binary diff --git a/doc/development/database/single_table_inheritance.md b/doc/development/database/single_table_inheritance.md index c8d082e8a67..ad0101e1594 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Single Table Inheritance 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 4b5d1fc8f72..fb005e51902 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Strings and the Text data type @@ -15,7 +15,7 @@ When adding new columns to store strings or other textual information: the `#text ... limit: 100` helper (see below) when creating a table, or by using the `add_text_limit` when altering an existing table. -The standard Rails `text` column type can not be defined with a limit, but we extend `create_table` to +The standard Rails `text` column type cannot be defined with a limit, but we extend `create_table` to add a `limit: 255` option. Outside of `create_table`, `add_text_limit` can be used to add a [check constraint](https://www.postgresql.org/docs/11/ddl-constraints.html) to an already existing column. @@ -50,7 +50,7 @@ For example, consider a migration that creates a table with two text columns, `db/migrate/20200401000001_create_db_guides.rb`: ```ruby -class CreateDbGuides < Gitlab::Database::Migration[1.0] +class CreateDbGuides < Gitlab::Database::Migration[2.0] def change create_table :db_guides do |t| t.bigint :stars, default: 0, null: false @@ -74,7 +74,7 @@ For example, consider a migration that adds a new text column `extended_title` t `db/migrate/20200501000001_add_extended_title_to_sprints.rb`: ```ruby -class AddExtendedTitleToSprints < Gitlab::Database::Migration[1.0] +class AddExtendedTitleToSprints < Gitlab::Database::Migration[2.0] # rubocop:disable Migration/AddLimitToTextColumns # limit is added in 20200501000002_add_text_limit_to_sprints_extended_title @@ -89,7 +89,7 @@ A second migration should follow the first one with a limit added to `extended_t `db/migrate/20200501000002_add_text_limit_to_sprints_extended_title.rb`: ```ruby -class AddTextLimitToSprintsExtendedTitle < Gitlab::Database::Migration[1.0] +class AddTextLimitToSprintsExtendedTitle < Gitlab::Database::Migration[2.0] disable_ddl_transaction! def up @@ -131,7 +131,7 @@ Issues is a pretty busy and large table with more than 25 million rows, so we do other processes that try to access it while running the update. Also, after checking our production database, we know that there are `issues` with more characters in -their title than the 1024 character limit, so we can not add and validate the constraint in one step. +their title than the 1024 character limit, so we cannot add and validate the constraint in one step. NOTE: Even if we did not have any record with a title larger than the provided limit, another @@ -165,7 +165,7 @@ in a post-deployment migration, `db/post_migrate/20200501000001_add_text_limit_migration.rb`: ```ruby -class AddTextLimitMigration < Gitlab::Database::Migration[1.0] +class AddTextLimitMigration < Gitlab::Database::Migration[2.0] disable_ddl_transaction! def up @@ -196,7 +196,7 @@ to add a background migration for the 13.0 milestone (current), `db/post_migrate/20200501000002_schedule_cap_title_length_on_issues.rb`: ```ruby -class ScheduleCapTitleLengthOnIssues < Gitlab::Database::Migration[1.0] +class ScheduleCapTitleLengthOnIssues < Gitlab::Database::Migration[2.0] # Info on how many records will be affected on GitLab.com # time each batch needs to run on average, etc ... BATCH_SIZE = 5000 @@ -207,30 +207,25 @@ class ScheduleCapTitleLengthOnIssues < Gitlab::Database::Migration[1.0] disable_ddl_transaction! - class Issue < ::ApplicationRecord - include EachBatch - - self.table_name = 'issues' - end - def up - queue_background_migration_jobs_by_range_at_intervals( - Issue.where('char_length(title_html) > 1024'), - ISSUES_MIGRATION, - DELAY_INTERVAL, + queue_batched_background_migration( + ISSUES_BACKGROUND_MIGRATION, + :issues, + :id, + job_interval: DELAY_INTERVAL, batch_size: BATCH_SIZE ) end def down - # no-op : the part of the title_html after the limit is lost forever + delete_batched_background_migration(ISSUES_BACKGROUND_MIGRATION, :issues, :id, []) end end ``` To keep this guide short, we skipped the definition of the background migration and only provided a high level example of the post-deployment migration that is used to schedule the batches. -You can find more information on the guide about [background migrations](background_migrations.md) +You can find more information on the guide about [batched background migrations](batched_background_migrations.md) #### Validate the text limit (next release) @@ -241,7 +236,7 @@ helper in a final post-deployment migration, `db/post_migrate/20200601000001_validate_text_limit_migration.rb`: ```ruby -class ValidateTextLimitMigration < Gitlab::Database::Migration[1.0] +class ValidateTextLimitMigration < Gitlab::Database::Migration[2.0] disable_ddl_transaction! def up @@ -260,7 +255,7 @@ Increasing text limits on existing database columns can be safely achieved by fi and then dropping the previous limit: ```ruby -class ChangeMaintainerNoteLimitInCiRunner < Gitlab::Database::Migration[1.0] +class ChangeMaintainerNoteLimitInCiRunner < Gitlab::Database::Migration[2.0] disable_ddl_transaction! def up @@ -278,7 +273,7 @@ end If you have to clean up a text column for a really [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3) (for example, the `artifacts` in `ci_builds`), your background migration goes on for a while and -it needs an additional [background migration cleaning up](background_migrations.md#cleaning-up) +it needs an additional [batched background migration cleaning up](batched_background_migrations.md#cleaning-up) in the release after adding the data migration. In that rare case you need 3 releases end-to-end: diff --git a/doc/development/database/swapping_tables.md b/doc/development/database/swapping_tables.md index efb481ccf35..f659d1408d3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Swapping Tables diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md index 582c988bef9..bf12329473d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database table partitioning @@ -142,7 +142,7 @@ substantial. Partitioning should only be leveraged if the access patterns of the data support the partitioning strategy, otherwise performance suffers. -## Partitioning a table +## Partitioning a table (Range) Unfortunately, tables can only be partitioned at their creation, making it nontrivial to apply to a busy database. A suite of migration @@ -256,3 +256,217 @@ The final step of the migration makes the partitioned table ready for use by the application. This section will be updated when the migration helper is ready, for now development can be followed in the [Tracking Issue](https://gitlab.com/gitlab-org/gitlab/-/issues/241267). + +## Partitioning a table (List) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96815) in GitLab 15.4. + +Add the partitioning key column to the table you are partitioning. +Include the partitioning key in the following constraints: + +- The primary key. +- All foreign keys referencing the table to be partitioned. +- All unique constraints. + +### Step 1 - Add partition key + +Add the partitioning key column. For example, in a rails migration: + +```ruby +class AddPartitionNumberForPartitioning < Gitlab::Database::Migration[2.0] + enable_lock_retries! + + TABLE_NAME = :table_name + COLUMN_NAME = :partition_id + DEFAULT_VALUE = 100 + + def change + add_column(TABLE_NAME, COLUMN_NAME, :bigint, default: 100) + end +end +``` + +### Step 2 - Create required indexes + +Add indexes including the partitioning key column. For example, in a rails migration: + +```ruby +class PrepareIndexesForPartitioning < Gitlab::Database::Migration[2.0] + disable_ddl_transaction! + + TABLE_NAME = :table_name + INDEX_NAME = :index_name + + def up + add_concurrent_index(TABLE_NAME, [:id, :partition_id], unique: true, name: INDEX_NAME) + end + + def down + remove_concurrent_index_by_name(TABLE_NAME, INDEX_NAME) + end +end +``` + +### Step 3 - Swap primary key + +Swap the primary key including the partitioning key column. For example, in a rails migration: + +```ruby +class PreparePrimaryKeyForPartitioning < Gitlab::Database::Migration[2.0] + disable_ddl_transaction! + + TABLE_NAME = :table_name + PRIMARY_KEY = :primary_key + OLD_INDEX_NAME = :old_index_name + NEW_INDEX_NAME = :new_index_name + + def up + swap_primary_key(TABLE_NAME, PRIMARY_KEY, NEW_INDEX_NAME) + end + + def down + add_concurrent_index(TABLE_NAME, :id, unique: true, name: OLD_INDEX_NAME) + add_concurrent_index(TABLE_NAME, [:id, :partition_id], unique: true, name: NEW_INDEX_NAME) + + unswap_primary_key(TABLE_NAME, PRIMARY_KEY, OLD_INDEX_NAME) + end +end +``` + +NOTE: +Do not forget to set the primary key explicitly in your model as `ActiveRecord` does not support composite primary keys. + +```ruby +class Model < ApplicationRecord + self.primary_key = :id +end +``` + +### Step 4 - Enforce unique constraint + +Enforce unique indexes including the partitioning key column. For example, in a rails migration: + +```ruby +class PrepareUniqueContraintForPartitioning < Gitlab::Database::Migration[2.0] + disable_ddl_transaction! + + TABLE_NAME = :table_name + OLD_UNIQUE_INDEX_NAME = :index_name_unique + NEW_UNIQUE_INDEX_NAME = :new_index_name + + def up + add_concurrent_index(TABLE_NAME, [:some_column, :partition_id], unique: true, name: NEW_UNIQUE_INDEX_NAME) + + remove_concurrent_index_by_name(TABLE_NAME, OLD_UNIQUE_INDEX_NAME) + end + + def down + add_concurrent_index(TABLE_NAME, :some_column, unique: true, name: OLD_UNIQUE_INDEX_NAME) + + remove_concurrent_index_by_name(TABLE_NAME, NEW_UNIQUE_INDEX_NAME) + end +end +``` + +### Step 5 - Enforce foreign key constraint + +Enforce foreign keys including the partitioning key column. For example, in a rails migration: + +```ruby +class PrepareForeignKeyForPartitioning < Gitlab::Database::Migration[2.0] + disable_ddl_transaction! + + SOURCE_TABLE_NAME = :source_table_name + TARGET_TABLE_NAME = :target_table_name + COLUMN = :foreign_key_id + TARGET_COLUMN = :id + CONSTRAINT_NAME = :fk_365d1db505_p + PARTITION_COLUMN = :partition_id + + def up + add_concurrent_foreign_key( + SOURCE_TABLE_NAME, + TARGET_TABLE_NAME, + column: [PARTITION_COLUMN, COLUMN], + target_column: [PARTITION_COLUMN, TARGET_COLUMN], + validate: false + name: CONSTRAINT_NAME + ) + + validate_foreign_key(TARGET_TABLE_NAME, CONSTRAINT_NAME) + end + + def down + drop_constraint(TARGET_TABLE_NAME, CONSTRAINT_NAME) + end +end +``` + +### Step 6 - Create parent table and attach existing table as the initial partition + +You can now create the parent table attaching the existing table as the initial +partition by using the following helpers provided by the database team. + +For example, using list partitioning in Rails post migrations: + +```ruby +class PrepareTableConstraintsForListPartitioning < Gitlab::Database::Migration[2.0] + include Gitlab::Database::PartitioningMigrationHelpers::TableManagementHelpers + + disable_ddl_transaction! + + TABLE_NAME = :table_name + PARENT_TABLE_NAME = :p_table_name + FIRST_PARTITION = 100 + PARTITION_COLUMN = :partition_id + + def up + prepare_constraint_for_list_partitioning( + table_name: TABLE_NAME, + partitioning_column: PARTITION_COLUMN, + parent_table_name: PARENT_TABLE_NAME, + initial_partitioning_value: FIRST_PARTITION + ) + end + + def down + revert_preparing_constraint_for_list_partitioning( + table_name: TABLE_NAME, + partitioning_column: PARTITION_COLUMN, + parent_table_name: PARENT_TABLE_NAME, + initial_partitioning_value: FIRST_PARTITION + ) + end +end +``` + +```ruby +class ConvertTableToListPartitioning < Gitlab::Database::Migration[2.0] + include Gitlab::Database::PartitioningMigrationHelpers::TableManagementHelpers + + disable_ddl_transaction! + + TABLE_NAME = :table_name + PARENT_TABLE_NAME = :p_table_name + FIRST_PARTITION = 100 + PARTITION_COLUMN = :partition_id + + def up + convert_table_to_first_list_partition( + table_name: TABLE_NAME, + partitioning_column: PARTITION_COLUMN, + parent_table_name: PARENT_TABLE_NAME, + initial_partitioning_value: FIRST_PARTITION + ) + end + + def down + revert_converting_table_to_first_list_partition( + table_name: TABLE_NAME, + partitioning_column: PARTITION_COLUMN, + parent_table_name: PARENT_TABLE_NAME, + initial_partitioning_value: FIRST_PARTITION + ) + end +end +``` diff --git a/doc/development/database/transaction_guidelines.md b/doc/development/database/transaction_guidelines.md index 1583bbc02c2..26bb6c2ce8f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Transaction guidelines @@ -139,5 +139,5 @@ end ``` The `ApplicationRecord` class uses a different database connection than the `Ci::Build` records. -The two statements in the transaction block are not part of the transaction and are -rolled back in case something goes wrong. They act as 3rd part calls. +The two statements in the transaction block are not part of the transaction and are not +rolled back in case something goes wrong. They act as third-party calls. diff --git a/doc/development/database/understanding_explain_plans.md b/doc/development/database/understanding_explain_plans.md index c3cb408b35f..fff9d755e9a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Understanding EXPLAIN plans @@ -546,7 +546,7 @@ improve this query, other than _not_ running it at all. What is important here is that while some may recommend to straight up add an index the moment you see a sequential scan, it is _much more important_ to first understand what your query does, how much data it retrieves, and so on. After -all, you can not optimize something you do not understand. +all, you cannot optimize something you do not understand. ### Cardinality and selectivity @@ -719,7 +719,7 @@ and through its [web interface](https://console.postgres.ai/gitlab/joe-instances With Joe Bot you can execute DDL statements (like creating indexes, tables, and columns) and get query plans for `SELECT`, `UPDATE`, and `DELETE` statements. -For example, in order to test new index on a column that is not existing on production yet, you can do the following: +For example, to test new index on a column that is not existing on production yet, you can do the following: Create the column: diff --git a/doc/development/database/verifying_database_capabilities.md b/doc/development/database/verifying_database_capabilities.md index 55347edf4ec..c1dd29082ba 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Verifying Database Capabilities diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 14d73437c36..58776c5330c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Database Review Guidelines @@ -240,9 +240,11 @@ Include in the MR description: - Check queries timing (If any): In a single transaction, cumulative query time executed in a migration needs to fit comfortably in `15s` - preferably much less than that - on GitLab.com. - For column removals, make sure the column has been [ignored in a previous release](database/avoiding_downtime_in_migrations.md#dropping-columns) -- Check [background migrations](database/background_migrations.md): +- Check [batched background migrations](database/batched_background_migrations.md): - Establish a time estimate for execution on GitLab.com. For historical purposes, it's highly recommended to include this estimation on the merge request description. + This can be the number of expected batches times the delay interval. + - Manually trigger the [database testing](database/database_migration_pipeline.md) job (`db:gitlabcom-database-testing`) in the `test` stage. - If a single `update` is below than `1s` the query can be placed directly in a regular migration (inside `db/migrate`). - Background migrations are normally used, but not limited to: @@ -253,8 +255,6 @@ Include in the MR description: it's suggested to treat background migrations as [post migrations](migration_style_guide.md#choose-an-appropriate-migration-type): place them in `db/post_migrate` instead of `db/migrate`. - - If a migration [has tracking enabled](database/background_migrations.md#background-jobs-tracking), - ensure `mark_all_as_succeeded` is called even if no work is done. - Check [timing guidelines for migrations](migration_style_guide.md#how-long-a-migration-should-take) - Check migrations are reversible and implement a `#down` method - Check new table migrations: diff --git a/doc/development/deleting_migrations.md b/doc/development/deleting_migrations.md deleted file mode 100644 index 5d5ca431598..00000000000 --- a/doc/development/deleting_migrations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'database/deleting_migrations.md' -remove_date: '2022-07-08' ---- - -This document was moved to [another location](database/deleting_migrations.md). - -<!-- This redirect file can be deleted after <2022-07-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 (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/dependencies.md b/doc/development/dependencies.md index 329539f0cc2..3b935ceba22 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependencies diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index 1e9d3ebda77..a940cd9404c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deprecating GitLab features diff --git a/doc/development/developing_with_solargraph.md b/doc/development/developing_with_solargraph.md index d7e41187ace..7b9912a865e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using Solargraph diff --git a/doc/development/development_processes.md b/doc/development/development_processes.md index 27ebe98bc63..10818b749ab 100644 --- a/doc/development/development_processes.md +++ b/doc/development/development_processes.md @@ -1,7 +1,7 @@ --- stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Development processes @@ -22,7 +22,7 @@ Must-reads: Complementary reads: -- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md) +- [Contribute to GitLab](contributing/index.md) - [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) - [Patch release process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/patch/process.md#process-for-developers) - [Guidelines for implementing Enterprise Edition features](ee_features.md) @@ -56,10 +56,10 @@ group. For example, if you're documenting a new internal API used exclusively by a given group, request an engineering review from one of the group's members. After the engineering review is complete, assign the MR to the -[Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) +[Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) in the modified documentation page's metadata. If the page is not assigned to a specific group, follow the -[Technical Writing review process for development guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines). +[Technical Writing review process for development guidelines](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines). #### Broader changes @@ -79,12 +79,12 @@ In these cases, use the following workflow: - [Frontend](https://about.gitlab.com/handbook/engineering/frontend/) - [Backend](https://about.gitlab.com/handbook/engineering/) - [Database](https://about.gitlab.com/handbook/engineering/development/database/) - - [User Experience (UX)](https://about.gitlab.com/handbook/engineering/ux/) + - [User Experience (UX)](https://about.gitlab.com/handbook/product/ux/) - [Security](https://about.gitlab.com/handbook/engineering/security/) - [Quality](https://about.gitlab.com/handbook/engineering/quality/) - [Engineering Productivity](https://about.gitlab.com/handbook/engineering/quality/engineering-productivity/) - [Infrastructure](https://about.gitlab.com/handbook/engineering/infrastructure/) - - [Technical Writing](https://about.gitlab.com/handbook/engineering/ux/technical-writing/) + - [Technical Writing](https://about.gitlab.com/handbook/product/ux/technical-writing/) You can skip this step for MRs authored by EMs or Staff Engineers responsible for their area. @@ -100,10 +100,10 @@ In these cases, use the following workflow: @clefelhocz1. 1. After all approvals are complete, assign the MR to the - [Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) + [Technical Writer associated with the stage and group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) in the modified documentation page's metadata. If the page is not assigned to a specific group, follow the - [Technical Writing review process for development guidelines](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines). + [Technical Writing review process for development guidelines](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines). The Technical Writer may ask for additional approvals as previously suggested before merging the MR. ### Reviewer values diff --git a/doc/development/diffs.md b/doc/development/diffs.md index 5f03ba93a4d..b38fcea4f00 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Working with diffs @@ -148,7 +148,7 @@ This limit is hardcoded and only applied on GitLab. Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to map metadata about each type of Diff File. It has information whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. -`DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type in order to check if it can be rendered. +`DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type to check if it can be rendered. ## Merge request diffs against the `HEAD` of the target branch @@ -169,7 +169,7 @@ In order to display an up-to-date diff, in GitLab 12.9 we [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) merge request diffs compared against `HEAD` of the target branch: the target branch is artificially merged into the source branch, then the resulting -merge ref is compared to the source branch in order to calculate an accurate +merge ref is compared to the source branch to calculate an accurate diff. Until we complete the epics ["use merge refs for diffs"](https://gitlab.com/groups/gitlab-org/-/epics/854) diff --git a/doc/development/directory_structure.md b/doc/development/directory_structure.md index f909fda897f..27384fa559f 100644 --- a/doc/development/directory_structure.md +++ b/doc/development/directory_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Backend directory structure diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 9d62f2061ca..0ca10bc93dd 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Distributed Tracing - development guidelines **(FREE)** diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 87d2930dcb5..dae62fea603 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/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://about.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" @@ -34,7 +34,7 @@ Possible version history entries are: > - [Enabled on GitLab.com](issue-link) in GitLab X.X. > - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only. > - [Enabled on self-managed](issue-link) in GitLab X.X. -> - [Generally available](issue-link) in GitLab X.Y. [Feature flag `flag_name`](issue-link) removed. +> - [Generally available](issue-link) in GitLab X.Y. Feature flag `flag_name` removed. ``` You can combine entries if they happened in the same release: @@ -115,5 +115,5 @@ And, when the feature is done and fully available to all users: > - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/issue/etc) in GitLab 13.8. > - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. -> - [Generally available](issue-link) in GitLab 14.0. [Feature flag `forti_token_cloud`](issue-link) removed. +> - [Generally available](issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed. ``` diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index ad19a40a3f5..1bd8b37ff5f 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation." --- diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 73c1874f09e..c52b3b5adae 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/engineering/ux/technical-writing/#assignments +info: To 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: Learn how to contribute to GitLab Documentation. --- @@ -94,7 +94,7 @@ belongs to, as well as an information block as described below: ```plaintext 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 + https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments ``` For example: @@ -103,7 +103,7 @@ For example: --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- ``` @@ -171,7 +171,7 @@ contains an array of groups and their assigned technical writer. This task: To prepare an update to the `CODEOWNERS` file: -1. Update `lib/tasks/gitlab/tw/codeowners.rake` with the latest [TW team assignments](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). +1. Update `lib/tasks/gitlab/tw/codeowners.rake` with the latest [TW team assignments](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). Make this update in a standalone merge request, as it runs a long pipeline and requires backend maintainer review. Make sure this is merged before you update `CODEOWNERS` in another merge request. @@ -465,7 +465,7 @@ RSpec.describe '<What I am taking screenshots of>', :js do #### Full page screenshots -To take a full page screenshot simply `visit the page` and perform any expectation on real content (to have capybara wait till the page is ready and not take a white screenshot). +To take a full page screenshot, `visit the page` and perform any expectation on real content (to have capybara wait till the page is ready and not take a white screenshot). #### Element screenshot diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index 1bc697f2878..1118dc97926 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/engineering/ux/technical-writing/#assignments +info: To 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: 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 2991c1b3224..dc84f3a08dd 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/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://about.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.' diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md index a50efceb307..cb04f0909c1 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/engineering/ux/technical-writing/#assignments +info: To 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: Learn how documentation review apps work. --- diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index 8a9c2e1e8d7..b5c3a59b0eb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Documentation deployments diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md index 7f29d3fba9e..8a1d9b9fee3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 05e697869b9..37d10b16fcd 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/engineering/ux/technical-writing/#assignments +info: To 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: "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 44e4aac2756..d4553614fad 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Documentation site architecture diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index bc79bf0fbe2..d629bc0b87e 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/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://about.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.' @@ -17,9 +17,9 @@ In addition to this page, the following resources can help you craft and contrib - [Doc contribution guidelines](../index.md) - [Recommended word list](word_list.md) - [Doc style and consistency testing](../testing.md) -- [UI text guidelines](https://design.gitlab.com/content/error-messages/) +- [Guidelines for UI error messages](https://design.gitlab.com/content/error-messages/) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) -- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) +- [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - [Google Developer Documentation Style Guide](https://developers.google.com/style) - [Recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&state=merged&label_name[]=tw-style¬[label_name][]=docs%3A%3Afix) @@ -115,7 +115,7 @@ the documentation helps others efficiently accomplish tasks and solve problems. If you have questions when considering, authoring, or editing documentation, ask the Technical Writing team. They're available on Slack in `#docs` or in GitLab by -mentioning [the writer for](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments) +mentioning [the writer for](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments) the applicable [DevOps stage or group](https://about.gitlab.com/handbook/product/categories/#devops-stages). Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Review the @@ -333,7 +333,7 @@ When possible, try to avoid acronyms in headings. ### Numbers -When using numbers in text, spell out zero through nine, and use numbers for 10 and greater. For details, see the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/numbers). +When using numbers in text, spell out zero through nine, and use numbers for 10 and greater. For details, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/numbers). ## Text @@ -465,10 +465,18 @@ When using code block style: ## Lists -- Always start list items with a capital letter, unless they're parameters or - commands that are in backticks, or similar. -- Always leave a blank line before and after a list. -- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). +- Use a period after every sentence, including those that complete an introductory phrase. + Do not use semicolons or commas. +- Majority rules. Use either full sentences or all fragments. Avoid a mix. +- Always start list items with a capital letter. +- Separate the introductory phrase from explanatory text with a colon (`:`). For example: + + ```markdown + You can: + + - Do this thing. + - Do this other thing. + ``` ### Choose between an ordered or unordered list @@ -492,40 +500,27 @@ These things are imported: - Thing 3 ``` -You can choose to introduce either list with a colon, but you do not have to. - -### Markup +### List markup - Use dashes (`-`) for unordered lists instead of asterisks (`*`). -- Prefix `1.` to every item in an ordered list. When rendered, the list items - display with sequential numbering. - -### Punctuation - -- Don't add commas (`,`) or semicolons (`;`) to the ends of list items. -- If a list item is a complete sentence (with a subject and a verb), add a period at the end. -- Majority rules. If the majority of items do not end in a period, do not end any of the items in a period. -- Separate list items from explanatory text with a colon (`:`). For example: - - ```markdown - The list is as follows: - - - First item: this explains the first item. - - Second item: this explains the second item. - ``` +- Start every item in an ordered list with `1.`. When rendered, the list items + are sequential. +- Leave a blank line before and after a list. +- Begin a line with spaces (not tabs) to denote a [nested sub-item](#nesting-inside-a-list-item). ### Nesting inside a list item -It's possible to nest items under a list item, so that they render with the same -indentation as the list item. This can be done with: +You can nest items under a list item, so they render with the same +indentation as the list item. You can do this with: - [Code blocks](#code-blocks) - [Blockquotes](#blockquotes) - [Alert boxes](#alert-boxes) - [Images](#images) +- [Tabs](#tabs) -Items nested in lists should always align with the first character of the list -item. In unordered lists (using `-`), this means two spaces for each level of +Nested items should always align with the first character of the list +item. For unordered lists (using `-`), use two spaces for each level of indentation: ````markdown @@ -555,26 +550,9 @@ For ordered lists, use three spaces for each level of indentation: 1. Ordered list item 1 A line nested using 3 spaces to align with the `O` above. - -1. Ordered list item 2 - - > A quote block that will nest - > inside list item 2. - -1. Ordered list item 3 - - ```plaintext - a code block that nests inside list item 3 - ``` - -1. Ordered list item 4 - -  ```` -You can nest full lists inside other lists using the same rules as above. If you -want to mix types, that's also possible, if you don't mix items at the same -level: +You can nest lists in other lists. ```markdown 1. Ordered list item one. @@ -676,125 +654,66 @@ For other punctuation rules, refer to the [Pajamas Design System Punctuation section](https://design.gitlab.com/content/punctuation/). This is overridden by the [documentation-specific punctuation rules](#punctuation). -### Anchor links +## Links -Headings generate anchor links when rendered. `## This is an example` generates -the anchor `#this-is-an-example`. +Links help the docs adhere to the +[single source of truth](#documentation-is-the-single-source-of-truth-ssot) principle. -NOTE: -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39717) in -GitLab 13.4, [product badges](#product-tier-badges) used in headings aren't -included in the generated anchor links. For example, when you link to -`## This is an example **(FREE)**`, use the anchor `#this-is-an-example`. +### Links within the same repository -Keep in mind that the GitLab user interface links to many documentation pages -and anchor links to take the user to the right spot. When you change -a heading, search `doc/*`, `app/views/*`, and `ee/app/views/*` for the old -anchor. If you do not fix these links, the [`ui-docs-lint` job](../testing.md#ui-link-tests) -in your merge request fails. - -Important: +To link to another page in the same repository, +use a relative file path. For example, `../user/gitlab_com/index.md`. -- Avoid crosslinking documentation to headings unless you need to link to a - specific section of the document. This avoids breaking anchors in the - future in case the heading is changed. -- If possible, avoid changing headings, because they're not only linked internally. - There are various links to GitLab documentation on the internet, such as - tutorials, presentations, StackOverflow posts, and other sources. -- Do not link to `h1` headings. +Use inline link Markdown markup `[Text](https://example.com)`, +rather than reference-style links, like `[Text][identifier]`. -Note that with Kramdown, it's possible to add a custom ID to an HTML element -with Markdown markup, but they don't work in `/help`. Because of this, don't use -this option. +Put the entire link on a single line so that [linters](../testing.md) can find it. -## Links +### Links in separate repositories -Links are important in GitLab documentation. Use links instead of -summarizing to help preserve a [single source of truth](#documentation-is-the-single-source-of-truth-ssot) -in GitLab documentation. - -We include guidance for links in these categories: - -- How to set up [anchor links](#anchor-links) for headings. -- How to set up [criteria](#basic-link-criteria) for configuring a link. -- What to set up when [linking to a `help`](../../documentation/index.md#linking-to-help) - page. -- How to set up [links to internal documentation](#links-to-internal-documentation) - for cross-references. -- How to set up [links to external documentation](#links-to-external-documentation) - for authoritative sources. -- When to use [links requiring permissions](#links-requiring-permissions). -- How to set up a [link to a video](#link-to-video). -- How to [link to specific lines of code](#link-to-specific-lines-of-code) - -### Basic link criteria - -- Use inline link Markdown markup `[Text](https://example.com)`. - It's easier to read, review, and maintain. Do not use `[Text][identifier]` reference-style links. -- Use meaningful anchor text. - For example, instead of writing something like `Read more about merge requests [here](LINK)`, - write `Read more about [merge requests](LINK)`. -- Put the entire link on a single line. Some of our [linters](../testing.md) do not - validate links when split over multiple lines, and incorrect or broken links could - slip through. - -### Links to internal documentation +To link to a page in a different repository, use an absolute URL. +For example, to link from a page in the GitLab repo to the Charts repo, +use a URL like `https://docs.gitlab.com/charts/`. -NOTE: -**Internal** refers to documentation in the same project. When linking to -documentation in separate projects (for example, linking to Omnibus documentation -from GitLab documentation), you must use absolute URLs. +### Anchor links -Do not use absolute URLs like `https://docs.gitlab.com/ee/index.html` to -cross-link to other documentation in the same project. Use relative links to -the file, like `../index.md`. (These are converted to HTML when the site is -rendered.) +Each heading has an anchor link. For example, a topic with the title +`## This is an example` has the anchor `#this-is-an-example`. -Relative linking enables crosslinks to work: +The first topic on a page (the `h1`) has an anchor link, +but do not use it. Link to the page instead. -- in Review Apps, local previews, and `/help`. -- when working on the documentation locally, so you can verify that they work as - early as possible in the process. -- in the GitLab user interface when browsing doc files in their respective - repositories. For example, the links displayed at - `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`. +If a heading has a [product tier badge](#product-tier-badges), +do not include it in the anchor link. For example, for the heading +`## This is an example **(FREE)**`, use the anchor `#this-is-an-example`. -To link to internal documentation: +With Kramdown, you can add a custom ID to an HTML element, but these IDs +don't work in `/help`, so you should not use them. -- Use relative links to Markdown files in the same repository. -- Do not use absolute URLs or URLs from `docs.gitlab.com`. -- Use `../` to navigate to higher-level directories. -- Don't prepend `./` to links to files or directories. To link to a file in the - same directory or one of its sub-directories, use the syntax `path/to/file.md`. -- Don't link relative to root. For example, `/ee/user/gitlab_com/index.md`. +#### Changing links and titles - Don't: +When you change a heading, the anchor link changes. To ensure you update +any related links, search these directories: - - `https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html` - - `/ee/administration/geo/replication/troubleshooting.md` - - `./troubleshooting.md` +- `doc/*` +- `app/views/*` +- `ee/app/views/*` - Do: `../../geo/replication/troubleshooting.md` +If you do not fix these links, the [`ui-docs-lint` job](../testing.md#ui-link-tests) +in your merge request fails. -- Always add the filename `file.md` at the end of the link with the `.md` - extension, not `.html`. +### Text for links - Don't: +Use descriptive text for links, rather than words like `here` or `this page.` - - `../../merge_requests/` - - `../../issues/tags.html` - - `../../issues/tags.html#stages` +For example, instead of: - Do: +- `For more information, see [this page](LINK).` +- `For more information, go [here](LINK).` - - `../../merge_requests/index.md` - - `../../issues/tags.md` - - `../../issues/tags.md#stages` - - `issues/tags.md` +Use: -NOTE: -Using the Markdown extension is necessary for the [`/help`](../index.md#gitlab-help) -section of GitLab. +- `For more information, see [merge requests](LINK)`. ### Links to external documentation @@ -900,6 +819,28 @@ To open group settings: 1. Expand **General pipelines**. ``` +To open either project or group settings: + +```markdown +1. On the top bar, select **Main menu**, and: + - For a project, select ***Projects** and find your project. + - For a group, select **Groups** and find your group. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. +``` + +To create a project: + +```markdown +1. On the top bar, select **Create new... > New project**. +``` + +To create a group: + +```markdown +1. On the top bar, select **Create new... > New group**. +``` + To open the Admin Area: ```markdown @@ -1127,6 +1068,14 @@ Do not use words to describe the icon: - Avoid: `Select **Erase job log** (the trash icon).` - Use instead: `Select **Erase job log** (**{remove}**).` This generates as: Select **Erase job log** (**{remove}**). +When the button doesn't have any hover text, you can describe the icon. +Follow up by creating a +[UX bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Bug) +to add hover text to the button to improve accessibility. + +- Avoid: `Select **{ellipsis_v}**.` +- Use instead: `Select the vertical ellipsis (**{ellipsis_v}**).` This generates as: Select the vertical ellipsis (**{ellipsis_v}**). + ## Videos Adding GitLab YouTube video tutorials to the documentation is highly diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 029c7389290..65ad8dea688 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -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 +info: To 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: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- @@ -17,7 +17,7 @@ recommends these word choices. In addition: For guidance not on this page, we defer to these style guides: -- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) +- [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) - [Google Developer Documentation Style Guide](https://developers.google.com/style) <!-- vale off --> @@ -125,7 +125,7 @@ Instead of: - This feature enables users to add files to their repository. This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. -[View details in the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). +[View details in the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). ## Alpha @@ -141,7 +141,7 @@ Instead of **and/or**, use **or** or rewrite the sentence to spell out both opti ## and so on Do not use **and so on**. Instead, be more specific. For details, see -[the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/and-so-on). +[the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/and-so-on). ## area @@ -218,7 +218,7 @@ Instead of: ## cannot, can not -Use **cannot** instead of **can not**. You can also use **can't**. +Use **cannot** instead of **can not**. See also [contractions](index.md#contractions). @@ -316,7 +316,7 @@ Do not use **Developer permissions**. A user who is assigned the Developer role ## disable -See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. +See [the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) ## disallow @@ -363,9 +363,13 @@ Do not use Latin abbreviations. Use **for example**, **such as**, **for instance Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) +## emojis + +Use **emojis** to refer to the plural form of **emoji**. + ## enable -See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance on **enable**. +See [the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance on **enable**. Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) ## enter @@ -509,13 +513,16 @@ For example, **Snowplow Guide**. Instead, speak about the feature itself, and ho When writing about the Guest role: - Use a capital **G**. -- Do not use bold. -- Do not use the phrase, **if you are a guest** to mean someone who is assigned the Guest - role. Instead, write it out. For example, **if you are assigned the Guest role**. -- To describe a situation where the Guest role is the minimum required: +- Write it out: + - Use: if you are assigned the Guest role + - Instead of: if you are a guest + +- When the Guest role is the minimum required role: - Use: at least the Guest role - Instead of: the Guest role or higher +Do not use bold. + Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions. ## handy @@ -656,13 +663,16 @@ Instead of: When writing about the Maintainer role: - Use a capital **M**. -- Do not use bold. -- Do not use the phrase, **if you are a maintainer** to mean someone who is assigned the Maintainer - role. Instead, write it out. For example, **if you are assigned the Maintainer role**. -- To describe a situation where the Maintainer role is the minimum required: +- Write it out. + - Use: if you are assigned the Maintainer role + - Instead of: if you are a maintainer + +- When the Maintainer role is the minimum required role: - Use: at least the Maintainer role - Instead of: the Maintainer role or higher +Do not use bold. + Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions. ## mankind @@ -796,11 +806,14 @@ For example, a log file might overwrite a log file of the same name. When writing about the Owner role: - Use a capital **O**. -- Do not use bold. -- Do not use the phrase, **if you are an owner** to mean someone who is assigned the Owner - role. Instead, write it out. For example, **if you are assigned the Owner role**. +- Write it out. + - Use: if you are assigned the Owner role + - Instead of: if you are an owner +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 @@ -818,7 +831,7 @@ Use lowercase for **personal access token**. ## please -Do not use **please**. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +Do not use **please**. For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). ## press @@ -851,13 +864,16 @@ Use **register** instead of **sign up** when talking about creating an account. When writing about the Reporter role: - Use a capital **R**. -- Do not use bold. -- Do not use the phrase, **if you are a reporter** to mean someone who is assigned the Reporter - role. Instead, write it out. For example, **if you are assigned the Reporter role**. -- To describe a situation where the Reporter role is the minimum required: +- Write it out. + - Use: if you are assigned the Reporter role + - Instead of: if you are a reporter + +- When the Reporter role is the minimum required role: - Use: at least the Reporter role - Instead of: the Reporter role or higher +Do not use bold. + Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. ## Repository Mirroring diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 59a078bdec0..c801bb9f877 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/engineering/ux/technical-writing/#assignments +info: To 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: Learn how to contribute to GitLab Documentation. --- diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index a20bb93a97f..dfd003b642d 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Concept topic type diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index af3e66fe87a..8403fd26517 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Documentation topic types (CTRT) diff --git a/doc/development/documentation/topic_types/reference.md b/doc/development/documentation/topic_types/reference.md index 42f4f5f6f94..e7ee8b20925 100644 --- a/doc/development/documentation/topic_types/reference.md +++ b/doc/development/documentation/topic_types/reference.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reference topic type diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 3488cb90cf9..60508fbf6ee 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Task topic type diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md index 35187bd892e..e2136de2e06 100644 --- a/doc/development/documentation/topic_types/troubleshooting.md +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: none group: Style Guide -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 +info: To 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 topic type diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 85733603cfe..12381b84c2c 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/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this Style Guide page, see https://about.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.' @@ -139,7 +139,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/engineering/ux/technical-writing/#assignments + info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments remove_date: '2022-08-02' redirect_to: '../newpath/to/file/index.md' --- @@ -154,7 +154,7 @@ To remove a page: 1. Remove the page's entry from the global navigation by editing [`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) in `gitlab-docs`. This content is removed from the documentation as part of the Technical Writing team's -[regularly scheduled tasks](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks). +[regularly scheduled tasks](https://about.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks). ### Remove a topic @@ -179,7 +179,7 @@ To remove a topic: ``` This content is removed from the documentation as part of the Technical Writing team's -[regularly scheduled tasks](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks). +[regularly scheduled tasks](https://about.gitlab.com/handbook/product/ux/technical-writing/#regularly-scheduled-tasks). ## Which versions are removed diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index fb43a2e995a..85d3d5e9cfc 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to update GitLab documentation @@ -13,7 +13,7 @@ Anyone can contribute to the GitLab documentation! You can create a merge reques accomplish their work with GitLab. If you are working on a feature or enhancement, use the -[feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change). +[feature workflow process described in the GitLab Handbook](https://about.gitlab.com/handbook/product/ux/technical-writing/workflow/#for-a-product-change). ## How to update the docs @@ -54,7 +54,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/engineering/ux/technical-writing/#assignments). + [DevOps stage group](https://about.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. @@ -86,7 +86,7 @@ merge documentation changes. Maintainers must make a good-faith effort to ensure - Meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide/index.md). If the author or reviewer has any questions, they can mention the writer who is assigned to the relevant -[DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). +[DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). The process involves the following: @@ -96,7 +96,7 @@ The process involves the following: - Technical Writer (Optional). If not completed for a merge request before merging, must be scheduled post-merge. Schedule post-merge reviews only if an urgent merge is required. To request a: - Pre-merge review, assign the Technical Writer listed for the applicable - [DevOps stage group](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments). + [DevOps stage group](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments). - Post-merge review, see [Post-merge reviews](#post-merge-reviews). - Maintainer. For merge requests, Maintainers: - Can always request any of the above reviews. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 869cb0bab0a..2516196d2e0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Guidelines for implementing Enterprise Edition features @@ -72,7 +72,7 @@ To guard your licensed feature: ``` 1. Optional. If your global feature is also available to namespaces with a paid plan, combine two -feature identifiers to allow both admins and group users. For example: +feature identifiers to allow both administrators and group users. For example: ```ruby License.feature_available?(:my_feature_name) || group.licensed_feature_available?(:my_feature_name_for_namespace) # Both admins and group members can see this EE feature @@ -176,12 +176,19 @@ This works because for every path that is present in CE's eager-load/auto-load paths, we add the same `ee/`-prepended path in [`config/application.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/925d3d4ebc7a2c72964ce97623ae41b8af12538d/config/application.rb#L42-52). This also applies to views. -#### Testing EE-only features +#### Testing EE-only backend features To test an EE class that doesn't exist in CE, create the spec file as you normally would in the `ee/spec` directory, but without the second `ee/` subdirectory. For example, a class `ee/app/models/vulnerability.rb` would have its tests in `ee/spec/models/vulnerability_spec.rb`. +By default, licensed features are disabled while specs are running. To effectively test your feature +you must explicitly enable the feature using the `stub_licensed_features` helper, for example: + +```ruby + stub_licensed_features(my_awesome_feature_name: true) +``` + ### Extend CE features with EE backend code For features that build on existing CE features, write a module in the `EE` @@ -817,7 +824,7 @@ end Sometimes we need EE-specific behavior in some of the APIs. Normally we could use EE methods to override CE methods, however API routes are not methods and -therefore can't be simply overridden. We need to extract them into a standalone +therefore cannot be overridden. We need to extract them into a standalone method, or introduce some "hooks" where we could inject behavior in the CE route. Something like this: @@ -868,8 +875,8 @@ end #### EE `route_setting` -It's very hard to extend this in an EE module, and this is simply storing -some meta-data for a particular route. Given that, we could simply leave the +It's very hard to extend this in an EE module, and this is storing +some meta-data for a particular route. Given that, we could leave the EE `route_setting` in CE as it doesn't hurt and we don't use those meta-data in CE. @@ -1047,7 +1054,7 @@ FactoryBot.define do end ``` -## Separate of EE code in the frontend +## Separation of EE code in the frontend To separate EE-specific JS-files, move the files into an `ee` folder. @@ -1089,10 +1096,13 @@ ee/app/assets/javascripts/ee_only_feature/index.js Feature guarding `licensed_feature_available?` and `License.feature_available?` typical occurs in the controller, as described in the [backend guide](#ee-only-features). -#### Test EE-only features +#### Testing EE-only frontend features Add your EE tests to `ee/spec/frontend/` following the same directory structure you use for CE. +Check the note under [Testing EE-only backend features](#testing-ee-only-backend-features) regarding +enabling licensed features. + ### Extend CE features with EE frontend code Use the [`push_licensed_feature`](#guard-your-ee-feature) to guard frontend features that extend @@ -1406,5 +1416,5 @@ to avoid conflicts during CE to EE merge. ### GitLab-svgs Conflicts in `app/assets/images/icons.json` or `app/assets/images/icons.svg` can -be resolved simply by regenerating those assets with +be resolved by regenerating those assets with [`yarn run svg`](https://gitlab.com/gitlab-org/gitlab-svgs). diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index b3996e16fa1..ab2d241a781 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Elasticsearch knowledge **(PREMIUM SELF)** @@ -64,7 +64,7 @@ Please see the `sha_tokenizer` explanation later below for an example. Used when indexing a blob's filename and content. Uses the `whitespace` tokenizer and the filters: [`code`](#code), `lowercase`, and `asciifolding` -The `whitespace` tokenizer was selected in order 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)` in order to be properly searched. +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. @@ -94,7 +94,7 @@ Example: #### `path_tokenizer` -This is a custom tokenizer that uses the [`path_hierarchy` tokenizer](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/analysis-pathhierarchy-tokenizer.html) with `reverse: true` in order to allow searches to find paths no matter how much or how little of the path is given as input. +This is a custom tokenizer that uses the [`path_hierarchy` tokenizer](https://www.elastic.co/guide/en/elasticsearch/reference/5.5/analysis-pathhierarchy-tokenizer.html) with `reverse: true` to allow searches to find paths no matter how much or how little of the path is given as input. Example: @@ -461,8 +461,8 @@ _from "Disk-based Shard Allocation | Elasticsearch Reference" [5.6](https://www. The use of Elasticsearch in GitLab is only ever as a secondary data store. This means that all of the data stored in Elasticsearch can always be derived again from other data sources, specifically PostgreSQL and Gitaly. Therefore if -the Elasticsearch data store is ever corrupted for whatever reason you can -simply reindex everything from scratch. +the Elasticsearch data store is ever corrupted for whatever reason you can reindex +everything from scratch. If your Elasticsearch index is incredibly large it may be too time consuming or cause too much downtime to reindex from scratch. There aren't any built in diff --git a/doc/development/emails.md b/doc/development/emails.md index c997916aa21..2d03d8bca2f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Working with email in development @@ -176,7 +176,7 @@ in the Helm Chart configuration rather than the `Gemfile`. #### Preserving backwards compatibility -Removing the `Gemfile` would break incoming e-mail processing for source +Removing the `Gemfile` would break incoming email processing for source installs. For now, source installs are advised to upgrade manually to the version specified in Omnibus and run `bin/mail_room` directly as done with Omnibus. diff --git a/doc/development/event_store.md b/doc/development/event_store.md index 37035083e23..b9200d3be25 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab EventStore diff --git a/doc/development/experiment_guide/experiment_code_reviews.md b/doc/development/experiment_guide/experiment_code_reviews.md index 07bc0f59463..7242acfbdcf 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Experiment code reviews diff --git a/doc/development/experiment_guide/experiment_rollout.md b/doc/development/experiment_guide/experiment_rollout.md index e68520f7812..b2e1b1168d3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Experiment rollouts and feature flags diff --git a/doc/development/experiment_guide/gitlab_experiment.md b/doc/development/experiment_guide/gitlab_experiment.md deleted file mode 100644 index 5ddbe9b3de9..00000000000 --- a/doc/development/experiment_guide/gitlab_experiment.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2022-08-05' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after 2022-08-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/development/experiment_guide/implementing_experiments.md b/doc/development/experiment_guide/implementing_experiments.md index 19200d48637..e1407473731 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Implementing an A/B/n experiment @@ -136,7 +136,7 @@ somewhat abstract and hard to understand initially, but this approach enables us communicate about experiments as something that's wider than just user behavior. NOTE: -Using `actor:` utilizes cookies if the `current_user` is nil. If you don't need +Using `actor:` uses cookies if the `current_user` is nil. If you don't need cookies though - meaning that the exposed functionality would only be visible to signed in users - `{ user: current_user }` would be just as effective. @@ -318,7 +318,7 @@ Given that we've defined a class for our experiment, and have defined the varian The first way is by running the experiment. Assuming the experiment has been run, it surfaces in the client layer without having to do anything special. -The second way doesn't run the experiment and is intended to be used if the experiment must only surface in the client layer. To accomplish this we can `.publish` the experiment. This does not run any logic, but does surface the experiment details in the client layer so they can be utilized there. +The second way doesn't run the experiment and is intended to be used if the experiment must only surface in the client layer. To accomplish this we can `.publish` the experiment. This does not run any logic, but does surface the experiment details in the client layer so they can be used there. An example might be to publish an experiment in a `before_action` in a controller. Assuming we've defined the `PillColorExperiment` class, like we have above, we can surface it to the client by publishing it instead of running it: diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 500a19fe1ad..e185cd702a4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Experiment Guide diff --git a/doc/development/experiment_guide/testing_experiments.md b/doc/development/experiment_guide/testing_experiments.md index 78a5d606490..2e88029a27f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Testing experiments diff --git a/doc/development/export_csv.md b/doc/development/export_csv.md index 29e80f676da..5d35c880ffd 100644 --- a/doc/development/export_csv.md +++ b/doc/development/export_csv.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export to CSV diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index bdd6c5d6e84..67166a93cb4 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Accessibility @@ -68,9 +68,9 @@ We should ensure that: To provide markup with accessible names, ensure every: -- `input` has an associated `label`. -- `button` and `a` have child text, or `aria-label` when child text isn't present, such as for an icon button with no content. -- `img` has an `alt` attribute. +- input has an [associated `label`](#examples-of-providing-accessible-names). +- button and link have [visible text](#buttons-and-links-with-descriptive-accessible-names), or `aria-label` when there is no visible text, such as for an icon button with no content. +- image has an [`alt` attribute](#images-with-accessible-names). - `fieldset` has `legend` as its first child. - `figure` has `figcaption` as its first child. - `table` has `caption` as its first child. @@ -100,12 +100,12 @@ Text input examples: ```html <!-- Input with label --> <gl-form-group :label="__('Issue title')" label-for="issue-title"> - <gl-form-input id="issue-title" v-model="title" name="title" /> + <gl-form-input id="issue-title" v-model="title" /> </gl-form-group> <!-- Input with hidden label --> -<gl-form-group :label="__('Issue title')" label-for="issue-title" :label-sr-only="true"> - <gl-form-input id="issue-title" v-model="title" name="title" /> +<gl-form-group :label="__('Issue title')" label-for="issue-title" label-sr-only> + <gl-form-input id="issue-title" v-model="title" /> </gl-form-group> ``` @@ -114,12 +114,12 @@ Textarea examples: ```html <!-- Textarea with label --> <gl-form-group :label="__('Issue description')" label-for="issue-description"> - <gl-form-textarea id="issue-description" v-model="description" name="description" /> + <gl-form-textarea id="issue-description" v-model="description" /> </gl-form-group> <!-- Textarea with hidden label --> -<gl-form-group :label="__('Issue description')" label-for="issue-description" :label-sr-only="true"> - <gl-form-textarea id="issue-description" v-model="description" name="description" /> +<gl-form-group :label="__('Issue description')" label-for="issue-description" label-sr-only> + <gl-form-textarea id="issue-description" v-model="description" /> </gl-form-group> ``` @@ -128,11 +128,11 @@ Alternatively, you can use a plain `label` element: ```html <!-- Input with label using `label` --> <label for="issue-title">{{ __('Issue title') }}</label> -<gl-form-input id="issue-title" v-model="title" name="title" /> +<gl-form-input id="issue-title" v-model="title" /> <!-- Input with hidden label using `label` --> <label for="issue-title" class="gl-sr-only">{{ __('Issue title') }}</label> -<gl-form-input id="issue-title" v-model="title" name="title" /> +<gl-form-input id="issue-title" v-model="title" /> ``` #### Select inputs with accessible names @@ -142,12 +142,12 @@ Select input examples: ```html <!-- Select input with label --> <gl-form-group :label="__('Issue status')" label-for="issue-status"> - <gl-form-select id="issue-status" v-model="status" name="status" :options="options" /> + <gl-form-select id="issue-status" v-model="status" :options="options" /> </gl-form-group> <!-- Select input with hidden label --> -<gl-form-group :label="__('Issue status')" label-for="issue-status" :label-sr-only="true"> - <gl-form-select id="issue-status" v-model="status" name="status" :options="options" /> +<gl-form-group :label="__('Issue status')" label-for="issue-status" label-sr-only> + <gl-form-select id="issue-status" v-model="status" :options="options" /> </gl-form-group> ``` @@ -157,12 +157,12 @@ Single checkbox: ```html <!-- Single checkbox with label --> -<gl-form-checkbox v-model="status" name="status" value="task-complete"> +<gl-form-checkbox v-model="status" value="task-complete"> {{ __('Task complete') }} </gl-form-checkbox> <!-- Single checkbox with hidden label --> -<gl-form-checkbox v-model="status" name="status" value="task-complete"> +<gl-form-checkbox v-model="status" value="task-complete"> <span class="gl-sr-only">{{ __('Task complete') }}</span> </gl-form-checkbox> ``` @@ -172,24 +172,24 @@ Multiple checkboxes: ```html <!-- Multiple labeled checkboxes grouped within a fieldset --> <gl-form-group :label="__('Task list')"> - <gl-form-checkbox name="task-list" value="task-1">{{ __('Task 1') }}</gl-form-checkbox> - <gl-form-checkbox name="task-list" value="task-2">{{ __('Task 2') }}</gl-form-checkbox> + <gl-form-checkbox value="task-1">{{ __('Task 1') }}</gl-form-checkbox> + <gl-form-checkbox value="task-2">{{ __('Task 2') }}</gl-form-checkbox> </gl-form-group> <!-- Or --> <gl-form-group :label="__('Task list')"> - <gl-form-checkbox-group v-model="selected" :options="options" name="task-list" /> + <gl-form-checkbox-group v-model="selected" :options="options" /> </gl-form-group> <!-- Multiple labeled checkboxes grouped within a fieldset with hidden legend --> -<gl-form-group :label="__('Task list')" :label-sr-only="true"> - <gl-form-checkbox name="task-list" value="task-1">{{ __('Task 1') }}</gl-form-checkbox> - <gl-form-checkbox name="task-list" value="task-2">{{ __('Task 2') }}</gl-form-checkbox> +<gl-form-group :label="__('Task list')" label-sr-only> + <gl-form-checkbox value="task-1">{{ __('Task 1') }}</gl-form-checkbox> + <gl-form-checkbox value="task-2">{{ __('Task 2') }}</gl-form-checkbox> </gl-form-group> <!-- Or --> -<gl-form-group :label="__('Task list')" :label-sr-only="true"> - <gl-form-checkbox-group v-model="selected" :options="options" name="task-list" /> +<gl-form-group :label="__('Task list')" label-sr-only> + <gl-form-checkbox-group v-model="selected" :options="options" /> </gl-form-group> ``` @@ -199,12 +199,12 @@ Single radio input: ```html <!-- Single radio with a label --> -<gl-form-radio v-model="status" name="status" value="opened"> +<gl-form-radio v-model="status" value="opened"> {{ __('Opened') }} </gl-form-radio> <!-- Single radio with a hidden label --> -<gl-form-radio v-model="status" name="status" value="opened"> +<gl-form-radio v-model="status" value="opened"> <span class="gl-sr-only">{{ __('Opened') }}</span> </gl-form-radio> ``` @@ -214,24 +214,24 @@ Multiple radio inputs: ```html <!-- Multiple labeled radio inputs grouped within a fieldset --> <gl-form-group :label="__('Issue status')"> - <gl-form-radio name="status" value="opened">{{ __('Opened') }}</gl-form-radio> - <gl-form-radio name="status" value="closed">{{ __('Closed') }}</gl-form-radio> + <gl-form-radio value="opened">{{ __('Opened') }}</gl-form-radio> + <gl-form-radio value="closed">{{ __('Closed') }}</gl-form-radio> </gl-form-group> <!-- Or --> <gl-form-group :label="__('Issue status')"> - <gl-form-radio-group v-model="selected" :options="options" name="status" /> + <gl-form-radio-group v-model="selected" :options="options" /> </gl-form-group> <!-- Multiple labeled radio inputs grouped within a fieldset with hidden legend --> -<gl-form-group :label="__('Issue status')" :label-sr-only="true"> - <gl-form-radio name="status" value="opened">{{ __('Opened') }}</gl-form-radio> - <gl-form-radio name="status" value="closed">{{ __('Closed') }}</gl-form-radio> +<gl-form-group :label="__('Issue status')" label-sr-only> + <gl-form-radio value="opened">{{ __('Opened') }}</gl-form-radio> + <gl-form-radio value="closed">{{ __('Closed') }}</gl-form-radio> </gl-form-group> <!-- Or --> -<gl-form-group :label="__('Issue status')" :label-sr-only="true"> - <gl-form-radio-group v-model="selected" :options="options" name="status" /> +<gl-form-group :label="__('Issue status')" label-sr-only> + <gl-form-radio-group v-model="selected" :options="options" /> </gl-form-group> ``` @@ -242,11 +242,11 @@ File input examples: ```html <!-- File input with a label --> <label for="attach-file">{{ __('Attach a file') }}</label> -<input id="attach-file" type="file" name="attach-file" /> +<input id="attach-file" type="file" /> <!-- File input with a hidden label --> <label for="attach-file" class="gl-sr-only">{{ __('Attach a file') }}</label> -<input id="attach-file" type="file" name="attach-file" /> +<input id="attach-file" type="file" /> ``` #### GlToggle components with an accessible names @@ -337,7 +337,7 @@ element is interactive you must ensure: - It can receive keyboard focus. - It has a visible focus state. -Use semantic HTML, such as `a` and `button`, which provides these behaviours by default. +Use semantic HTML, such as `a` (`GlLink`) and `button` (`GlButton`), which provides these behaviours by default. Keep in mind that: @@ -351,7 +351,7 @@ See the [Pajamas Keyboard-only page](https://design.gitlab.com/accessibility-aud Prefer **no** `tabindex` to using `tabindex`, since: -- Using semantic HTML such as `button` implicitly provides `tabindex="0"`. +- Using semantic HTML such as `button` (`GlButton`) implicitly provides `tabindex="0"`. - Tabbing order should match the visual reading order and positive `tabindex`s interfere with this. ### Avoid using `tabindex="0"` to make an element interactive @@ -359,8 +359,8 @@ Prefer **no** `tabindex` to using `tabindex`, since: Use interactive elements instead of `div` and `span` tags. For example: -- If the element should be clickable, use a `button`. -- If the element should be text editable, use an `input` or `textarea`. +- If the element should be clickable, use a `button` (`GlButton`). +- If the element should be text editable, use an [`input` or `textarea`](#text-inputs-with-accessible-names). Once the markup is semantically complete, use CSS to update it to its desired visual state. diff --git a/doc/development/fe_guide/architecture.md b/doc/development/fe_guide/architecture.md index 1d08296eafc..0c85a21fdf4 100644 --- a/doc/development/fe_guide/architecture.md +++ b/doc/development/fe_guide/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Architecture diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index b42a17d7870..f90a2b37a1c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Axios diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md index f262e48b6da..8cc274c732e 100644 --- a/doc/development/fe_guide/content_editor.md +++ b/doc/development/fe_guide/content_editor.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Content Editor development guidelines **(FREE)** diff --git a/doc/development/fe_guide/customizable_dashboards.md b/doc/development/fe_guide/customizable_dashboards.md new file mode 100644 index 00000000000..38ee750d421 --- /dev/null +++ b/doc/development/fe_guide/customizable_dashboards.md @@ -0,0 +1,99 @@ +--- +stage: Analytics +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 +--- + +# Customizable dashboards **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98610) in GitLab 15.5 as an [Alpha feature](../../policy/alpha-beta-support.md#alpha-features). + +Customizable dashboards provide a dashboard structure that allows users to create +their own dashboards and commit the structure to a repository. + +## Usage + +To use customizable dashboards: + +1. Create your dashboard component. +1. Render an instance of `CustomizableDashboard`. +1. Pass a list of widgets to render. + +For example, a customizable dashboard for users over time: + +```vue +<script> +import CustomizableDashboard from 'ee/vue_shared/components/customizable_dashboard/customizable_dashboard.vue'; +import { s__ } from '~/locale'; + +export default { + name: 'AnalyticsDashboard', + components: { + CustomizableDashboard, + }, + data() { + return { + widgets: [ + { + component: 'CubeLineChart', // The name of the widget component. + title: s__('ProductAnalytics|Users / Time'), // The title shown on the widget component. + // Gridstack settings based upon https://github.com/gridstack/gridstack.js/tree/master/doc#item-options. + // All values are grid row/column numbers up to 12. + // We use the default 12 column grid https://github.com/gridstack/gridstack.js#change-grid-columns. + gridAttributes: { + size: { + height: 4, + width: 6, + minHeight: 4, + minWidth: 6, + }, + position: { + xPos: 0, + yPos: 0, + }, + }, + // Options that are used to set bespoke values for each widget. + // Available customizations are determined by the widget itself. + customizations: {}, + // Chart options defined by the charting library being used by the widget. + chartOptions: { + xAxis: { name: __('Time'), type: 'time' }, + yAxis: { name: __('Counts') }, + }, + // The data for the widget. + // This could be imported or in this case, a query passed to be used by the widgets API. + // Each widget type determines how it handles this property. + data: { + query: { + users: { + measures: ['Jitsu.count'], + dimensions: ['Jitsu.eventType'], + }, + }, + }, + }, + ] + }; + }, +}; +</script> + +<template> + <h1>{{ s__('ProductAnalytics|Analytics dashboard') }}</h1> + <customizable-dashboard :widgets="widgets" /> +</template> +``` + +The widgets data can be retrieved from a file or API request, or imported through HTML data attributes. + +For each widget, a `component` is defined. Each `component` is a component declaration and should be included in +[`vue_shared/components/customizable_dashboard/widgets_base.vue`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/assets/javascripts/vue_shared/components/customizable_dashboard/widgets_base.vue) +as a dynamic import, to keep the memory usage down until it is used. + +For example: + +```javascript +components: { + CubeLineChart: () => import('ee/product_analytics/dashboards/components/widgets/cube_line_chart.vue') +} +``` diff --git a/doc/development/fe_guide/dark_mode.md b/doc/development/fe_guide/dark_mode.md index 34901bbb1e6..d687d9740c9 100644 --- a/doc/development/fe_guide/dark_mode.md +++ b/doc/development/fe_guide/dark_mode.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- This page is about developing dark mode for GitLab. We also have documentation on how diff --git a/doc/development/fe_guide/dependencies.md b/doc/development/fe_guide/dependencies.md index c4f30fd36c9..b9bacada499 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Frontend dependencies diff --git a/doc/development/fe_guide/design_anti_patterns.md b/doc/development/fe_guide/design_anti_patterns.md index 580f488bd33..07de86f5810 100644 --- a/doc/development/fe_guide/design_anti_patterns.md +++ b/doc/development/fe_guide/design_anti_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Design Anti-patterns @@ -146,7 +146,7 @@ Even in these scenarios, consider avoiding the Singleton pattern. #### Utility Functions -When no state needs to be managed, we can simply export utility functions from a module without +When no state needs to be managed, we can export utility functions from a module without messing with any class instantiation. ```javascript diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index 03575f7e7f9..3c273ab18e9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Design Patterns diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index 3273263de3b..fc91ff55b24 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Frontend Development Process @@ -26,7 +26,7 @@ Use your best judgment when to use it and contribute new points through merge re - [ ] Check the current set weight of the issue, does it fit your estimate? - [ ] Are all [departments](https://about.gitlab.com/handbook/engineering/#engineering-teams) that are needed from your perspective already involved in the issue? (For example is UX missing?) - [ ] Is the specification complete? Are you missing decisions? How about error handling/defaults/edge cases? Take your time to understand the needed implementation and go through its flow. -- [ ] Are all necessary UX specifications available that you will need in order to implement? Are there new UX components/patterns in the designs? Then contact the UI component team early on. How should error messages or validation be handled? +- [ ] Are all necessary UX specifications available that you will need to implement? Are there new UX components/patterns in the designs? Then contact the UI component team early on. How should error messages or validation be handled? - [ ] **Library usage** Use Vuex as soon as you have even a medium state to manage, use Vue router if you need to have different views internally and want to link from the outside. Check what libraries we already have for which occasions. - [ ] **Plan your implementation:** - [ ] **Architecture plan:** Create a plan aligned with GitLab's architecture, how you are going to do the implementation, for example Vue application setup and its components (through [onion skinning](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35873#note_39994091)), Store structure and data flow, which existing Vue components can you reuse. It's a good idea to go through your plan with another engineer to refine it. diff --git a/doc/development/fe_guide/emojis.md b/doc/development/fe_guide/emojis.md index 3c7fc20440b..3296783a616 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Emojis diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index 6a645416c0a..3b349d880c0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Frontend FAQ diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 6dcc57b0ff5..9ed3e551ff2 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # GraphQL @@ -330,7 +330,7 @@ Along with creating local data, we can also extend existing GraphQL types with ` ##### Mocking API response with local Apollo cache -Using local Apollo Cache is helpful when we have a need to mock some GraphQL API responses, queries, or mutations locally (such as when they're still not added to our actual API). +Using local Apollo Cache is helpful when we have a reason to mock some GraphQL API responses, queries, or mutations locally (such as when they're still not added to our actual API). For example, we have a [fragment](#fragments) on `DesignVersion` used in our queries: @@ -341,7 +341,7 @@ fragment VersionListItem on DesignVersion { } ``` -We also need to fetch the version author and the `created at` property to display in the versions dropdown. But, these changes are still not implemented in our API. We can change the existing fragment to get a mocked response for these new fields: +We also must fetch the version author and the `created at` property to display in the versions dropdown list. But, these changes are still not implemented in our API. We can change the existing fragment to get a mocked response for these new fields: ```javascript fragment VersionListItem on DesignVersion { @@ -627,7 +627,7 @@ GraphQL entities are not yet part of the schema, or if they are feature-flagged ### Manually triggering queries Queries on a component's `apollo` property are made automatically when the component is created. -Some components instead want the network request made on-demand, for example a dropdown with lazy-loaded items. +Some components instead want the network request made on-demand, for example a dropdown list with lazy-loaded items. There are two ways to do this: @@ -1318,7 +1318,7 @@ automatically find and index the schema. #### Testing Apollo components -If we use `ApolloQuery` or `ApolloMutation` in our components, in order to test their functionality we need to add a stub first: +If we use `ApolloQuery` or `ApolloMutation` in our components, to test their functionality we need to add a stub first: ```javascript import { ApolloMutation } from 'vue-apollo'; diff --git a/doc/development/fe_guide/haml.md b/doc/development/fe_guide/haml.md index 7e72570454e..d76d718e8e5 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # HAML diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index 73f196ef51f..df296f13f48 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Icons and SVG Illustrations diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index d90c270153e..6403cff549f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Frontend Development Guidelines diff --git a/doc/development/fe_guide/keyboard_shortcuts.md b/doc/development/fe_guide/keyboard_shortcuts.md index aab252da305..aeeee72e6be 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Implementing keyboard shortcuts diff --git a/doc/development/fe_guide/logging.md b/doc/development/fe_guide/logging.md index 26633eade43..30cf290fbe8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 a2ff10cc57f..e5e813bf921 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request widget extensions **(FREE)** diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 2e1fabd739c..3aa901093f0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performance diff --git a/doc/development/fe_guide/principles.md b/doc/development/fe_guide/principles.md index 1bf37c8d008..6d1a3238b73 100644 --- a/doc/development/fe_guide/principles.md +++ b/doc/development/fe_guide/principles.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Principles diff --git a/doc/development/fe_guide/registry_architecture.md b/doc/development/fe_guide/registry_architecture.md index be14d5d920c..a87d38634d5 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Registry architecture diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md index 6f500c8f0fa..4b7ce6d11e3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Security diff --git a/doc/development/fe_guide/source_editor.md b/doc/development/fe_guide/source_editor.md index 88508e94380..b7cd903485e 100644 --- a/doc/development/fe_guide/source_editor.md +++ b/doc/development/fe_guide/source_editor.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Source Editor **(FREE)** diff --git a/doc/development/fe_guide/storybook.md b/doc/development/fe_guide/storybook.md index a3a1fa2160f..e57c117bc39 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Storybook diff --git a/doc/development/fe_guide/style/html.md b/doc/development/fe_guide/style/html.md index 90ff88bc975..b1cce29bc61 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # HTML style guide diff --git a/doc/development/fe_guide/style/index.md b/doc/development/fe_guide/style/index.md index f3da78647be..94ed9544cf5 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab development style guides diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index b86bdfafa21..38fb926197b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/development/fe_guide/style_guide_js.html' --- diff --git a/doc/development/fe_guide/style/scss.md b/doc/development/fe_guide/style/scss.md index 17e80762a38..aacf07fda92 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/development/fe_guide/style_guide_scss.html' --- diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index 39dc9cc9c4e..a21d7c4577b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vue.js style guide diff --git a/doc/development/fe_guide/tooling.md b/doc/development/fe_guide/tooling.md index 4b55580c33c..c9efb8e939d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tooling diff --git a/doc/development/fe_guide/troubleshooting.md b/doc/development/fe_guide/troubleshooting.md index ab10c5bf988..873a14b8f14 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/engineering/ux/technical-writing/#assignments +info: To 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 frontend development issues diff --git a/doc/development/fe_guide/view_component.md b/doc/development/fe_guide/view_component.md index 7ddce609ee7..662d1ad32fc 100644 --- a/doc/development/fe_guide/view_component.md +++ b/doc/development/fe_guide/view_component.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ViewComponent diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 5cb461c8ca0..00d9588d087 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vue @@ -408,11 +408,11 @@ export function useCount(initialValue) { const count = ref(initialValue) function incrementCount() { - ref.value += 1 + count.value += 1 } function decrementCount() { - ref.value -= 1 + count.value -= 1 } return { count, incrementCount, decrementCount } diff --git a/doc/development/fe_guide/vue3_migration.md b/doc/development/fe_guide/vue3_migration.md index 068b0c5b475..c3ce42a80a5 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migration to Vue 3 diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 2d1569b7812..5047f1b7f89 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vuex diff --git a/doc/development/fe_guide/widgets.md b/doc/development/fe_guide/widgets.md index c6bb89d1fe8..3364c778d76 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Widgets diff --git a/doc/development/feature_categorization/index.md b/doc/development/feature_categorization/index.md index a93ed58336d..0bf506b53ba 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Feature Categorization diff --git a/doc/development/feature_development.md b/doc/development/feature_development.md index fd1c7f4afa5..760ba033633 100644 --- a/doc/development/feature_development.md +++ b/doc/development/feature_development.md @@ -1,7 +1,7 @@ --- stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Feature development @@ -114,6 +114,7 @@ Consult these topics for information on contributing to specific GitLab features - [Cached queries guidelines](cached_queries.md), for tracking down N+1 queries masked by query caching, memory profiling and why should we avoid cached queries. +- [JSON guidelines](json.md) for how to handle JSON in a performant manner. ## Database guides @@ -128,6 +129,12 @@ See [database guidelines](database/index.md). - [How to run Jenkins in development environment](integrations/jenkins.md) - [How to run local `Codesandbox` integration for Web IDE Live Preview](integrations/codesandbox.md) +The following integration guides are internal. Some integrations require access to administrative accounts of third-party services and are available only for GitLab team members to contribute to: + +- [Jira app development](https://gitlab.com/gitlab-org/manage/integrations/team/-/blob/main/integrations/jira.md) +- [Slack app development](https://gitlab.com/gitlab-org/manage/integrations/team/-/blob/main/integrations/slack.md) +- [ZenTao development](https://gitlab.com/gitlab-org/manage/integrations/team/-/blob/main/integrations/zentao.md) + ## Testing guides - [Testing standards and style guidelines](testing_guide/index.md) diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index 63dad3070c7..e6c3c20d50b 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -2,15 +2,18 @@ type: reference, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- -# Feature flag controls +# Use ChatOps to enable and disable feature flags -## Access +NOTE: +This document explains how to contribute to the development of the GitLab product. +If you want to use feature flags to show and hide functionality in your own applications, +view [this feature flags information](../../operations/feature_flags.md) instead. -To be able to turn on/off features behind feature flags in any of the -GitLab Inc. provided environments such as staging and production, you need to +To turn on/off features behind feature flags in any of the +GitLab-provided environments, like staging and production, you need to have access to the [ChatOps](../chatops_on_gitlabcom.md) bot. The ChatOps bot is currently running on the ops instance, which is different from [GitLab.com](https://gitlab.com) or [`dev.gitlab.org`](https://dev.gitlab.org). @@ -47,12 +50,12 @@ Note that all the examples in that file must be preceded by If you get an error "Whoops! This action is not allowed. This incident will be reported." that means your Slack account is not allowed to -change feature flags or you do not [have access](#access). +change feature flags or you do not have access. ### Enabling a feature for pre-production testing As a first step in a feature rollout, you should enable the feature on -[`about.staging.gitlab.com`](https://about.staging.gitlab.com) +[`staging.gitlab.com`](https://staging.gitlab.com) and [`dev.gitlab.org`](https://dev.gitlab.org). These two environments have different scopes. @@ -173,7 +176,7 @@ For project level features: Feature.enabled?(:feature_ice_cold_projects, project) ``` -If you are not certain what percentages to use, simply use the following steps: +If you are not certain what percentages to use, use the following steps: 1. 25% 1. 50% diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 444b53f9c8d..f1cde4ae1ea 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -2,24 +2,20 @@ type: reference, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Feature flags in the development of GitLab NOTE: -The documentation below covers feature flags used by GitLab to deploy its own features, which **is not** the same -as the [feature flags offered as part of the product](../../operations/feature_flags.md). - -This document provides guidelines on how to use feature flags -for the development of GitLab to conditionally and/or incrementally enable features -and test them in production/staging. +This document explains how to contribute to the development of the GitLab product. +If you want to use feature flags to show and hide functionality in your own applications, +view [this feature flags information](../../operations/feature_flags.md) instead. WARNING: All newly-introduced feature flags should be [disabled by default](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flags-in-gitlab-development). -NOTE: -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. +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. @@ -56,7 +52,7 @@ When the feature implementation is delivered among multiple merge requests: 1. When the feature is ready to be announced, create a merge request that adds documentation about the feature, including [documentation for the feature flag itself](../documentation/feature_flags.md), and a [changelog entry](#changelog). In the same merge request either flip the feature flag to - be **on by default** or remove it entirely in order to enable the new behavior. + be **on by default** or remove it entirely to enable the new behavior. One might be tempted to think that feature flags will delay the release of a feature by at least one month (= one release). This is not the case. A feature diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md index f30a041931e..7a46cd40da1 100644 --- a/doc/development/features_inside_dot_gitlab.md +++ b/doc/development/features_inside_dot_gitlab.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Features inside the `.gitlab/` directory @@ -16,6 +16,6 @@ When implementing new features, please refer to these existing features to avoid - [CODEOWNERS](../user/project/code_owners.md#set-up-code-owners): `.gitlab/CODEOWNERS`. - [Route Maps](../ci/review_apps/index.md#route-maps): `.gitlab/route-map.yml`. - [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-values-for-helm-chart): `.gitlab/auto-deploy-values.yaml`. -- [Insights](../user/project/insights/index.md#configure-your-insights): `.gitlab/insights.yml`. +- [Insights](../user/project/insights/index.md#configure-project-insights): `.gitlab/insights.yml`. - [Service Desk Templates](../user/project/service_desk.md#using-customized-email-templates): `.gitlab/service_desk_templates/`. - [Web IDE](../user/project/web_ide/index.md#web-ide-configuration-file): `.gitlab/.gitlab-webide.yml`. diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index 04e2f381c97..11acb8a2161 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File Storage in GitLab diff --git a/doc/development/fips_compliance.md b/doc/development/fips_compliance.md index 1029ed88eac..475c1a49000 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # FIPS compliance @@ -67,7 +67,7 @@ listed here that also do not work properly in FIPS mode: - [Static Application Security Testing (SAST)](../user/application_security/sast/index.md) supports a reduced set of [analyzers](../user/application_security/sast/index.md#fips-enabled-images) when operating in FIPS-compliant mode. -- Advanced Search is currently not included in FIPS mode. It must not be enabled in order to be FIPS-compliant. +- Advanced Search is currently not included in FIPS mode. It must not be enabled to be FIPS-compliant. - [Gravatar or Libravatar-based profile images](../administration/libravatar.md) are not FIPS-compliant. Additionally, these package repositories are disabled in FIPS mode: @@ -417,7 +417,7 @@ In this environment, OpenSSL refuses to perform cryptographic operations forbidden by the FIPS standards. This enables you to reproduce FIPS-related bugs, and validate fixes. -You should be able to open a web browser inside the virtual machine and log in +You should be able to open a web browser inside the virtual machine and sign in to the GitLab instance. You can disable FIPS mode again by running this command, then restarting the diff --git a/doc/development/gemfile.md b/doc/development/gemfile.md index 87304a761ea..7d3531afb49 100644 --- a/doc/development/gemfile.md +++ b/doc/development/gemfile.md @@ -1,20 +1,67 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gemfile guidelines -When adding a new entry to `Gemfile` or upgrading an existing dependency pay +When adding a new entry to `Gemfile`, or upgrading an existing dependency pay attention to the following rules. +## Bundler checksum verification + +In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98508), gem +checksums are checked before installation. This verification is still +experimental so it is only active for CI. + +If the downloaded gem's checksum does not match the checksum record in +`Gemfile.checksum`, you will see an error saying that Bundler cannot continue +installing a gem because there is a potential security issue. + +You will see this error as well if you updated, or added a new gem without +updating `Gemfile.checksum`. To fix this error, +[update the Gemfile.checksum](#updating-the-checksum-file). + +You can opt-in to this verification locally by setting the +`BUNDLER_CHECKSUM_VERIFICATION_OPT_IN` environment variable: + +```shell +export BUNDLER_CHECKSUM_VERIFICATION_OPT_IN=1 +bundle install +``` + +### Updating the checksum file + +This needs to be done for any new, or updated gems. + +1. When updating `Gemfile.lock`, make sure to also update `Gemfile.checksum` with: + + ```shell + bundle exec bundler-checksum init + ``` + +1. Check and commit the changes for `Gemfile.checksum`. + ## No gems fetched from Git repositories We do not allow gems that are fetched from Git repositories. All gems have to be available in the RubyGems index. We want to minimize external build dependencies and build times. +## Review the new dependency for quality + +We should not add 3rd-party dependencies to GitLab that would not pass our own quality standards. +This means that new dependencies should, at a minimum, meet the following criteria: + +- They have an active developer community. At the minimum a maintainer should still be active + to merge change requests in case of emergencies. +- There are no issues open that we know may impact the availablity or performance of GitLab. +- The project is tested using some form of test automation. The test suite must be passing + using the Ruby version currently used by GitLab. +- If the project uses a C extension, consider requesting an additional review from a C or MRI + domain expert. C extensions can greatly impact GitLab stability and performance. + ## Request an Appsec review When adding a new gem to our `Gemfile` or even changing versions in diff --git a/doc/development/geo.md b/doc/development/geo.md index 1ae9d9ee32b..884c09cc174 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo (development) **(PREMIUM SELF)** @@ -69,8 +69,8 @@ the lock, it switches to standby mode. Geo uses [streaming replication](#streaming-replication) to replicate the database from the **primary** to the **secondary** sites. This replication gives the **secondary** sites access to all the data saved -in the database. So users can log in on the **secondary** and read all -the issues, merge requests, and so on, on the **secondary** site. +in the database, so users can sign in to the **secondary** site and read, +for example, all the issues and merge requests. ### Repository replication diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index 18774b9b3fd..3624d280f86 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo self-service framework diff --git a/doc/development/geo/proxying.md b/doc/development/geo/proxying.md index d4cb611e965..67d4129a9d0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo proxying diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md index a20bdf633cd..dcfcd2e864a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How Git object deduplication works in GitLab diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 66b535682f5..a570b5dd7eb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly developers guide @@ -219,7 +219,7 @@ as a [CI/CD variable](../ci/variables/index.md). If you are making changes to the RPC client, such as adding a new endpoint or adding a new parameter to an existing endpoint, follow the guide for -[Gitaly protobuf specifications](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md). After pushing +[Gitaly protobuf specifications](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/protobuf.md). After pushing the branch with the changes (`new-feature-branch`, for example): 1. Change the `gitaly` line in the Rails' `Gemfile` to: diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 9740ae04553..9ba375439f4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Working with the GitHub importer @@ -114,6 +114,9 @@ GitHub are stored in a single table. Therefore, they have globally-unique IDs an Therefore, both issues and pull requests have a common API for most related things. +NOTE: +This stage is optional and can consume significant extra import time (controlled by `Gitlab::GithubImport::Settings`). + ### 9. Stage::ImportNotesWorker This worker imports regular comments for both issues and pull requests. For @@ -127,16 +130,23 @@ comments. ### 10. Stage::ImportAttachmentsWorker -This worker imports release notes attachments that are linked inside Markdown. -For every release of the project, we schedule a job of -`Gitlab::GithubImport::ImportReleaseAttachmentsWorker` for every comment. +This worker imports note attachments that are linked inside Markdown. +For each entity with Markdown text in the project, we schedule a job of: + +- `Gitlab::GithubImport::ImportReleaseAttachmentsWorker` for every release. +- `Gitlab::GithubImport::ImportNoteAttachmentsWorker` for every note. +- `Gitlab::GithubImport::ImportIssueAttachmentsWorker` for every issue. +- `Gitlab::GithubImport::ImportMergeRequestAttachmentsWorker` for every merge request. Each job: -1. Iterates over all attachment links inside of a specific release note. +1. Iterates over all attachment links inside of a specific record. 1. Downloads the attachment. 1. Replaces the old link with a newly-generated link to GitLab. +NOTE: +It's an optional stage that could consume significant extra import time (controlled by `Gitlab::GithubImport::Settings`). + ### 11. Stage::ImportProtectedBranchesWorker This worker imports protected branch rules. @@ -197,7 +207,7 @@ GitHub has a rate limit of 5,000 API calls per hour. The number of requests necessary to import a project is largely dominated by the number of unique users involved in a project (for example, issue authors). Other data such as issue pages and comments typically only requires a few dozen requests to import. This is -because we need the Email address of users in order to map them to GitLab users. +because we need the Email address of users to map them to GitLab users. We handle this by doing the following: diff --git a/doc/development/gitlab_flavored_markdown/index.md b/doc/development/gitlab_flavored_markdown/index.md index 7f7781cbc62..0af31892726 100644 --- a/doc/development/gitlab_flavored_markdown/index.md +++ b/doc/development/gitlab_flavored_markdown/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Flavored Markdown (GLFM) developer documentation **(FREE)** diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md index c1227e5d33f..95d06907aa6 100644 --- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md +++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md @@ -1,34 +1,67 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Flavored Markdown (GLFM) Specification Guide **(FREE)** +## Summary + +- _GitLab_ Flavored Markdown (GLFM) is based on + [_GitHub_ Flavored Markdown](https://github.github.com/gfm/) (GFM), + which is based on [CommonMark](https://spec.commonmark.org/current/). +- GLFM is divided into two "sets" of Markdown syntax: + - An "[official specification](#official-specifications)", + which is not dependent upon any specific + implementation or environment, and can be supported in any editor. + - "[Internal extensions](#internal-extensions)", which may be + dependent upon the GitLab environment and metadata. +- Everything in each of these sets of syntax is specified by + [special Markdown files](#input-specification-files) + based on the [CommonMark specification syntax](https://spec.commonmark.org/0.30/#about-this-document), + which contain side-by-side "examples" of Markdown and the corresponding + generated HTML, and associated documentation describing each example. +- There are also [YAML metadata files](#input-specification-files), which + may contain additional information on how individual Markdown/HTML examples + should be processed and rendered. +- These Markdown/YAML files and the examples they contain serve multiple goals: + - They are the canonical "source of truth" for how GLFM should be rendered. + - They support rendering a [formatted HTML document](#spechtml) containing all + of the examples and associated documentation, as the + [GFM and CommonMark specs](#various-markdown-specifications) also do. + - They support running standard CommonMark [conformance testing](#markdown-conformance-testing) + against the official specification. + - They support [snapshot testing](#markdown-snapshot-testing) of GitLab + internal GLFM processing logic. This is accomplished by automatically + generating YAML ["example snapshot files"](#example-snapshot-files) + which are used as fixtures to drive automated testing within the GitLab app. +- There are [various scripts and logic](#scripts) + which are used to accomplish the above goals. + +## Introduction + GitLab supports Markdown in various places. The Markdown dialect we use is called -GitLab Flavored Markdown, or GLFM. +GitLab Flavored Markdown (GLFM). + +NOTE: +In this document, _GFM_ refers to _GitHub_ Flavored Markdown, not _GitLab_ Flavored Markdown. +Refer to the [section on acronyms](#acronyms-glfm-ghfm-gfm-commonmark) +for a detailed explanation of the various acronyms used in this document. The specification for the GLFM dialect is based on the [GitHub Flavored Markdown (GFM) specification](https://github.github.com/gfm/), which is in turn based on the [CommonMark specification](https://spec.commonmark.org/current/). The GLFM specification includes -[several extensions](../../../user/markdown.md#differences-between-gitlab-flavored-markdown-and-standard-markdown) -to the GFM specification. +[many additions](../../../user/markdown.md#differences-between-gitlab-flavored-markdown-and-standard-markdown) +compared to the GFM specification. -See the [section on acronyms](#acronyms-glfm-ghfm-gfm-commonmark) for a -detailed explanation of the various acronyms used in this document. This guide is a developer-facing document that describes the various terms and definitions, goals, tools, and implementations related to the GLFM specification. It is intended to support and augment the [user-facing documentation](../../../user/markdown.md) for GitLab Flavored Markdown. NOTE: -In this document, _GFM_ refers to _GitHub_ Flavored Markdown, not _GitLab_ Flavored Markdown. -Refer to the [section on acronyms](#acronyms-glfm-ghfm-gfm-commonmark) -for a detailed explanation of the various acronyms used in this document. - -NOTE: This guide and the implementation and files described in it are still a work in progress. As the work progresses, rewrites and consolidation between this guide and the [user-facing documentation](../../../user/markdown.md) @@ -43,7 +76,7 @@ to by the acronym GFM, and this document follows that convention as well. _GitLab_ Flavored Markdown is referred to as GLFM in this document, to distinguish it from GitHub Flavored Markdown. -Unfortunately, this convention is not followed consistently in the rest +Unfortunately, this convention is not yet followed consistently in the rest of the documentation or GitLab codebase. In many places, the GFM acronym is used to refer to _GitLab_ Flavored Markdown. An [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/24592) exists to resolve @@ -53,7 +86,7 @@ Some places in the code refer to both the GitLab and GitHub specifications simultaneous in the same areas of logic. In these situations, _GitHub_ Flavored Markdown may be referred to with variable or constant names like `ghfm_` to avoid confusion. For example, we use the `ghfm` acronym for the -[`ghfm_spec_v_0.29.txt` GitHub Flavored Markdown specification file](#github-flavored-markdown-specification) +[`ghfm_spec_v_0.29.md` GitHub Flavored Markdown specification file](#github-flavored-markdown-specification), which is committed to the `gitlab` repository and used as input to the [`update_specification.rb` script](#update-specificationrb-script). @@ -77,7 +110,7 @@ Here are the HTML-rendered versions of the specifications: NOTE: The creation of the -[GitLab Flavored Markdown (GLFM) specification](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output/spec.html) +[HTML-rendered version of the GitLab Flavored Markdown (GLFM) specification](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output/spec.html) file is still pending. However, GLFM has more complex parsing, rendering, and testing requirements than @@ -134,7 +167,8 @@ Markdown for issues, pull requests, or merge requests within the editor or IDE. ### Markdown examples Everywhere in the context of the specification and this guide, the term -_examples_ is specifically used to refer to the Markdown + HTML pairs used +_examples_ is specifically used to refer to the convention of using +backtick-delimited Markdown + HTML pairs to illustrate the canonical parsing (or rendering) behavior of various Markdown source strings in the standard [CommonMark specification format](https://spec.commonmark.org/0.30/#example-1). @@ -143,6 +177,9 @@ In this context, it should not be confused with other similar or related meaning _example_, such as [RSpec examples](https://relishapp.com/rspec/rspec-core/docs/example-groups/basic-structure-describe-it). +See the section on the [`glfm_official_specification_examples.md`](#glfm_official_specification_examplesmd) file +for more details on the backtick-delimited Markdown+HTML example syntax. + ### Parsers and renderers To understand the various ways in which a specification is used, and how it related @@ -169,11 +206,20 @@ of specification-driven testing referred to in this documentation and elsewhere. #### Markdown conformance testing +NOTE: +Markdown conformance testing for GLFM is not yet implemented. + _Markdown conformance testing_ refers to the standard testing method used by all CommonMark Markdown dialects to verify that a specific implementation conforms to the CommonMark Markdown specification. It is enforced by running the standard CommonMark tool [`spec_tests.py`](https://github.com/github/cmark-gfm/blob/master/test/spec_tests.py) -against a given `spec.txt` specification and the implementation. +against a given `spec.txt` specification and the implementation, as +[described in the specification itself](https://github.github.com/gfm/#about-this-document) + +Conformance testing is _only_ to be run against GLFM [official specification](#official-specifications) +examples, and is _not_ to be run against [internal extension](#internal-extensions) examples. +This is because the internal extension examples may have dependencies on the GitLab environment +or metadata, but the standard CommonMark conformance testing tool does not support this. NOTE: `spec_tests.py` may eventually be re-implemented in Ruby, to not have a dependency on Python. @@ -187,7 +233,14 @@ tests which use the fixture data. This fixture data is contained in YAML files. are generated and updated based on the Markdown examples in the specification, and the existing GLFM parser and render implementations. They may also be manually updated as necessary to test-drive incomplete implementations. -Regarding the terminology used here: + +Snapshot testing is intended to be comprehensive, so it is run against _all_ examples - both the GLFM +[official specification](#official-specifications) and [internal extension](#internal-extensions) examples. +This means that it uses configuration files to support providing GitLab-specific environment or metadata +which is required by internal extension examples, such +as [`glfm_example_metadata.yml`](#glfm_example_metadatayml). + +Regarding the terminology used for Markdown snapshot testing: <!-- vale gitlab.InclusionCultural = NO --> @@ -270,13 +323,14 @@ implementations: ### Multiple versions of rendered HTML Both of these GLFM renderer implementations (static and WYSIWYG) produce -HTML which differs from the canonical HTML examples from the specification. -For every Markdown example in the GLFM specification, three +HTML which may differ from the canonical HTML examples in the +<abbr title="GitLab Flavored Markdown">GLFM</abbr> [official specification](#official-specifications). +Therefore, for every Markdown example in the GLFM specification, three versions of HTML can potentially be rendered from the example: -- Static HTML. -- WYSIWYG HTML. -- Canonical HTML. +- Static HTML +- WYSIWYG HTML +- Canonical HTML #### Static HTML @@ -286,22 +340,57 @@ added for dynamically creating an issue from a task list item. The GitLab [Markdown API](../../../api/markdown.md) generates HTML for a given Markdown string using this method. +The Markdown specified in the [Markdown examples](#markdown-examples) is used to automatically generate HTML in +[`glfm_specification/example_snapshots/html.yml`](#glfm_specificationexample_snapshotshtmlyml) via +[`update-example-snapshots.rb`](#update-example-snapshotsrb-script). These examples are +used when running [Markdown snapshot testing](#markdown-snapshot-testing). + #### WYSIWYG HTML **WYSIWYG HTML** is HTML produced by the frontend (JavaScript) Content Editor, which includes parsing and rendering logic. It is used to present an editable document in the ProseMirror WYSIWYG editor. +Just like static HTML, +the Markdown specified in the [Markdown examples](#markdown-examples) is used to automatically generate HTML in +[`glfm_specification/example_snapshots/html.yml`](#glfm_specificationexample_snapshotshtmlyml) via +[`update-example-snapshots.rb`](#update-example-snapshotsrb-script). These examples are +used when running [Markdown snapshot testing](#markdown-snapshot-testing). + #### Canonical HTML -**Canonical HTML** is the clean, basic version of HTML rendered from Markdown. +**Canonical HTML** is the clean, basic version of HTML rendered from Markdown, with no +unnecessary classes/elements related to styling or any other implementation-specific behavior. + +Its purpose is to support [Markdown conformance testing](#markdown-conformance-testing) against the +GLFM [`spec.txt`](#spectxt). + +Always hardcoded and manually curated, the HTML is never automatically generated. +The [Markdown examples](#markdown-examples) specifying it are contained +in different files depending on which [Markdown specification](#various-markdown-specifications) +a given example originally comes from. + +Canonical HTML is **_always specified_** for all [Markdown examples](#markdown-examples) +in the CommonMark, <abbr title="GitHub Flavored Markdown">GFM</abbr>, and <abbr title="GitLab Flavored Markdown">GLFM</abbr> +[official specifications](#official-specifications). + +However, it is **_never specified_** for GLFM [internal extensions](#internal-extensions) in the [Markdown examples](#markdown-examples). +**This is because the internal extensions are never tested via [Markdown conformance testing](#markdown-conformance-testing). +Therefore, canonical HTML for internal extension examples is never used by any scripts or automated testing.** + +Here are more details on the sources of canonical HTML examples: -1. For the examples which come from the CommonMark specification and +1. For the examples which are part of the CommonMark specification and GFM extensions specification, the canonical HTML is the exact identical HTML found in the - GFM `spec.txt` example blocks. -1. For GLFM extensions to the <abbr title="GitHub Flavored Markdown">GFM</abbr> / CommonMark - specification, a `glfm_canonical_examples.txt` [input specification file](#input-specification-files) - contains the Markdown examples and corresponding canonical HTML examples. + [GFM `spec.txt`](https://github.com/github/cmark-gfm/blob/master/test/spec.txt) [Markdown example](#markdown-examples) blocks. + These examples are copied verbatim from the GFM `spec.txt` into the GLFM + version of [`spec.txt`](#spectxt). +1. For the examples which are part of the GLFM [_official specification_](#official-specifications), + the canonical HTML is manually maintained and curated via the examples contained in the + [`glfm_official_specification_examples.md`](#glfm_official_specification_examplesmd) [input specification file](#input-specification-files). +1. For the examples which are part of the GLFM [_internal extensions_](#internal-extensions), + the canonical HTML **is never specified**, and **must be left empty in all examples** contained in + the [`glfm_internal_extension_examples.md`](#glfm_internal_extension_examplesmd) [input specification file](#input-specification-files). ### Canonicalization of HTML @@ -309,7 +398,11 @@ The rendered [static HTML](#static-html) and [WYSIWYG HTML](#wysiwyg-html) from the backend (Ruby) and frontend (JavaScript) renderers usually contains extra styling or HTML elements, to support specific appearance and behavioral requirements. -Neither the backend nor the frontend rendering logic can directly render the clean, basic canonical HTML. +Neither the backend nor the frontend rendering logic can directly render the clean, basic HTML +which is necessary to perform comparison to the [canonical HTML](#canonical-html) +when running [Markdown conformance testing](#markdown-conformance-testing) +for the [GLFM official specification examples](#glfm_official_specification_examplesmd). + Nor should they be able to, because: - It's not a direct requirement to support any GitLab application feature. @@ -318,16 +411,9 @@ Nor should they be able to, because: Instead, the rendered static or WYSIWYG HTML is converted to canonical HTML by a _canonicalization_ process. This process can strip all the extra styling and behavioral HTML from the static or WYSIWYG HTML, resulting in canonical HTML which exactly -matches the Markdown + HTML examples in a standard `spec.txt` specification. +matches the canonical HTML examples in a standard `spec.txt` specification. Use the [`canonicalize-html.rb` script](#canonicalize-htmlrb-script) for this process. -More explanation about this canonicalization process in the sections below. - -NOTE: -Some of the static or WYSIWYG HTML examples may not be representable as canonical -HTML. (For example, when they are represented as an image.) In these cases, the Markdown -conformance test for the example can be skipped by setting `skip_update_example_snapshots: true` -for the example in `glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml`. ### Normalization @@ -416,7 +502,7 @@ of how the normalizations are specified. ## Goals -Given the constraints above, we have a few goals related to the GLFM +Given all the constraints above, we can summarize the various goals related to the GLFM specification and testing infrastructure: 1. A canonical `spec.txt` exists, and represents the official specification for @@ -425,17 +511,18 @@ specification and testing infrastructure: (GFM) specification, just as <abbr title="GitHub Flavored Markdown">GFM</abbr> is a strict superset [of the CommonMark specification](https://github.github.com/gfm/#what-is-github-flavored-markdown-). - Therefore, it contains the superset of all canonical Markdown + HTML examples - for CommonMark, GFM, and GLFM. + 1. Therefore, it contains the superset of all [Markdown examples](#markdown-examples) + for CommonMark and GFM, as well as the GLFM + [official specification](#official-specifications) and [internal extensions](#internal-extensions). 1. It contains a prose introduction section which is specific to GitLab and GLFM. 1. It contains all other non-introduction sections verbatim from the - GFM - `spec.txt`. - 1. It contains a new extra section for the GLFM GitLab-specific extensions, - with both prose and examples describing the extensions. - 1. It should be in the standard format which can processed by the standard - CommonMark tools [`spec_tests.py`](https://github.com/github/cmark-gfm/blob/master/test/spec_tests.py), - which is a [script used to run the Markdown conformance tests](https://github.github.com/gfm/#about-this-document) + [GFM specification](#github-flavored-markdown-specification). + 1. It contains new, extra sections for all the additional Markdown contained in the GLFM + [official specification](#official-specifications) and [internal extensions](#internal-extensions), + with [Markdown examples](#markdown-examples) and accompanying prose, just like the CommonMark and GFM examples. + 1. All its headers and [Markdown examples](#markdown-examples) should be in the standard format which can be processed by the standard + CommonMark tool [`spec_tests.py`](https://github.com/github/cmark-gfm/blob/master/test/spec_tests.py) used to perform + [Markdown conformance testing](#markdown-conformance-testing) against all examples contained in a `spec.txt`. 1. The GLFM parsers and HTML renderers for both the static backend (Ruby) and WYSIWYG frontend (JavaScript) implementations @@ -445,9 +532,9 @@ specification and testing infrastructure: NOTE: Consistent does not mean that both of these implementations render to the identical HTML. They each have different implementation-specific additions - to the HTML they render, so therefore their rendered HTML is - ["canonicalized"](#canonicalization-of-html) to canonical HTML prior running - the Markdown conformance tests. + to the HTML they render, so their rendered HTML is + ["canonicalized"](#canonicalization-of-html) to canonical HTML prior to running + [Markdown conformance testing](#markdown-conformance-testing). 1. For _both_ the static backend (Ruby) and WYSIWYG frontend (JavaScript) implementations, a set of example snapshots exists in the form of YAML files, which correspond to every Markdown example in the GLFM `spec.txt`. These example snapshots @@ -519,7 +606,7 @@ them from the corresponding implementation class entry point files under #### `update-specification.rb` script -The `scripts/glfm/update-specification.rb` script uses specification input files to +The `scripts/glfm/update-specification.rb` script uses [input specification files](#input-specification-files) to generate and update `spec.txt` (Markdown) and `spec.html` (HTML). The `spec.html` is generated by passing the generated (or updated) `spec.txt` Markdown to the backend API for rendering to static HTML: @@ -531,14 +618,15 @@ subgraph script: A --> B{Backend Markdown API} end subgraph input:<br/>input specification files - C[ghfm_spec_v_0.29.txt] --> A - D[glfm_intro.txt] --> A - E[glfm_canonical_examples.txt] --> A + C[ghfm_spec_v_0.29.md] --> A + D[glfm_intro.md] --> A + E[glfm_official_specification_examples.md] --> A + F[glfm_internal_extension_examples.md] --> A end subgraph output:<br/>GLFM specification files - A --> F[spec.txt] - F --> B - B --> G[spec.html] + A --> G[spec.txt] + G --> B + B --> H[spec.html] end ``` @@ -650,38 +738,65 @@ subgraph output:<br/>test results/output end ``` +#### `verify-all-generated-files-are-up-to-date.rb` script + +The `scripts/glfm/verify-all-generated-files-are-up-to-date.rb` script +runs the [`update-specification.rb`](#update-specificationrb-script). +[`update-example-snapshots.rb`](#update-example-snapshotsrb-script) scripts, +It fails with an exception and non-zero return code if running these scripts +results in any diffs to the generated and committed +[output specification files](#output-specification-files) or +[example snapshot files](#example-snapshot-files). + +This script is run via the `glfm-verify` CI job to ensure that all changes to the +[input specification files](#input-specification-files) +are reflected in the generated output specification and example snapshot files. + ### Specification files These files represent the GLFM specification itself. They are all -located under the root `glfm_specification`, and are further divided into two -subfolders: - -- `input`: Contains files which are imported or manually edited. -- `output`: Contains files which are automatically generated. +located under the root `glfm_specification` and are further divided into +subcategories based on their usage and purpose: + +- `glfm_specification` + - `input`: Contains files that are downloaded or manually edited. + These are the original input to drive all other automated GLFM + specification scripts, processes, or tests. + - `github_flavored_markdown`: Contains only the downloaded and committed + [`ghfm_spec_v_0.29.md`](#github-flavored-markdown-specification) specification. + - `gitlab_flavored_markdown`: Contains all `glfm_*` files. + - `*.md` [input specification files](#input-specification-files), + which represent the GLFM specification itself. + - `*.yml` [input specification configuration files](#input-specification-configuration-files), + which control various aspects of the automated GLFM scripts and processes. + - `output`: Contains [output specification files](#output-specification-files), + which are automatically generated from the + input files by running the [`update-specification.rb`](#update-specificationrb-script) script. #### Input specification files -The `glfm_specification/input` directory contains files which are the original -input to drive all other automated GLFM specification scripts/processes/tests. -They are either downloaded, as in the case of the -GFM `spec.txt` file, or manually -updated, as in the case of all GFM files. +Input specification files are manually curated Markdown files that represent the specification itself. +They are located at `glfm_specification/input/github_flavored_markdown/*.md` and +`glfm_specification/input/gitlab_flavored_markdown/*.md`. + +See the main [specification files](#specification-files) section for more context and details. ##### GitHub Flavored Markdown specification -[`glfm_specification/input/github_flavored_markdown/ghfm_spec_v_0.29.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/github_flavored_markdown/ghfm_spec_v_0.29.txt) -is the official latest [GFM `spec.txt`](https://github.com/github/cmark-gfm/blob/master/test/spec.txt). +[`glfm_specification/input/github_flavored_markdown/ghfm_spec_v_0.29.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/github_flavored_markdown/ghfm_spec_v_0.29.md) +is a copy of the official latest [GFM `spec.txt`](https://github.com/github/cmark-gfm/blob/master/test/spec.txt). -- It is automatically downloaded and updated by `update-specification.rb` script. +- It is automatically downloaded and updated by the `update-specification.rb` script. - When it is downloaded, the version number is added to the filename. +- The extension is changed from `*.txt` to `*.md` so that it can be handled better by Markdown editors. NOTE: -This file uses the `ghfm` acronym instead of `gfm`, as +For extra clarity, this file uses the `ghfm` acronym in its name instead of `gfm`, as explained in the [Acronyms section](#acronyms-glfm-ghfm-gfm-commonmark). -##### `glfm_intro.txt` +##### `glfm_intro.md` -[`glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_intro.txt) +[`glfm_specification/input/gitlab_flavored_markdown/glfm_intro.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_intro.md) is the GitLab-specific version of the prose in the introduction section of the GLFM specification. - It is manually updated. @@ -690,13 +805,24 @@ is the GitLab-specific version of the prose in the introduction section of the G ##### `glfm_canonical_examples.txt` -[`glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt) -is the manually updated canonical Markdown+HTML examples for GLFM extensions. +The `glfm_canonical_examples.txt` file is deprecated and no longer exists. It has been replaced by two files: -- It contains examples in the [standard backtick-delimited `spec.txt` format](#various-markdown-specifications), - each of which contain a Markdown example and the corresponding canonical HTML. +- [`glfm_official_specification_examples.md`](#glfm_official_specification_examplesmd) + which contains the [GLFM official specification](#official-specifications) examples. +- [`glfm_internal_extension_examples.md`](#glfm_internal_extension_examplesmd) + which contains the [GLFM internal extension](#internal-extensions) examples. + +##### `glfm_official_specification_examples.md` + +[`glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification_examples.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification_examples.md) +consists of the manually updated Markdown+HTML examples for the +[GLFM official specification](#official-specifications), and their associated documentation and descriptions. + +- It contains [Markdown examples](#markdown-examples) in the + [standard backtick-delimited `spec.txt` format](#various-markdown-specifications), + each of which contains Markdown and the corresponding canonical HTML that should be rendered. - For all GitLab examples, the "extension" annotation after the backticks should consist of only - `example gitlab`. It does not currently include any additional extension annotations describing + `example`. It does not currently include any additional extension annotations describing the specific Markdown, unlike the GitHub Flavored Markdown examples, which do include these additional annotations (such as `example strikethrough`). - The `update-specification.rb` script inserts it as new sections before the appendix @@ -706,7 +832,53 @@ is the manually updated canonical Markdown+HTML examples for GLFM extensions. - `H3` header sections must be nested within `H2` header sections. They cannot be nested directly within `H1` header sections. -`glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt` sample entries: +`glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification_examples.md` sample entries: + +<!-- markdownlint-disable MD048 --> + +~~~plaintext +# Section with GLFM official specification examples + +## Strong + +### Strong with two asterisks + +```````````````````````````````` example +**bold** +. +<p><strong>bold</strong></p> +```````````````````````````````` + +### Strong with HTML + +```````````````````````````````` example +<strong> +bold +</strong> +. +<p><strong> +bold +</strong></p> +```````````````````````````````` +~~~ + +<!-- markdownlint-enable MD048 --> + +##### `glfm_internal_extension_examples.md` + +[`glfm_specification/input/gitlab_flavored_markdown/glfm_internal_extension_examples.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_internal_extension_examples.md) +consists of the manually updated Markdown examples for the +[GLFM internal extensions](#internal-extensions), and their associated documentation and descriptions. + +Its general format is identical to [`glfm_official_specification_examples.md`](#glfm_official_specification_examplesmd), +consisting of `H1`, `H2`, or `H3` sections containing [Markdown examples](#markdown-examples) in the +[standard backtick-delimited `spec.txt` format](#various-markdown-specifications). + +However, as described in the [canonical HTML section](#canonical-html), only the Markdown portion of each +example is specified, and the HTML portion is left empty, because internal extension examples are +never used for [Markdown conformance testing](#markdown-conformance-testing). + +`glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification_examples.md` sample entries: NOTE: All lines in this example are prefixed with a `|` character. This prefix helps avoid false @@ -714,31 +886,40 @@ errors when this file is checked by `markdownlint`, and possible errors in other The actual file should not have these prefixed `|` characters. ```plaintext -|# First GitLab-Specific Section with Examples +|# Section with GLFM Internal Extension Examples | -|## Strong but with two asterisks +|## Video | -|```````````````````````````````` example gitlab -|**bold** +|```````````````````````````````` example +| |. -|<p><strong>bold</strong></p> -|```````````````````````````````` -| -|# Second GitLab-Specific Section with Examples -| -|## Strong but with HTML -| -|```````````````````````````````` example gitlab -|<strong> -|bold -|</strong> -|. -|<p><strong> -|bold -|</strong></p> |```````````````````````````````` ``` +#### Input specification configuration files + +Input specification configuration files are manually curated YAML files that control various +aspects of the automated GLFM scripts and processes. They are located at +`glfm_specification/input/gitlab_flavored_markdown/*.yml`. + +See the main [specification files](#specification-files) section for more context and details. + +##### Configuration file validation + +All of the manually curated example names in the configuration files must correspond to +an existing [Markdown example](#markdown-examples) name found in +[`example_snapshots/examples_index.yml`](#glfm_specificationexample_snapshotsexamples_indexyml), +which is automatically generated based on the [input specification files](#input-specification-files). + +If there is an invalid reference to an example name that does not exist, the +[`scripts/glfm/update-example-snapshots.rb`](#update-example-snapshotsrb-script) +script fails with a descriptive error. + +The only exceptions to this validation are example names beginning with `00_`, which are reserved +for [YAML aliases](https://yaml.org/spec/1.2.2/#692-node-anchors). +See the section on [`glfm_example_normalizations.yml`](#glfm_example_normalizationsyml) +for more details and examples. + ##### `glfm_example_status.yml` [`glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml) @@ -801,8 +982,8 @@ The following optional entries are supported for each example. They all default ##### `glfm_example_normalizations.yml` [`glfm_specification/input/gitlab_flavored_markdown/glfm_example_normalizations.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/input/gitlab_flavored_markdown/glfm_example_normalizations.yml) -controls the [normalization](#normalization) process. It allows one or more `regex`/`replacement` pairs -to be specified for a Markdown example. +is used to control the [fixture-based normalization](#fixture-based-normalization) process. +It allows one or more `regex`/`replacement` pairs to be specified for a Markdown example. - It is manually updated. - It has a nested structure corresponding to the example and type of entry it refers to. @@ -811,6 +992,11 @@ to be specified for a Markdown example. - The YAML anchors use a naming convention based on the index number of the example, to ensure unique anchor names and avoid naming conflicts. +NOTE: +Other approaches to [normalization](#normalization) such as [fixture-based normalization](#fixture-based-normalization) +or [environment-variable-based normalization](#environment-variable-based-normalization) are always preferable to +[fixture-based normalization](#fixture-based-normalization). + `glfm_specification/input/gitlab_flavored_markdown/glfm_example_normalizations.yml` sample entries: ```yaml @@ -891,11 +1077,11 @@ allows control over other aspects of the snapshot example generation process. #### Output specification files The `glfm_specification/output` directory contains the CommonMark standard format -`spec.txt` file which represents the canonical GLFM specification which is generated +`spec.txt` file which represents the GLFM specification which is generated by the `update-specification.rb` script. It also contains the rendered `spec.html` which is generated based on the `spec.txt` as input. -These output `spec.*` files, which represent the official, canonical GLFM specification, +These output `spec.*` files, which represent the GLFM specification, are colocated under the same parent folder `glfm_specification` with the other `input` specification files. They're located here both for convenience, and because they are all a mix of manually edited and generated files. @@ -909,12 +1095,16 @@ move or copy a hosted version of the rendered HTML `spec.html` version to anothe [`glfm_specification/output/spec.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output/spec.txt) is a Markdown specification file, in the standard format -with prose and Markdown + canonical HTML examples. It is generated or updated by the -`update-specification.rb` script. +with prose and Markdown + canonical HTML examples. It also serves as input for other scripts such as `update-example-snapshots.rb` and `run-spec-tests.sh`. +It is generated or updated by the `update-specification.rb` script, using the +[input specification files](#input-specification-files) as input. +See the [`update-specification.rb` script section](#update-specificationrb-script) +for a diagram and more description on this process. + ##### spec.html [`glfm_specification/output/spec.html`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/output/spec.html) @@ -945,14 +1135,14 @@ be manually edited as necessary to help drive the implementations. [`glfm_specification/example_snapshots/examples_index.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/glfm_specification/example_snapshots/examples_index.yml) is the main list of all -CommonMark, GFM, and GLFM example names, each with a unique canonical name. +CommonMark, GFM, and GLFM example names, each with a uniquely identifying name. - It is generated from the hierarchical sections and examples in the GFM `spec.txt` specification. - For CommonMark and GFM examples, these sections originally came from the GFM `spec.txt`. -- For GLFM examples, it is generated from `glfm_canonical_examples.txt`, which is - the additional Section 7 in the GLFM `spec.txt`. +- For GLFM examples, it is generated from + [`glfm_official_specification_examples.md`](#glfm_official_specification_examplesmd) and [`glfm_internal_extension_examples.md`](#glfm_internal_extension_examplesmd). - It also contains extra metadata about each example, such as: 1. `spec_txt_example_position` - The position of the example in the generated GLFM `spec.txt` file. - This value is the index order of each individual Markdown + HTML5 example in the file. It is _not_ @@ -998,8 +1188,8 @@ for each entry in `glfm_specification/example_snapshots/examples_index.yml` it is generated (or updated) from the standard GFM `spec.txt` using the `update-example-snapshots.rb` script. - For GLFM, it is generated (or updated) from the - `glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt` - input specification file. + [`glfm_official_specification_examples.md`](#glfm_official_specification_examplesmd) and [`glfm_internal_extension_examples.md`](#glfm_internal_extension_examplesmd) + input specification files. `glfm_specification/example_snapshots/markdown.yml` sample entry: @@ -1018,8 +1208,8 @@ Three types of entries exist, with different HTML for each: - **Canonical** - The ["Canonical"](#canonicalization-of-html) HTML. - For CommonMark and GFM examples, the HTML comes from the examples in `spec.txt`. - - For GLFM examples, it is generated/updated from - `glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt`. + - For [GLFM official specification](#official-specifications) examples, it is generated/updated from + [`glfm_official_specification_examples.md`](#glfm_official_specification_examplesmd). - **Static** - This is the static (backend (Ruby)-generated) HTML for each entry in `glfm_specification/example_snapshots/examples_index.yml`. @@ -1094,13 +1284,14 @@ This section describes how the scripts can be used to manage the GLFM specificat 1. Run [`update-specification.rb`](#update-specificationrb-script) to update the GLFM specification [output specification files](#output-specification-files). 1. Visually inspect and confirm any resulting changes to the [output specification files](#output-specification-files). -1. Run [`run-spec-tests.sh`](http://gdk.test:3005/ee/development/gitlab_flavored_markdown/specification_guide/index.html#run-spec-testssh-script) to run the conformance tests against the canonicalized GLFM specification. +1. Run [`run-spec-tests.sh`](#run-spec-testssh-script) to run the conformance tests against the canonicalized GLFM specification. 1. Commit any changes to the [output specification files](#output-specification-files). ### Update the example snapshots and run snapshot tests 1. If you are working on an in-progress feature or bug, make any necessary manual updates to the [input specification files](#input-specification-files). This may include: - 1. Updating the canonical Markdown or HTML examples in `glfm_specification/input/gitlab_flavored_markdown/glfm_canonical_examples.txt`. + 1. Updating the canonical Markdown or HTML examples in + [`glfm_official_specification_examples.md`](#glfm_official_specification_examplesmd) or [`glfm_internal_extension_examples.md`](#glfm_internal_extension_examplesmd). 1. Updating `glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml` to reflect the current status of the examples or tests. 1. Run [`update-specification.rb`](#update-specificationrb-script) to update the `spec.txt` to reflect any changes which were made to the [input specification files](#input-specification-files). 1. Visually inspect and confirm any resulting changes to the [output specification files](#output-specification-files). diff --git a/doc/development/go_guide/dependencies.md b/doc/development/go_guide/dependencies.md index 7cad5bbf417..f2b1ae9e7b8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Management in Go diff --git a/doc/development/go_guide/go_upgrade.md b/doc/development/go_guide/go_upgrade.md index 4e2a0d95910..d931140d9da 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing Go versions @@ -158,6 +158,8 @@ if you need help finding the correct person or labels: | GitLab Quality Images | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab-build-images/-/issues) | | GitLab Shell | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab-shell/-/issues) | | GitLab Workhorse | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) | +| GitLab Browser-based DAST | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) | +| GitLab Coverage Fuzzer | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) | | LabKit | [Issue Tracker](https://gitlab.com/gitlab-org/labkit/-/issues) | | [Node Exporter](https://github.com/prometheus/node_exporter) | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) | | [PgBouncer Exporter](https://github.com/prometheus-community/pgbouncer_exporter) | [Issue Tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) | diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 3adafa8750f..197c7616d82 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Go standards and style guidelines @@ -357,7 +357,7 @@ Every binary ideally must have structured (JSON) logging in place as it helps with searching and filtering the logs. At GitLab we use structured logging in JSON format, as all our infrastructure assumes that. When using [Logrus](https://github.com/sirupsen/logrus) you can turn on structured -logging simply by using the build in [JSON formatter](https://github.com/sirupsen/logrus#formatters). This follows the +logging by using the build in [JSON formatter](https://github.com/sirupsen/logrus#formatters). This follows the same logging type we use in our [Ruby applications](../logging.md#use-structured-json-logging). #### How to use Logrus @@ -436,6 +436,25 @@ of the Code Review Comments page on the Go wiki for more details. Most editors/IDEs allow you to run commands before/after saving a file, you can set it up to run `goimports -local gitlab.com/gitlab-org` so that it's applied to every file when saving. +### Naming branches + +Only use the characters `a-z`, `0-9` or `-` in branch names. This restriction is due to the fact that `go get` doesn't work as expected when a branch name contains certain characters, such as a slash `/`: + +```shell +$ go get -u gitlab.com/gitlab-org/security-products/analyzers/report/v3@some-user/some-feature + +go get: gitlab.com/gitlab-org/security-products/analyzers/report/v3@some-user/some-feature: invalid version: version "some-user/some-feature" invalid: disallowed version string +``` + +If a branch name contains a slash, it forces us to refer to the commit SHA instead, which is less flexible. For example: + +```shell +$ go get -u gitlab.com/gitlab-org/security-products/analyzers/report/v3@5c9a4279fa1263755718cf069d54ba8051287954 + +go: downloading gitlab.com/gitlab-org/security-products/analyzers/report/v3 v3.15.3-0.20221012172609-5c9a4279fa12 +... +``` + ### Initializing slices If initializing a slice, provide a capacity where possible to avoid extra diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index af11340737f..25651639170 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gotchas diff --git a/doc/development/graphql_guide/authorization.md b/doc/development/graphql_guide/authorization.md index 717a6d29fbc..7b69ce36071 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL Authorization diff --git a/doc/development/graphql_guide/batchloader.md b/doc/development/graphql_guide/batchloader.md index 492d3bc9007..ef0b97f4f62 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL BatchLoader @@ -134,7 +134,7 @@ z.sync ``` NOTE: -There is no dependency analysis in the use of batch-loading. There is simply +There is no dependency analysis in the use of batch-loading. There is a pending queue of requests, and as soon as any one result is needed, all pending requests are evaluated. @@ -146,7 +146,7 @@ def publisher ::Gitlab::Graphql::Loaders::BatchModelLoader.new(::Publisher, object.publisher_id).find end -# Here we need the publisher in order to generate the catalog URL +# Here we need the publisher to generate the catalog URL def catalog_url ::Gitlab::Graphql::Lazy.with_value(publisher) do |p| UrlHelpers.book_catalog_url(publisher, object.isbn) diff --git a/doc/development/graphql_guide/graphql_pro.md b/doc/development/graphql_guide/graphql_pro.md index 3170f0cfdc2..ec28ceb4f20 100644 --- a/doc/development/graphql_guide/graphql_pro.md +++ b/doc/development/graphql_guide/graphql_pro.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL Pro @@ -16,6 +16,6 @@ The main purpose is for support. Per the website: > creator and maintainer. Get prioritized support for issues and requests. Note that we **cannot** use the Pro version directly in our product, since we are -an Open Core product - we can not require customers to purchase the Pro version, nor can we ship it. +an Open Core product - we cannot require customers to purchase the Pro version, nor can we ship it. Details on the billing account and gem licensing can be found in the Engineering 1Password vault. diff --git a/doc/development/graphql_guide/index.md b/doc/development/graphql_guide/index.md index 412825e06d3..9c6a2559e5c 100644 --- a/doc/development/graphql_guide/index.md +++ b/doc/development/graphql_guide/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL development guidelines diff --git a/doc/development/graphql_guide/monitoring.md b/doc/development/graphql_guide/monitoring.md index 28d1a4a9046..1e4c083653e 100644 --- a/doc/development/graphql_guide/monitoring.md +++ b/doc/development/graphql_guide/monitoring.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring GraphQL diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md index 72f321a1fd2..7b9d2158c60 100644 --- a/doc/development/graphql_guide/pagination.md +++ b/doc/development/graphql_guide/pagination.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GraphQL pagination diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index ea22b33f1bc..158eb19764b 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Internationalization for GitLab diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index 0870a0e6750..757bcc0ebf1 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Translate GitLab to your language diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md index 43f19f8a9d6..2a086c796c9 100644 --- a/doc/development/i18n/merging_translations.md +++ b/doc/development/i18n/merging_translations.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merging translations from Crowdin @@ -79,7 +79,7 @@ recreate it with the following steps: ## Manually update the translation levels There's no automated way to pull the translation levels from Crowdin, to display -this information in the language selection dropdown. Therefore, the translation +this information in the language selection dropdown list. Therefore, the translation levels are hard-coded in the `TRANSLATION_LEVELS` constant in [`i18n.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/i18n.rb), and must be regularly updated. diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index f986a852567..b5d57f9912b 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Proofread Translations @@ -65,6 +65,7 @@ are very appreciative of the work done by translators and proofreaders! - Michael Hahnle - [GitLab](https://gitlab.com/mhah), [Crowdin](https://crowdin.com/profile/mhah) - Katrin Leinweber - [GitLab](https://gitlab.com/katrinleinweber), [Crowdin](https://crowdin.com/profile/katrinleinweber) - Vladislav Wanner - [GitLab](https://gitlab.com/RumBugen), [Crowdin](https://crowdin.com/profile/RumBugen) + - Daniel Ziegenberg - [GitLab](https://gitlab.com/ziegenberg), [Crowdin](https://crowdin.com/profile/ziegenberg) - Greek - Proofreaders needed. - Hebrew diff --git a/doc/development/i18n/translation.md b/doc/development/i18n/translation.md index 61f9d7a25c3..2c8d7eac2a6 100644 --- a/doc/development/i18n/translation.md +++ b/doc/development/i18n/translation.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Translating GitLab diff --git a/doc/development/image_scaling.md b/doc/development/image_scaling.md index 2078db8294c..4b19c21a457 100644 --- a/doc/development/image_scaling.md +++ b/doc/development/image_scaling.md @@ -1,7 +1,7 @@ --- stage: Data Stores group: Application Performance -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Image scaling guide @@ -13,7 +13,7 @@ For a general introduction to the history of image scaling at GitLab, you might ## Why image scaling? -Since version 13.6, GitLab scales down images on demand in order to reduce the page data footprint. +Since version 13.6, GitLab scales down images on demand to reduce the page data footprint. This both reduces the amount of data "on the wire", but also helps with rendering performance, since the browser has less work to do. @@ -68,7 +68,7 @@ controller mixin. Upon receiving a request coming from a client through Workhors it should trigger the image scaler as per the criteria mentioned above, and if so, render a special response header field (`Gitlab-Workhorse-Send-Data`) with the necessary parameters for Workhorse to carry out the scaling request. If Rails decides the request does not constitute a valid image scaling request, -we simply follow the path we take to serve any ordinary upload. +we follow the path we take to serve any ordinary upload. ### Workhorse diff --git a/doc/development/import_export.md b/doc/development/import_export.md index c66ac0418ac..f864dd3b678 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import/Export development documentation diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 1f3bf860257..b879d635350 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Test Import Project @@ -16,7 +16,7 @@ There are several ways to import a project. ### Importing via UI -The first option is to simply [import the Project tarball file via the GitLab UI](../user/project/settings/import_export.md#import-a-project-and-its-data): +The first option is to [import the Project tarball file via the GitLab UI](../user/project/settings/import_export.md#import-a-project-and-its-data): 1. Create the group `qa-perf-testing` 1. Import the [GitLab FOSS project tarball](https://gitlab.com/gitlab-org/quality/performance-data/-/blob/master/projects_export/gitlabhq_export.tar.gz) into the Group. @@ -59,7 +59,7 @@ This script was introduced in GitLab 12.6 for importing large GitLab project exp As part of this script we also disable direct and background upload to avoid situations where a huge archive is being uploaded to GCS (while being inside a transaction, which can cause idle transaction timeouts). -We can simply run this script from the terminal: +We can run this script from the terminal: Parameters: @@ -111,7 +111,7 @@ The specified project export file in `archive_path` is missing. ##### `Exception: Permission denied @ rb_sysopen - (filename)` -The specified project export file can not be accessed by the `git` user. +The specified project export file cannot be accessed by the `git` user. Setting the file owner to `git:git`, changing the file permissions to `0400`, and moving it to a public folder (for example `/tmp/`) fixes the issue. diff --git a/doc/development/index.md b/doc/development/index.md index 34e6f466664..d4a34051bc8 100644 --- a/doc/development/index.md +++ b/doc/development/index.md @@ -3,7 +3,7 @@ comments: false type: index, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "Development Guidelines: learn how to contribute to GitLab." --- diff --git a/doc/development/integrations/codesandbox.md b/doc/development/integrations/codesandbox.md index 8fd1f0e331d..d7d0ea48db0 100644 --- a/doc/development/integrations/codesandbox.md +++ b/doc/development/integrations/codesandbox.md @@ -1,7 +1,7 @@ --- stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up local CodeSandbox development environment diff --git a/doc/development/integrations/index.md b/doc/development/integrations/index.md index 0387ba2e4dd..a0a81775391 100644 --- a/doc/development/integrations/index.md +++ b/doc/development/integrations/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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: "GitLab's development guidelines for Integrations" --- diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index bb541d26df2..f314f4536e2 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # How to run Jenkins in development environment (on macOS) **(FREE)** diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index ade81e29ffb..fb0d239db46 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up a development environment **(FREE)** diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 2c5dd1c0500..f40caf29cfa 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Security scanner integration @@ -180,7 +180,7 @@ Here are some examples to get you started: As documented in the [Docker Official Images](https://github.com/docker-library/official-images#tags-and-aliases) project, it is strongly encouraged that version number tags be given aliases which allows the user to easily refer to the "most recent" release of a particular series. -See also [Docker Tagging: Best practices for tagging and versioning Docker images](https://docs.microsoft.com/en-us/archive/blogs/stevelasker/docker-tagging-best-practices-for-tagging-and-versioning-docker-images). +See also [Docker Tagging: Best practices for tagging and versioning Docker images](https://learn.microsoft.com/en-us/archive/blogs/stevelasker/docker-tagging-best-practices-for-tagging-and-versioning-docker-images). ## Command line @@ -358,6 +358,10 @@ analyzer to use the latest available schemas. After the deprecation period for a schema version, the file is removed from GitLab. Reports that declare removed versions are rejected, and an error message displays on the corresponding pipeline. +If a report uses a `PATCH` version that doesn't match any vendored schema version, it is validated against +the latest vendored `PATCH` version. For example, if a report version is 14.0.23 and the latest vendored +version is 14.0.6, the report is validated against version 14.0.6. + GitLab uses the [`json_schemer`](https://www.rubydoc.info/gems/json_schemer) gem to perform validation. @@ -430,10 +434,29 @@ The value of the `category` field matches the report type: - `sast` - `dast` -##### Scanner +##### Scan + +The `scan` field is an object that embeds meta information about the scan itself: the `analyzer` +and `scanner` that performed the scan, the `start_time` and `end_time` the scan executed, +and `status` of the scan (either "success" or "failure"). + +Both the `analyzer` and `scanner` fields are objects that embeds a human-readable `name` and a technical `id`. +The `id` should not collide with any other analyzers or scanners another integrator would provide. + +##### Scan Primary Identifiers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. Disabled by default. + +The `scan.primary_identifiers` field is an optional field containing an array of +[primary identifiers](../../user/application_security/terminology/index.md#primary-identifier)). +This is an exhaustive list of all rulesets for which the analyzer performed the scan. + +Even when the [`Vulnerabilities`](#vulnerabilities) array for a given scan may be empty, this optional field +should contain the complete list of potential identifiers to inform the Rails application of which +rules were executed. -The `scanner` field is an object that embeds a human-readable `name` and a technical `id`. -The `id` should not collide with any other scanner another integrator would provide. +When populated, the Rails application will automatically resolve previously detected vulnerabilities as no +longer relevant when their primary identifier is not included. ##### Name, message, and description diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index 63f86a3f95d..ba0654971d3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure Partner Integration - Onboarding Process diff --git a/doc/development/interacting_components.md b/doc/development/interacting_components.md index c137faf464c..f4becd06245 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Developing against interacting components or features diff --git a/doc/development/internal_api/index.md b/doc/development/internal_api/index.md index c35d40a7b7f..9b77a20a0d6 100644 --- a/doc/development/internal_api/index.md +++ b/doc/development/internal_api/index.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- # Internal API **(FREE)** -The internal API is used by different GitLab components, it can not be +The internal API is used by different GitLab components, it cannot be used by other consumers. This documentation is intended for people working on the GitLab codebase. @@ -21,7 +21,7 @@ Before adding a new internal endpoint, consider if the API would potentially be useful to the wider GitLab community and can be made externally accessible. One reason we might favor internal API endpoints sometimes is when using such an endpoint requires -internal data that external actors can not have. For example, in the internal Pages API we might use +internal data that external actors cannot have. For example, in the internal Pages API we might use a secret token that identifies a request as internal or sign a request with a public key that is not available to a wider community. @@ -665,8 +665,7 @@ Example response: ## Subscriptions -The subscriptions endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`) -in order to apply subscriptions including trials, and add-on purchases, for personal namespaces or top-level groups within GitLab.com. +The subscriptions endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`) to apply subscriptions including trials, and add-on purchases, for personal namespaces or top-level groups within GitLab.com. ### Creating a subscription @@ -966,3 +965,253 @@ Example response: ### Known consumers - CustomersDot + +## SCIM API **(PREMIUM SAAS)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10. + +The SCIM API implements the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). As this API is for +**system** use for SCIM provider integration, it is subject to change without notice. + +To use this API, [Group SSO](../../user/group/saml_sso/index.md) must be enabled for the group. +This API is only in use where [SCIM for Group SSO](../../user/group/saml_sso/scim_setup.md) is enabled. It's a prerequisite to the creation of SCIM identities. + +Not to be confused with the [main SCIM API](../../api/scim.md). + +### 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. + +```plaintext +GET /api/scim/v2/groups/:group_path/Users +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `filter` | string | no | A [filter](#available-filters) expression. | +| `group_path` | string | yes | Full path to the group. | +| `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one will be interpreted as 1. | +| `count` | integer | no | Desired maximum number of query results. | + +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: + +```shell +curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \ + --header "Authorization: Bearer <your_scim_token>" \ + --header "Content-Type: application/scim+json" +``` + +Example response: + +```json +{ + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "totalResults": 1, + "itemsPerPage": 20, + "startIndex": 1, + "Resources": [ + { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", + "active": true, + "name.formatted": "Test User", + "userName": "username", + "meta": { "resourceType":"User" }, + "emails": [ + { + "type": "work", + "value": "name@example.com", + "primary": true + } + ] + } + ] +} +``` + +### Get a single SCIM provisioned user + +```plaintext +GET /api/scim/v2/groups/:group_path/Users/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `id` | string | yes | External UID of the user. | +| `group_path` | string | yes | Full path to the group. | + +Example request: + +```shell +curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +Example response: + +```json +{ + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", + "active": true, + "name.formatted": "Test User", + "userName": "username", + "meta": { "resourceType":"User" }, + "emails": [ + { + "type": "work", + "value": "name@example.com", + "primary": true + } + ] +} +``` + +### Create a SCIM provisioned user + +```plaintext +POST /api/scim/v2/groups/:group_path/Users/ +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:---------------|:----------|:----|:--------------------------| +| `externalId` | string | yes | External UID of the user. | +| `userName` | string | yes | Username of the user. | +| `emails` | JSON string | yes | Work email. | +| `name` | JSON string | yes | Name of the user. | +| `meta` | string | no | Resource type (`User`). | + +Example request: + +```shell +curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/groups/test_group/Users" \ + --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +Example response: + +```json +{ + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", + "active": true, + "name.formatted": "Test User", + "userName": "username", + "meta": { "resourceType":"User" }, + "emails": [ + { + "type": "work", + "value": "name@example.com", + "primary": true + } + ] +} +``` + +Returns a `201` status code if successful. + +### Update a single SCIM provisioned user + +Fields that can be updated are: + +| SCIM/IdP field | GitLab field | +|:---------------------------------|:-----------------------------------------------------------------------------| +| `id/externalId` | `extern_uid` | +| `name.formatted` | `name` ([Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/363058)) | +| `emails\[type eq "work"\].value` | `email` ([Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/363058)) | +| `active` | Identity removal if `active` = `false` | +| `userName` | `username` ([Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/363058)) | + +```plaintext +PATCH /api/scim/v2/groups/:group_path/Users/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `id` | string | yes | External UID of the user. | +| `group_path` | string | yes | Full path to the group. | +| `Operations` | JSON string | yes | An [operations](#available-operations) expression. | + +Example request: + +```shell +curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --data '{ "Operations": [{"op":"Add","path":"name.formatted","value":"New Name"}] }' \ + --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. + +```plaintext +DELETE /api/scim/v2/groups/:group_path/Users/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| ------------ | ------ | -------- | ------------------------- | +| `id` | string | yes | External UID of the user. | +| `group_path` | string | yes | Full path to the group. | + +Example request: + +```shell +curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \ + --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +Returns an empty response with a `204` status code if successful. + +### Available filters + +They match an expression as specified in [the RFC7644 filtering section](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2). + +| Filter | Description | +| ----- | ----------- | +| `eq` | The attribute matches exactly the specified value. | + +Example: + +```plaintext +id eq a-b-c-d +``` + +### Available operations + +They perform an operation as specified in [the RFC7644 update section](https://www.rfc-editor.org/rfc/rfc7644#section-3.5.2). + +| Operator | Description | +| ----- | ----------- | +| `Replace` | The attribute's value is updated. | +| `Add` | The attribute has a new value. | + +Example: + +```json +{ "op": "Add", "path": "name.formatted", "value": "New Name" } +``` diff --git a/doc/development/internal_api/internal_api_allowed.md b/doc/development/internal_api/internal_api_allowed.md index 83dbb54babd..89c76c88df4 100644 --- a/doc/development/internal_api/internal_api_allowed.md +++ b/doc/development/internal_api/internal_api_allowed.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/development/internal_users.md b/doc/development/internal_users.md index 24785c0cf48..67000d969af 100644 --- a/doc/development/internal_users.md +++ b/doc/development/internal_users.md @@ -3,7 +3,7 @@ description: "Internal users documentation." type: concepts, reference, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Internal users diff --git a/doc/development/issuable-like-models.md b/doc/development/issuable-like-models.md index 42dfe2e0f2f..0b48883fe58 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issuable-like Rails models utilities diff --git a/doc/development/issue_types.md b/doc/development/issue_types.md index 820c37aeb14..465f539e026 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue Types (DEPRECATED) @@ -42,7 +42,7 @@ issues or when linking objects of the type from Epics. It should use the same - You can't close it from a commit or a merge request. - You can't mark it as related to another issue. -If an Issue type can not be used you can still define a first-class type and +If an Issue type cannot be used you can still define a first-class type and then include concerns such as `Issuable` or `Noteable` to reuse functionality which is common for all our issue-related resources. But you still need to define the interface for working with the new resource and update some other diff --git a/doc/development/json.md b/doc/development/json.md new file mode 100644 index 00000000000..8a2575401fb --- /dev/null +++ b/doc/development/json.md @@ -0,0 +1,46 @@ +--- +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 +--- + +# JSON Guidelines + +At GitLab we handle a lot of JSON data. To best ensure we remain performant +when handling large JSON encodes or decodes, we use our own JSON class +instead of the default methods. + +## `Gitlab::Json` + +This class should be used in place of any calls to the default `JSON` class, +`.to_json` calls, and the like. It implements the majority of the public +methods provided by `JSON`, such as `.parse`, `.generate`, `.dump`, etc, and +should be entirely identical in its response. + +The difference being that by sending all JSON handling through `Gitlab::Json` +we can change the gem being used in the background. We use `oj` +instead of the `json` gem, which uses C extensions and is therefore notably +faster. + +This class came into existence because, due to the age of the GitLab application, +it was proving impossible to just replace the `json` gem with `oj` by default because: + +- The number of tests with exact expectations of the responses. +- The subtle variances between different JSON processors, particularly + around formatting. + +The `Gitlab::Json` class takes this into account and can +vary the adapter based on the use case, and account for outdated formatting +expectations. + +## `Gitlab::Json::PrecompiledJson` + +This class is used by our hooks into the Grape framework to ensure that +already-generated JSON is not then run through JSON generation +a second time when returning the response. + +## `Gitlab::Json::LimitedEncoder` + +This class can be used to generate JSON but fail with an error if the +resulting JSON would be too large. The default limit for the `.encode` +method is 25 MB, but this can be customized when using the method. diff --git a/doc/development/kubernetes.md b/doc/development/kubernetes.md index 1c83bef5620..e7764326db3 100644 --- a/doc/development/kubernetes.md +++ b/doc/development/kubernetes.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Kubernetes integration - development guidelines **(FREE)** diff --git a/doc/development/lfs.md b/doc/development/lfs.md index 20157e9e805..4d3371af1d4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git LFS **(FREE)** diff --git a/doc/development/licensing.md b/doc/development/licensing.md index a50c514733e..d7dfdb7357d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Licensing and Compatibility @@ -18,7 +18,7 @@ Some gems may not include their license information in their `gemspec` file, and ### License Finder commands -There are a few basic commands License Finder provides that you need in order to manage license detection. +There are a few basic commands License Finder provides that you need to manage license detection. To verify that the checks are passing, and/or to see what dependencies are causing the checks to fail: diff --git a/doc/development/logging.md b/doc/development/logging.md index 467fb68f3ae..44a47f96de1 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Developers Guide to Logging **(FREE)** diff --git a/doc/development/maintenance_mode.md b/doc/development/maintenance_mode.md index f70cca1040e..b61b7472385 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Internal workings of GitLab Maintenance Mode **(PREMIUM SELF)** diff --git a/doc/development/mass_insert.md b/doc/development/mass_insert.md index 4b1716ff00a..24f6127a3de 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mass inserting Rails models diff --git a/doc/development/merge_request_application_and_rate_limit_guidelines.md b/doc/development/merge_request_application_and_rate_limit_guidelines.md index 62bf62f6275..07a48ad7723 100644 --- a/doc/development/merge_request_application_and_rate_limit_guidelines.md +++ b/doc/development/merge_request_application_and_rate_limit_guidelines.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Application and rate limit guidelines diff --git a/doc/development/merge_request_concepts/index.md b/doc/development/merge_request_concepts/index.md index d463f6ba290..14d9582ad84 100644 --- a/doc/development/merge_request_concepts/index.md +++ b/doc/development/merge_request_concepts/index.md @@ -2,7 +2,7 @@ type: reference, dev stage: Create group: Code Review -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Merge request concepts diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 895fc6f92a4..9d1489836fb 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge Request Performance Guidelines @@ -44,7 +44,7 @@ and running. Can the queries used potentially take down any critical services and result in engineers being woken up in the night? Can a malicious user abuse the code to -take down a GitLab instance? Do my changes simply make loading a certain page +take down a GitLab instance? Do my changes make loading a certain page slower? Does execution time grow exponentially given enough load or data in the database? @@ -281,7 +281,7 @@ be clearly mentioned in the merge request description. ## Batch process **Summary:** Iterating a single process to external services (for example, PostgreSQL, Redis, Object Storage) -should be executed in a **batch-style** in order to reduce connection overheads. +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. @@ -488,7 +488,7 @@ We can consider the following types of storages: - **Object-based persistent storage** (long term storage) this type of storage uses external services like [AWS S3](https://en.wikipedia.org/wiki/Amazon_S3). The Object Storage can be treated as infinitely scalable and redundant. Accessing this storage usually requires - downloading the file in order to manipulate it. The Object Storage can be considered as an ultimate + downloading the file to manipulate it. The Object Storage can be considered as an ultimate solution, as by definition it can be assumed that it can handle unlimited concurrent uploads and downloads of files. This is also ultimate solution required to ensure that application can run in containerized deployments (Kubernetes) at ease. diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 4e569579f37..f59c1fd8368 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migration Style Guide @@ -175,6 +175,14 @@ git checkout origin/master db/structure.sql VERSION=<migration ID> bundle exec rails db:migrate:main ``` +### Adding new tables to GitLab Schema + +GitLab connects to two different Postgres databases: `main` and `ci`. New tables should be defined in [`lib/gitlab/database/gitlab_schemas.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/gitlab_schemas.yml) with the databases they need to be added to. + + ```yaml + <TABLE_NAME>: :gitlab_main + ``` + ## Avoiding downtime The document ["Avoiding downtime in migrations"](database/avoiding_downtime_in_migrations.md) specifies @@ -267,7 +275,7 @@ in that limit. Singular query timings should fit within the [standard limit](dat In case you need to insert, update, or delete a significant amount of data, you: - Must disable the single transaction with `disable_ddl_transaction!`. -- Should consider doing it in a [Background Migration](database/background_migrations.md). +- Should consider doing it in a [batched background migration](database/batched_background_migrations.md). ## Migration helpers and versioning @@ -604,7 +612,7 @@ Note that it is not necessary to check if the index exists prior to removing it, however it is required to specify the name of the index that is being removed. This can be done either by passing the name as an option to the appropriate form of `remove_index` or `remove_concurrent_index`, -or more simply by using the `remove_concurrent_index_by_name` method. Explicitly +or by using the `remove_concurrent_index_by_name` method. Explicitly specifying the name is important to ensure the correct index is removed. For a small table (such as an empty one or one with less than `1,000` records), @@ -982,6 +990,43 @@ NOTE: `add_sequence` should be avoided for columns with foreign keys. Adding sequence to these columns is **only allowed** in the down method (restore previous schema state). +## Swapping primary key + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98645) in GitLab 15.5. + +Swapping the primary key is required to partition a table as the **partition key must be included in the primary key**. + +You can use the `swap_primary_key` method provided by the database team. + +Under the hood, it works like this: + +- Drop the primary key constraint. +- Add the primary key using the index defined beforehand. + +```ruby +class SwapPrimaryKey < Gitlab::Database::Migration[2.0] + TABLE_NAME = :table_name + PRIMARY_KEY = :table_name_pkey + OLD_INDEX_NAME = :old_index_name + NEW_INDEX_NAME = :new_index_name + + def up + swap_primary_key(TABLE_NAME, PRIMARY_KEY, NEW_INDEX_NAME) + end + + def down + add_concurrent_index(TABLE_NAME, :id, unique: true, name: OLD_INDEX_NAME) + add_concurrent_index(TABLE_NAME, [:id, :partition_id], unique: true, name: NEW_INDEX_NAME) + + unswap_primary_key(TABLE_NAME, PRIMARY_KEY, OLD_INDEX_NAME) + end +end +``` + +NOTE: +Make sure to introduce the new index beforehand in a separate migration in order +to swap the primary key. + ## Integer column type By default, an integer column can hold up to a 4-byte (32-bit) number. That is @@ -1221,7 +1266,7 @@ by an integer. For example: `users` would turn into `users0` ## Using models in migrations (discouraged) The use of models in migrations is generally discouraged. As such models are -[contraindicated for background migrations](database/background_migrations.md#isolation), +[contraindicated for batched background migrations](database/batched_background_migrations.md#isolation), the model needs to be declared in the migration. If using a model in the migrations, you should first @@ -1236,7 +1281,7 @@ in a previous migration. ### Example: Add a column `my_column` to the users table -It is important not to leave out the `User.reset_column_information` command, in order to ensure that the old schema is dropped from the cache and ActiveRecord loads the updated schema information. +It is important not to leave out the `User.reset_column_information` command, to ensure that the old schema is dropped from the cache and ActiveRecord loads the updated schema information. ```ruby class AddAndSeedMyColumn < Gitlab::Database::Migration[2.0] diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md index 8e39186d396..733823d7f6e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 0f3531cf5dd..808554d6027 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Backwards compatibility across updates diff --git a/doc/development/omnibus.md b/doc/development/omnibus.md index 4e2f2b0c763..a0ba2751a06 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # What you should know about Omnibus packages diff --git a/doc/development/packages.md b/doc/development/packages.md deleted file mode 100644 index a79f5f09677..00000000000 --- a/doc/development/packages.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'packages/index.md' -remove_date: '2022-08-19' ---- - -This document was moved to [another location](packages/index.md). - -<!-- This redirect file can be deleted after <2022-08-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/development/packages/debian_repository.md b/doc/development/packages/debian_repository.md index a417ced2e65..71f6c916652 100644 --- a/doc/development/packages/debian_repository.md +++ b/doc/development/packages/debian_repository.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Debian Repository diff --git a/doc/development/packages/dependency_proxy.md b/doc/development/packages/dependency_proxy.md new file mode 100644 index 00000000000..f3e323fb9fa --- /dev/null +++ b/doc/development/packages/dependency_proxy.md @@ -0,0 +1,197 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Dependency Proxy + +The Dependency Proxy is a pull-through-cache for registry images from DockerHub. This document describes how this +feature is constructed in GitLab. + +## Container registry + +The Dependency Proxy for the container registry acts a stand-in for a remote container registry. In our case, +the remote registry is the public DockerHub registry. + +```mermaid +flowchart TD + id1([$ docker]) --> id2([GitLab Dependency Proxy]) + id2 --> id3([DockerHub]) +``` + +From the user's perspective, the GitLab instance is just a container registry that they are interacting with to +pull images by using `docker login gitlab.com` + +When you use `docker login gitlab.com`, the Docker client uses the [v2 API](https://docs.docker.com/registry/spec/api/) +to make requests. + +To support authentication, we must include one route: + +- [API Version Check](https://docs.docker.com/registry/spec/api/#api-version-check) + +To support `docker pull` requests, we must include two additional routes: + +- [Pulling an image manifest](https://docs.docker.com/registry/spec/api/#pulling-an-image-manifest) +- [Pulling an image layer (blob)](https://docs.docker.com/registry/spec/api/#pulling-a-layer) + +These routes are defined in [`gitlab-org/gitlab/config/routes/group.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/3f76455ac9cf90a927767e55c837d6b07af818df/config/routes/group.rb#L164-175). + +In its simplest form, the Dependency Proxy manages three requests: + +- Logging in / returning a JWT +- Fetching a manifest +- Fetching a blob + +Here is what the general request sequence looks like for the Dependency Proxy: + +```mermaid +sequenceDiagram + Client->>+GitLab: Login? / request token + GitLab->>+Client: JWT + Client->>+GitLab: request a manifest for an image + GitLab->>+ExternalRegistry: request JWT + ExternalRegistry->>+GitLab : JWT + GitLab->>+ExternalRegistry : request manifest + ExternalRegistry->>+GitLab : return manifest + GitLab->>+GitLab : store manifest + GitLab->>+Client : return manifest + loop request image layers + Client->>+GitLab: request a blob from the manifest + GitLab->>+ExternalRegistry: request JWT + ExternalRegistry->>+GitLab : JWT + GitLab->>+ExternalRegistry : request blob + ExternalRegistry->>+GitLab : return blob + GitLab->>+GitLab : store blob + GitLab->>+Client : return blob + end +``` + +### Authentication and authorization + +When a Docker client authenticates with a registry, the registry tells the client where to get a JSON Web Token +(JWT) and to use it for all subsequent requests. This allows the authentication service to live in a separate +application from the registry. For example, the GitLab container registry directs Docker clients to get a token +from `https://gitlab.com/jwt/auth`. This endpoint is part of the `gitlab-org/gitlab` project, also known as the +rails project or web service. + +When a user tries to sign in to the dependency proxy with a Docker client, we must tell it where to get a JWT. We +can use the same endpoint we use with the container registry: `https://gitlab.com/jwt/auth`. But in our case, +we tell the Docker client to specify `service=dependency_proxy` in the parameters so can use a separate underlying +service to generate the token. + +This sequence diagram shows the request flow for logging into the Dependency Proxy. + +```mermaid +sequenceDiagram + autonumber + participant C as Docker CLI + participant R as GitLab (Dependency Proxy) + + Note right of C: User tries `docker login gitlab.com` and enters username/password + C->>R: GET /v2/ + Note left of R: Check for Authorization header, return 401 if none, return 200 if token exists and is valid + R->>C: 401 Unauthorized with header "WWW-Authenticate": "Bearer realm=\"http://gitlab.com/jwt/auth\",service=\"registry.docker.io\"" + Note right of C: Request Oauth token using HTTP Basic Auth + C->>R: GET /jwt/auth + Note left of R: Token is returned + R->>C: 200 OK (with Bearer token included) + Note right of C: original request is tested again + C->>R: GET /v2/ (this time with `Authorization: Bearer [token]` header) + Note right of C: Login Succeeded + R->>C: 200 OK +``` + +The dependency proxy uses its own authentication service, separate from the authentication managed by the UI +(`ApplicationController`) and API (`ApiGuard`). Once the service has created a JWT, the `DependencyProxy::ApplicationController` +manages authentication and authorization for the rest of the requests. It manages the user by using `GitLab::Auth::Result` and +is similar to the authentication implemented by the Git client requests in `GitHttpClientController`. + +### Caching + +Blobs are cached artifacts with no logic around them. We cache them by digest. When we receive a request for a new blob, +we check to see if we have a blob with the requested digest, and return it. Otherwise we fetch it from the external +registry and cache it. + +Manifests are more complicated, partially due to [rate limiting on DockerHub](https://www.docker.com/increase-rate-limits/). +A manifest is essentially a recipe for creating an image. It has a list of blobs to create a certain image. So +`alpine:latest` has a manifest associated with it that specifies the blobs needed to create the `alpine:latest` +image. The interesting part is that `alpine:latest` can change over time, so we can't just cache the manifest and +assume it is OK to use forever. Instead, we must check the digest of the manifest, which is an Etag. This gets +interesting because the requests for manifests often don't include the digest. So how do we know if the manifest +we have cached is still the most up-to-date `alpine:latest`? DockerHub allows free HEAD requests that don't count +toward their rate limit. The HEAD request returns the manifest digest so we can tell whether or not the one we +have is stale. + +With this knowledge, we have built the following logic to manage manifest requests: + +```mermaid +graph TD + A[Receive manifest request] --> | We have the manifest cached.| B{Docker manifest HEAD request} + A --> | We do not have manifest cached.| C{Docker manifest GET request} + B --> | Digest matches the one in the DB | D[Fetch manifest from cache] + B --> | Network failure, cannot reach DockerHub | D[Fetch manifest from cache] + B --> | Digest does not match the one in DB | C + C --> E[Save manifest to cache, save digest to database] + D --> F + E --> F[Return manifest] +``` + +### Workhorse for file handling + +Management of file uploads and caching happens in [Workhorse](../workhorse/index.md). This explains the additional +[`POST` routes](https://gitlab.com/gitlab-org/gitlab/-/blob/3f76455ac9cf90a927767e55c837d6b07af818df/config/routes/group.rb#L170-173) +that we have for the Dependency Proxy. + +The [send_dependency](https://gitlab.com/gitlab-org/gitlab/-/blob/7359d23f4e078479969c872924150219c6f1665f/app/helpers/workhorse_helper.rb#L46-53) +method makes a request to Workhorse including the previously fetched JWT from the external registry. Workhorse then +can use that token to request the manifest or blob the user originally requested. The Workhorse code lives in +[`workhorse/internal/dependencyproxy/dependencyproxy.go`](https://gitlab.com/gitlab-org/gitlab/-/blob/b8f44a8f3c26efe9932c2ada2df75ef7acb8417b/workhorse/internal/dependencyproxy/dependencyproxy.go#L4). + +Once we put it all together, the sequence for requesting an image file looks like this: + +```mermaid +sequenceDiagram + Client->>Workhorse: GET /v2/*group_id/dependency_proxy/containers/*image/manifests/*tag + Workhorse->>Rails: GET /v2/*group_id/dependency_proxy/containers/*image/manifests/*tag + Rails->>Rails: Check DB. Is manifest persisted in cache? + + alt In Cache + Rails->>Workhorse: Respond with send-url injector + Workhorse->>Client: Send the file to the client + else Not In Cache + Rails->>Rails: Generate auth token and download URL for the manifest in upstream registry + Rails->>Workhorse: Respond with send-dependency injector + Workhorse->>External Registry: Request the manifest + External Registry->>Workhorse: Download the manifest + Workhorse->>Rails: GET /v2/*group_id/dependency_proxy/containers/*image/manifest/*tag/authorize + Rails->>Workhorse: Respond with upload instructions + Workhorse->>Client: Send the manifest file to the client with original headers + Workhorse->>Object Storage: Save the manifest file with some of it's header values + Workhorse->>Rails: Finalize the upload + end +``` + +### Cleanup policies + +The cleanup policies for the Dependency Proxy work as time-to-live policies. They allow users to set the number +of days a file is allowed to remain cached if it has been unread. Since there is no way to associate the blobs +with the images they belong to (to do this, we would need to build the metadata database that the container registry +folks built), we can set up rules like "if this blob has not been pulled in 90 days, delete it". This means that +any files that are continuously getting pulled will not be removed from the cache, but if, for example, +`alpine:latest` changes and one of the underlying blobs is no longer used, it will eventually get cleaned up +because it has stopped getting pulled. We use the `read_at` attribute to track the last time a given +`dependency_proxy_blob` or `dependency_proxy_manifest` was pulled. + +These work using a cron worker, [DependencyProxy::CleanupDependencyProxyWorker](https://gitlab.com/gitlab-org/gitlab/-/blob/7359d23f4e078479969c872924150219c6f1665f/app/workers/dependency_proxy/cleanup_dependency_proxy_worker.rb#L4), +that will kick off two [limited capacity](../sidekiq/limited_capacity_worker.md) workers: one to delete blobs, +and one to delete manifests. The capacity is set in an [application setting](settings.md#container-registry). + +### Historic reference links + +- [Dependency proxy for private groups](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46042) - initial authentication implementation +- [Manifest caching](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) - initial manifest caching implementation +- [Workhorse for blobs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71890) - initial workhorse implementation +- [Workhorse for manifest](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73033) - moving manifest cache logic to Workhorse +- [Deploy token support](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64363) - authorization largely updated +- [SSO support](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67373) - changes how policies are checked diff --git a/doc/development/packages/index.md b/doc/development/packages/index.md index 55deaa229ba..41d6e1b84fd 100644 --- a/doc/development/packages/index.md +++ b/doc/development/packages/index.md @@ -1,13 +1,15 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Registry Development Development and Architectural documentation for the package registry +- [Debian repository structure](debian_repository.md) +- [Dependency proxy structure](dependency_proxy.md) - [Developing a new format](new_format_development.md) - [Settings](settings.md) - [Structure / Schema](structure.md) diff --git a/doc/development/packages/new_format_development.md b/doc/development/packages/new_format_development.md index 73a2b2f1f81..e9decea3094 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 -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Developing support for a new package format diff --git a/doc/development/packages/settings.md b/doc/development/packages/settings.md index 37961c0504c..d591f708954 100644 --- a/doc/development/packages/settings.md +++ b/doc/development/packages/settings.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Settings diff --git a/doc/development/packages/structure.md b/doc/development/packages/structure.md index f8d9da2cc73..e5426f8e2b8 100644 --- a/doc/development/packages/structure.md +++ b/doc/development/packages/structure.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Structure diff --git a/doc/development/pages/index.md b/doc/development/pages/index.md index af9d4d33683..6ee8a9ac433 100644 --- a/doc/development/pages/index.md +++ b/doc/development/pages/index.md @@ -2,7 +2,7 @@ type: reference, dev stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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: "GitLab's development guidelines for GitLab Pages" --- diff --git a/doc/development/performance.md b/doc/development/performance.md index 479782e0ccf..4f22d9ceb03 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performance Guidelines @@ -79,7 +79,7 @@ GitLab provides built-in tools to help improve performance and availability: - [Service measurement](service_measurement.md) for measuring and logging service execution. GitLab team members can use [GitLab.com's performance monitoring systems](https://about.gitlab.com/handbook/engineering/monitoring/) located at -[`dashboards.gitlab.net`](https://dashboards.gitlab.net), this requires you to log in using your +[`dashboards.gitlab.net`](https://dashboards.gitlab.net), this requires you to sign in using your `@gitlab.com` email address. Non-GitLab team-members are advised to set up their own Prometheus and Grafana stack. @@ -391,7 +391,7 @@ We store these results also when running nightly scheduled CI jobs on the default branch on `gitlab.com`. Statistics of these profiling data are [available online](https://gitlab-org.gitlab.io/rspec_profiling_stats/). For example, you can find which tests take longest to run or which execute the most -queries. This can be handy for optimizing our tests or identifying performance +queries. Use this to optimize our tests or identify performance issues in our code. ## Memory optimization @@ -925,7 +925,7 @@ SOME_CONSTANT = 'bar' ## How to seed a database with millions of rows You might want millions of project rows in your local database, for example, -in order to compare relative query performance, or to reproduce a bug. You could +to compare relative query performance, or to reproduce a bug. You could do this by hand with SQL commands or using [Mass Inserting Rails Models](mass_insert.md) functionality. Assuming you are working with ActiveRecord models, you might also find these links helpful: diff --git a/doc/development/permissions.md b/doc/development/permissions.md index d348d659cad..cc7c1229e50 100644 --- a/doc/development/permissions.md +++ b/doc/development/permissions.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Implementing permissions @@ -37,7 +37,7 @@ Groups and projects can have the following visibility levels: - private (`0`) - an entity is visible only to the approved members of the entity By default, subgroups can **not** have higher visibility levels. -For example, if you create a new private group, it can not include a public subgroup. +For example, if you create a new private group, it cannot include a public subgroup. The visibility level of a group can be changed only if all subgroups and sub-projects have the same or lower visibility level. For example, a group can be set diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 648a2aac339..01e42fda2c9 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipelines for the GitLab project @@ -62,11 +62,14 @@ The test mappings contain a map of each source files to a list of test files whi In the `detect-tests` job, we use this mapping to identify the minimal tests needed for the current merge request. +Later on in [the `rspec fail-fast` job](#fail-fast-job-in-merge-request-pipelines), we run the minimal tests needed for the current merge request. + #### Exceptional cases In addition, there are a few circumstances where we would always run the full RSpec tests: - when the `pipeline:run-all-rspec` label is set on the merge request +- when the `pipeline:run-full-rspec` label is set on the merge request, this label is assigned by triage automation when the merge request is approved by any reviewer - when the merge request is created by an automation (for example, Gitaly update or MR targeting a stable branch) - when the merge request is created in a security mirror - when any CI configuration file is changed (for example, `.gitlab-ci.yml` or `.gitlab/ci/**/*`) @@ -92,23 +95,11 @@ In addition, there are a few circumstances where we would always run the full Je ### Fork pipelines -We only run the minimal RSpec & Jest jobs for fork pipelines unless the `pipeline:run-all-rspec` +We run only the minimal RSpec & Jest jobs for fork pipelines, unless the `pipeline:run-all-rspec` label is set on the MR. The goal is to reduce the CI/CD minutes consumed by fork pipelines. See the [experiment issue](https://gitlab.com/gitlab-org/quality/team-tasks/-/issues/1170). -## Faster feedback when reverting merge requests - -When you need to revert a merge request, to get accelerated feedback, you can add the `~pipeline:revert` label to your merge request. - -When this label is assigned, the following steps of the CI/CD pipeline are skipped: - -- The `e2e:package-and-test` job. -- The `rspec:undercoverage` job. -- The entire [Review Apps process](testing_guide/review_apps.md). - -Apply the label to the merge request, and run a new pipeline for the MR. - ## Fail-fast job in merge request pipelines To provide faster feedback when a merge request breaks existing tests, we are experimenting with a @@ -155,6 +146,18 @@ merge request. This prevents `rspec fail-fast` duration from exceeding the avera This number can be overridden by setting a CI/CD variable named `RSPEC_FAIL_FAST_TEST_FILE_COUNT_THRESHOLD`. +## Faster feedback when reverting merge requests + +When you need to revert a merge request, to get accelerated feedback, you can add the `~pipeline:revert` label to your merge request. + +When this label is assigned, the following steps of the CI/CD pipeline are skipped: + +- The `e2e:package-and-test` job. +- The `rspec:undercoverage` job. +- The entire [Review Apps process](testing_guide/review_apps.md). + +Apply the label to the merge request, and run a new pipeline for the MR. + ## Test jobs We have dedicated jobs for each [testing level](testing_guide/testing_levels.md) and each job runs depending on the @@ -356,6 +359,11 @@ with latest `master`, and then it triggers a regular branch pipeline for never be merged back to `master`. Any other Ruby 3 changes should go into `master` directly, which should be compatible with Ruby 2.7. +Previously, `ruby3-sync` was using a project token stored in `RUBY3_SYNC_TOKEN` +(now backed up in `RUBY3_SYNC_TOKEN_NOT_USED`), however due to various +permissions issues, we ended up using an access token from `gitlab-bot` so now +`RUBY3_SYNC_TOKEN` is actually an access token from `gitlab-bot`. + ### Long-term plan We follow the [PostgreSQL versions shipped with Omnibus GitLab](../administration/package_information/postgresql_versions.md): @@ -392,8 +400,7 @@ In general, pipelines for an MR fall into one of the following types (from short A "pipeline type" is an abstract term that mostly describes the "critical path" (for example, the chain of jobs for which the sum of individual duration equals the pipeline's duration). -We use these "pipeline types" in [metrics dashboards](https://app.periscopedata.com/app/gitlab/858266/GitLab-Pipeline-Durations) -in order to detect what types and jobs need to be optimized first. +We use these "pipeline types" in [metrics dashboards](https://app.periscopedata.com/app/gitlab/858266/GitLab-Pipeline-Durations) to detect what types and jobs need to be optimized first. An MR that touches multiple areas would be associated with the longest type applicable. For instance, an MR that touches backend and frontend would fall into the "Frontend" pipeline type since this type takes longer to finish than the "Backend" pipeline type. @@ -581,8 +588,9 @@ The current stages are: ### Dependency Proxy Some of the jobs are using images from Docker Hub, where we also use -`${GITLAB_DEPENDENCY_PROXY}` as a prefix to the image path, so that we pull +`${GITLAB_DEPENDENCY_PROXY_ADDRESS}` as a prefix to the image path, so that we pull images from our [Dependency Proxy](../user/packages/dependency_proxy/index.md). +By default, this variable is set from the value of `${GITLAB_DEPENDENCY_PROXY}`. `${GITLAB_DEPENDENCY_PROXY}` is a group CI/CD variable defined in [`gitlab-org`](https://gitlab.com/gitlab-org) as @@ -590,13 +598,32 @@ images from our [Dependency Proxy](../user/packages/dependency_proxy/index.md). defined as: ```yaml -image: ${GITLAB_DEPENDENCY_PROXY}alpine:edge +image: ${GITLAB_DEPENDENCY_PROXY_ADDRESS}alpine:edge ``` Projects in the `gitlab-org` group pull from the Dependency Proxy, while forks that reside on any other personal namespaces or groups fall back to Docker Hub unless `${GITLAB_DEPENDENCY_PROXY}` is also defined there. +#### Work around for when a pipeline is started by a Project access token user + +When a pipeline is started by a Project access token user (e.g. the `release-tools approver bot` user which +automatically updates the Gitaly version used in the main project), +[the Dependency proxy isn't accessible](https://gitlab.com/gitlab-org/gitlab/-/issues/332411#note_1130388163) +and the job fails at the `Preparing the "docker+machine" executor` step. +To work around that, we have a special workflow rule, that overrides the +`${GITLAB_DEPENDENCY_PROXY_ADDRESS}` variable so that Depdendency proxy isn't used in that case: + +```yaml +- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $GITLAB_USER_LOGIN =~ /project_\d+_bot\d*/' + variables: + GITLAB_DEPENDENCY_PROXY_ADDRESS: "" +``` + +NOTE: +We don't directly override the `${GITLAB_DEPENDENCY_PROXY}` variable because group-level +variables have higher precedence over `.gitlab-ci.yml` variables. + ### Common job definitions Most of the jobs [extend from a few CI definitions](../ci/yaml/index.md#extends) @@ -731,7 +758,7 @@ This works well for the following reasons: - `.static-analysis-cache` - `.rubocop-cache` - `.coverage-cache` - - `.danger-review-cache` + - `.ruby-node-cache` - `.qa-cache` - `.yarn-cache` - `.assets-compile-cache` (the key includes `${NODE_ENV}` so it's actually two different caches). @@ -749,34 +776,87 @@ This works well for the following reasons: ### Artifacts strategy -We limit the artifacts that are saved and retrieved by jobs to the minimum in order to reduce the upload/download time and costs, as well as the artifacts storage. +We limit the artifacts that are saved and retrieved by jobs to the minimum to reduce the upload/download time and costs, as well as the artifacts storage. ### Components caching -Some external components (currently only GitLab Workhorse) of GitLab need to be built from source as a preliminary step for running tests. +Some external components (GitLab Workhorse and frontend assets) of GitLab need to be built from source as a preliminary step for running tests. + +#### `cache-workhorse` -In [this MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79766), we introduced a new `build-components` job that: +In [this MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79766), and then +[this MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96297), +we introduced a new `cache-workhorse` job that: - runs automatically for all GitLab.com `gitlab-org/gitlab` scheduled pipelines - runs automatically for any `master` commit that touches the `workhorse/` folder -- is manual for GitLab.com's `gitlab-org`'s MRs +- is manual for GitLab.com's `gitlab-org`'s MRs that touches caching-related files This job tries to download a generic package that contains GitLab Workhorse binaries needed in the GitLab test suite (under `tmp/tests/gitlab-workhorse`). - If the package URL returns a 404: 1. It runs `scripts/setup-test-env`, so that the GitLab Workhorse binaries are built. 1. It then creates an archive which contains the binaries and upload it [as a generic package](https://gitlab.com/gitlab-org/gitlab/-/packages/). -- Otherwise, if the package already exists, it exit the job successfully. +- Otherwise, if the package already exists, it exits the job successfully. We also changed the `setup-test-env` job to: -1. First download the GitLab Workhorse generic package build and uploaded by `build-components`. +1. First download the GitLab Workhorse generic package build and uploaded by `cache-workhorse`. 1. If the package is retrieved successfully, its content is placed in the right folder (for example, `tmp/tests/gitlab-workhorse`), preventing the building of the binaries when `scripts/setup-test-env` is run later on. 1. If the package URL returns a 404, the behavior doesn't change compared to the current one: the GitLab Workhorse binaries are built as part of `scripts/setup-test-env`. NOTE: The version of the package is the workhorse tree SHA (for example, `git rev-parse HEAD:workhorse`). +#### `cache-assets` + +In [this MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96297), +we introduced three new `cache-assets:test`, `cache-assets:test as-if-foss`, +and `cache-assets:production` jobs that: + +- never run unless `$CACHE_ASSETS_AS_PACKAGE == "true"` +- runs automatically for all GitLab.com `gitlab-org/gitlab` scheduled pipelines +- runs automatically for any `master` commit that touches the assets-related folders +- is manual for GitLab.com's `gitlab-org`'s MRs that touches caching-related files + +This job tries to download a generic package that contains GitLab compiled assets +needed in the GitLab test suite (under `app/assets/javascripts/locale/**/app.js`, +and `public/assets`). + +- If the package URL returns a 404: + 1. It runs `bin/rake gitlab:assets:compile`, so that the GitLab assets are compiled. + 1. It then creates an archive which contains the assets and uploads it [as a generic package](https://gitlab.com/gitlab-org/gitlab/-/packages/). + The package version is set to the assets folders' hash sum. +- Otherwise, if the package already exists, it exits the job successfully. + +#### `compile-*-assets` + +We also changed the `compile-test-assets`, `compile-test-assets as-if-foss`, +and `compile-production-assets` jobs to: + +1. First download the "native" cache assets, which contain: + - The [compiled assets](https://gitlab.com/gitlab-org/gitlab/-/blob/a6910c9086bb28e553f5e747ec2dd50af6da3c6b/.gitlab/ci/global.gitlab-ci.yml#L86-87). + - A [`cached-assets-hash.txt` file](https://gitlab.com/gitlab-org/gitlab/-/blob/a6910c9086bb28e553f5e747ec2dd50af6da3c6b/.gitlab/ci/global.gitlab-ci.yml#L85) + containing the `SHA256` hexdigest of all the source files on which the assets depend on. + This list of files is a pessimistic list and the assets might not depend on + some of these files. At worst we compile the assets more often, which is better than + using outdated assets. + + The file is [created after assets are compiled](https://gitlab.com/gitlab-org/gitlab/-/blob/a6910c9086bb28e553f5e747ec2dd50af6da3c6b/.gitlab/ci/frontend.gitlab-ci.yml#L83). +1. We then we compute the `SHA256` hexdigest of all the source files the assets depend on, **for the current checked out branch**. We [store the hexdigest in the `GITLAB_ASSETS_HASH` variable](https://gitlab.com/gitlab-org/gitlab/-/blob/a6910c9086bb28e553f5e747ec2dd50af6da3c6b/.gitlab/ci/frontend.gitlab-ci.yml#L27). +1. If `$CACHE_ASSETS_AS_PACKAGE == "true"`, we download the generic package built and uploaded by [`cache-assets:*`](#cache-assets). + - If the cache is up-to-date for the checked out branch, we download the native cache + **and** the cache package. We could optimize that by not downloading + the genetic package but the native cache is actually very often outdated because it's + rebuilt only every 2 hours. +1. We [run the `assets_compile_script` function](https://gitlab.com/gitlab-org/gitlab/-/blob/a6910c9086bb28e553f5e747ec2dd50af6da3c6b/.gitlab/ci/frontend.gitlab-ci.yml#L35), + which [itself runs](https://gitlab.com/gitlab-org/gitlab/-/blob/c023191ef412e868ae957f3341208a41ca678403/scripts/utils.sh#L76) + the [`assets:compile` Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/c023191ef412e868ae957f3341208a41ca678403/lib/tasks/gitlab/assets.rake#L80-109). + + This task is responsible for deciding if assets need to be compiled or not. + It [compares the `HEAD` `SHA256` hexdigest from `$GITLAB_ASSETS_HASH` with the `master` hexdigest from `cached-assets-hash.txt`](https://gitlab.com/gitlab-org/gitlab/-/blob/c023191ef412e868ae957f3341208a41ca678403/lib/tasks/gitlab/assets.rake#L86). +1. If the hashes are the same, we don't compile anything. If they're different, we compile the assets. + ### Pre-clone step NOTE: diff --git a/doc/development/policies.md b/doc/development/policies.md index ddd6b8e9bce..b50d654ed28 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # `DeclarativePolicy` framework diff --git a/doc/development/polling.md b/doc/development/polling.md index f854891a528..ff239effb80 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Polling with ETag caching @@ -61,5 +61,5 @@ route matching easier. For more information see: - [`Poll-Interval` header](fe_guide/performance.md#real-time-components) -- [RFC 7232](https://tools.ietf.org/html/rfc7232) +- [RFC 7232](https://www.rfc-editor.org/rfc/rfc7232) - [ETag proposal](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26926) diff --git a/doc/development/post_deployment_migrations.md b/doc/development/post_deployment_migrations.md deleted file mode 100644 index c3922718e77..00000000000 --- a/doc/development/post_deployment_migrations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'database/post_deployment_migrations.md' -remove_date: '2022-07-08' ---- - -This document was moved to [another location](database/post_deployment_migrations.md). - -<!-- This redirect file can be deleted after <2022-07-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 (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/product_qualified_lead_guide/index.md b/doc/development/product_qualified_lead_guide/index.md index 90b8d905264..89a05d59fc9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Product Qualified Lead (PQL) development guide diff --git a/doc/development/profiling.md b/doc/development/profiling.md index a3142b06e12..3eb2c7c9144 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Profiling @@ -20,6 +20,9 @@ The first argument to the profiler is either a full URL (including the instance hostname) or an absolute path, including the leading slash. +By default the report dump will be stored in a temporary file, which can be +interacted with using the [stackprof API](#reading-a-gitlabprofiler-report). + When using the script, command-line documentation is available by passing no arguments. @@ -31,10 +34,11 @@ For example: ```ruby Gitlab::Profiler.profile('/my-user') -# Returns a RubyProf::Profile for the regular operation of this request +# Returns the location of the temp file where the report dump is stored class UsersController; def show; sleep 100; end; end Gitlab::Profiler.profile('/my-user') -# Returns a RubyProf::Profile where 100 seconds is spent in UsersController#show +# Returns the location of the temp file where the report dump is stored +# where 100 seconds is spent in UsersController#show ``` For routes that require authorization you must provide a user to @@ -52,57 +56,14 @@ documented with the method source. Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first, logger: Logger.new($stdout)) ``` -There is also a RubyProf printer available: -`Gitlab::Profiler::TotalTimeFlatPrinter`. This acts like -`RubyProf::FlatPrinter`, but its `min_percent` option works on the method's -total time, not its self time. (This is because we often spend most of our time -in library code, but this comes from calls in our application.) It also offers a -`max_percent` option to help filter out outer calls that aren't useful (like -`ActionDispatch::Integration::Session#process`). - -There is a convenience method for using this, -`Gitlab::Profiler.print_by_total_time`: - -```ruby -result = Gitlab::Profiler.profile('/my-user') -Gitlab::Profiler.print_by_total_time(result, max_percent: 60, min_percent: 2) -# Measure Mode: wall_time -# Thread ID: 70005223698240 -# Fiber ID: 70004894952580 -# Total: 1.768912 -# Sort by: total_time -# -# %self total self wait child calls name -# 0.00 1.017 0.000 0.000 1.017 14 *ActionView::Helpers::RenderingHelper#render -# 0.00 1.017 0.000 0.000 1.017 14 *ActionView::Renderer#render_partial -# 0.00 1.017 0.000 0.000 1.017 14 *ActionView::PartialRenderer#render -# 0.00 1.007 0.000 0.000 1.007 14 *ActionView::PartialRenderer#render_partial -# 0.00 0.930 0.000 0.000 0.930 14 Hamlit::TemplateHandler#call -# 0.00 0.928 0.000 0.000 0.928 14 Temple::Engine#call -# 0.02 0.865 0.000 0.000 0.864 638 *Enumerable#inject -``` - -To print the profile in HTML format, use the following example: - -```ruby -result = Gitlab::Profiler.profile('/my-user') - -printer = RubyProf::CallStackPrinter.new(result) -printer.print(File.open('/tmp/profile.html', 'w')) -``` - -### Stackprof support - -By default, `Gitlab::Profiler.profile` uses a tracing profiler called [`ruby-prof`](https://ruby-prof.github.io/). However, sampling profilers -[run faster and use less memory](https://jvns.ca/blog/2017/12/17/how-do-ruby---python-profilers-work-/), so they might be preferred. - -You can switch to [Stackprof](https://github.com/tmm1/stackprof) (a sampling profiler) to generate a profile by passing `sampling_mode: true`. Pass in a `profiler_options` hash to configure the output file (`out`) of the sampling data. For example: ```ruby -Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first, sampling_mode: true, profiler_options: { out: 'tmp/profile.dump' }) +Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first, profiler_options: { out: 'tmp/profile.dump' }) ``` +## Reading a GitLab::Profiler report + You can get a summary of where time was spent by running Stackprof against the sampling data. For example: ```shell @@ -244,7 +205,7 @@ Example output: ``` NOTE: -This endpoint is only available for Rails web workers. Sidekiq workers can not be inspected this way. +This endpoint is only available for Rails web workers. Sidekiq workers cannot be inspected this way. ## Settings that impact performance @@ -286,7 +247,7 @@ The following table lists these variables along with their default values. ([Source](https://github.com/ruby/ruby/blob/45b29754cfba8435bc4980a87cd0d32c648f8a2e/gc.c#L254-L308)) -GitLab may decide to change these settings in order to speed up application performance, lower memory requirements, or both. +GitLab may decide to change these settings to speed up application performance, lower memory requirements, or both. You can see how each of these settings affect GC performance, memory use and application start-up time for an idle instance of GitLab by running the `scripts/perf/gc/collect_gc_stats.rb` script. It will output GC stats and general timing data to standard diff --git a/doc/development/project_templates.md b/doc/development/project_templates.md index f688d54ad4f..2f1ded23e38 100644 --- a/doc/development/project_templates.md +++ b/doc/development/project_templates.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Contribute a built-in project template @@ -50,7 +50,7 @@ Before GitLab can implement the project template, you must [create a merge reque 1. [Export the project](../user/project/settings/import_export.md#export-a-project-and-its-data) and save the file as `<name>.tar.gz`, where `<name>` is the short name of the project. Move this file to the root directory of `gitlab-org/gitlab`. -1. In `gitlab-org/gitlab`, create and checkout a new branch. +1. In `gitlab-org/gitlab`, create and check out a new branch. 1. Edit the following files to include the project template: - For **non-Enterprise** project templates: - In `lib/gitlab/project_template.rb`, add details about the template diff --git a/doc/development/projections.md b/doc/development/projections.md index e1dc37a7ce8..e45a16c267d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Projections diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index b3f259efc3d..c2caa354567 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Working with Prometheus Metrics **(FREE)** diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md index 6751559b2ef..8ad584a8edc 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pry debugging diff --git a/doc/development/python_guide/index.md b/doc/development/python_guide/index.md index 77dd328b513..08d2f46c1cd 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Python Development Guidelines diff --git a/doc/development/rails_initializers.md b/doc/development/rails_initializers.md index fca24cf8c01..24647429a57 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rails initializers diff --git a/doc/development/rails_update.md b/doc/development/rails_update.md index bda21860eae..a541de020fb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rails update guidelines diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index f300904fc19..505f480c410 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rake tasks for developers diff --git a/doc/development/reactive_caching.md b/doc/development/reactive_caching.md index b4deffe162a..3239748193f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # `ReactiveCaching` diff --git a/doc/development/real_time.md b/doc/development/real_time.md index f113d4dd3b7..2aa48fed8eb 100644 --- a/doc/development/real_time.md +++ b/doc/development/real_time.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Real-Time Features @@ -19,7 +19,7 @@ out using the instructions below. ## Reuse an existing WebSocket connection Features reusing an existing connection incur minimal risk. Feature flag rollout -is recommended in order to give more control to self-hosting customers. However, +is recommended to give more control to self-hosting customers. However, it is not necessary to roll out in percentages, or to estimate new connections for GitLab.com. diff --git a/doc/development/redis.md b/doc/development/redis.md index e48048be624..75c7df0737b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redis guidelines diff --git a/doc/development/redis/new_redis_instance.md b/doc/development/redis/new_redis_instance.md index 24885b40eb9..d9d4bb6a9f8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Add a new Redis instance diff --git a/doc/development/refactoring_guide/index.md b/doc/development/refactoring_guide/index.md index 9793db3bb85..5dd505ff5c6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Refactoring guide @@ -18,14 +18,14 @@ Pinning tests help you ensure that you don't unintentionally change the output o 1. For each possible input, identify the significant possible values. 1. Create a test to save a full detailed snapshot for each helpful combination values per input. This should guarantee that we have "pinned down" the current behavior. The snapshot could be literally a screenshot, a dump of HTML, or even an ordered list of debugging statements. 1. Run all the pinning tests against the code, before you start refactoring (Oracle) -1. Perform the refactor (or checkout the commit with the work done) +1. Perform the refactor (or check out the commit with the work done) 1. Run again all the pinning test against the post refactor code (Pin) 1. Compare the Oracle with the Pin. If the Pin is different, you know the refactoring doesn't preserve existing behavior. 1. Repeat the previous three steps as necessary until the refactoring is complete. ### Example commit history -Leaving in the commits for adding and removing pins helps others checkout and verify the result of the test. +Leaving in the commits for adding and removing pins helps others check out and verify the result of the test. ```shell AAAAAA Add pinning tests to funky_foo @@ -77,7 +77,7 @@ expect(cleanForSnapshot(wrapper.element)).toMatchSnapshot(); - [Pinning test in a Haml to Vue refactor](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27691#pinning-tests) - [Pinning test in isolating a bug](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32198#note_212736225) -- [Pinning test in refactoring dropdown](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28173) +- [Pinning test in refactoring dropdown list](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28173) - [Pinning test in refactoring vulnerability_details.vue](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25830/commits) - [Pinning test in refactoring notes_award_list.vue](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29528#pinning-test) - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Video of pair programming session on pinning tests](https://youtu.be/LrakPcspBK4) diff --git a/doc/development/reference_processing.md b/doc/development/reference_processing.md index 1dfe6496e79..5a026e0a2a0 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/engineering/ux/technical-writing/#assignments +info: To 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: '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 bd25fa1377e..ee759efd7e2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Renaming features diff --git a/doc/development/repository_mirroring.md b/doc/development/repository_mirroring.md index 573ffaccaf9..a9164398afb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository mirroring diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index 826782d7036..2701192137c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Guidelines for reusing abstractions @@ -63,7 +63,7 @@ do so, but then we'd need as many options as we have features. Every option adds two code paths, which means that for four features we have to cover 8 different code paths. -A much more reliable (and pleasant) way of dealing with this, is to simply use +A much more reliable (and pleasant) way of dealing with this, is to use the underlying bits that make up `GroupProjectsFinder` directly. This means we may need a little bit more code in `IssuableFinder`, but it also gives us much more control and certainty. This means we might end up with something like this: @@ -96,7 +96,7 @@ This is just a sketch, but it shows the general idea: we would use whatever the ## End goal The guidelines in this document are meant to foster _better_ code reuse, by -clearly defining what can be reused where, and what to do when you can not reuse +clearly defining what can be reused where, and what to do when you cannot reuse something. Clearly separating abstractions makes it harder to use the wrong one, makes it easier to debug the code, and (hopefully) results in fewer performance problems. @@ -122,7 +122,7 @@ the various abstractions and what they can (not) reuse: Everything in `app/controllers`. -Controllers should not do much work on their own, instead they simply pass input +Controllers should not do much work on their own, instead they pass input to other classes and present the results. ### API endpoints @@ -135,40 +135,70 @@ API endpoints have the same abstraction level as controllers. Everything that resides in `app/services`. -Services should consider inheriting from: - -- `BaseContainerService` for services scoped by container (project or group) -- `BaseProjectService` for services scoped to projects -- `BaseGroupService` for services scoped to groups - -or, create a new base class and update the list above. - -Legacy classes inherited from `BaseService` for historical reasons. - -In Service classes the use of `execute` and `#execute` is preferred over `call` and `#call`. - -Model properties should be passed to the constructor in a `params` hash, and will be assigned directly. - -To pass extra parameters (which need to be processed, and are not model properties), -include an `options` hash in the constructor and store it in an instance variable: - -```ruby -# container: Project, or Group -# current_user: Current user -# params: Model properties from the controller, already allowlisted with strong parameters -# options: Configuration for this service, can be any of the following: -# notify: Whether to send a notifcation to the current user -# cc: Email address to copy when sending a notification -def initialize(container:, current_user: nil, params: {}, options: {}) - super(container, current_user, params) - @options = options -end -``` - -View the [initial discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90008#note_988744060) -and [further discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90853#note_1053425083). - -Classes that are not service objects should be [created elsewhere](directory_structure.md#use-namespaces-to-define-bounded-contexts), such as in `lib`. +Service classes represent operations that coordinates changes between models +(such as entities and value objects). Changes impact the state of the application. + +1. When an object makes no changes to the state of the application, then it's not a service. + It may be a [finder](#finders) or a value object. +1. When there is no operation, there is no need to execute a service. The class would + probably be better designed as an entity, a value object, or a policy. + +When implementing a service class, consider: + +1. A service class initializer should contain in its arguments: + 1. A [model](#models) instance that is being acted upon. Should be first positional + argument of the initializer. The argument name of the argument is left to the + developer's discretion, such as: `issue`, `project`, `merge_request`. + 1. When service represents an action initiated by a user or executed in the + context of a user, the initializer must have the `current_user:` keyword argument. + Services with `current_user:` argument run high-level business logic. + 1. When service does not have a user context and it's not directly initiated + by a user (like background service or side-effects), the `current_user:` + argument is not needed. This describes low-level domain logic or instance-wide logic. + 1. For all additional data required by a service, the explicit keyword arguments are recommended. + When a service requires too long of a list of arguments, consider splitting them into: + - `params`: A hash with model properties that will be assigned directly. + - `options`: A hash with extra parameters (which need to be processed, + and are not model properties). The `options` hash should be stored in an instance variable. + + ```ruby + # merge_request: A model instance that is being acted upon. + # assignee: new MR assignee that will be assigned to the MR + # after the service is executed. + def initialize(merge_request, assignee:) + @merge_request = merge_request + @assignee = assignee + end + ``` + + ```ruby + # issue: A model instance that is being acted upon. + # current_user: Current user. + # params: Model properties. + # options: Configuration for this service. Can be any of the following: + # - notify: Whether to send a notification to the current user. + # - cc: Email address to copy when sending a notification. + def initialize(issue:, current_user:, params: {}, options: {}) + @issue = issue + @current_user = current_user + @params = params + @options = options + end + ``` + +1. It implements a single public instance method `#execute`, which invokes service class behavior: + - The `#execute` method takes no arguments. All required data is passed into initializer. + - Optional. If needed, the `#execute` method returns its result via [`ServiceResponse`](#serviceresponse). + +Several base classes implement the service classes convention. You may consider inheriting from: + +- `BaseContainerService` for services scoped by container (project or group). +- `BaseProjectService` for services scoped to projects. +- `BaseGroupService` for services scoped to groups. + +Classes that are not service objects should be +[created elsewhere](directory_structure.md#use-namespaces-to-define-bounded-contexts), +such as in `lib`. #### ServiceResponse @@ -235,7 +265,7 @@ For example: `:job_not_retriable`, `:duplicate_package`, `:merge_request_not_mer Everything in `app/finders`, typically used for retrieving data from a database. -Finders can not reuse other finders in an attempt to better control the SQL +Finders cannot reuse other finders in an attempt to better control the SQL queries they produce. Finders' `execute` method should return `ActiveRecord::Relation`. Exceptions diff --git a/doc/development/routing.md b/doc/development/routing.md index 54a531730f9..16ed15fdcc6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Routing diff --git a/doc/development/ruby3_gotchas.md b/doc/development/ruby3_gotchas.md index db328b0b1a5..4768d6e1182 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Ruby 3 gotchas diff --git a/doc/development/ruby_upgrade.md b/doc/development/ruby_upgrade.md index 3b89a6fd1ea..ccd65b4e7e9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Ruby upgrade guidelines diff --git a/doc/development/scalability.md b/doc/development/scalability.md index 66f436bd391..671086f33b2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab scalability @@ -216,7 +216,7 @@ core. It does not support multi-threading. Dumb secondaries: Redis secondaries (also known as replicas) don't actually handle any load. Unlike PostgreSQL secondaries, they don't even serve -read queries. They simply replicate data from the primary and take over +read queries. They replicate data from the primary and take over only when the primary fails. ### Redis Sentinels diff --git a/doc/development/sec/analyzer_development_guide.md b/doc/development/sec/analyzer_development_guide.md new file mode 100644 index 00000000000..a35bc2b7237 --- /dev/null +++ b/doc/development/sec/analyzer_development_guide.md @@ -0,0 +1,185 @@ +--- +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 +--- + +# Sec section analyzer development + +Analyzers are shipped as Docker images to execute within a CI pipeline context. This guide describes development and testing +practices across analyzers. + +## Shared modules + +There are a number of shared Go modules shared across analyzers for common behavior and interfaces: + +- The [`command`](https://gitlab.com/gitlab-org/security-products/analyzers/command#how-to-use-the-library) Go package implements a CLI interface. +- The [`common`](https://gitlab.com/gitlab-org/security-products/analyzers/common) project provides miscellaneous shared modules for logging, certificate handling, and directory search capabilities. +- The [`report`](https://gitlab.com/gitlab-org/security-products/analyzers/report) Go package's `Report` and `Finding` structs marshal JSON reports. +- The [`template`](https://gitlab.com/gitlab-org/security-products/analyzers/template) project scaffolds new analyzers. + +## How to use the analyzers + +Analyzers are shipped as Docker images. For example, to run the +[semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) Docker image to scan the working directory: + +1. `cd` into the directory of the source code you want to scan. +1. Run `docker login registry.gitlab.com` and provide username plus + [personal](../../user/profile/personal_access_tokens.md#create-a-personal-access-token) + or [project](../../user/project/settings/project_access_tokens.md#create-a-project-access-token) + access token with at least the `read_registry` scope. +1. Run the Docker image: + + ```shell + docker run \ + --interactive --tty --rm \ + --volume "$PWD":/tmp/app \ + --env CI_PROJECT_DIR=/tmp/app \ + -w /tmp/app \ + registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep:latest /analyzer run + ``` + +1. The Docker container generates a report in the mounted project directory with a report filename corresponding to the analyzer category. For example, [SAST](../../user/application_security/sast) generates a file named `gl-sast-report.json`. + +## Analyzers development + +To update the analyzer: + +1. Modify the Go source code. +1. Build a new Docker image. +1. Run the analyzer against its test project. +1. Compare the generated report with what's expected. + +Here's how to create a Docker image named `analyzer`: + +```shell +docker build -t analyzer . +``` + +For example, to test Secret Detection run the following: + +```shell +wget https://gitlab.com/gitlab-org/security-products/ci-templates/-/raw/master/scripts/compare_reports.sh +sh ./compare_reports.sh sd test/fixtures/gl-secret-detection-report.json test/expect/gl-secret-detection-report.json \ +| patch -Np1 test/expect/gl-secret-detection-report.json && Git commit -m 'Update expectation' test/expect/gl-secret-detection-report.json +rm compare_reports.sh +``` + +You can also compile the binary for your own environment and run it locally +but `analyze` and `run` probably won't work +since the runtime dependencies of the analyzer are missing. + +Here's an example based on +[SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs): + +```shell +go build -o analyzer +./analyzer search test/fixtures +./analyzer convert test/fixtures/app/spotbugsXml.Xml > ./gl-sast-report.json +``` + +## How to test the analyzers + +Video walkthrough of how Dependency Scanning analyzers are using [downstream pipeline](../../ci/pipelines/downstream_pipelines.md) feature to test analyzers using test projects: + +[](http://www.youtube.com/watch?v=KauRBlfUbDE) + +### Testing local changes + +To test local changes in the shared modules (such as `command` or `report`) for an analyzer +you can use the +[`go mod replace`](https://github.com/golang/go/wiki/Modules#when-should-i-use-the-replace-directive) +directive to load `command` with your local changes instead of using the version of command that has been +tagged remotely. For example: + +```shell +go mod edit -replace gitlab.com/gitlab-org/security-products/analyzers/command/v3=/local/path/to/command +``` + +Alternatively you can achieve the same result by manually updating the `go.mod` file: + +```plaintext +module gitlab.com/gitlab-org/security-products/analyzers/awesome-analyzer/v2 + +replace gitlab.com/gitlab-org/security-products/analyzers/command/v3 => /path/to/command + +require ( + ... + gitlab.com/gitlab-org/security-products/analyzers/command/v3 v2.19.0 +) +``` + +#### Testing local changes in Docker + +To use Docker with `replace` in the `go.mod` file: + +1. Copy the contents of `command` into the directory of the analyzer. `cp -r /path/to/command path/to/analyzer/command`. +1. Add a copy statement in the analyzer's `Dockerfile`: `COPY command /command`. +1. Update the `replace` statement to make sure it matches the destination of the `COPY` statement in the step above: +`replace gitlab.com/gitlab-org/security-products/analyzers/command/v3 => /command` + +## Versioning and release process + +Analyzers are independent projects that follow their own versioning. `Patch` version bumps tend to correspond to a `Minor` version bump of the underlying tools (i.e. [`bandit`](https://wiki.openstack.org/wiki/Security/Projects/Bandit)), allowing us greater flexibility in reserving `Minor` bumps for more significant changes to our scanners. In case of breaking changes imposed by the wrapped scanner, creating a new analyzer on a separate repository must be considered. + +The analyzers are released as Docker images following this scheme: + +- each push to the `master` branch will override the `edge` image tag +- each push to any `awesome-feature` branch will generate a matching `awesome-feature` image tag +- each Git tag will generate the corresponding `Major.Minor.Patch` image tag. A manual job allows to override the corresponding `Major` and the `latest` image tags to point to this `Major.Minor.Patch`. + +To release a new analyzer Docker image, there are two different options: + +- Manual release process +- Automatic release process + +### Manual release process + +1. Ensure that the `CHANGELOG.md` entry for the new analyzer is correct. +1. Ensure that the release source (typically the `master` or `main` branch) has a passing pipeline. +1. Create a new release for the analyzer project by selecting the **Deployments** menu on the left-hand side of the project window, then selecting the **Releases** sub-menu. +1. Select **New release** to open the **New Release** page. + 1. In the **Tag name** drop down, enter the same version used in the `CHANGELOG.md`, for example `v2.4.2`, and select the option to create the tag (`Create tag v2.4.2` here). + 1. In the **Release title** text box enter the same version used above, for example `v2.4.2`. + 1. In the `Release notes` text box, copy and paste the notes from the corresponding version in the `CHANGELOG.md`. + 1. Leave all other settings as the default values. + 1. Select **Create release**. + +After following the above process and creating a new release, a new Git tag is created with the `Tag name` provided above. This triggers a new pipeline with the given tag version and a new analyzer Docker image is built. + +If the analyzer uses the [`analyzer.yml` template](https://gitlab.com/gitlab-org/security-products/ci-templates/blob/b446fd3/includes-dev/analyzer.yml#L209-217), then the pipeline triggered as part of the **New release** process above automatically tags and deploys a new version of the analyzer Docker image. + +If the analyzer does not use the `analyzer.yml` template, you'll need to manually tag and deploy a new version of the analyzer Docker image: + +1. Select the **CI/CD** menu on the left-hand side of the project window, then select the **Pipelines** sub-menu. +1. A new pipeline should currently be running with the same tag used previously, for example `v2.4.2`. +1. After the pipeline has completed, it will be in a `blocked` state. +1. Select the `Manual job` play button on the right hand side of the window and select `tag version` to tag and deploy a new version of the analyzer Docker image. + +Use your best judgment to decide when to create a Git tag, which will then trigger the release job. If you +can't decide, then ask for other's input. + +### Automatic release process + +The following must be performed before the automatic release process can be used: + +1. Configure `CREATE_GIT_TAG: true` as a [`CI/CD` environment variable](../../ci/variables/index.md). +1. Check the `Variables` in the CI/CD project settings. Unless the project already inherits the `GITLAB_TOKEN` environment variable from the project group, create a [project access token](../../user/project/settings/project_access_tokens.md) with `complete read/write access to the API` and configure `GITLAB_TOKEN` as a [`CI/CD` environment variable](../../ci/variables/index.md) which refers to this token. + +After the above steps have been completed, the automatic release process executes as follows: + +1. A project maintainer merges an MR into the default branch. +1. The default pipeline is triggered, and the `upsert git tag` job is executed. + - If the most recent version in the `CHANGELOG.md` matches one of the Git tags, the job is a no-op. + - Else, this job automatically creates a new release and Git tag using the [releases API](../../api/releases/index.md#create-a-release). The version and message is obtained from the most recent entry in the `CHANGELOG.md` file for the project. +1. A pipeline is automatically triggered for the new Git tag. This pipeline releases the `latest`, `major`, `minor` and `patch` Docker images of the analyzer. + +### 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. Announce the release on the relevant group Slack channel. Example message: + + > FYI I've just released `ANALYZER_NAME` `ANALYZER_VERSION`. `LINK_TO_RELEASE` + +**Never delete a Git tag that has been pushed** as there is a good +chance that the tag will be used and/or cached by the Go package registry. diff --git a/doc/development/sec/index.md b/doc/development/sec/index.md index 06c20cee0bb..c9805044e58 100644 --- a/doc/development/sec/index.md +++ b/doc/development/sec/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -18,6 +18,7 @@ See [Terminology](../../user/application_security/terminology) for an overview o - [Scanning](#scanning) - [Processing, visualization, and management](#processing-visualization-and-management) - [Severity Levels](../../user/application_security/vulnerabilities/severities.md) +- [Analyzer Development](analyzer_development_guide.md) ## Overview @@ -45,7 +46,7 @@ flowchart LR ### Scanning The scanning part is responsible for finding vulnerabilities in given resources, and exporting results. -The scans are executed in CI/CD jobs via several small projects called [Analyzers](../../user/application_security/terminology/index.md#analyzer), which can be found in our [Analyzers sub-group](https://gitlab.com/gitlab-org/security-products/analyzers). +The scans are executed in CI/CD jobs via several small projects called [Analyzers](../../user/application_security/terminology/index.md#analyzer), which can be found in our [Analyzers subgroup](https://gitlab.com/gitlab-org/security-products/analyzers). The Analyzers are wrappers around security tools called [Scanners](../../user/application_security/terminology/index.md#scanner), developed internally or externally, to integrate them into GitLab. The Analyzers are mainly written in Go. @@ -65,5 +66,5 @@ Depending on the context, the security reports may be stored either in the datab ## CI/CD template development -While CI/CD templates are the responsibiility of the Verify section, many are critical to the Sec Section's feature usage. +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). diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index 4c2f3118366..67f7c556055 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Secure Coding Guidelines @@ -53,6 +53,10 @@ Each time you implement a new feature/endpoint, whether it is at UI, API or Grap Be careful to **also test [visibility levels](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/master/doc/development/permissions.md#feature-specific-permissions)** and not only project access rights. +The HTTP status code returned when an authorization check fails should generally be `404 Not Found` to avoid revealing information +about whether or not the requested resource exists. `403 Forbidden` may be appropriate if you need to display a specific message to the user +about why they cannot access the resource. If you are displaying a generic message such as "access denied", consider returning `404 Not Found` instead. + Some example of well implemented access controls and tests: 1. [example1](https://dev.gitlab.org/gitlab/gitlab-ee/-/merge_requests/710/diffs?diff_id=13750#af40ef0eaae3c1e018809e1d88086e32bccaca40_43_43) @@ -1067,7 +1071,7 @@ Symlink attacks makes it possible for an attacker to read the contents of arbitr #### Ruby -For zip files, the [`rubyzip`](https://rubygems.org/gems/rubyzip) Ruby gem is already patched against symlink attacks as it simply ignores symbolic links, so for this vulnerable example we will extract a `tar.gz` file with `Gem::Package::TarReader`: +For zip files, the [`rubyzip`](https://rubygems.org/gems/rubyzip) Ruby gem is already patched against symlink attacks as it ignores symbolic links, so for this vulnerable example we will extract a `tar.gz` file with `Gem::Package::TarReader`: ```ruby # Vulnerable tar.gz extraction example! diff --git a/doc/development/service_measurement.md b/doc/development/service_measurement.md index 17e509672f2..9d22e9c376c 100644 --- a/doc/development/service_measurement.md +++ b/doc/development/service_measurement.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Developers Guide to service measurement -You can enable service measurement in order to debug any slow service's execution time, number of SQL calls, garbage collection stats, memory usage, etc. +You can enable service measurement to debug any slow service's execution time, number of SQL calls, garbage collection stats, memory usage, etc. ## Measuring module @@ -43,7 +43,7 @@ DummyService.prepend(Measurable) In case when you are prepending a module from the `EE` namespace with EE features, you need to prepend Measurable after prepending the `EE` module. -This way, `Measurable` is at the bottom of the ancestor chain, in order to measure execution of `EE` features as well: +This way, `Measurable` is at the bottom of the ancestor chain, to measure execution of `EE` features as well: ```ruby class DummyService diff --git a/doc/development/service_ping/implement.md b/doc/development/service_ping/implement.md index 5448bbb4293..88a1454393f 100644 --- a/doc/development/service_ping/implement.md +++ b/doc/development/service_ping/implement.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Implement Service Ping @@ -179,7 +179,7 @@ As the HyperLogLog algorithm is probabilistic, the **results always include erro The highest encountered error rate is 4.9%. When correctly used, the `estimate_batch_distinct_count` method enables efficient counting over -columns that contain non-unique values, which can not be assured by other counters. +columns that contain non-unique values, which cannot be assured by other counters. ##### estimate_batch_distinct_count method @@ -605,7 +605,7 @@ alt_usage_data(value = nil, fallback: -1, &block) Arguments: -- `value`: a simple static value in which case the value is simply returned. +- `value`: a static value in which case the value is returned. - or a `block`: which is evaluated - `fallback: -1`: the common value used for any metrics that are failing. @@ -712,10 +712,10 @@ We also use `#database-lab` and [explain.depesz.com](https://explain.depesz.com/ - Use specialized indexes. For examples, see these merge requests: - [Example 1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26871) - [Example 2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26445) -- Use defined `start` and `finish`, and simple queries. - These values can be memoized and reused, as in this [example merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37155). -- Avoid joins and write the queries as simply as possible, - as in this [example merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36316). +- Use defined `start` and `finish`. These values can be memoized and reused, as in this + [example merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37155). +- Avoid joins and unnecessary complexity in your queries. See this + [example merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36316) as an example. - Set a custom `batch_size` for `distinct_count`, as in this [example merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38000). ## Add the metric definition @@ -839,6 +839,22 @@ However, it has the following limitations: WARNING: This feature is intended solely for internal GitLab use. +The aggregated metrics feature provides insight into the data attributes in a collection of Service Ping metrics. +This aggregation allows you to count data attributes in events without counting each occurrence of the same data attribute in multiple events. +For example, you can aggregate the number of users who perform several actions, such as creating a new issue and opening a new merge request. +You can then count each user that performed any combination of these actions. + +### Defining aggregated metric via metric YAML definition + +To add data for aggregated metrics to the Service Ping payload, +create metric YAML definition file following [Aggregated metric instrumentation guide](metrics_instrumentation.md#aggregated-metrics). + +### (DEPRECATED) Defining aggregated metric via aggregated metric YAML config file + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98206) in GitLab 15.5 +and is planned for removal in 15.5. Use [metrics definition YAMLs](https://gitlab.com/gitlab-org/gitlab/-/issues/370963) instead. + To add data for aggregated metrics to the Service Ping payload, add a corresponding definition to: - [`config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/aggregates/) for metrics available in the Community Edition. diff --git a/doc/development/service_ping/index.md b/doc/development/service_ping/index.md index f252eb967aa..0a4e5998345 100644 --- a/doc/development/service_ping/index.md +++ b/doc/development/service_ping/index.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Ping Guide **(FREE SELF)** diff --git a/doc/development/service_ping/metrics_dictionary.md b/doc/development/service_ping/metrics_dictionary.md index d063c4c7601..3439f581e7f 100644 --- a/doc/development/service_ping/metrics_dictionary.md +++ b/doc/development/service_ping/metrics_dictionary.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metrics Dictionary Guide @@ -136,6 +136,9 @@ We use the following categories to classify a metric: - `subscription`: Data related to licensing. - `standard`: Standard set of identifiers that are included when collecting data. +An aggregate metric is a metric that is the sum of two or more child metrics. Service Ping uses the data category of +the aggregate metric to determine whether or not the data is included in the reported Service Ping payload. + ### Metric name suggestion examples #### Metric with `data_source: database` diff --git a/doc/development/service_ping/metrics_instrumentation.md b/doc/development/service_ping/metrics_instrumentation.md index debb3a68c04..7a3f291460c 100644 --- a/doc/development/service_ping/metrics_instrumentation.md +++ b/doc/development/service_ping/metrics_instrumentation.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Metrics instrumentation guide @@ -254,6 +254,86 @@ options: - i_quickactions_approve ``` +## Aggregated metrics + +The aggregated metrics feature provides insight into the number of data attributes, for example `pseudonymized_user_ids`, that occurred in a collection of events. For example, you can aggregate the number of users who perform multiple actions such as creating a new issue and opening +a new merge request. + +You can use a YAML file to define your aggregated metrics. The following arguments are required: + +- `options.events`: List of event names to aggregate into metric data. All events in this list must + use the same data source. Additional data source requirements are described in + [Database sourced aggregated metrics](implement.md#database-sourced-aggregated-metrics) and + [Redis sourced aggregated metrics](implement.md#redis-sourced-aggregated-metrics). +- `options.aggregate.operator`: Operator that defines how the aggregated metric data is counted. Available operators are: + - `OR`: Removes duplicates and counts all entries that triggered any of the listed events. + - `AND`: Removes duplicates and counts all elements that were observed triggering all of the following events. +- `options.aggregate.attribute`: Information pointing to the attribute that is being aggregated across events. +- `time_frame`: One or more valid time frames. Use these to limit the data included in aggregated metrics to events within a specific date-range. Valid time frames are: + - `7d`: The last 7 days of data. + - `28d`: The last 28 days of data. + - `all`: All historical data, only available for `database` sourced aggregated metrics. +- `data_source`: Data source used to collect all events data included in the aggregated metrics. Valid data sources are: + - [`database`](implement.md#database-sourced-aggregated-metrics) + - [`redis_hll`](implement.md#redis-sourced-aggregated-metrics) + +Refer to merge request [98206](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98206) for an example of a merge request that adds an `AggregatedMetric` metric. + +Count unique `user_ids` that occurred in at least one of the events: `incident_management_alert_status_changed`, +`incident_management_alert_assigned`, `incident_management_alert_todo`, `incident_management_alert_create_incident`. + +```yaml +time_frame: 28d +instrumentation_class: AggregatedMetric +data_source: redis_hll +options: + aggregate: + operator: OR + attribute: user_id + events: + - `incident_management_alert_status_changed` + - `incident_management_alert_assigned` + - `incident_management_alert_todo` + - `incident_management_alert_create_incident` +``` + +### Availability-restrained Aggregated metrics + +If the Aggregated metric should only be available in the report under specific conditions, then you must specify these conditions in a new class that is a child of the `AggregatedMetric` class. + +```ruby +# frozen_string_literal: true + +module Gitlab + module Usage + module Metrics + module Instrumentations + class MergeUsageCountAggregatedMetric < AggregatedMetric + available? { Feature.enabled?(:merge_usage_data_missing_key_paths) } + end + end + end + end +end +``` + +You must also use the class's name in the YAML setup. + +```yaml +time_frame: 28d +instrumentation_class: MergeUsageCountAggregatedMetric +data_source: redis_hll +options: + aggregate: + operator: OR + attribute: user_id + events: + - `incident_management_alert_status_changed` + - `incident_management_alert_assigned` + - `incident_management_alert_todo` + - `incident_management_alert_create_incident` +``` + ## Numbers metrics - `operation`: Operations for the given `data` block. Currently we only support `add` operation. diff --git a/doc/development/service_ping/metrics_lifecycle.md b/doc/development/service_ping/metrics_lifecycle.md index 28f77b6f587..f13aebeb16e 100644 --- a/doc/development/service_ping/metrics_lifecycle.md +++ b/doc/development/service_ping/metrics_lifecycle.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Ping metric lifecycle @@ -120,7 +120,7 @@ To remove a metric: Do not remove the metric's YAML definition altogether. Some self-managed instances might not immediately update to the latest version of GitLab, and therefore continue to report the removed metric. The Product Intelligence team - requires a record of all removed metrics in order to identify and filter them. + 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). diff --git a/doc/development/service_ping/performance_indicator_metrics.md b/doc/development/service_ping/performance_indicator_metrics.md index d2abc597a22..4c1c61aa05b 100644 --- a/doc/development/service_ping/performance_indicator_metrics.md +++ b/doc/development/service_ping/performance_indicator_metrics.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Performance Indicator Metrics guide diff --git a/doc/development/service_ping/review_guidelines.md b/doc/development/service_ping/review_guidelines.md index 1b00858be7e..a1806551303 100644 --- a/doc/development/service_ping/review_guidelines.md +++ b/doc/development/service_ping/review_guidelines.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Ping review guidelines diff --git a/doc/development/service_ping/troubleshooting.md b/doc/development/service_ping/troubleshooting.md index 4431d5df3ff..201d6a385eb 100644 --- a/doc/development/service_ping/troubleshooting.md +++ b/doc/development/service_ping/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To 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 Service Ping diff --git a/doc/development/service_ping/usage_data.md b/doc/development/service_ping/usage_data.md index 4181bd90a02..2f2df14f56d 100644 --- a/doc/development/service_ping/usage_data.md +++ b/doc/development/service_ping/usage_data.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Usage Data Metrics guide diff --git a/doc/development/session.md b/doc/development/session.md index 61a130e3a53..c30364c27f8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Accessing session data diff --git a/doc/development/shared_files.md b/doc/development/shared_files.md index 4f13bb80761..3bf18a4d410 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Shared files diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index d8a3f86685e..3935e98199a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Guidelines for shell commands in the GitLab codebase diff --git a/doc/development/shell_scripting_guide/index.md b/doc/development/shell_scripting_guide/index.md index 0591d2c64d0..d3d9304446e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 ac34d099202..cfb709d9110 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq Compatibility across Updates diff --git a/doc/development/sidekiq/idempotent_jobs.md b/doc/development/sidekiq/idempotent_jobs.md index da36cdc72aa..80c6c403549 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq idempotent jobs diff --git a/doc/development/sidekiq/index.md b/doc/development/sidekiq/index.md index 003f54d48b5..e8c939571cf 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq guides @@ -186,3 +186,9 @@ default weight, which is 1. Each Sidekiq worker must be tested using RSpec, just like any other class. These tests should be placed in `spec/workers`. + +## Interacting with Sidekiq Redis and APIs + +The application should minimise interaction with of any `Sidekiq.redis` and Sidekiq [APIs](https://github.com/mperham/sidekiq/blob/main/lib/sidekiq/api.rb). Such interactions in generic application logic should be abstracted to a [Sidekiq middleware](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/sidekiq_middleware) for re-use across teams. By decoupling application logic from Sidekiq's datastore, it allows for greater freedom when horizontally scaling the GitLab background processing setup. + +Some exceptions to this rule would be migration-related logic or administration operations. diff --git a/doc/development/sidekiq/limited_capacity_worker.md b/doc/development/sidekiq/limited_capacity_worker.md index 5b86e01781c..5efb9b16725 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq limited capacity worker diff --git a/doc/development/sidekiq/logging.md b/doc/development/sidekiq/logging.md index b461047ea47..8a2a77b5226 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq logging diff --git a/doc/development/sidekiq/worker_attributes.md b/doc/development/sidekiq/worker_attributes.md index a1d24d0c392..48a222d65a0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sidekiq worker attributes @@ -60,7 +60,7 @@ that branch, but be told in the UI that the branch does not exist. We deem these jobs to be `urgency :high`. Extra effort is made to ensure that these jobs are started within a very short -period of time after being scheduled. However, in order to ensure throughput, +period of time after being scheduled. However, to ensure throughput, these jobs also have very strict execution duration requirements: 1. The median job execution time should be less than 1 second. @@ -117,7 +117,7 @@ Most background jobs in the GitLab application communicate with other GitLab services. For example, PostgreSQL, Redis, Gitaly, and Object Storage. These are considered to be "internal" dependencies for a job. -However, some jobs are dependent on external services in order to complete +However, some jobs are dependent on external services to complete successfully. Some examples include: 1. Jobs which call web-hooks configured by a user. diff --git a/doc/development/snowplow/event_dictionary_guide.md b/doc/development/snowplow/event_dictionary_guide.md index 7980395b1a9..c5a21f5a081 100644 --- a/doc/development/snowplow/event_dictionary_guide.md +++ b/doc/development/snowplow/event_dictionary_guide.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Event dictionary guide diff --git a/doc/development/snowplow/implementation.md b/doc/development/snowplow/implementation.md index 9a923b115a2..26016eeba84 100644 --- a/doc/development/snowplow/implementation.md +++ b/doc/development/snowplow/implementation.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Implement Snowplow tracking diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md index 42a968b9df0..7327f18fcaf 100644 --- a/doc/development/snowplow/index.md +++ b/doc/development/snowplow/index.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Snowplow @@ -90,7 +90,7 @@ Each click event provides attributes that describe the event. | Attribute | Type | Required | Description | | --------- | ------- | -------- | ----------- | | category | text | true | The page or backend section of the application. Unless infeasible, use the Rails page attribute by default in the frontend, and namespace + class name on the backend, for example, `Notes::CreateService`. | -| action | text | true | The action the user takes, or aspect that's being instrumented. The first word must describe the action or aspect. For example, clicks must be `click`, activations must be `activate`, creations must be `create`. Use underscores to describe what was acted on. For example, activating a form field is `activate_form_input`, an interface action like clicking on a dropdown is `click_dropdown`, a behavior like creating a project record from the backend is `create_project`. | +| action | text | true | The action the user takes, or aspect that's being instrumented. The first word must describe the action or aspect. For example, clicks must be `click`, activations must be `activate`, creations must be `create`. Use underscores to describe what was acted on. For example, activating a form field is `activate_form_input`, an interface action like clicking on a dropdown list is `click_dropdown`, a behavior like creating a project record from the backend is `create_project`. | | label | text | false | The specific element or object to act on. This can be one of the following: the label of the element, for example, a tab labeled 'Create from template' for `create_from_template`; a unique identifier if no text is available, for example, `groups_dropdown_close` for closing the Groups dropdown in the top bar; or the name or title attribute of a record being created. For Service Ping metrics adapted to Snowplow events, this should be the full metric [key path](../service_ping/metrics_dictionary.md#metric-key_path) taken from its definition file. | | property | text | false | Any additional property of the element, or object being acted on. For Service Ping metrics adapted to Snowplow events, this should be additional information or context that can help analyze the event. For example, in the case of `usage_activity_by_stage_monthly.create.merge_requests_users`, there are four different possible merge request actions: "create", "merge", "comment", and "close". Each of these would be a possible property value. | | value | decimal | false | Describes a numeric value (decimal) directly related to the event. This could be the value of an input. For example, `10` when clicking `internal` visibility. | diff --git a/doc/development/snowplow/infrastructure.md b/doc/development/snowplow/infrastructure.md index ea4653dc91d..ae416f40c98 100644 --- a/doc/development/snowplow/infrastructure.md +++ b/doc/development/snowplow/infrastructure.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Snowplow infrastructure diff --git a/doc/development/snowplow/review_guidelines.md b/doc/development/snowplow/review_guidelines.md index 44de849792c..756dbd0ca92 100644 --- a/doc/development/snowplow/review_guidelines.md +++ b/doc/development/snowplow/review_guidelines.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Snowplow review guidelines diff --git a/doc/development/snowplow/schemas.md b/doc/development/snowplow/schemas.md index 799f8335000..482c0e0105b 100644 --- a/doc/development/snowplow/schemas.md +++ b/doc/development/snowplow/schemas.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Snowplow schemas diff --git a/doc/development/snowplow/troubleshooting.md b/doc/development/snowplow/troubleshooting.md index 3ad4c6c9549..306040f8c9c 100644 --- a/doc/development/snowplow/troubleshooting.md +++ b/doc/development/snowplow/troubleshooting.md @@ -1,16 +1,16 @@ --- stage: Analytics group: Product Intelligence -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 +info: To 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 Snowplow ## Monitoring -This page covers dashboards and alerts coming from a number of internal tools. +This page covers dashboards and alerts coming from a number of internal tools. -For a brief video overview of the tools used to monitor Snowplow usage, please check out [this internal video](https://www.youtube.com/watch?v=NxPS0aKa_oU) (you must be logged into GitLab Unfiltered to view). +For a brief video overview of the tools used to monitor Snowplow usage, please check out [this internal video](https://www.youtube.com/watch?v=NxPS0aKa_oU) (you must be logged into GitLab Unfiltered to view). ## Good events drop @@ -74,7 +74,7 @@ Enrichers are not scalling well for the amount of events we receive. See the [dashboard](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#dashboards:name=SnowPlow). -Could we get assistance in order to fix the delay? +Could we get assistance to fix the delay? Thank you! ``` diff --git a/doc/development/spam_protection_and_captcha/exploratory_testing.md b/doc/development/spam_protection_and_captcha/exploratory_testing.md index e508265cf83..e17d25acb9d 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: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 e3f4e9069e5..846165d35f1 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: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 dbe8c4aa4e9..1ba1c1678c4 100644 --- a/doc/development/spam_protection_and_captcha/index.md +++ b/doc/development/spam_protection_and_captcha/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 d0519cba68f..d0ca6d350dc 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: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 ad74977eb67..7a9f8b5def1 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: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # REST API 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 9aeb9e96d44..ff7049dd29f 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: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web UI spam protection and CAPTCHA support diff --git a/doc/development/sql.md b/doc/development/sql.md index 029874011c4..5829d27b8ee 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SQL Query Guidelines 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 19f98d404e7..a8f932b78c0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 f4e646c8634..9f9ba609271 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 c8c18b93a8f..fb5d5bbe379 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Stage group dashboard @@ -54,8 +54,8 @@ description, note the following: precision is 2. In some extremely low panels, you can see `0.00`, even though there is still some real traffic. -To inspect the raw data of the panel for further calculation, select **Inspect** from the dropdown -list of a panel. Queries, raw data, and panel JSON structure are available. +To inspect the raw data of the panel for further calculation, select **Inspect** from the dropdown list of a panel. +Queries, raw data, and panel JSON structure are available. Read more at [Grafana panel inspection](http://grafana.com/docs/grafana/next/panels/query-a-data-source/). All the dashboards are powered by [Grafana](https://grafana.com/), a frontend for displaying metrics. diff --git a/doc/development/stage_group_observability/index.md b/doc/development/stage_group_observability/index.md index 868e55735e8..08f751c508e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Observability for stage groups diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 221d6b89b20..f1a23f06699 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -2,7 +2,7 @@ type: reference, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "GitLab development guidelines - testing best practices." --- diff --git a/doc/development/testing_guide/contract/consumer_tests.md b/doc/development/testing_guide/contract/consumer_tests.md index 46f4f446ad9..67bb7160749 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: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Writing consumer tests diff --git a/doc/development/testing_guide/contract/index.md b/doc/development/testing_guide/contract/index.md index 30a4adaca44..8412a260c7d 100644 --- a/doc/development/testing_guide/contract/index.md +++ b/doc/development/testing_guide/contract/index.md @@ -1,7 +1,7 @@ --- stage: none group: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Contract testing @@ -66,7 +66,7 @@ As mentioned in the [folder structure section](#consumer-tests), consumer tests #### Provider naming -These are the API endpoints that provides the data to the consumer so they are simply named according to the API endpoint they pertain to. Be mindful that this name is as descriptive as possible. For example, if we're writing a test for the `GET /groups/:id/projects` endpoint, we don't want to simply name it "Projects endpoint" as there is a `GET /projects` endpoint as well that also fetches a list of projects the user has access to across all of GitLab. An easy way to name them is by checking out our [API documentation](../../../api/api_resources.md) and naming it the same way it is named in there. So the [`GET /groups/:id/projects`](../../../api/groups.md#list-a-groups-projects) would be called `List a group’s projects` and [`GET /projects`](../../../api/projects.md#list-all-projects) would be called `List all projects`. Subsequently, the test files are named `list_a_groups_projects_helper.rb` and `list_all_projects_helper.rb` respectively. +These are the API endpoints that provides the data to the consumer so they are named according to the API endpoint they pertain to. Be mindful that this name is as descriptive as possible. For example, if we're writing a test for the `GET /groups/:id/projects` endpoint, we don't want to name it "Projects endpoint" as there is a `GET /projects` endpoint as well that also fetches a list of projects the user has access to across all of GitLab. An easy way to name them is by checking out our [API documentation](../../../api/api_resources.md) and naming it the same way it is named in there. So the [`GET /groups/:id/projects`](../../../api/groups.md#list-a-groups-projects) would be called `List a group’s projects` and [`GET /projects`](../../../api/projects.md#list-all-projects) would be called `List all projects`. Subsequently, the test files are named `list_a_groups_projects_helper.rb` and `list_all_projects_helper.rb` respectively. There are some cases where the provider being tested may not be documented so, in those cases, fall back to choosing a name that is as descriptive as possible to ensure it's easy to tell what the provider is for. diff --git a/doc/development/testing_guide/contract/provider_tests.md b/doc/development/testing_guide/contract/provider_tests.md index 92ac4c4ed71..1772ed9384e 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: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 a13011d0101..b81379d89b2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Beginner's guide to writing end-to-end tests @@ -120,6 +120,22 @@ module QA end ``` +### The `product_group` metadata + +Assign `product_group` metadata and specify what product group this test belongs to. In this case, `authentication_and_authorization`. + +```ruby +# frozen_string_literal: true + +module QA + RSpec.describe 'Manage' do + describe 'Login', product_group: :authentication_and_authorization do + + end + end +end +``` + ### The `it` blocks (examples) Every test suite contains at least one `it` block (example). A good way to start @@ -128,7 +144,7 @@ writing end-to-end tests is to write test case descriptions as `it` blocks: ```ruby module QA RSpec.describe 'Manage' do - describe 'Login' do + describe 'Login', product_group: :authentication_and_authorization do it 'can login' do end @@ -152,7 +168,7 @@ Begin by logging in. module QA RSpec.describe 'Manage' do - describe 'Login' do + describe 'Login', product_group: :authentication_and_authorization do it 'can login' do Flow::Login.sign_in @@ -175,7 +191,7 @@ should answer the question "What do we test?" module QA RSpec.describe 'Manage' do - describe 'Login' do + describe 'Login', product_group: :authentication_and_authorization do it 'can login' do Flow::Login.sign_in @@ -222,7 +238,7 @@ a call to `sign_in`. module QA RSpec.describe 'Manage' do - describe 'Login' do + describe 'Login', product_group: :authentication_and_authorization do before do Flow::Login.sign_in end @@ -246,12 +262,12 @@ end ``` The `before` block is essentially a `before(:each)` and is run before each example, -ensuring we now log in at the beginning of each test. +ensuring we now sign in at the beginning of each test. ## Test setup using resources and page objects Next, let's test something other than Login. Let's test Issues, which are owned by the Plan -stage, so [create a file](#identify-the-devops-stage) in +stage and the Project Management Group, so [create a file](#identify-the-devops-stage) in `qa/specs/features/browser_ui/3_create/issues` called `issues_spec.rb`. ```ruby @@ -259,7 +275,7 @@ stage, so [create a file](#identify-the-devops-stage) in module QA RSpec.describe 'Plan' do - describe 'Issues' do + describe 'Issues', product_group: :project_management do let(:issue) do Resource::Issue.fabricate_via_api! do |issue| issue.title = 'My issue' 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 b17ca9e6f8f..37eda7f76f5 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: Development -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # End-to-end testing Best Practices @@ -10,7 +10,7 @@ This is a tailored extension of the Best Practices [found in the testing guide]( ## Class and module naming -The QA framework uses [Zeitwerk](https://github.com/fxn/zeitwerk) for class and module autoloading. The default Zeitwerk [inflector](https://github.com/fxn/zeitwerk#zeitwerkinflector) simply converts snake_cased file names to PascalCased module or class names. It is advised to stick to this pattern to avoid manual maintenance of inflections. +The QA framework uses [Zeitwerk](https://github.com/fxn/zeitwerk) for class and module autoloading. The default Zeitwerk [inflector](https://github.com/fxn/zeitwerk#zeitwerkinflector) converts snake_cased file names to PascalCased module or class names. It is advised to stick to this pattern to avoid manual maintenance of inflections. In case custom inflection logic is needed, custom inflectors are added in the [qa.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa.rb) file in the `loader.inflector.inflect` method invocation. @@ -299,7 +299,7 @@ point of failure and so the screenshot would not be captured at the right moment ## Ensure tests do not leave the browser logged in -All tests expect to be able to log in at the start of the test. +All tests expect to be able to sign in at the start of the test. For an example see [issue #34736](https://gitlab.com/gitlab-org/gitlab/-/issues/34736). @@ -358,7 +358,7 @@ using the Git CLI. ## Preferred method to blur elements -To blur an element, the preferred method is to click another element that does not alter the test state. +To blur an element, the preferred method is to select another element that does not alter the test state. If there's a mask that blocks the page elements, such as may occur with some dropdowns, use WebDriver's native mouse events to simulate a click event on the coordinates of an element. Use the following method: `click_element_coordinates`. 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 a71e076b57f..f3911176263 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 8770a5d33cd..5cc82916cdd 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dynamic Element Validation @@ -48,7 +48,7 @@ click_element(:my_element, Some::Page) First it is important to define what a "required element" is. -Simply put, a required element is a visible HTML element that appears on a UI component without any user input. +A required element is a visible HTML element that appears on a UI component without any user input. "Visible" can be defined as 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 0a4c5fcf451..23b8ab7287b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 9a39161f1ad..8e25c817938 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Testing with feature flags diff --git a/doc/development/testing_guide/end_to_end/flows.md b/doc/development/testing_guide/end_to_end/flows.md index b99a1f9deb7..58702ceb861 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 cc9c02a65ce..1853ad47779 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # End-to-end Testing @@ -125,7 +125,7 @@ For example, when we [dequarantine](https://about.gitlab.com/handbook/engineerin a flaky test we first want to make sure that it's no longer flaky. We can do that using the `ce:custom-parallel` and `ee:custom-parallel` jobs. Both are manual jobs that you can configure using custom variables. -When clicking the name (not the play icon) of one of the parallel jobs, +When selecting the name (not the play icon) of one of the parallel jobs, you are prompted to enter variables. You can use any of [the variables that can be used with `gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#supported-gitlab-environment-variables) as well as these: 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 c93e8c9d13f..5fbf2ffbcde 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Page objects in GitLab QA @@ -10,7 +10,7 @@ In GitLab QA we are using a known pattern, called _Page Objects_. This means that we have built an abstraction for all pages in GitLab that we use to drive GitLab QA scenarios. Whenever we do something on a page, like filling -in a form or clicking a button, we do that only through a page object +in a form or selecting a button, we do that only through a page object associated with this area of GitLab. For example, when GitLab QA test harness signs in into GitLab, it needs to fill diff --git a/doc/development/testing_guide/end_to_end/resources.md b/doc/development/testing_guide/end_to_end/resources.md index a519d1ecb47..6e29e9b9dff 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Resource classes in GitLab QA 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 1abaf3ef323..b12c6bd443a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # 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 322f108783f..81e1c7d5dc0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Running tests that require special setup 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 a9571df1188..f380b24d7a5 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Style guide for writing end-to-end tests diff --git a/doc/development/testing_guide/end_to_end/troubleshooting.md b/doc/development/testing_guide/end_to_end/troubleshooting.md index 76d19dc0159..e0925cb71f4 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/engineering/ux/technical-writing/#assignments +info: To 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 end-to-end tests diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 7409f15969d..45f1d0ddf7e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Flaky tests @@ -45,15 +45,27 @@ 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 home-made `RspecFlaky::Listener` listener which records flaky -examples in a JSON report file on `main` (`retrieve-tests-metadata` and -`update-tests-metadata` jobs). +We also use a custom [`RspecFlaky::Listener`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/tooling/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. This was originally implemented in: <https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13021>. If you want to enable retries locally, you can use the `RETRIES` environment variable. For instance `RETRIES=1 bin/rspec ...` would retry the failing examples once. +To generate the reports locally, use the `FLAKY_RSPEC_GENERATE_REPORT` environment variable. +For example, `FLAKY_RSPEC_GENERATE_REPORT=1 bin/rspec ...`. + +### Usage of the `rspec/flaky/report-suite.json` report + +The `rspec/flaky/report-suite.json` report is: + +- Used for [automatically skipping known flaky tests](../pipelines.md#automatic-skipping-of-flaky-tests). +- [Imported into Snowflake](https://gitlab.com/gitlab-data/analytics/-/blob/master/extract/gitlab_flaky_tests/upload.py) + once per day, for monitoring with the [internal dashboard](https://app.periscopedata.com/app/gitlab/888968/EP---Flaky-tests). + ## Problems we had in the past at GitLab - [`rspec-retry` is biting us when some API specs fail](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29242): <https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9825> diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 22a8792bac6..d7627e2064f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Frontend testing standards and style guidelines @@ -200,7 +200,6 @@ import { shallowMountExtended } from 'helpers/vue_test_utils_helper' const wrapper = shallowMountExtended(ExampleComponent); -// In this example, `wrapper` is a `@vue/test-utils` wrapper returned from `mount` or `shallowMount`. it('exists', () => { // Best (especially for integration tests) wrapper.findByRole('link', { name: /Click Me/i }) @@ -291,7 +290,7 @@ it('tests a promise rejection', async () => { }); ``` -You can also simply return a promise from the test function. +You can also return a promise from the test function. Using the `done` and `done.fail` callbacks is discouraged when working with promises. They should not be used. diff --git a/doc/development/testing_guide/index.md b/doc/development/testing_guide/index.md index e50902c4995..753089fa673 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Testing standards and style guidelines diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index b272d23522e..d86d1c3c7b4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Review Apps @@ -84,7 +84,7 @@ the GitLab handbook information for the [shared 1Password account](https://about ### Enable a feature flag for my Review App -1. Open your Review App and log in as documented above. +1. Open your Review App and sign in as documented above. 1. Create a personal access token. 1. Enable the feature flag using the [Feature flag API](../../api/features.md). @@ -101,7 +101,7 @@ the GitLab handbook information for the [shared 1Password account](https://about 1. [Filter Workloads by your Review App slug](https://console.cloud.google.com/kubernetes/workload?project=gitlab-review-apps). For example, `review-qa-raise-e-12chm0`. 1. Find and open the `toolbox` Deployment. For example, `review-qa-raise-e-12chm0-toolbox`. 1. Select the Pod in the "Managed pods" section. For example, `review-qa-raise-e-12chm0-toolbox-d5455cc8-2lsvz`. -1. Select the `KUBECTL` dropdown, then `Exec` -> `toolbox`. +1. Select the `KUBECTL` dropdown list, then `Exec` -> `toolbox`. 1. Replace `-c toolbox -- ls` with `-it -- gitlab-rails console` from the default command or - Run `kubectl exec --namespace review-qa-raise-e-12chm0 review-qa-raise-e-12chm0-toolbox-d5455cc8-2lsvz -it -- gitlab-rails console` and diff --git a/doc/development/testing_guide/smoke.md b/doc/development/testing_guide/smoke.md index 4fd2729a4d3..62a09ca864b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Smoke Tests diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index c1bf3609b53..c93a5fd539b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Testing levels diff --git a/doc/development/testing_guide/testing_migrations_guide.md b/doc/development/testing_guide/testing_migrations_guide.md index 3006a2230ac..b276a7e2a3a 100644 --- a/doc/development/testing_guide/testing_migrations_guide.md +++ b/doc/development/testing_guide/testing_migrations_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -22,7 +22,8 @@ a database schema. Adding a `:migration` tag to a test signature enables some custom RSpec `before` and `after` hooks in our [`spec/support/migration.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/f81fa6ab1dd788b70ef44b85aaba1f31ffafae7d/spec/support/migration.rb) -to run. +to run. If performing a migration against a database schema other than +`:gitlab_main` (for example `:gitlab_ci`), then you must specify it as well: `migration: :gitlab_ci`. See [spec/migrations/change_public_projects_cost_factor_spec.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/migrations/change_public_projects_cost_factor_spec.rb#L6-6) for an example. A `before` hook reverts all migrations to the point that a migration under test is not yet migrated. diff --git a/doc/development/testing_guide/testing_rake_tasks.md b/doc/development/testing_guide/testing_rake_tasks.md index 30d193de2f2..3dfe1f9b725 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Testing Rake tasks diff --git a/doc/development/transient/prevention-patterns.md b/doc/development/transient/prevention-patterns.md index 93712b104e6..98634df22e9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Preventing Transient Bugs diff --git a/doc/development/uploads/background.md b/doc/development/uploads/background.md deleted file mode 100644 index 1ad1aec23f2..00000000000 --- a/doc/development/uploads/background.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2022-07-25' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2022-07-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/uploads/implementation.md b/doc/development/uploads/implementation.md deleted file mode 100644 index 1ad1aec23f2..00000000000 --- a/doc/development/uploads/implementation.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2022-07-25' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2022-07-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/uploads/index.md b/doc/development/uploads/index.md index b8326489d40..41ec71451fb 100644 --- a/doc/development/uploads/index.md +++ b/doc/development/uploads/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads development guide diff --git a/doc/development/uploads/working_with_uploads.md b/doc/development/uploads/working_with_uploads.md index 5a5f987c37c..c88762e6bd5 100644 --- a/doc/development/uploads/working_with_uploads.md +++ b/doc/development/uploads/working_with_uploads.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Uploads guide: Adding new uploads diff --git a/doc/development/utilities.md b/doc/development/utilities.md index 3f6187a4c2e..45a6b74f33a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab utilities diff --git a/doc/development/value_stream_analytics.md b/doc/development/value_stream_analytics.md index bbea89d5645..0d321133705 100644 --- a/doc/development/value_stream_analytics.md +++ b/doc/development/value_stream_analytics.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Value stream analytics development guide @@ -326,3 +326,25 @@ in your rails console (`rails c`): ```ruby Analytics::CycleAnalytics::ReaggregationWorker.new.perform ``` + +### Seed data + +#### Value stream analytics + +Seed issues and merge requests for value stream analytics: + + ```shell + // Seed 10 issues for the project specified by <project-id> + $ VSA_SEED_PROJECT_ID=<project-id> VSA_ISSUE_COUNT=10 SEED_VSA=true FILTER=cycle_analytics rake db:seed_fu + ``` + +#### DORA metrics + +Seed DORA daily metrics for value stream, insights and CI/CD analytics: + +1. [Create an environment from the UI](../ci/environments/index.md#create-a-static-environment) named `production`. +1. Open the rails console: + + ```shell + rails c + ``` 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 6087d4bd8f7..a07998550bf 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: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Aggregated Value Stream Analytics @@ -43,7 +43,7 @@ Benefits of the aggregated VSA backend: - Simpler database queries (fewer JOINs). - Faster aggregations, only a single table is accessed. - Possibility to introduce further aggregations for improving the first page load time. -- Better performance for large groups (with many sub-groups, projects, issues and, merge requests). +- Better performance for large groups (with many subgroups, projects, issues and, merge requests). - Ready for database decomposition. The VSA related database tables could live in a separate database with a minimal development effort. - Ready for keyset pagination which can be useful for exporting the data. @@ -165,7 +165,7 @@ Creation time always happens first, so this stage always reports negative durati The data collection scans and processes all issues and merge requests records in the group hierarchy, starting from the top-level group. This means that if a group only has one value stream -in a sub-group, we nevertheless collect data of all issues and merge requests in the hierarchy of +in a subgroup, we nevertheless collect data of all issues and merge requests in the hierarchy of this group. This aims to simplify the data collection mechanism. Moreover, data research shows that most group hierarchies have their stages configured on the top level. @@ -278,7 +278,7 @@ attributes. - `summary`, `time_summary` - Top-level aggregations, most of the metrics are using different APIs/ finders and not invoking the aggregated backend. -When clicking on a specific stage, the `records` endpoint is invoked, which returns the related +When selecting a specific stage, the `records` endpoint is invoked, which returns the related records (paginated) for the chosen stage in a specific order. ### Database decomposition diff --git a/doc/development/wikis.md b/doc/development/wikis.md index deea3d38470..67dc567cc5f 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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: "GitLab's development guidelines for Wikis" --- diff --git a/doc/development/windows.md b/doc/development/windows.md index 17dfaddef36..5f32848da79 100644 --- a/doc/development/windows.md +++ b/doc/development/windows.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -76,7 +76,7 @@ Build a Google Cloud image with the above shared runners repository by doing the 1. Copy and save the password as it is not shown again. 1. Select **RDP** down arrow. 1. Select **Download the RDP file**. -1. Open the downloaded RDP file with the Windows remote desktop app (<https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients>). +1. Open the downloaded RDP file with the Windows remote desktop app (<https://learn.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients>). 1. Select **Continue** to accept the certificate. 1. Enter the password and select **Next**. diff --git a/doc/development/work_items.md b/doc/development/work_items.md index f15c66ae847..eabad175bf7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Work items and work item types @@ -88,8 +88,8 @@ so that in future we can allow users to define custom WITs, we will move the to `work_item_types` will involve creating the set of WITs for all root-level groups. NOTE: -At first, defining a WIT will only be possible at the root-level group, which would then be inherited by sub-groups. -We will investigate the possibility of defining new WITs at sub-group levels at a later iteration. +At first, defining a WIT will only be possible at the root-level group, which would then be inherited by subgroups. +We will investigate the possibility of defining new WITs at subgroup levels at a later iteration. ### Introducing work_item_types table @@ -150,8 +150,27 @@ of widgets. In order to customize each WIT with corresponding active widgets we will need a data structure to map each WIT to specific widgets. +The intent is for work item types to be highly configurable, both by GitLab for +implementing various work item schemes for customers (an opinionated GitLab +workflow, or SAFe 5, etc), and eventually for customers to customize their own +workflows. + +In this case, a work item scheme would be defined as a set of types with +certain characteristics (some widgets enabled, others not), such as an Epic, +Story, Bug, and Task, etc. + +As we're building a new work item architecture, we want to build the ability to +define these various types in a very flexible manner. Having GitLab use +this system first (without introducing customer customization) allows us to +better build out the initial system. + NOTE: -The exact structure of the WITs widgets metadata is still to be defined. +Currently work item's `base_type` is used to define static mapping of what +widgets are available for each type (current status), this definition should be +rather stored in database table. The exact structure of the WIT widgets +metadata is still to be defined. `base_type` was added to help converting other +types of resources (requirements and incidents) into work items. Eventually (when +these resources become regular work items), `base_type` will be removed. ### Custom work item types diff --git a/doc/development/work_items_widgets.md b/doc/development/work_items_widgets.md index 92919c10a9f..89602d969e6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Work items widgets @@ -88,7 +88,7 @@ To maximize component reusability, widgets should be field wrappers owning the work item query and mutation of the attribute it's responsible for. A field component is a generic and simple component. It has no knowledge of the -attribute or work item details, such as input field, date selector, or dropdown. +attribute or work item details, such as input field, date selector, or dropdown list. Widgets must be configurable to support various use cases, depending on work items. When building widgets, use slots to provide extra context while minimizing @@ -96,18 +96,18 @@ the use of props and injected attributes. ### Examples -We have a [dropdown field component](https://gitlab.com/gitlab-org/gitlab/-/blob/eea9ad536fa2d28ee6c09ed7d9207f803142eed7/app/assets/javascripts/vue_shared/components/dropdown/dropdown_widget/dropdown_widget.vue) +We have a [dropdown list component](https://gitlab.com/gitlab-org/gitlab/-/blob/eea9ad536fa2d28ee6c09ed7d9207f803142eed7/app/assets/javascripts/vue_shared/components/dropdown/dropdown_widget/dropdown_widget.vue) for use as reference. -Any work item widget can wrap the dropdown component. The widget has knowledge of +Any work item widget can wrap the dropdown list. The widget has knowledge of the attribute it mutates, and owns the mutation for it. Multiple widgets can use the same field component. For example: - Title and description widgets use the input field component. - Start and end date use the date selector component. -- Labels, milestones, and assignees selectors use the dropdown component. +- Labels, milestones, and assignees selectors use the dropdown list. -Some frontend widgets already use the dropdown component. Use them as a reference +Some frontend widgets already use the dropdown list. Use them as a reference for work items widgets development: - `ee/app/assets/javascripts/boards/components/assignee_select.vue` diff --git a/doc/development/workhorse/channel.md b/doc/development/workhorse/channel.md index 33d7cc63f00..f5693b57f7a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Websocket channel support for Workhorse diff --git a/doc/development/workhorse/configuration.md b/doc/development/workhorse/configuration.md index a94ba2b4fc6..82e44a6f995 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Workhorse configuration diff --git a/doc/development/workhorse/gitlab_features.md b/doc/development/workhorse/gitlab_features.md index 3b240d4cbc6..8b899242935 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Features that rely on Workhorse diff --git a/doc/development/workhorse/index.md b/doc/development/workhorse/index.md index f210f511954..0f4e55a002a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Workhorse diff --git a/doc/development/workhorse/new_features.md b/doc/development/workhorse/new_features.md index 5c00903497a..dbde06ddee4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Adding new features to Workhorse diff --git a/doc/development/workspace/index.md b/doc/development/workspace/index.md index b01a7826b3d..f4738e3fc31 100644 --- a/doc/development/workspace/index.md +++ b/doc/development/workspace/index.md @@ -3,7 +3,7 @@ comments: false type: index, dev stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "Development Guidelines: learn about workspace when developing GitLab." --- diff --git a/doc/downgrade_ee_to_ce/index.md b/doc/downgrade_ee_to_ce/index.md index 2aa99eae084..6a3fcab8bde 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 c48efbc120a..3c2ce212b99 100644 --- a/doc/drawers/advanced_search_syntax.md +++ b/doc/drawers/advanced_search_syntax.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 source: /doc/user/search/global_search/advanced_search_syntax.md --- diff --git a/doc/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md index af736c11d59..64384372a44 100644 --- a/doc/gitlab-basics/add-file.md +++ b/doc/gitlab-basics/add-file.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md index 02e9117fa3a..4b53535a711 100644 --- a/doc/gitlab-basics/command-line-commands.md +++ b/doc/gitlab-basics/command-line-commands.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Edit files through the command line **(FREE)** diff --git a/doc/gitlab-basics/feature_branch_workflow.md b/doc/gitlab-basics/feature_branch_workflow.md index 989a1557ef2..de051c67bc2 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/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" disqus_identifier: 'https://docs.gitlab.com/ee/workflow/workflow.html' --- diff --git a/doc/gitlab-basics/index.md b/doc/gitlab-basics/index.md deleted file mode 100644 index 3cd5dfe7d18..00000000000 --- a/doc/gitlab-basics/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../user/index.md' -remove_date: '2022-07-08' ---- - -This document was moved to [another location](../user/index.md). - -<!-- This redirect file can be deleted after 2022-07-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 (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/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index 875bd00ee55..056fad4061b 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-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/engineering/ux/technical-writing/#assignments +info: To determine 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 description: "Introduction to using Git through the command line." --- @@ -37,7 +37,7 @@ prompt, command shell, and command line). Here are some options: - [iTerm2](https://iterm2.com/). You can integrate it with [Zsh](https://git-scm.com/book/id/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Zsh) and [Oh My Zsh](https://ohmyz.sh/) for color highlighting and other advanced features. - For Windows users: - Built-in command line. On the Windows taskbar, select the search icon and type `cmd`. - - [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7). + - [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7). - Git Bash. It is built into [Git for Windows](https://gitforwindows.org/). - For Linux users: - Built-in [Linux Terminal](https://ubuntu.com/tutorials/command-line-for-beginners#3-opening-a-terminal). @@ -147,10 +147,14 @@ between your computer and GitLab. git clone https://gitlab.com/gitlab-tests/sample-project.git ``` -1. GitLab requests your username and password: - - If you have 2FA enabled for your account, you must [clone using a token](#clone-using-a-token) - with `read_repository` or `write_repository` permissions instead of your account's password. - - If you don't have 2FA enabled, use your account's password. +1. GitLab requests your username and password. + + If you have enabled two-factor authentication (2FA) on your account, you cannot use your account password. Instead, you can do one of the following: + + - [Clone using a token](#clone-using-a-token) with `read_repository` or `write_repository` permissions. + - Install [Git Credential Manager](../user/profile/account/two_factor_authentication.md#git-credential-manager). + + If you have not enabled 2FA, use your account password. 1. To view the files, go to the new directory: diff --git a/doc/index.md b/doc/index.md index 1ac8cdb19ce..c359ec7b639 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false 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/eks_clusters_aws.md b/doc/install/aws/eks_clusters_aws.md index c939bac888c..03f7cd19ed5 100644 --- a/doc/install/aws/eks_clusters_aws.md +++ b/doc/install/aws/eks_clusters_aws.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # EKS cluster provisioning best practices **(FREE SELF)** diff --git a/doc/install/aws/gitlab_hybrid_on_aws.md b/doc/install/aws/gitlab_hybrid_on_aws.md index b7a01cf61f4..ad3d28d15e3 100644 --- a/doc/install/aws/gitlab_hybrid_on_aws.md +++ b/doc/install/aws/gitlab_hybrid_on_aws.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- {::options parse_block_html="true" /} diff --git a/doc/install/aws/gitlab_sre_for_aws.md b/doc/install/aws/gitlab_sre_for_aws.md index 2e7de6cf2d4..c55ce993cfc 100644 --- a/doc/install/aws/gitlab_sre_for_aws.md +++ b/doc/install/aws/gitlab_sre_for_aws.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: Doing SRE for GitLab instances and runners on AWS. --- diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 1227dd43369..93a966b69fb 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: Read through the GitLab installation methods. type: index @@ -65,7 +65,7 @@ Instances running on Community Edition (CE) require a migration to Enterprise Ed NOTE: Because any given GitLab upgrade might involve data disk updates or database schema upgrades, swapping out the AMI is not sufficient for taking upgrades. -1. Log in to the AWS Web Console, so that clicking the links in the following step take you directly to the AMI list. +1. Log in to the AWS Web Console, so that selecting the links in the following step take you directly to the AMI list. 1. Pick the edition you want: - [GitLab Enterprise Edition](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#Images:visibility=public-images;ownerAlias=782774275127;search=GitLab%20EE;sort=desc:name): If you want to unlock the enterprise features, a license is needed. diff --git a/doc/install/aws/manual_install_aws.md b/doc/install/aws/manual_install_aws.md index 2aa2aa0c3f7..7dbb245dd99 100644 --- a/doc/install/aws/manual_install_aws.md +++ b/doc/install/aws/manual_install_aws.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- {::options parse_block_html="true" /} @@ -268,7 +268,7 @@ On the EC2 dashboard, look for Load Balancer in the left navigation bar: 1. Select **Configure Health Check** and set up a health check for your EC2 instances. 1. For **Ping Protocol**, select HTTP. 1. For **Ping Port**, enter 80. - 1. For **Ping Path** - we recommend that you [use the Readiness check endpoint](../../administration/load_balancer.md#readiness-check). You must add [the VPC IP Address Range (CIDR)](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-groups.html#elb-vpc-nacl) to the [IP allowlist](../../administration/monitoring/ip_whitelist.md) for the [Health Check endpoints](../../user/admin_area/monitoring/health_check.md) + 1. For **Ping Path** - we recommend that you [use the Readiness check endpoint](../../administration/load_balancer.md#readiness-check). You must add [the VPC IP Address Range (CIDR)](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-groups.html#elb-vpc-nacl) to the [IP allowlist](../../administration/monitoring/ip_allowlist.md) for the [Health Check endpoints](../../user/admin_area/monitoring/health_check.md) 1. Keep the default **Advanced Details** or adjust them according to your needs. 1. Select **Add EC2 Instances** - don't add anything as we create an Auto Scaling Group later to manage instances for us. 1. Select **Add Tags** and add any tags you need. @@ -465,7 +465,7 @@ We need a preconfigured, custom GitLab AMI to use in our launch configuration la From the EC2 dashboard: 1. Use the section below titled "[Find official GitLab-created AMI IDs on AWS](#find-official-gitlab-created-ami-ids-on-aws)" to find the correct AMI to launch. -1. After clicking **Launch** on the desired AMI, select an instance type based on your workload. Consult the [hardware requirements](../../install/requirements.md#hardware-requirements) to choose one that fits your needs (at least `c5.xlarge`, which is sufficient to accommodate 100 users). +1. After selecting **Launch** on the desired AMI, select an instance type based on your workload. Consult the [hardware requirements](../../install/requirements.md#hardware-requirements) to choose one that fits your needs (at least `c5.xlarge`, which is sufficient to accommodate 100 users). 1. Select **Configure Instance Details**: 1. In the **Network** dropdown list, select `gitlab-vpc`, the VPC we created earlier. 1. In the **Subnet** dropdown list, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. @@ -670,9 +670,9 @@ Depending on how you installed GitLab and if you did not change the password by - Your instance ID if you used the official GitLab AMI. - A randomly generated password stored for 24 hours in `/etc/gitlab/initial_root_password`. -To change the default password, log in as the `root` user with the default password and [change it in the user profile](../../user/profile#change-your-password). +To change the default password, log in as the `root` user with the default password and [change it in the user profile](../../user/profile/user_passwords.md#change-your-password). -When our [auto scaling group](#create-an-auto-scaling-group) spins up new instances, we are able to log in with username `root` and the newly created password. +When our [auto scaling group](#create-an-auto-scaling-group) spins up new instances, we are able to sign in with username `root` and the newly created password. ### Create custom AMI diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index dd2e7d678e8..9d825bbadcd 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/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/engineering/ux/technical-writing/#assignments +info: To 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: 'Learn how to spin up a pre-configured GitLab VM on Microsoft Azure.' type: howto --- @@ -61,7 +61,7 @@ The first items you need to configure are the basic settings of the underlying v 1. Enter a name for the VM, for example `GitLab`. 1. Select a region. 1. In **Availability options**, select **Availability zone** and set it to `1`. - Read more about the [availability zones](https://docs.microsoft.com/en-us/azure/virtual-machines/availability). + Read more about the [availability zones](https://learn.microsoft.com/en-us/azure/virtual-machines/availability). 1. Ensure the selected image is set to **GitLab - Gen1**. 1. Select the VM size based on the [hardware requirements](../requirements.md#hardware-requirements). Because the minimum system requirements to run a GitLab environment for up to 500 users @@ -83,7 +83,7 @@ For the disks: 1. For the OS disk type, select **Premium SSD**. 1. Select the default encryption. -[Read more about the types of disks](https://docs.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview) that Azure provides. +[Read more about the types of disks](https://learn.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview) that Azure provides. Review your settings, and then proceed to the Networking tab. @@ -159,7 +159,7 @@ to assign a descriptive DNS name to the VM: Eventually, most users want to use their own domain name. For you to do this, you need to add a DNS `A` record with your domain registrar that points to the public IP address of your Azure VM. -You can use [Azure's DNS](https://docs.microsoft.com/en-us/azure/dns/dns-delegate-domain-azure-dns) +You can use [Azure's DNS](https://learn.microsoft.com/en-us/azure/dns/dns-delegate-domain-azure-dns) or some [other registrar](https://docs.gitlab.com/omnibus/settings/dns.html). ### Change the GitLab external URL @@ -185,7 +185,7 @@ To set up the GitLab external URL: NOTE: If you need to reset your credentials, read - [how to reset SSH credentials for a user on an Azure VM](https://docs.microsoft.com/en-us/troubleshoot/azure/virtual-machines/troubleshoot-ssh-connection#reset-ssh-credentials-for-a-user). + [how to reset SSH credentials for a user on an Azure VM](https://learn.microsoft.com/en-us/troubleshoot/azure/virtual-machines/troubleshoot-ssh-connection#reset-ssh-credentials-for-a-user). 1. Open `/etc/gitlab/gitlab.rb` with your editor. 1. Find `external_url` and replace it with your own domain name. For the sake @@ -236,7 +236,7 @@ The credentials are: - Password: the password is automatically created, and there are [two ways to find it](https://docs.bitnami.com/azure/faq/get-started/find-credentials/). -After signing in, be sure to immediately [change the password](../../user/profile/index.md#change-your-password). +After signing in, be sure to immediately [change the password](../../user/profile/user_passwords.md#change-your-password). ## Maintain your GitLab instance diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md deleted file mode 100644 index 86ccf194786..00000000000 --- a/doc/install/digitaloceandocker.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'docker.md' -remove_date: '2022-08-29' ---- - -This document was moved to [another location](docker.md). - -<!-- This redirect file can be deleted after <2022-08-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 (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/docker.md b/doc/install/docker.md index bf08fecc9ca..93988454a27 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Docker images **(FREE SELF)** @@ -122,7 +122,7 @@ After starting a container you can visit `gitlab.example.com` (or `http://192.168.59.103` if you used boot2docker on macOS). It might take a while before the Docker container starts to respond to queries. -Visit the GitLab URL, and log in with username `root` +Visit the GitLab URL, and sign in with the username `root` and the password from the following command: ```shell @@ -298,13 +298,12 @@ sudo docker exec -it gitlab editor /etc/gitlab/gitlab.rb Once you open `/etc/gitlab/gitlab.rb` make sure to set the `external_url` to point to a valid URL. -To receive e-mails from GitLab you have to configure the +To receive emails from GitLab you have to configure the [SMTP settings](https://docs.gitlab.com/omnibus/settings/smtp.html) because the GitLab Docker image doesn't have an SMTP server installed. You may also be interested in [enabling HTTPS](https://docs.gitlab.com/omnibus/settings/ssl.html). -After you make all the changes you want, you will need to restart the container -in order to reconfigure GitLab: +After you make all the changes you want, you will need to restart the container to reconfigure GitLab: ```shell sudo docker restart gitlab diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index e924b6f7c41..7ba1fbad5ea 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/engineering/ux/technical-writing/#assignments +info: To 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: 'Learn how to install a GitLab instance on Google Cloud Platform.' --- @@ -31,7 +31,7 @@ After you have performed those two steps, you can [create a VM](#creating-the-vm To deploy GitLab on GCP you must create a virtual machine: -1. Go to <https://console.cloud.google.com/compute/instances> and log in with your Google credentials. +1. Go to <https://console.cloud.google.com/compute/instances> and sign in with your Google credentials. 1. Select **Create**  @@ -49,7 +49,7 @@ To deploy GitLab on GCP you must create a virtual machine: ## Installing GitLab -After a few seconds, the instance is created and available to log in. The next step is to install GitLab onto the instance. +After a few seconds, the instance is created and available to sign in. The next step is to install GitLab onto the instance.  diff --git a/doc/install/index.md b/doc/install/index.md index 89203c652d1..4aef471ad5c 100644 --- a/doc/install/index.md +++ b/doc/install/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: Read through the GitLab installation methods. type: index diff --git a/doc/install/install_methods.md b/doc/install/install_methods.md index 6c62deba6fa..a872941dfaf 100644 --- a/doc/install/install_methods.md +++ b/doc/install/install_methods.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false description: Read through the GitLab installation methods. type: index diff --git a/doc/install/installation.md b/doc/install/installation.md index 5982e354ae5..6108ec8d0e0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Installation from source **(FREE SELF)** @@ -49,7 +49,7 @@ If the highest number stable branch is unclear, check the [GitLab blog](https:// | Software | Minimum version | Notes | | -------- | --------------- | ----- | | [Ruby](#2-ruby) | `2.7` | From GitLab 13.6, Ruby 2.7 is required. Ruby 3.0 is not supported yet (see [the relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/5149) for the current status). 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. | -| [Go](#3-go) | `1.16` | | +| [Go](#3-go) | `1.17` | From GitLab 15.2, Go 1.17 or later is required. | | [Git](#git) | `2.33.x` | From GitLab 14.4, Git 2.33.x and later is required. It's highly recommended that you use the [Git version provided by Gitaly](#git). | | [Node.js](#4-node) | `14.15.0` | GitLab uses [webpack](https://webpack.js.org/) to compile frontend assets. Node.js 16.x is recommended, as it's faster. You can check which version you're running with `node -v`. You must update it to a newer version if needed. | @@ -120,6 +120,10 @@ sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdb libcurl4-openssl-dev libicu-dev logrotate rsync python3-docutils pkg-config cmake runit-systemd ``` +NOTE: +GitLab requires OpenSSL version 1.1. If your Linux distribution includes a different version of OpenSSL, +you might have to install 1.1 manually. + If you want to use Kerberos for user authentication, install `libkrb5-dev` (if you don't know what Kerberos is, you can assume you don't need it): diff --git a/doc/install/migrate/compare_sm_to_saas.md b/doc/install/migrate/compare_sm_to_saas.md index df79987a2fa..e12861632b8 100644 --- a/doc/install/migrate/compare_sm_to_saas.md +++ b/doc/install/migrate/compare_sm_to_saas.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Comparison of GitLab self-managed with GitLab SaaS diff --git a/doc/install/next_steps.md b/doc/install/next_steps.md index 4df2da875a6..c718d895c8a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Steps after installing GitLab **(FREE SELF)** diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 6bce71e84c1..a620540369f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 8d1cf9afc5c..2d6a9411f25 100644 --- a/doc/install/postgresql_extensions.md +++ b/doc/install/postgresql_extensions.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 6c60ee09d78..3fe34f6a9b0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 03870897417..8a1533dc268 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 755dc5230e9..87b812f3f9b 100644 --- a/doc/integration/advanced_search/elasticsearch.md +++ b/doc/integration/advanced_search/elasticsearch.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Elasticsearch integration **(PREMIUM SELF)** @@ -742,7 +742,7 @@ Make sure to prepare for this task by having a ### Deleted documents -Whenever a change or deletion is made to an indexed GitLab object (a merge request description is changed, a file is deleted from the default branch in a repository, a project is deleted, etc), a document in the index is deleted. However, since these are "soft" deletes, the overall number of "deleted documents", and therefore wasted space, increases. Elasticsearch does intelligent merging of segments in order to remove these deleted documents. However, depending on the amount and type of activity in your GitLab installation, it's possible to see as much as 50% wasted space in the index. +Whenever a change or deletion is made to an indexed GitLab object (a merge request description is changed, a file is deleted from the default branch in a repository, a project is deleted, etc), a document in the index is deleted. However, since these are "soft" deletes, the overall number of "deleted documents", and therefore wasted space, increases. Elasticsearch does intelligent merging of segments to remove these deleted documents. However, depending on the amount and type of activity in your GitLab installation, it's possible to see as much as 50% wasted space in the index. In general, we recommend letting Elasticsearch merge and reclaim space automatically, with the default settings. From [Lucene's Handling of Deleted Documents](https://www.elastic.co/blog/lucenes-handling-of-deleted-documents "Lucene's Handling of Deleted Documents"), _"Overall, besides perhaps decreasing the maximum segment size, it is best to leave Lucene's defaults as-is and not fret too much about when deletes are reclaimed."_ diff --git a/doc/integration/advanced_search/elasticsearch_troubleshooting.md b/doc/integration/advanced_search/elasticsearch_troubleshooting.md index e1a566541c2..7136c273a2a 100644 --- a/doc/integration/advanced_search/elasticsearch_troubleshooting.md +++ b/doc/integration/advanced_search/elasticsearch_troubleshooting.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To 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 Elasticsearch **(PREMIUM SELF)** diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index a2b70d42bb6..09f16c76765 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -1,7 +1,7 @@ --- stage: Anti-Abuse group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Akismet **(FREE)** diff --git a/doc/integration/alicloud.md b/doc/integration/alicloud.md index 1619bdc9504..263b3837d1d 100644 --- a/doc/integration/alicloud.md +++ b/doc/integration/alicloud.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use AliCloud as an OmniAuth authentication provider **(FREE)** diff --git a/doc/integration/arkose.md b/doc/integration/arkose.md index 0135785dc11..aa27e3ba4a4 100644 --- a/doc/integration/arkose.md +++ b/doc/integration/arkose.md @@ -1,7 +1,7 @@ --- stage: Anti-Abuse group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Arkose Protect @@ -29,7 +29,7 @@ user doesn't need to take any additional action and can sign in as usual. ## How do we treat malicious sign-in attempts? Users are not denied access if Arkose Protect considers they are malicious. However, -their risk score is exposed in the admin console so that we can make more informed decisions when it +their risk score is exposed in the administrator console so that we can make more informed decisions when it comes to manually blocking users. When we decide to block a user, feedback is sent to ArkoseLabs to improve their risk prediction model. diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index 71c71bd8b5c..448807e91fc 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auth0 OmniAuth Provider **(FREE SELF)** @@ -11,28 +11,22 @@ application. 1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). You can also create an account using the same link. - 1. Select **New App/API**. - -1. Provide the Application Name ('GitLab' works fine). - -1. After creating, you should see the **Quick Start** options. Disregard them and - select **Settings** above the **Quick Start** options. - +1. Enter the **Application Name**. For example, 'GitLab'. +1. After creating the application, you should see the **Quick Start** options. + Disregard these options and select **Settings** instead. 1. At the top of the Settings screen, you should see your **Domain**, **Client ID**, and - **Client Secret**. These values are needed in the configuration file. For example: + **Client Secret** in the Auth0 Console. Note these settings to complete the configuration + file later. For example: - Domain: `test1234.auth0.com` - Client ID: `t6X8L2465bNePWLOvt9yi41i` - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` - 1. Fill in the **Allowed Callback URLs**: - - `http://YOUR_GITLAB_URL/users/auth/auth0/callback` (or) - - `https://YOUR_GITLAB_URL/users/auth/auth0/callback` - + - `http://<your_gitlab_url>/users/auth/auth0/callback` (or) + - `https://<your_gitlab_url>/users/auth/auth0/callback` 1. Fill in the **Allowed Origins (CORS)**: - - `http://YOUR_GITLAB_URL` (or) - - `https://YOUR_GITLAB_URL` - + - `http://<your_gitlab_url>` (or) + - `https://<your_gitlab_url>` 1. On your GitLab server, open the configuration file. For Omnibus GitLab: @@ -61,9 +55,9 @@ application. name: "auth0", # label: "Provider name", # optional label for login button, defaults to "Auth0" args: { - client_id: "YOUR_AUTH0_CLIENT_ID", - client_secret: "YOUR_AUTH0_CLIENT_SECRET", - domain: "YOUR_AUTH0_DOMAIN", + client_id: "<your_auth0_client_id>", + client_secret: "<your_auth0_client_secret>", + domain: "<your_auth0_domain>", scope: "openid profile email" } } @@ -76,21 +70,17 @@ application. - { name: 'auth0', # label: 'Provider name', # optional label for login button, defaults to "Auth0" args: { - client_id: 'YOUR_AUTH0_CLIENT_ID', - client_secret: 'YOUR_AUTH0_CLIENT_SECRET', - domain: 'YOUR_AUTH0_DOMAIN', + client_id: '<your_auth0_client_id>', + client_secret: '<your_auth0_client_secret>', + domain: '<your_auth0_domain>', scope: 'openid profile email' } } ``` -1. Change `YOUR_AUTH0_CLIENT_ID` to the client ID from the Auth0 Console page - from step 5. - -1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console - page from step 5. - +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. Reconfigure or restart GitLab, depending on your installation method: - - *If you installed from Omnibus GitLab,* [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab. - *If you installed from source,* diff --git a/doc/integration/azure.md b/doc/integration/azure.md index da1aa574bd6..8c30a0cef77 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -1,19 +1,19 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Microsoft Azure as an authentication provider **(FREE SELF)** You can enable the Microsoft Azure OAuth 2.0 OmniAuth provider and sign in to GitLab with your Microsoft Azure credentials. You can configure the provider that uses -[the earlier Azure Active Directory v1.0 endpoint](https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code), +[the earlier Azure Active Directory v1.0 endpoint](https://learn.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-protocols-oauth-code), or the provider that uses the v2.0 endpoint. NOTE: For new projects, Microsoft suggests you use the -[OpenID Connect protocol](../administration/auth/oidc.md#microsoft-azure), +[OpenID Connect protocol](../administration/auth/oidc.md#configure-microsoft-azure), which uses the Microsoft identity platform (v2.0) endpoint. ## Register an Azure application @@ -22,8 +22,8 @@ To enable the Microsoft Azure OAuth 2.0 OmniAuth provider, you must register an Azure application and get a client ID and secret key. 1. Sign in to the [Azure portal](https://portal.azure.com). -1. If you have multiple Azure Active Directory tenants, switch to the desired tenant. -1. [Register an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) +1. If you have multiple Azure Active Directory tenants, switch to the desired tenant. Note the tenant ID. +1. [Register an application](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) and provide the following information: - The redirect URI, which requires the URL of the Azure OAuth callback of your GitLab installation. For example: @@ -33,7 +33,7 @@ an Azure application and get a client ID and secret key. 1. Save the client ID and client secret. The client secret is only displayed once. - If required, you can [create a new application secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret). + If required, you can [create a new application secret](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret). `client ID` and `client secret` are terms associated with OAuth 2.0. In some Microsoft documentation, the terms are named `Application ID` and @@ -41,7 +41,7 @@ In some Microsoft documentation, the terms are named `Application ID` and ## Add API permissions (scopes) -If you're using the v2.0 endpoint, after you create the application, [configure it to expose a web API](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). +If you're using the v2.0 endpoint, after you create the application, [configure it to expose a web API](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis). Add the following delegated permissions under the Microsoft Graph API: - `email` @@ -70,7 +70,7 @@ Alternatively, add the `User.Read.All` application permission. 1. [Configure the initial settings](omniauth.md#configure-initial-settings). -1. Add the provider configuration. Replace `CLIENT ID`, `CLIENT SECRET`, and `TENANT ID` +1. Add the provider configuration. Replace `<client_id>`, `<client_secret>`, and `<tenant_id>` with the values you got when you registered the Azure application. - **For Omnibus installations** @@ -83,9 +83,9 @@ Alternatively, add the `User.Read.All` application permission. name: "azure_oauth2", # label: "Provider name", # optional label for login button, defaults to "Azure AD" args: { - client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID", + client_id: "<client_id>", + client_secret: "<client_secret>", + tenant_id: "<tenant_id>", } } ] @@ -99,15 +99,15 @@ Alternatively, add the `User.Read.All` application permission. "name" => "azure_activedirectory_v2", "label" => "Provider name", # optional label for login button, defaults to "Azure AD v2" "args" => { - "client_id" => "CLIENT ID", - "client_secret" => "CLIENT SECRET", - "tenant_id" => "TENANT ID", + "client_id" => "<client_id>", + "client_secret" => "<client_secret>", + "tenant_id" => "<tenant_id>", } } ] ``` - For [alternative Azure clouds](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud), + For [alternative Azure clouds](https://learn.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud), configure `base_azure_url` under the `args` section. For example, for Azure Government Community Cloud (GCC): ```ruby @@ -116,9 +116,9 @@ Alternatively, add the `User.Read.All` application permission. "name" => "azure_activedirectory_v2", "label" => "Provider name", # optional label for login button, defaults to "Azure AD v2" "args" => { - "client_id" => "CLIENT ID", - "client_secret" => "CLIENT SECRET", - "tenant_id" => "TENANT ID", + "client_id" => "<client_id>", + "client_secret" => "<client_secret>", + "tenant_id" => "<tenant_id>", "base_azure_url" => "https://login.microsoftonline.us" } } @@ -132,9 +132,9 @@ Alternatively, add the `User.Read.All` application permission. ```yaml - { name: 'azure_oauth2', # label: 'Provider name', # optional label for login button, defaults to "Azure AD" - args: { client_id: 'CLIENT ID', - client_secret: 'CLIENT SECRET', - tenant_id: 'TENANT ID' } } + args: { client_id: '<client_id>', + client_secret: '<client_secret>', + tenant_id: '<tenant_id>' } } ``` For the v2.0 endpoint: @@ -142,26 +142,24 @@ Alternatively, add the `User.Read.All` application permission. ```yaml - { name: 'azure_activedirectory_v2', label: 'Provider name', # optional label for login button, defaults to "Azure AD v2" - args: { client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID" } } + args: { client_id: "<client_id>", + client_secret: "<client_secret>", + tenant_id: "<tenant_id>" } } ``` - For [alternative Azure clouds](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud), + For [alternative Azure clouds](https://learn.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud), configure `base_azure_url` under the `args` section. For example, for Azure Government Community Cloud (GCC): ```yaml - { name: 'azure_activedirectory_v2', label: 'Provider name', # optional label for login button, defaults to "Azure AD v2" - args: { client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID", + args: { client_id: "<client_id>", + client_secret: "<client_secret>", + tenant_id: "<tenant_id>", base_azure_url: "https://login.microsoftonline.us" } } ``` - In addition, you can optionally add the following parameters to the `args` section: - - - `scope` for [OAuth2 scopes](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow). The default is `openid profile email`. + You can also optionally add the `scope` for [OAuth 2.0 scopes](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow) parameter to the `args` section. The default is `openid profile email`. 1. Save the configuration file. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 43032902a21..38d8f0049db 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrate your GitLab server with Bitbucket Cloud **(FREE SELF)** @@ -22,14 +22,9 @@ To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket.org. Bitbucket generates an application ID and secret key for you to use. -WARNING: -To help prevent an [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) -vulnerability in which users' GitLab accounts could be compromised, append `/users/auth` -to the end of the Bitbucket authorization callback URL. - 1. Sign in to [Bitbucket.org](https://bitbucket.org). -1. Navigate to your individual user settings (**Bitbucket settings**) or a team's - settings (**Manage team**), depending on how you want the application registered. +1. Go to your individual user settings (**Bitbucket settings**) or a team's + settings (**Manage team**), depending on how you want to register the application. It does not matter if the application is registered as an individual or a team, that is entirely up to you. 1. In the left menu under **Access Management**, select **OAuth**. @@ -44,6 +39,12 @@ to the end of the Bitbucket authorization callback URL. `https://gitlab.example.com/users/auth`. Leaving this field empty [results in an `Invalid redirect_uri` message](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). + + WARNING: + To help prevent an [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) + vulnerability in which users' GitLab accounts could be compromised, append `/users/auth` + to the end of the Bitbucket authorization callback URL. + - **URL:** The URL to your GitLab installation, such as `https://gitlab.example.com`. 1. Grant at least the following permissions: @@ -85,8 +86,8 @@ to the end of the Bitbucket authorization callback URL. { name: "bitbucket", # label: "Provider name", # optional label for login button, defaults to "Bitbucket" - app_id: "BITBUCKET_APP_KEY", - app_secret: "BITBUCKET_APP_SECRET", + app_id: "<bitbucket_app_key>", + app_secret: "<bitbucket_app_secret>", url: "https://bitbucket.org/" } ] @@ -100,12 +101,12 @@ to the end of the Bitbucket authorization callback URL. providers: - { name: 'bitbucket', # label: 'Provider name', # optional label for login button, defaults to "Bitbucket" - app_id: 'BITBUCKET_APP_KEY', - app_secret: 'BITBUCKET_APP_SECRET', + app_id: '<bitbucket_app_key>', + app_secret: '<bitbucket_app_secret>', url: 'https://bitbucket.org/' } ``` - Where `BITBUCKET_APP_KEY` is the Key and `BITBUCKET_APP_SECRET` the Secret + Where `<bitbucket_app_key>` is the **Key** and `<bitbucket_app_secret>` the **Secret** from the Bitbucket application page. 1. Save the configuration file. diff --git a/doc/integration/cas.md b/doc/integration/cas.md index 45c79cd9726..35c5a6db4a7 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CAS OmniAuth provider (deprecated) **(FREE SELF)** diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index 42337006189..31e254658c1 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Datadog integration **(FREE)** diff --git a/doc/integration/ding_talk.md b/doc/integration/ding_talk.md index 71dadd766b2..18423fa1607 100644 --- a/doc/integration/ding_talk.md +++ b/doc/integration/ding_talk.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DingTalk OAuth 2.0 OmniAuth provider **(FREE SELF)** @@ -19,7 +19,7 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene 1. Fill in the application details: - - **Application Name**: This can be anything. Consider something like `<Organization>'s GitLab`, or `<Your Name>'s GitLab`, or something else descriptive. + - **Application Name**: This can be anything. Consider something like `<Organization>'s GitLab`, `<Your Name>'s GitLab`, or something else descriptive. - **Application Description**: Create a description. - **Application icon**: Upload qualified icons if needed. @@ -31,7 +31,7 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene  -1. Under the **Application Credentials** section, there should be an AppKey and AppSecret (see the screenshot). Keep this page open as you continue the configuration. +1. In the **Application Credentials** section, note the **AppKey** and **AppSecret** as you use these values later.  @@ -62,8 +62,8 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene { name: "dingtalk", # label: "Provider name", # optional label for login button, defaults to "Ding Talk" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET" + app_id: "<your_appkey>", + app_secret: "<your_appsecret>" } ] ``` @@ -73,16 +73,16 @@ Sign in to DingTalk Open Platform and create an application on it. DingTalk gene ```yaml - { name: 'dingtalk', # label: 'Provider name', # optional label for login button, defaults to "Ding Talk" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET' } + app_id: '<your_appkey>', + app_secret: '<your_appsecret>' } ``` -1. Change `YOUR_APP_ID` to the AppKey from the application information page in step 6. +1. Replace `<your_appkey>` with the AppKey from the **Application Credentials** in step 6. -1. Change `YOUR_APP_SECRET` to the AppSecret from the application information page in step 6. +1. Replace `<your_appsecret>` with the AppSecret from the **Application Credentials** in step 6. 1. Save the configuration file. -1. For the changes to take effect: - - If you installed via Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - If you installed from source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +1. For the changes to take effect, if you installed: + - Using Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + - From source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md deleted file mode 100644 index 0b34f7018da..00000000000 --- a/doc/integration/elasticsearch.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'advanced_search/elasticsearch.md' -remove_date: '2022-09-13' ---- - -This document was moved to [another location](advanced_search/elasticsearch.md). - -<!-- This redirect file can be deleted after <2022-09-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 -->
\ No newline at end of file diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index ac470291c27..a3c206176b9 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External issue tracker **(FREE)** diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index ea5a3cc6d38..7c6afffc847 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Facebook OAuth 2.0 OmniAuth Provider **(FREE)** diff --git a/doc/integration/github.md b/doc/integration/github.md index ad90c714dac..6b59128966a 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitHub as an authentication provider **(FREE SELF)** diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index fee1e573384..0658c921610 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 c2b27e79d6e..26d0da4b49d 100644 --- a/doc/integration/gitpod.md +++ b/doc/integration/gitpod.md @@ -2,7 +2,7 @@ type: reference, how-to stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Gitpod integration **(FREE)** diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 8b984122c8b..42b89670a68 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gmail actions buttons for GitLab **(FREE)** diff --git a/doc/integration/google.md b/doc/integration/google.md index 80176fac41b..3d174e56bf3 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google OAuth 2.0 OmniAuth Provider **(FREE SELF)** diff --git a/doc/integration/index.md b/doc/integration/index.md index f5b088b47f7..147edcc9e0f 100644 --- a/doc/integration/index.md +++ b/doc/integration/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- @@ -9,6 +9,10 @@ comments: false GitLab can be integrated with external services for enhanced functionality. +## Services + +Services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [integrations](../user/project/integrations/index.md). + ## Issue trackers You can use an [external issue tracker](external-issue-tracker.md) at the same time as the GitLab @@ -61,10 +65,6 @@ or [Kroki](../administration/integration/kroki.md) to use diagrams in AsciiDoc a - Enable integrated code intelligence powered by [Sourcegraph](sourcegraph.md). - Add [Elasticsearch](advanced_search/elasticsearch.md) for [Advanced Search](../user/search/advanced_search.md). -## Integrations - -Integration with services such as Campfire, Flowdock, Jira, Pivotal Tracker, and Slack are available as [Integrations](../user/project/integrations/index.md). - ## Troubleshooting ### SSL certificate errors diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 0a4c2c27c31..8a438dde52e 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jenkins integration **(FREE)** @@ -222,15 +222,7 @@ Or check for duplicate messages in `/var/log/gitlab/gitlab-rail`, like: 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start ``` -To fix this issue: - -1. Increase the `gitlab_rails['webhook_timeout']` value in the `gitlab.rb` - configuration file. -1. [Restart](../administration/restart_gitlab.md) GitLab: - - ```shell - gitlab-ctl reconfigure - ``` +On self-managed GitLab instances, you can fix this issue by [increasing the webhook timeout value](../administration/instance_limits.md#webhook-timeout). ### Enable job logs in Jenkins diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index 5010545b73a..53f7162402b 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments remove_date: '2022-10-29' redirect_to: 'jenkins.md' --- diff --git a/doc/integration/jira/configure.md b/doc/integration/jira/configure.md index 58789afff46..66339d5ec27 100644 --- a/doc/integration/jira/configure.md +++ b/doc/integration/jira/configure.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the Jira integration in GitLab **(FREE)** diff --git a/doc/integration/jira/connect-app.md b/doc/integration/jira/connect-app.md index 5c8f78a94b1..171c1cbe484 100644 --- a/doc/integration/jira/connect-app.md +++ b/doc/integration/jira/connect-app.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab.com for Jira Cloud app **(FREE)** diff --git a/doc/integration/jira/development_panel.md b/doc/integration/jira/development_panel.md index d52d86c5658..bdb79d65d5e 100644 --- a/doc/integration/jira/development_panel.md +++ b/doc/integration/jira/development_panel.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Jira development panel integration **(FREE)** @@ -70,7 +70,7 @@ To simplify administration, we recommend that a GitLab group maintainer or group | Jira usage | GitLab.com customers need | GitLab self-managed customers need | |------------|---------------------------|------------------------------------| | [Atlassian cloud](https://www.atlassian.com/migration/assess/why-cloud) | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). This offers real-time sync between GitLab.com and Jira. For more information, see the documentation for the [GitLab.com for Jira Cloud app](connect-app.md). | The [GitLab.com for Jira Cloud app](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See the documentation for [installing the GitLab.com for Jira Cloud app for self-managed instances](connect-app.md#install-the-gitlabcom-for-jira-cloud-app-for-self-managed-instances) for more information. | -| Your own server | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | The [Jira DVCS Connector](dvcs.md). | +| Your own server | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | The [Jira DVCS (distributed version control system) connector](dvcs.md). This syncs data hourly. | Each GitLab project can be configured to connect to an entire Jira instance. That means after configuration, one GitLab project can interact with all Jira projects in that instance. For: diff --git a/doc/integration/jira/dvcs.md b/doc/integration/jira/dvcs.md index ce097a4db23..f33536b7b91 100644 --- a/doc/integration/jira/dvcs.md +++ b/doc/integration/jira/dvcs.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira DVCS connector **(FREE)** diff --git a/doc/integration/jira/index.md b/doc/integration/jira/index.md index 2f694094940..5daad4094f4 100644 --- a/doc/integration/jira/index.md +++ b/doc/integration/jira/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira integrations **(FREE)** @@ -122,3 +122,59 @@ and complete the CAPTCHA. 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. + +### Bulk change all Jira integrations to Jira instance-level values + +To change all Jira projects to use instance-level integration settings: + +1. In a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session), run the following: + + ```ruby + jira_integration_instance_id = Integrations::Jira.find_by(instance: true).id + Integrations::Jira.where(active: true, instance: false, template: false, inherit_from_id: nil).find_each do |integration| + integration.update_attribute(:inherit_from_id, jira_integration_instance_id) + end + ``` + +1. Modify and save the instance-level integration from the UI to propagate the changes to all group-level and project-level integrations. + +### Check if Jira Cloud is linked + +You can use the [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session) to check if Jira Cloud is linked to: + +A specified namespace: + +```ruby +JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup')) +``` + +A specified project: + +```ruby +Project.find_by_full_path('path/to/project').jira_subscription_exists? +``` + +Any namespace: + +```ruby +installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net") +installation.subscriptions +``` + +### Bulk update the service integration password for all projects + +To reset the Jira user's password for all projects with active Jira integrations, +run the following in a [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN services s ON p.id = s.project_id WHERE s.type = 'JiraService' AND s.active = true") + +p.each do |project| + project.jira_integration.update_attribute(:password, '<your-new-password>') +end +``` + +### `500 Whoops` when accessing a Jira issue in GitLab + +When accessing a Jira issue in GitLab, you might get a `500 Whoops, something went wrong on our end` error. +Check [`production.log`](../../administration/logs/index.md#productionlog) to see if it contains a `:NoMethodError (undefined method 'duedate' for #<JIRA::Resource::Issue:0x00007f406d7b3180>)` exception. If that's the case, ensure the **Due date** field is visible for issues in the integrated Jira project. diff --git a/doc/integration/jira/issues.md b/doc/integration/jira/issues.md index 98dd4526fd9..3a5d8e66b2d 100644 --- a/doc/integration/jira/issues.md +++ b/doc/integration/jira/issues.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira integration issue management **(FREE)** diff --git a/doc/integration/jira/jira_cloud_configuration.md b/doc/integration/jira/jira_cloud_configuration.md index 08cd34860ff..d47c84df5e5 100644 --- a/doc/integration/jira/jira_cloud_configuration.md +++ b/doc/integration/jira/jira_cloud_configuration.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create an API token for Jira in Atlassian cloud **(FREE)** diff --git a/doc/integration/jira/jira_server_configuration.md b/doc/integration/jira/jira_server_configuration.md index 63625dd5065..42de883753c 100644 --- a/doc/integration/jira/jira_server_configuration.md +++ b/doc/integration/jira/jira_server_configuration.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Jira Server credentials **(FREE)** diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 5c9af96ebe8..c7cbc4389f5 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Kerberos integration **(PREMIUM SELF)** @@ -295,7 +295,7 @@ this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token 1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. After this change, Git remote URLs have to be updated to -`https://gitlab.example.com:8443/mygroup/myproject.git` in order to use +`https://gitlab.example.com:8443/mygroup/myproject.git` to use Kerberos ticket-based authentication. ## Upgrading from password-based to ticket-based Kerberos sign-ins diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index 1e57e45aef3..04b0157b737 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Mattermost @@ -272,7 +272,7 @@ There are 4 users on local instance ### Use `mmctl` through a remote connection For remote connections or local connections where the socket cannot be used, -create a non SSO user and give that user admin privileges. Those credentials +create a non SSO user and give that user administrator privileges. Those credentials can then be used to authenticate `mmctl`: ```shell diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index e3ec1aa16a1..a337873a67e 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -1,42 +1,42 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Generic OAuth2 provider **(FREE SELF)** +# Generic OAuth 2.0 provider **(FREE SELF)** The `omniauth-oauth2-generic` gem allows single sign-on (SSO) between GitLab -and your OAuth2 provider (or any OAuth2 provider compatible with this gem). +and your OAuth 2.0 provider, or any OAuth 2.0 provider compatible with this gem). This strategy allows for the configuration of this OmniAuth SSO process: 1. Strategy directs the client to your authorization URL (**configurable**), with the specified ID and key. -1. The OAuth2 provider handles authentication of the request, user, and (optionally) - authorization to access user's profile. -1. The OAuth2 provider directs the client back to GitLab where Strategy handles - the retrieval of the access token. +1. The OAuth 2.0 provider handles authentication of the request, user, and (optionally) + authorization to access the user's profile. +1. The OAuth 2.0 provider directs the client back to GitLab where Strategy + retrieves the access token. 1. Strategy requests user information from a **configurable** "user profile" - URL (using the access token). -1. Strategy parses user information from the response, using a **configurable** + URL using the access token. +1. Strategy parses user information from the response using a **configurable** format. 1. GitLab finds or creates the returned user and signs them in. -## Limitations of this strategy +This strategy: -- It can only be used for single sign-on, and doesn't provide any other access - granted by any OAuth2 provider (like importing projects or users). -- It supports only the Authorization Grant flow (most common for client-server - applications, like GitLab). -- It can't fetch user information from more than one URL. -- It hasn't been tested with user information formats, other than JSON. +- Can only be used for single sign-on, and does not provide any other access + granted by any OAuth 2.0 provider. For example, importing projects or users. +- Only supports the Authorization Grant flow, which is most common for client-server + applications like GitLab. +- Cannot fetch user information from more than one URL. +- Has not been tested with user information formats, except JSON. -## Configure the OAuth2 provider +## Configure the OAuth 2.0 provider To configure the provider: -1. Register your application in the OAuth2 provider you want to authenticate with. +1. Register your application in the OAuth 2.0 provider you want to authenticate with. The redirect URI you provide when registering the application should be: @@ -44,9 +44,9 @@ To configure the provider: http://your-gitlab.host.com/users/auth/oauth2_generic/callback ``` - You should now be able to get a Client ID and Client Secret. Where this - appears differs for each provider. This may also be called Application ID - and Secret. + You should now be able to get a client ID and client secret. Where these + appear is different for each provider. This may also be called application ID + and application secret. 1. On your GitLab server, open the appropriate configuration file. @@ -99,15 +99,14 @@ To configure the provider: ] ``` - For more information about these settings, see [the gem's README](https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example). + For more information about these settings, see the [gem's README](https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example). 1. Save the configuration file. -1. [Restart](../administration/restart_gitlab.md#installations-from-source) - GitLab for the changes to take effect. +1. For the changes to take effect, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign-in page there should now be a new button below the regular sign-in -form. Select the button to begin your provider's authentication process. This -directs the browser to your OAuth2 provider's authentication page. If -everything goes well, you are returned to your GitLab instance and are +On the sign-in page there should now be a new icon below the regular sign-in +form. Select that icon to begin your provider's authentication process. This +directs the browser to your OAuth 2.0 provider's authentication page. If +everything goes well, you are returned to your GitLab instance and signed in. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 21184f7b678..964c5edcbc1 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure GitLab as an OAuth 2.0 authentication identity provider @@ -126,7 +126,7 @@ application can perform. Available scopes are depicted in the following table. | `profile` | Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). | | `email` | Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). | -At any time you can revoke any access by clicking **Revoke**. +At any time you can revoke any access by selecting **Revoke**. ## Hashed OAuth application secrets @@ -137,3 +137,17 @@ On self-managed GitLab, by default, this feature is not available. To make it av On GitLab.com, this feature is not available. By default, OAuth application secrets are stored as plain text in the database. When enabled, OAuth application secrets are stored in the database in hashed format and are only available to users immediately after creating OAuth applications. + +## Hashed OAuth tokens + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364110) in GitLab 15.3 [with a flag](../administration/feature_flags.md) named `hash_oauth_tokens`. Enabled on GitLab.com. Disabled by default for self-managed. +> - [Enabled by default on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 15.5. + +FLAG: +On self-managed GitLab, by default, this feature is enabled. If you detect a problem, ask an administrator to +[disable the feature flag](../administration/feature_flags.md) named `hash_oauth_tokens`. If the feature flag is disabled, any tokens that were stored +in encrypted format are inaccessible. Users must reauthorize applications. +On GitLab.com, this feature is enabled. + +By default, OAuth access tokens are stored in the database in PBKDF2+SHA512 format. GitLab administrators can disable this and OAuth access tokens are +then stored in plaintext in the database. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 0dfc78b508b..55d1d1bcbb8 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # OmniAuth **(FREE SELF)** @@ -439,8 +439,9 @@ then override the icon in one of two ways: ## Change apps or configuration -Because GitLab doesn't support having multiple providers in OAuth, GitLab configuration and user identification must be -updated at the same time if the provider or app is changed. +Because OAuth in GitLab doesn't support setting the same external authentication and authorization provider as multiple providers, GitLab configuration and +user identification must be updated at the same time if the provider or app is changed. +For example, you can set up `saml` and `azure_activedirectory_v2` but cannot add a second `azure_activedirectory_v2` to the same configuration. These instructions apply to all methods of authentication where GitLab stores an `extern_uid` and it is the only data used for user authentication. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index cc9c8ffd012..ad4cf195d7b 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab as OpenID Connect identity provider **(FREE)** diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index a5fd8db63bd..93d859dd183 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # reCAPTCHA **(FREE SELF)** diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 70d6e0aa0d8..d4d2bfacb4f 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -1,12 +1,12 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Salesforce OmniAuth Provider **(FREE SELF)** -You can integrate your GitLab instance with [Salesforce](https://www.salesforce.com/) to enable users to log in to your GitLab instance with their Salesforce account. +You can integrate your GitLab instance with [Salesforce](https://www.salesforce.com/) to enable users to sign in to your GitLab instance with their Salesforce account. ## Create a Salesforce Connected App diff --git a/doc/integration/saml.md b/doc/integration/saml.md index ef31f276025..0f7f3e336ef 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -795,7 +795,7 @@ documentation on how to use SAML to sign in to GitLab. Examples: -- [ADFS (Active Directory Federation Services)](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) +- [ADFS (Active Directory Federation Services)](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) - [Auth0](https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-identity-provider) GitLab provides the following setup notes for guidance only. diff --git a/doc/integration/security_partners/index.md b/doc/integration/security_partners/index.md index 507157f9326..a337ed7757b 100644 --- a/doc/integration/security_partners/index.md +++ b/doc/integration/security_partners/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index db1d5a8cce4..ff892f006a5 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Slash commands in Mattermost and Slack **(FREE)** diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 731c21c17fa..39efccb7c50 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/integration/trello_power_up.md b/doc/integration/trello_power_up.md index 8a8952cb594..df3755dbf31 100644 --- a/doc/integration/trello_power_up.md +++ b/doc/integration/trello_power_up.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Trello Power-Up **(FREE)** diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index aa9014adc49..90fb63ff40a 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -1,45 +1,51 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Twitter OAuth 1.0a OmniAuth Provider **(FREE SELF)** NOTE: -Twitter OAuth 2.0 support is [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/366213). +Twitter OAuth 2.0 support is [not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/366213). To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter generates a client ID and secret key for you to use. +## Create a new Twitter application + 1. Sign in to [Twitter Application Management](https://developer.twitter.com/apps). -1. Select "Create new app". +1. Select **Create new app**. 1. Fill in the application details. - - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or + - **Name**: This can be anything. Consider something like `<Organization>'s GitLab`, `<Your Name>'s GitLab` or something else descriptive. - - Description: Create a description. - - Website: The URL to your GitLab installation. `https://gitlab.example.com` - - Callback URL: `https://gitlab.example.com/users/auth/twitter/callback` - - Agree to the "Developer Agreement". + - **Description**: Create a description. + - **Website**: The URL to your GitLab installation. For example, `https://gitlab.example.com` + - **Callback URL**: `https://gitlab.example.com/users/auth/twitter/callback` + - **Developer Agreement**: Select **Yes, I agree**.  -1. Select "Create your Twitter application." +1. Select **Create your Twitter application**. + +## Configure the application settings -1. Select the "Settings" tab. +1. Select the **Settings** tab. -1. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in with Twitter." +1. Underneath the **Callback URL**, select the **Allow this application to be used to Sign in with Twitter** checkbox. -1. Select "Update settings" at the bottom to save changes. +1. Select **Update settings** to save the changes. -1. Select the "Keys and Access Tokens" tab. +1. Select the **Keys and Access Tokens** tab. -1. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration. +1. Find your **API key** and **API secret**. Keep this tab open as you continue configuration.  +## Configure your application on the GitLab server + 1. On your GitLab server, open the configuration file. For Omnibus package: @@ -58,7 +64,7 @@ Twitter. Twitter generates a client ID and secret key for you to use. 1. See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. -1. Add the provider configuration: +1. Add the provider configuration. For Omnibus package: @@ -67,8 +73,8 @@ Twitter. Twitter generates a client ID and secret key for you to use. { name: "twitter", # label: "Provider name", # optional label for login button, defaults to "Twitter" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET" + app_id: "<your_api_key>", + app_secret: "<your_api_secret>" } ] ``` @@ -78,18 +84,20 @@ Twitter. Twitter generates a client ID and secret key for you to use. ```yaml - { name: 'twitter', # label: 'Provider name', # optional label for login button, defaults to "Twitter" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET' } + app_id: '<your_api_key>', + app_secret: '<your_api_secret>' } ``` -1. Change 'YOUR_APP_ID' to the API key from Twitter page in step 11. +1. Change `<your_api_key>` to the API key from the Twitter **Keys and Access Tokens** tab. -1. Change 'YOUR_APP_SECRET' to the API secret from the Twitter page in step 11. +1. Change `<your_api_secret>` to the API secret from the Twitter **Keys and Access Tokens** tab. 1. Save the configuration file. -1. For the changes to take effect: - - If you installed via Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). - - If you installed from source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). +1. For the changes to take effect, if you installed: + + - Using Omnibus, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + - From source, [restart GitLab](../administration/restart_gitlab.md#installations-from-source). -On the sign in page there should now be a Twitter icon below the regular sign in form. Select the icon to begin the authentication process. Twitter asks the user to sign in and authorize the GitLab application. If everything goes well the user is returned to GitLab and signed in. +On the sign-in page, find the Twitter option below the regular sign-in form. Select the option to begin the authentication process. Twitter asks you to sign in and authorize the GitLab application. After authorization, +you are returned to GitLab and signed in. diff --git a/doc/integration/vault.md b/doc/integration/vault.md index f85c71a5bb3..ad807f9eb7a 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -1,137 +1,157 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vault Authentication with GitLab OpenID Connect **(FREE)** [Vault](https://www.vaultproject.io/) is a secrets management application offered by HashiCorp. -It allows you to store and manage sensitive information such as secret environment variables, encryption keys, and authentication tokens. -Vault offers Identity-based Access, which means Vault users can authenticate through several of their preferred cloud providers. +It allows you to store and manage sensitive information such as secret environment +variables, encryption keys, and authentication tokens. -This document explains how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature. -The following assumes you already have Vault installed and running. +Vault offers Identity-based Access, which means Vault users can authenticate +through several of their preferred cloud providers. -1. **Get the OpenID Connect client ID and secret from GitLab:** +The following content explains how Vault users can authenticate themselves through +GitLab by using our OpenID authentication feature. - First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault. - To do this, sign in to GitLab and follow these steps: +## Prerequisites - 1. In the top-right corner, select your avatar. - 1. Select **Edit profile**. - 1. On the left sidebar, select **Applications**. - 1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - 1. Select the **OpenID** scope. - 1. Select **Save application**. - 1. Copy client ID and secret, or keep the page open for reference. +1. [Install Vault](https://www.vaultproject.io/docs/install). +1. Run Vault. -  +## Get the OpenID Connect client ID and secret from GitLab -1. **Enable OIDC auth on Vault:** +First you must create a GitLab application to obtain an application ID and secret +for authenticating into Vault. To do this, sign in to GitLab and follow these steps: - OpenID Connect is not enabled in Vault by default. This needs to be enabled in the terminal. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Applications**. +1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). +1. Select the **OpenID** scope. +1. Select **Save application**. +1. Copy the **Client ID** and **Client Secret**, or keep the page open for reference. - Open a terminal session and run the following command to enable the OpenID Connect authentication provider in Vault: + - ```shell - vault auth enable oidc - ``` +## Enable OpenID Connect on Vault - You should see the following output in the terminal: +OpenID Connect (OIDC) is not enabled in Vault by default. - ```plaintext - Success! Enabled oidc auth method at: oidc/ - ``` +To enable the OIDC authentication provider in Vault, open a terminal session +and run the following command: -1. **Write the OIDC configuration:** +```shell +vault auth enable oidc +``` - Next, Vault needs to be given the application ID and secret generated by GitLab. +You should see the following output in the terminal: - In the terminal session, run the following command to give Vault access to the GitLab application you've just created with an OpenID scope. This allows Vault to authenticate through GitLab. +```plaintext +Success! Enabled oidc auth method at: oidc/ +``` - Replace `your_application_id` and `your_secret` in the example below with the application ID and secret generated for your app: +## Write the OIDC configuration - ```shell - $ vault write auth/oidc/config \ - oidc_discovery_url="https://gitlab.com" \ - oidc_client_id="your_application_id" \ - oidc_client_secret="your_secret" \ - default_role="demo" \ - bound_issuer="localhost" - ``` +To give Vault the application ID and secret generated by GitLab and allow +Vault to authenticate through GitLab, run the following command in the terminal: - You should see the following output in the terminal: +```shell +vault write auth/oidc/config \ + oidc_discovery_url="https://gitlab.com" \ + oidc_client_id="<your_application_id>" \ + oidc_client_secret="<your_secret>" \ + default_role="demo" \ + bound_issuer="localhost" +``` - ```shell - Success! Data written to: auth/oidc/config - ``` +Replace `<your_application_id>` and `<your_secret>` with the application ID +and secret generated for your app. -1. **Write the OIDC Role Configuration:** +You should see the following output in the terminal: - Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) and scopes given to GitLab during the application creation process. The redirect URIs need to match where your Vault instance is running. The `oidc_scopes` field needs to include the `openid`. Similarly to the previous step, replace `your_application_id` with the generated application ID from GitLab: +```shell +Success! Data written to: auth/oidc/config +``` - This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we show how you can access this role through the Vault CLI. +## Write the OIDC role configuration - WARNING: - If you're using a public GitLab instance (GitLab.com or any other instance publicly - accessible), it's paramount to specify the `bound_claims` to allow access only to - members of your group/project. Otherwise, anyone with a public account can access - your Vault instance. +You must tell Vault the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) +and scopes given to GitLab when you created the application. - ```shell - vault write auth/oidc/role/demo -<<EOF - { - "user_claim": "sub", - "allowed_redirect_uris": "your_vault_instance_redirect_uris", - "bound_audiences": "your_application_id", - "oidc_scopes": "openid", - "role_type": "oidc", - "policies": "demo", - "ttl": "1h", - "bound_claims": { "groups": ["yourGroup/yourSubgrup"] } - } - EOF - ``` +Run the following command in the terminal: + +```shell +vault write auth/oidc/role/demo -<<EOF +{ + "user_claim": "sub", + "allowed_redirect_uris": "<your_vault_instance_redirect_uris>", + "bound_audiences": "<your_application_id>", + "oidc_scopes": "<openid>", + "role_type": "oidc", + "policies": "demo", + "ttl": "1h", + "bound_claims": { "groups": ["<yourGroup/yourSubgrup>"] } +} +EOF +``` + +Replace: + +- `<your_vault_instance_redirect_uris>` with redirect URIs that match where your + Vault instance is running. +- `<your_application_id>` with the application ID generated for your app. -1. **Sign in to Vault:** +The `oidc_scopes` field must include `openid`. - 1. Go to your Vault UI (example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc)). - 1. If the `OIDC` method is not currently selected, open the dropdown and select it. - 1. Select **Sign in With GitLab**, which opens a modal window: +This configuration is saved under the name of the role you are creating. In this +example, we are creating a `demo` role. -  +WARNING: +If you're using a public GitLab instance, such as GitLab.com, you must specify +the `bound_claims` to allow access only to members of your group or project. +Otherwise, anyone with a public account can access your Vault instance. - 1. Select **Authorize** to allow Vault to sign in through GitLab. This redirects you back to your Vault UI as a signed-in user. +## Sign in to Vault -  +1. Go to your Vault UI. For example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc). +1. If the `OIDC` method is not selected, open the dropdown list and select it. +1. Select **Sign in With GitLab**, which opens a modal window: -1. **Sign in using the Vault CLI** (optional): +  - Vault also allows you to sign in via their CLI. +1. To allow Vault to sign in through GitLab, select **Authorize**. This redirects you back to your Vault UI as a signed-in user. - After writing the same configurations from above, you can run the command below in your terminal to sign in with the role configuration created in step 4 above: +  + +## Sign in using the Vault CLI (optional) + +You can also sign into Vault using the [Vault CLI](https://www.vaultproject.io/docs/commands). + +1. To sign in with the role configuration you created in the previous example, + run the following command in your terminal: ```shell vault login -method=oidc port=8250 role=demo ``` - Here's a short explanation of what this command does: + This command sets: + + - `role=demo` so Vault knows which configuration we'd like to sign in with. + - `-method=oidc` to set Vault to use the `OIDC` sign-in method. + - `port=8250` to set the port that GitLab should redirect to. This port + number must match the port given to GitLab when listing + [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). - 1. In the **Write the OIDC Role Configuration** (step 4), we created a role called - `demo`. We set `role=demo` so Vault knows which configuration we'd like to - sign in with. - 1. To set Vault to use the `OIDC` sign-in method, we set `-method=oidc`. - 1. To set the port that GitLab should redirect to, we set `port=8250` or - another port number that matches the port given to GitLab when listing - [Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris). + After running this command, you should see a link in the terminal. - After running the command, it presents a link in the terminal. - Select the link in the terminal and a browser tab opens that confirms you're signed into Vault via OIDC: +1. Open this link in a web browser:  - The terminal outputs: + You should see in the terminal: ```plaintext Success! You are now authenticated. The token information displayed below diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md index 19f86ae41bc..257b26dd7c4 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Corporate contributor license agreement diff --git a/doc/legal/developer_certificate_of_origin.md b/doc/legal/developer_certificate_of_origin.md index 87185284e58..5c9f7f1fed7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Developer Certificate of Origin Version 1.1 diff --git a/doc/legal/index.md b/doc/legal/index.md index 9d7b799335c..ea0301284ea 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md index 573f535fd84..125ab1e6a8e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Individual contributor license agreement diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index 22e21c01fbd..3717eb46184 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -1,7 +1,7 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Error Tracking **(FREE)** @@ -88,7 +88,7 @@ Here, you can filter errors by title or by status (one of Ignored , Resolved, or ## Error Details -From error list, users can navigate to the error details page by clicking the title of any error. +From error list, users can navigate to the error details page by selecting the title of any error. This page has: @@ -112,7 +112,7 @@ You can take action on Sentry Errors from within the GitLab UI. Marking errors i > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39665) in GitLab 12.7. -From within the [Error Details](#error-details) page you can ignore a Sentry error by clicking the **Ignore** button near the top of the page. +From within the [Error Details](#error-details) page you can ignore a Sentry error by selecting the **Ignore** button near the top of the page. Ignoring an error prevents it from appearing in the [Error Tracking List](#error-tracking-list), and silences notifications that were set up within Sentry. @@ -121,7 +121,7 @@ Ignoring an error prevents it from appearing in the [Error Tracking List](#error > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39825) in GitLab 12.7. From within the [Error Details](#error-details) page you can resolve a Sentry error by -clicking the **Resolve** button near the top of the page. +selecting the **Resolve** button near the top of the page. Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue closes. diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index 0dccaa6bfe9..0afba821363 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -1,24 +1,24 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Feature Flags **(FREE)** +# Feature flags **(FREE)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) from GitLab Premium to GitLab Free in 13.5. -With Feature Flags, you can deploy your application's new features to production in smaller batches. +With feature flags, you can deploy your application's new features to production in smaller batches. You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery. Feature flags help reduce risk, allowing you to do controlled testing, and separate feature delivery from customer launch. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo). +For an example of feature flags in action, see [GitLab for deploys, feature flags, and error tracking](https://www.youtube.com/embed/5tw2p6lwXxo). NOTE: -The Feature Flags GitLab offer as a feature (described in this document) is not the same method -used for the [development of GitLab](../development/feature_flags/index.md). +To contribute to the development of the GitLab product, view +[this feature flag content](../development/feature_flags/index.md) instead. ## How it works @@ -43,7 +43,7 @@ To create and enable a feature flag: 1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`), or dashes (`-`), and does not end with a dash (`-`) or underscore (`_`). 1. Optional. Enter a description (255 characters maximum). -1. Add Feature Flag [**Strategies**](#feature-flag-strategies) to define how the flag should be applied. For each strategy, include the **Type** (defaults to [**All users**](#all-users)) +1. Add feature flag [**Strategies**](#feature-flag-strategies) to define how the flag should be applied. For each strategy, include the **Type** (defaults to [**All users**](#all-users)) and **Environments** (defaults to all environments). 1. Select **Create feature flag**. @@ -74,9 +74,9 @@ is 200. For GitLab SaaS, the maximum number is determined by [tier](https://abou You can apply a feature flag strategy across multiple environments, without defining the strategy multiple times. -GitLab Feature Flags use [Unleash](https://docs.getunleash.io/) as the feature flag +GitLab feature flags use [Unleash](https://docs.getunleash.io/) as the feature flag engine. In Unleash, there are [strategies](https://docs.getunleash.io/user_guide/activation_strategy) -for granular feature flag controls. GitLab Feature Flags can have multiple strategies, +for granular feature flag controls. GitLab feature flags can have multiple strategies, and the supported strategies are: - [All users](#all-users) @@ -162,7 +162,7 @@ target users. See the [Ruby example](#ruby-application-example) below. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35930) in GitLab 13.1. -Enables the feature for lists of users created [in the Feature Flags UI](#create-a-user-list), or with the [Feature Flag User List API](../api/feature_flag_user_lists.md). +Enables the feature for lists of users created [in the feature flags UI](#create-a-user-list), or with the [feature flag user list API](../api/feature_flag_user_lists.md). Similar to [User IDs](#user-ids), it uses the Unleash UsersIDs (`userWithId`) activation [strategy](https://docs.getunleash.io/user_guide/activation_strategy#userids). It's not possible to *disable* a feature for members of a user list, but you can achieve the same @@ -294,9 +294,9 @@ Unleash currently [offers many SDKs for various languages and frameworks](https: For API content, see: -- [Feature Flags API](../api/feature_flags.md) -- [Feature Flag Specs API](../api/feature_flag_specs.md) (Deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/213369) in GitLab 14.0.) -- [Feature Flag User Lists API](../api/feature_flag_user_lists.md) +- [Feature flags API](../api/feature_flags.md) +- [Feature flag specs API](../api/feature_flag_specs.md) (Deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/213369) in GitLab 14.0.) +- [Feature flag user lists API](../api/feature_flag_user_lists.md) ### Golang application example @@ -395,13 +395,13 @@ docker run \ | `UNLEASH_APP_NAME` | The name of the environment the application runs in. For more details, read [Get access credentials](#get-access-credentials). | | `UNLEASH_API_TOKEN` | Required to start the Unleash Proxy, but not used to connect to GitLab. Can be set to any value. | -## Feature Flag Related Issues **(PREMIUM)** +## Feature flag related issues **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36617) in GitLab 13.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/251234) in GitLab 13.5. > - Showing related feature flags in issues [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220333) in GitLab 14.1. -You can link related issues to a feature flag. In the Feature Flag **Linked issues** section, +You can link related issues to a feature flag. In the feature flag **Linked issues** section, select the `+` button and input the issue reference number or the full URL of the issue. The issues then appear in the related feature flag and the other way round. @@ -409,7 +409,7 @@ This feature is similar to the [linked issues](../user/project/issues/related_is ## Performance factors -In general, GitLab Feature Flags can be used in any applications, +In general, GitLab feature flags can be used in any applications, however, if it's a large application, it could require an additional configuration in advance. This section explains the performance factors to help your organization to identify what's needed to be done before using the feature. @@ -418,7 +418,7 @@ Please read [How it works](#how-it-works) section before diving into the details ### Maximum supported clients in application nodes GitLab accepts client requests as much as possible until it hits the [rate limiting](../security/rate_limits.md). -At the moment, the Feature Flag API falls into **Unauthenticated traffic (from a given IP address)** +At the moment, the feature flag API falls into **Unauthenticated traffic (from a given IP address)** in the [GitLab.com specific limits](../user/gitlab_com/index.md), so it's **500 requests per minute**. diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index 7e4223c0820..32603aa3753 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Alerts **(FREE)** @@ -13,7 +13,7 @@ Alerts are a critical entity in your incident management workflow. They represen Users with at least the Developer role can access the Alert list at **Monitor > Alerts** in your project's sidebar. The Alert list displays alerts sorted by start time, but -you can change the sort order by clicking the headers in the Alert list. +you can change the sort order by selecting the headers in the Alert list. The alert list displays the following information: diff --git a/doc/operations/incident_management/escalation_policies.md b/doc/operations/incident_management/escalation_policies.md index 56ff733e395..87455906b26 100644 --- a/doc/operations/incident_management/escalation_policies.md +++ b/doc/operations/incident_management/escalation_policies.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Escalation Policies **(PREMIUM)** diff --git a/doc/operations/incident_management/incident_timeline_events.md b/doc/operations/incident_management/incident_timeline_events.md index 743f9b429d6..5f98335d7aa 100644 --- a/doc/operations/incident_management/incident_timeline_events.md +++ b/doc/operations/incident_management/incident_timeline_events.md @@ -1,16 +1,14 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Timeline events -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344059) in GitLab 15.2 [with a flag](../../administration/feature_flags.md) named `incident_timeline`. Enabled by default. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `incident_timeline`. -On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344059) in GitLab 15.2 [with a flag](../../administration/feature_flags.md) named `incident_timeline`. Enabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/353426) in GitLab 15.3. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/353426) in GitLab 15.5. [Feature flag 'incident_timeline'](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) removed. Incident timelines are an important part of record keeping for incidents. Timelines can show executives and external viewers what happened during an incident, diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 2cb2e5f8045..edbe07f166c 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incidents **(FREE)** @@ -10,9 +10,6 @@ Incidents are critical entities in incident management workflows. They represent a service disruption or outage that needs to be restored urgently. GitLab provides tools for the triage, response, and remediation of incidents. -Users with at least Guest [permissions](../../user/permissions.md) can access -incidents [on public projects](../../user/permissions.md#project-members-permissions). - ## Incident creation You can create an incident manually or automatically. @@ -86,8 +83,14 @@ confirm that a GitLab incident is created from the incident. ## Incident list -For users with at least Guest [permissions](../../user/permissions.md), the -Incident list is available at **Monitor > Incidents** +Whether you can view an incident depends on the [project visibility level](../../user/public_access.md) and +the incident's confidentiality status: + +- Public project and a non-confidential incident: You don't have to be a member of the project. +- Private project and non-confidential incident: You must have at least the Guest role for the project. +- Confidential incident (regardless of project visibility): You must have at least the Reporter. + +The Incident list is available at **Monitor > Incidents** in your project's sidebar. The list contains the following metrics:  @@ -138,10 +141,9 @@ For a live example of the incident list in action, visit this > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230847) in GitLab 13.4. -Users with at least Guest [permissions](../../user/permissions.md) can view -the Incident Details page. Navigate to **Monitor > Incidents** in your project's -sidebar, and select an incident from the list. - +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Monitor > Incidents**. +1. Select an incident from the list. When you take any of these actions on an incident, GitLab logs a system note and displays it in the Incident Details view: @@ -192,7 +194,7 @@ When you upload an image, you can associate the image with text or a link to the  -If you add a link, you can access the original graph by clicking the hyperlink above the uploaded image. +If you add a link, you can access the original graph by selecting the hyperlink above the uploaded image. ### Alert details diff --git a/doc/operations/incident_management/index.md b/doc/operations/incident_management/index.md index 3b38d4ab427..9e66ab46692 100644 --- a/doc/operations/incident_management/index.md +++ b/doc/operations/incident_management/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incident management **(FREE)** diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md index 6e65fe875c5..ae6ffe549d5 100644 --- a/doc/operations/incident_management/integrations.md +++ b/doc/operations/incident_management/integrations.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Integrations **(FREE)** diff --git a/doc/operations/incident_management/linked_resources.md b/doc/operations/incident_management/linked_resources.md index 3fe4a325cdb..4c3ef34f634 100644 --- a/doc/operations/incident_management/linked_resources.md +++ b/doc/operations/incident_management/linked_resources.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked resources in incidents **(PREMIUM)** @@ -50,6 +50,24 @@ To add a linked resource: 1. Complete the required fields. 1. Select **Add**. +### Using a quick action **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5. + +To add multiple links to an incident, use the `/link` +[quick action](../../user/project/quick_actions.md): + +```plaintext +/link https://example.link.us/j/123456789 +``` + +You can also submit a short description with the link. +The description shows instead of the URL in the **Linked resources** section of the incident: + +```plaintext +/link https://example.link.us/j/123456789, multiple alerts firing +``` + ### Link Zoom meetings from an incident **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) in GitLab 15.4. @@ -63,7 +81,7 @@ Use the `/zoom` [quick action](../../user/project/quick_actions.md) to add multi You can also submit a short optional description with the link. The description shows instead of the URL in the **Linked resources** section of the incident issue: ```plaintext -/zoom https://example.zoom.us/j/123456789, Low on memory incident +/zoom https://example.zoom.us/j/123456789 Low on memory incident ``` ## Remove a linked resource diff --git a/doc/operations/incident_management/oncall_schedules.md b/doc/operations/incident_management/oncall_schedules.md index f1fb3503195..9dfac56f0ba 100644 --- a/doc/operations/incident_management/oncall_schedules.md +++ b/doc/operations/incident_management/oncall_schedules.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # On-call Schedule Management **(PREMIUM)** diff --git a/doc/operations/incident_management/paging.md b/doc/operations/incident_management/paging.md index 837fc9c72f5..55e1c9dfbcc 100644 --- a/doc/operations/incident_management/paging.md +++ b/doc/operations/incident_management/paging.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Paging and notifications **(FREE)** diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index ae4d75396ae..5dd690a1c9f 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Status Page **(ULTIMATE)** @@ -14,7 +14,7 @@ overview of recent incidents:  -Clicking an incident displays a detail page with more information about a particular incident: +Selecting an incident displays a detail page with more information about a particular incident:  @@ -140,7 +140,7 @@ you provided during setup. As part of publication, GitLab: - Publishes any files attached to incident issue descriptions, up to 5000 per issue. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205166) in GitLab 13.1.) -After publication, you can access the incident's details page by clicking the +After publication, you can access the incident's details page by selecting the **Published on status page** button displayed under the Incident's title.  diff --git a/doc/operations/index.md b/doc/operations/index.md index 05ce1c5d876..4f0d843f66e 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitor application performance **(FREE)** diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 6017e2ee16c..ffd304c8897 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up alerts for Prometheus metrics **(FREE)** diff --git a/doc/operations/metrics/dashboards/default.md b/doc/operations/metrics/dashboards/default.md index 5c7d6440a7e..7a68e8bf3b3 100644 --- a/doc/operations/metrics/dashboards/default.md +++ b/doc/operations/metrics/dashboards/default.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab-defined metrics dashboards (DEPRECATED) **(FREE)** diff --git a/doc/operations/metrics/dashboards/develop.md b/doc/operations/metrics/dashboards/develop.md index e09f56e27cf..da5a26fbffd 100644 --- a/doc/operations/metrics/dashboards/develop.md +++ b/doc/operations/metrics/dashboards/develop.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Developing templates for custom dashboards (DEPRECATED) **(FREE)** diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index bd1f75b7b42..4e0b50d1e04 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom dashboards (DEPRECATED) **(FREE)** @@ -124,7 +124,7 @@ can manage [the settings](settings.md) for your metrics dashboard. ## Chart Context Menu -You can take action related to a chart's data by clicking the +You can take action related to a chart's data by selecting the **{ellipsis_v}** **More actions** dropdown box above the upper right corner of any chart on a dashboard: diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index a4cdfc5b9a0..95e8bd82475 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Panel types for dashboards (DEPRECATED) **(FREE)** diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md index 45f0e906e9c..3fae4af9cd5 100644 --- a/doc/operations/metrics/dashboards/settings.md +++ b/doc/operations/metrics/dashboards/settings.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dashboard settings (DEPRECATED) **(FREE)** diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index 7d1754f79f5..aac22236dc7 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Templating variables for metrics dashboards (DEPRECATED) **(FREE)** diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index b796cf4cef5..5cd4dcdfa17 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using variables (DEPRECATED) **(FREE)** diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 62389fa01ee..399a8ecb615 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dashboard YAML properties (DEPRECATED) **(FREE)** diff --git a/doc/operations/metrics/dashboards/yaml_number_format.md b/doc/operations/metrics/dashboards/yaml_number_format.md index fd83bff3c08..cd597ea8783 100644 --- a/doc/operations/metrics/dashboards/yaml_number_format.md +++ b/doc/operations/metrics/dashboards/yaml_number_format.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unit formats reference **(FREE)** diff --git a/doc/operations/metrics/embed.md b/doc/operations/metrics/embed.md index 3fd5daba4fb..f622780530a 100644 --- a/doc/operations/metrics/embed.md +++ b/doc/operations/metrics/embed.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Embedding metric charts within GitLab Flavored Markdown **(FREE)** diff --git a/doc/operations/metrics/embed_grafana.md b/doc/operations/metrics/embed_grafana.md index 1a1ac77ce23..b307aa5fa32 100644 --- a/doc/operations/metrics/embed_grafana.md +++ b/doc/operations/metrics/embed_grafana.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Embed Grafana panels in Markdown **(FREE)** diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 82f093cf432..3e5ea688fde 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitor your environment's metrics **(FREE)** @@ -43,7 +43,7 @@ your Prometheus integration depends on where your apps are running: - **For a cluster integrated Prometheus** - GitLab can query [an in-cluster Prometheus](../../user/clusters/integrations.md#prometheus-cluster-integration). You must also complete a code deployment to your cluster for the **Monitor > Metrics** - page to contain data. You can do this using [Auto DevOps](../../topics/autodevops/quick_start_guide.md). + page to contain data. You can do this using [Auto DevOps](../../topics/autodevops/cloud_deployments/auto_devops_with_gke.md).  @@ -147,7 +147,7 @@ suggested if this feature is used. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208976) in GitLab 12.9. -You can edit existing additional custom metrics for your dashboard by clicking the +You can edit existing additional custom metrics for your dashboard by selecting the **{ellipsis_v}** **More actions** dropdown and selecting **Edit metric**.  diff --git a/doc/operations/product_analytics.md b/doc/operations/product_analytics.md index e21770bc579..f9b92f61fd2 100644 --- a/doc/operations/product_analytics.md +++ b/doc/operations/product_analytics.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Analytics -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Product Analytics **(FREE)** diff --git a/doc/operations/tracing.md b/doc/operations/tracing.md index 45f2febd73e..64d8f8a8707 100644 --- a/doc/operations/tracing.md +++ b/doc/operations/tracing.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tracing (DEPRECATED) **(FREE SELF)** diff --git a/doc/policy/alpha-beta-support.md b/doc/policy/alpha-beta-support.md index 6b0bd66041e..8d9b1f270f3 100644 --- a/doc/policy/alpha-beta-support.md +++ b/doc/policy/alpha-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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- <!-- any changes made to this page should be reflected in https://about.gitlab.com/support/statement-of-support/#alpha-beta-features and https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga --> diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 02a1c5a53dc..2bfc7f0243a 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -107,8 +107,7 @@ In some cases, however, we may need to backport *a bug fix* to more than one sta release, depending on the severity of the bug. The decision on whether backporting a change is performed is done at the discretion of the -[current release managers](https://about.gitlab.com/community/release-managers/), similar to what is -described in the [managing bugs](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md#managing-bugs) process, +[current release managers](https://about.gitlab.com/community/release-managers/), based on *all* of the following: 1. Estimated [severity](../development/contributing/issue_workflow.md#severity-labels) of the bug: diff --git a/doc/raketasks/backup_gitlab.md b/doc/raketasks/backup_gitlab.md index 0a38416825a..da004a1b774 100644 --- a/doc/raketasks/backup_gitlab.md +++ b/doc/raketasks/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Back up GitLab @@ -352,8 +352,6 @@ To create an [untarred](#skipping-tar-creation) incremental backup from a tarred sudo gitlab-backup create INCREMENTAL=yes SKIP=tar ``` -You can't create an incremental backup from an [untarred](#skipping-tar-creation) backup. - ### Back up specific repository storages > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86896) in GitLab 15.0. diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 03413aca2af..2ac79a913f3 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Back up and restore GitLab **(FREE SELF)** diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md index 59d8046c8db..2fa6fc2e564 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Clean up **(FREE SELF)** diff --git a/doc/raketasks/generate_sample_prometheus_data.md b/doc/raketasks/generate_sample_prometheus_data.md index cdc95c1f3cc..ec7f54a41c2 100644 --- a/doc/raketasks/generate_sample_prometheus_data.md +++ b/doc/raketasks/generate_sample_prometheus_data.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Generate sample Prometheus data **(FREE SELF)** diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index 5c95fe2eca1..6e7ba45167c 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import bare repositories **(FREE SELF)** @@ -19,7 +19,8 @@ Note that: - Existing projects are skipped. - Projects in hashed storage may be skipped. For more information, see [Importing bare repositories from hashed storage](#importing-bare-repositories-from-hashed-storage). -- The existing Git repositories ware moved from disk (removed from the original path). +- The existing Git repositories are moved from disk (removed from the original path). +- You must manually [push Git LFS objects](#push-git-lfs-objects). To import bare repositories into a GitLab instance: @@ -152,3 +153,12 @@ projects (this may take a while if there are 1000s of projects in a namespace): namespace = Namespace.find_by_full_path('gitlab-org') namespace.send(:write_projects_repository_config) ``` + +## Push Git LFS objects + +The import task doesn't import Git LFS objects. You must manually push the LFS objects to the newly +created GitLab repository using the following command: + +```shell +git lfs push --all +``` diff --git a/doc/raketasks/index.md b/doc/raketasks/index.md index c2580e26ff0..12d2d8b101a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/raketasks/list_repos.md b/doc/raketasks/list_repos.md index 4b971c3608f..57d24a2942d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Listing repository directories **(FREE SELF)** diff --git a/doc/raketasks/migrate_snippets.md b/doc/raketasks/migrate_snippets.md index c36009e69d0..62d2866e499 100644 --- a/doc/raketasks/migrate_snippets.md +++ b/doc/raketasks/migrate_snippets.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migration to versioned snippets **(FREE SELF)** diff --git a/doc/raketasks/restore_gitlab.md b/doc/raketasks/restore_gitlab.md index 7b3a60b436c..61198a3d9ca 100644 --- a/doc/raketasks/restore_gitlab.md +++ b/doc/raketasks/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Restore GitLab @@ -17,7 +17,7 @@ You can restore a backup only to _the exact same version and type (CE/EE)_ of GitLab that you created it on (for example CE 9.1.0). If your backup is a different version than the current installation, you must -[downgrade your GitLab installation](../update/package/downgrade.md) +[downgrade](../update/package/downgrade.md) or [upgrade](../update/package/index.md#upgrade-to-a-specific-version-using-the-official-repositories) your GitLab installation before restoring the backup. ## Restore prerequisites diff --git a/doc/raketasks/spdx.md b/doc/raketasks/spdx.md index 81da52bc327..31f860f45de 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SPDX license list import **(ULTIMATE SELF)** diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md index 02c76af1e69..84d943e2c21 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User management **(FREE SELF)** @@ -87,7 +87,7 @@ block_auto_created_users: false This task disables two-factor authentication (2FA) for all users that have it enabled. This can be useful if the GitLab `config/secrets.yml` file has been lost and users are unable -to log in, for example. +to sign in, for example. To disable two-factor authentication for all users, run: diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index 44ca4a3f47e..b4d01d21dc7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webhooks administration **(FREE SELF)** diff --git a/doc/raketasks/x509_signatures.md b/doc/raketasks/x509_signatures.md index 5090fc285cc..3404f6ae9cf 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # X.509 signatures **(FREE SELF)** diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md index 1ccc9bfd9be..cde377cbb73 100644 --- a/doc/security/asset_proxy.md +++ b/doc/security/asset_proxy.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Proxying assets **(FREE SELF)** @@ -11,7 +11,7 @@ the ability to steal a user's IP address by referencing images in issues and com For example, adding `` to an issue description causes the image to be loaded from the external -server in order to be displayed. However, this also allows the external server +server to be displayed. However, this also allows the external server to log the IP address of the user. One way to mitigate this is by proxying any external images to a server you diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index 5a6578f218b..e2aa4b5d4ab 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/security/index.md b/doc/security/index.md index 9e05621333b..ff0769e0d93 100644 --- a/doc/security/index.md +++ b/doc/security/index.md @@ -1,14 +1,14 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false type: index --- # Security **(FREE)** -- [Password storage](password_storage.md) +- [Passwords and OAuth tokens storage](password_storage.md) - [Password length limits](password_length_limits.md) - [Generated passwords for users created through integrated authentication](passwords_for_integrated_authentication_methods.md) - [Restrict SSH key technologies and minimum length](ssh_keys_restrictions.md) diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 2eeb436316f..37a9fdfdd81 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index 57466d1ed5d..fe51022eea7 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md index d3db8cbe4f6..6b20f8619ae 100644 --- a/doc/security/password_storage.md +++ b/doc/security/password_storage.md @@ -1,11 +1,15 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- -# Password storage **(FREE)** +# Password and OAuth token storage **(FREE)** + +GitLab administrators can configure how passwords and OAuth tokens are stored. + +## Password storage > PBKDF2 and SHA512 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360658) in GitLab 15.2 [with flags](../administration/feature_flags.md) named `pbkdf2_password_encryption` and `pbkdf2_password_encryption_write`. Disabled by default. @@ -17,8 +21,8 @@ library to hash user passwords. Created password hashes have these attributes: - **Hashing**: - **BCrypt**: By default, the [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt) hashing - function is used to generate the hash of the provided password. This is a - strong, industry-standard cryptographic hashing function. + function is used to generate the hash of the provided password. This cryptographic hashing function is + strong and industry-standard. - **PBKDF2 and SHA512**: Starting in GitLab 15.2, PBKDF2 and SHA512 are supported behind the following feature flags (disabled by default): - `pbkdf2_password_encryption` - Enables reading and comparison of PBKDF2 + SHA512 @@ -37,3 +41,13 @@ library to hash user passwords. Created password hashes have these attributes: is added to each password to harden against pre-computed hash and dictionary attacks. To increase security, each salt is randomly generated for each password, with no two passwords sharing a salt. + +## OAuth access token storage + +> - PBKDF2+SHA512 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/364110) in GitLab 15.3 [with flag](../administration/feature_flags.md) named `hash_oauth_tokens`. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98242) in GitLab 15.5. + +Depending on your version of GitLab and configuration, OAuth access tokens are stored in the database in PBKDF2+SHA512 format. For version information, see +the relevant [OAuth provider documentation](../integration/oauth_provider.md#hashed-oauth-tokens). + +As with PBKDF2+SHA512 password storage, access token values are [stretched](https://en.wikipedia.org/wiki/Key_stretching) 20,000 times to harden against brute-force attacks. diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md index d4eb16c07e7..961d147871e 100644 --- a/doc/security/passwords_for_integrated_authentication_methods.md +++ b/doc/security/passwords_for_integrated_authentication_methods.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/security/project_import_decompressed_archive_size_limits.md b/doc/security/project_import_decompressed_archive_size_limits.md index 5082d917748..4358e0a5566 100644 --- a/doc/security/project_import_decompressed_archive_size_limits.md +++ b/doc/security/project_import_decompressed_archive_size_limits.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index e48a9999a06..20a81ed0c30 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index 992a8585a47..248737fc908 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -14,6 +14,8 @@ You can reset user passwords by using a Rake task, a Rails console, or the To reset a user password, you must be an administrator of a self-managed GitLab instance. +The user's new password must meet all [password requirements](../user/profile/user_passwords.md#password-requirements). + ## Use a Rake task > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52347) in GitLab 13.9. @@ -120,6 +122,11 @@ To reset the root password, follow the steps listed previously. ## Troubleshooting +Use the following information to troubleshoot issues when resetting a +user's password. + +### Email confirmation issues + If the new password doesn't work, it might be [an email confirmation issue](../user/upgrade_email_bypass.md). You can attempt to fix this issue in a Rails console. For example, if a new `root` password isn't working: @@ -132,3 +139,9 @@ attempt to fix this issue in a Rails console. For example, if a new `root` passw ``` 1. Attempt to sign in again. + +### Unmet password requirements + +The password might be too short, too weak, or not meet complexity +requirements. Ensure the password you are attempting to set meets all +[password requirements](../user/profile/user_passwords.md#password-requirements). diff --git a/doc/security/responding_to_security_incidents.md b/doc/security/responding_to_security_incidents.md index b3bce785695..fb35c389583 100644 --- a/doc/security/responding_to_security_incidents.md +++ b/doc/security/responding_to_security_incidents.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 138ebb9858a..5a8450bb8e7 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Restrict allowed SSH key technologies and minimum length **(FREE SELF)** diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index e585f2caeca..0c9734cad36 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -129,7 +129,7 @@ This table shows available scopes per token. Scopes can be limited further on to also generally logged by proxies and application servers, which makes those credentials visible to system administrators. Instead, pass API calls an access token using headers like [the `Private-Token` header](../api/index.md#personalprojectgroup-access-tokens). - Tokens can also be stored using a [Git credential storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). -- Tokens should not be committed to your source code. Instead, consider an approach such as [using external secrets in CI](../ci/secrets/index.md). +- Tokens must not be committed to your source code. Instead, consider an approach such as [using external secrets in CI](../ci/secrets/index.md). - When creating a scoped token, consider using the most limited scope possible to reduce the impact of accidentally leaking the token. - When creating a token, consider setting a token that expires when your task is complete. For example, if performing a one-off import, set the token to expire after a few hours or a day. This reduces the impact of a token that is accidentally leaked because it is useless when it expires. diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index c808cf4e321..cc06e824d14 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Enforce two-factor authentication **(FREE)** diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index 041527f18af..4eded22ddaa 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -56,7 +56,7 @@ To unlock a locked user: 1. Exit the console with <kbd>Control</kbd>+<kbd>d</kbd> -The user should now be able to log in. +The user should now be able to sign in. <!-- ## Troubleshooting diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 172e26db618..3f7c66b311b 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User email confirmation at sign-up **(FREE SELF)** diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index ddb8392d2be..63a5e51e3b5 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User file uploads **(FREE)** diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index e1daa705355..49ab4215ea5 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md index 62e045a7593..ec932f2384b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Features available to Starter and Bronze subscribers @@ -82,8 +82,7 @@ the tiers are no longer mentioned in GitLab documentation: - Rake tasks: - [Displaying GitLab license information](../administration/raketasks/maintenance.md#show-gitlab-license-information) - Reference Architecture information: - - [Traffic load balancers](../administration/reference_architectures/index.md#traffic-load-balancer) - - [Zero downtime updates](../administration/reference_architectures/index.md#zero-downtime-updates) + - [Zero downtime upgrades](../administration/reference_architectures/index.md#zero-downtime-upgrades) - Repositories: - [Repository size limit](../user/admin_area/settings/account_and_limit_settings.md#repository-size-limit) - Repository mirroring: diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index aed8bafb780..c9b066144f3 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -259,12 +259,12 @@ generated for the renewal and available for viewing or download on the #### Enable or disable automatic subscription renewal To view or change automatic subscription renewal (at the same tier as the -previous period), log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in), and: +previous period), sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in), and: - If a **Resume subscription** button is displayed, your subscription was canceled - previously. Click it to resume automatic renewal. + 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. Click it to cancel automatic renewal. + renew at the end of the subscription period. Select it to cancel automatic renewal. 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. diff --git a/doc/subscriptions/gitlab_dedicated/index.md b/doc/subscriptions/gitlab_dedicated/index.md index e5f75fd5a7a..441a4d2aa30 100644 --- a/doc/subscriptions/gitlab_dedicated/index.md +++ b/doc/subscriptions/gitlab_dedicated/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Dedicated @@ -18,7 +18,8 @@ GitLab Dedicated enables you to offload the operational overhead of managing the ## Available features -- Authentication: Support for instance-level [SAML OmniAuth](../../integration/saml.md) functionality. GitLab Dedicated acts as the service provider, and you must provide the necessary [configuration](../../integration/saml.md#general-setup) in order for GitLab to communicate with your IdP. This is provided during onboarding. SAML [request signing](../../integration/saml.md#request-signing-optional) is supported. +- Authentication: Support for instance-level [SAML OmniAuth](../../integration/saml.md) functionality. GitLab Dedicated acts as the service provider, and you must provide the necessary [configuration](../../integration/saml.md#general-setup) in order for GitLab to communicate with your IdP. This is provided during onboarding. + - SAML [request signing](../../integration/saml.md#request-signing-optional), [group sync](../../user/group/saml_sso/group_sync.md#configure-saml-group-sync), and [SAML groups](../../integration/saml.md#saml-groups) are supported. - Networking: - Public connectivity with support for IP Allowlists. During onboarding, you can optionally specify a list of IP addresses that can access your Dedicated instance. Subsequently, when an IP not on the allowlist tries to access your instance the connection will be refused. - Optional. Private connectivity via [AWS PrivateLink](https://aws.amazon.com/privatelink/). @@ -26,41 +27,59 @@ GitLab Dedicated enables you to offload the operational overhead of managing the - Upgrades: - Monthly upgrades tracking one release behind the latest (n-1), with the latest security release. - Out of band security patches provided for high severity releases. -- Backups: regular backups taken and tested. -- Choice of cloud region: upon onboarding, choose the cloud region where you want to deploy your instance. Some AWS regions have limited features and as a result, we are not able to deploy production instances to those regions. See below for the [full list of regions](#aws-regions-not-supported) not currently supported. +- Backups: Regular backups taken and tested. +- Choice of cloud region: Upon onboarding, choose the cloud region where you want to deploy your instance. Some AWS regions have limited features and as a result, we are not able to deploy production instances to those regions. See below for the [full list of regions](#aws-regions-not-supported) not currently supported. - Security: Data encrypted at rest and in transit using latest encryption standards. -- Application: Self-managed [Ultimate feature set](https://about.gitlab.com/pricing/self-managed/feature-comparison/) with the exception of the unsupported features [listed below](#features-not-available-at-launch). +- Application: Self-managed [Ultimate feature set](https://about.gitlab.com/pricing/self-managed/feature-comparison/) with the exception of the unsupported features [listed below](#features-that-are-not-available). -## Features not available at launch +## Features that are not available -Features that are not available but we plan to support in the future: +### GitLab application features -- LDAP, Smartcard, Kerberos authentication -- Custom domain +The following GitLab application features are not available: + +- LDAP, Smartcard, or Kerberos authentication +- Multiple login providers - Advanced Search -- Pages -- GitLab-managed runners -- FortiAuthenticator/FortiToken 2FA +- GitLab Pages +- FortiAuthenticator, or FortiToken 2FA - Reply-by email - Service Desk +- GitLab-managed runners +- Any feature [not listed above](#available-features) which must be configured outside of the GitLab user interface. -Features that we do not plan to offer at all: +The following features will not be supported: - Mattermost -- Server-side Git Hooks +- Server-side Git hooks + +### Dedicated service features + +The following operational features are not available: + +- Custom domains +- Bring Your Own Key (BYOK) encryption +- Multiple Geo secondaries (Geo replicas) beyond the secondary site included by default +- Self-serve purchasing and configuration +- Multiple login providers +- Non-AWS cloud providers, such as GCP or Azure ### AWS regions not supported -The following AWS regions are not available at launch: +The following AWS regions are not available: -- Jakarta (ap-southeast-3) -- Bahrain (me-south-1) -- Hong Kong (ap-east-1) -- Cape Town (af-south-1) -- Milan (eu-south-1) -- Paris (eu-west-3) +- Jakarta (`ap-southeast-3`) +- Bahrain (`me-south-1`) +- Hong Kong (`ap-east-1`) +- Cape Town (`af-south-1`) +- Milan (`eu-south-1`) +- Paris (`eu-west-3`) - GovCloud +## Planned features + +Learn more about the planned improvements to Dedicated on the public [direction page](https://about.gitlab.com/direction/saas-platforms/dedicated/). + ## Contact us Fill in the following form to contact us and learn more about this offering. diff --git a/doc/subscriptions/img/support_diagram_c.png b/doc/subscriptions/img/support_diagram_c.png Binary files differdeleted file mode 100644 index e98baed8605..00000000000 --- a/doc/subscriptions/img/support_diagram_c.png +++ /dev/null diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index e71954f1968..1df222ac349 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -46,10 +46,7 @@ A new subscription must be purchased and applied as needed. Pricing is [tier-based](https://about.gitlab.com/pricing/), allowing you to choose the features which fit your budget. For information on what features are available -at each tier for each product, see: - -- [GitLab SaaS feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/) -- [GitLab self-managed feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/) +at each tier for each product, see: [GitLab self-managed feature comparison](https://about.gitlab.com/pricing/feature-comparison/) ## Find your subscription @@ -73,26 +70,30 @@ click E "./self_managed/index.html#view-your-subscription" With the [Customers Portal](https://customers.gitlab.com/) you can: -- [Change your personal details](#change-your-personal-details) +- [Change account owner information](#change-account-owner-information) - [Change your company details](#change-your-company-details) - [Change your payment method](#change-your-payment-method) - [Change the linked account](#change-the-linked-account) - [Change the namespace the subscription is linked to](#change-the-linked-namespace) - [Change customers portal account password](#change-customers-portal-account-password) -### Change your personal details +### Change account owner information -Your personal details are used on invoices. Your email address is used for the Customers Portal -login and license-related email. +Account owner personal details are used on invoices. The account owner email +address is used for the Customers Portal login and license-related email. -To change your personal details, including name, billing address, and email address: +To change account owner information, including name, billing address, and email address: 1. Log 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 your personal details. +1. Edit the personal details. 1. Select **Save changes**. +If you want to transfer ownership of the Customers Portal account +to another person, after you enter that person's personal details, you must also +[change the Customers Portal account password](#change-customers-portal-account-password). + ### Change your company details To change your company details, including company name and VAT number: @@ -138,7 +139,7 @@ To change the GitLab.com account linked to your Customers Portal account: 1. In a separate browser tab, go to [GitLab SaaS](https://gitlab.com) and ensure you are not logged in. 1. On the Customers Portal page, select **My account > Account details**. -1. Under **Your GitLab.com account**, select **Change linked account**. +1. Under **Your GitLab.com account**, select **Change linked account**. If the account is not yet linked, select **Link my GitLab.com account**. 1. Log in to the [GitLab SaaS](https://gitlab.com) account you want to link to the Customers Portal account. @@ -164,7 +165,7 @@ Only one namespace can be linked to a subscription. To change the password for this customers portal account: 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in). -1. Select the **My account** drop-down and select **Account details**. +1. Select the **My account** dropdown list and select **Account details**. 1. Make the required changes to the **Your password** section. 1. Select **Save changes**. @@ -172,42 +173,36 @@ To change the password for this customers portal account: ### GitLab for Education -For qualifying non-profit educational institutions, the [GitLab for Education](https://about.gitlab.com/solutions/education/) program provides -the top GitLab tier, plus 50,000 CI/CD minutes per month. - -The GitLab for Education license can only be used for instructional-use or -non-commercial academic research. - -Find more information on how to apply and renew at -[GitLab for Education](https://about.gitlab.com/solutions/education/). +For qualifying non-profit educational institutions, the [GitLab for Education Program](https://about.gitlab.com/solutions/education/) provides GitLab Ultimate, plus 50,000 CI/CD minutes per month. The subscription granted under GitLab for Education can only be used for instructional use or non-commercial academic research. For more information—including instructions for applying to the program and renewing program membership—see the [GitLab for Education Program page](https://about.gitlab.com/solutions/education/) and the [GitLab handbook](https://about.gitlab.com/handbook/marketing/community-relations/community-programs/education-program/). ### GitLab for Open Source -For qualifying open source projects, the [GitLab for Open Source Program](https://about.gitlab.com/solutions/open-source/) provides -GitLab Ultimate, plus 50,000 CI/CD minutes per month. For more information, see [program requirements](https://about.gitlab.com/solutions/open-source/join/#requirements), [renewals](https://about.gitlab.com/solutions/open-source/join/#renewals), and [program benefits](https://about.gitlab.com/solutions/open-source/join/). +For qualifying open source projects, the [GitLab for Open Source Program](https://about.gitlab.com/solutions/open-source/) provides GitLab Ultimate, plus 50,000 CI/CD minutes per month. For more information—including instructions for applying to the program and renewing program membership—see the [GitLab for Open Source Program page](https://about.gitlab.com/solutions/open-source/) and the [GitLab handbook](https://about.gitlab.com/handbook/marketing/community-relations/opensource-program/). -If you have any questions, send an email to `opensource@gitlab.com` for assistance. +#### Meeting GitLab for Open Source Program requirements -#### License requirements for GitLab for Open Source Program members +NOTE: +GitLab for Open Source Program benefits apply to an entire GitLab namespace. To qualify for the GitLab for Open Source Program, all projects in an applicant's namespace must meet program requirements. Applicants submit materials related to one project in the applying namespace, and the open source program team uses that project to verify eligibility of the entire namespace. -GitLab for Open Source Program benefits apply to an entire GitLab namespace. To qualify for the GitLab for Open Source Program, **all projects in an applicant's namespace** must carry an [OSI-approved license](https://opensource.org/licenses/). +To meet GitLab for Open Source Program requirements, first add an OSI-approved open source license to all projects in your namespace. -To add a license: +To add a license to a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the overview page, select **Add LICENSE**. If the license you want is not available as a license template, manually copy the entire, unaltered [text of your chosen license](https://opensource.org/licenses/alphabetical) into the `LICENSE` file. Note that GitLab defaults to **All rights reserved** if users do not perform this action. -Applicants must add the correct license to each project in their respective groups or namespaces When you're sure you're using OSI-approved licenses for your projects, you can take your screenshots. +Applicants must add the correct license to each project in their respective groups or namespaces. When you're sure you're using OSI-approved licenses for your projects, you can take your screenshots. #### Verification for Open Source Program -As part of the [application verification process](https://about.gitlab.com/solutions/open-source/join/), you must upload **three screenshots**: +Next, take screenshots of your project to confirm that project's eligibility. You must upload three screenshots: - [OSI-approved license overview](#screenshot-1-license-overview) - [OSI-approved license contents](#screenshot-2-license-contents) - [Publicly visible settings](#screenshot-3-publicly-visible-settings) -Benefits of the GitLab Open Source Program apply to all projects in a GitLab namespace. All projects in an eligible namespace must meet program requirements. However, if you submit materials for **one project** in your namespace, the open source program team uses that project to verify the contents of the entire namespace you use when applying to the program. +NOTE: +Benefits of the GitLab Open Source Program apply to all projects in a GitLab namespace. All projects in an eligible namespace must meet program requirements. ##### Screenshot 1: License overview @@ -239,24 +234,11 @@ To be eligible for the GitLab Open Source Program, projects must be publicly vis  NOTE: -Exceptions to this public visibility requirement apply in select circumstances (for example, in cases where a project may hold sensitive data). Email `opensource@gitlab.com` with details of your use case to request written permission for exceptions. +Exceptions to this public visibility requirement apply in select circumstances (for example, in cases where a project in an applicant's namespace may hold sensitive data). Email `opensource@gitlab.com` with details of your use case to request written permission for exceptions. ### GitLab for Startups -For qualifying startups, the [GitLab for Startups](https://about.gitlab.com/solutions/startups/) program provides -the top GitLab tier, plus 50,000 CI/CD minutes per month for 12 months. - -For more information, including program requirements, see the [Startup program's landing page](https://about.gitlab.com/solutions/startups/). - -Send all questions and requests related to the GitLab for Startups program to `startups@gitlab.com`. - -### Support for Community Programs - -Because these Community Programs are free of cost, regular Priority Support is not included. - -As a community member, you can follow this diagram to find support: - - +For qualifying startups, the [GitLab for Startups](https://about.gitlab.com/solutions/startups/) program provides GitLab Ultimate, plus 50,000 CI/CD minutes per month for 12 months. For more information—including instructions for applying to the program and renewing program membership—see the [GitLab for Startups Program page](https://about.gitlab.com/solutions/startups/) and the [GitLab handbook](https://about.gitlab.com/handbook/marketing/community-relations/startups-program/). ## Contact Support @@ -265,12 +247,9 @@ Learn more about: - The tiers of [GitLab Support](https://about.gitlab.com/support/). - [Submit a request via the Support Portal](https://support.gitlab.com/hc/en-us/requests/new). -We also encourage all users to search our project trackers for known issues and -existing feature requests in the -[GitLab project](https://gitlab.com/gitlab-org/gitlab/-/issues/). +We also encourage all users to search our project trackers for known issues and existing feature requests in the [GitLab project](https://gitlab.com/gitlab-org/gitlab/-/issues/). -These issues are the best avenue for getting updates on specific product plans -and for communicating directly with the relevant GitLab team members. +These issues are the best avenue for getting updates on specific product plans and for communicating directly with the relevant GitLab team members. <!-- ## Troubleshooting diff --git a/doc/subscriptions/quarterly_reconciliation.md b/doc/subscriptions/quarterly_reconciliation.md index 78c844b897c..508dd2924e3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Quarterly reconciliation and annual true-ups **(PREMIUM)** diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index 4ae38de54bc..4538e8587c9 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -261,7 +261,7 @@ It also displays the following information: ## Export your license usage -> Introduced in GitLab 14.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66826) in GitLab 14.2. If you are an administrator, you can export your license usage into a CSV: @@ -300,7 +300,7 @@ then [renew your GitLab self-managed subscription](#renew-a-subscription). The [Customers Portal](https://customers.gitlab.com/customers/sign_in) is your tool for renewing and modifying your subscription. Before going ahead with renewal, -log in and verify or update: +sign in and verify or update: - The invoice contact details on the **Account details** page. - The credit card on file on the **Payment Methods** page. diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index ef7598248fe..12ff5cb50b8 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Authentication **(FREE)** 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 653fe11c59d..6bebe9eb9e3 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 4c084f405cd..76fd6ad82d8 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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_gke.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md index 5f37ca30604..56f3de528b8 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE)** diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 4d97f012a92..0d4afc3c464 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customizing Auto DevOps **(FREE)** @@ -190,7 +190,7 @@ You can override the default values in the `values.yaml` file in the `HELM_UPGRADE_VALUES_FILE` [CI/CD variable](#cicd-variables) with the path and name. -Some values can not be overridden with the options above. Settings like `replicaCount` should instead be overridden with the `REPLICAS` +Some values cannot be overridden with the options above. Settings like `replicaCount` should instead be overridden with the `REPLICAS` [build and deployment](#build-and-deployment) CI/CD variable. Follow [this issue](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/issues/31) for more information. NOTE: diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index c21ed5ed444..73e87aa190f 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Auto DevOps **(FREE)** @@ -26,36 +26,24 @@ For an introduction to Auto DevOps, watch [Auto DevOps in GitLab 11.0](https://y ## Auto DevOps features -Based on the DevOps [stages](stages.md), use Auto DevOps to: - -**Build your app:** - -- [Auto Build](stages.md#auto-build) -- [Auto Dependency Scanning](stages.md#auto-dependency-scanning) - -**Test your app:** - -- [Auto Test](stages.md#auto-test) -- [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing) -- [Auto Code Intelligence](stages.md#auto-code-intelligence) -- [Auto Code Quality](stages.md#auto-code-quality) -- [Auto Container Scanning](stages.md#auto-container-scanning) -- [Auto License Compliance](stages.md#auto-license-compliance) - -**Deploy your app:** - -- [Auto Review Apps](stages.md#auto-review-apps) -- [Auto Deploy](stages.md#auto-deploy) - -**Monitor your app:** - -- [Auto Monitoring](stages.md#auto-monitoring) - -**Secure your app:** - -- [Auto Dynamic Application Security Testing (DAST)](stages.md#auto-dast) -- [Auto Static Application Security Testing (SAST)](stages.md#auto-sast) -- [Auto Secret Detection](stages.md#auto-secret-detection) +Auto DevOps supports development during each of the [DevOps stages](stages.md). + +| Stage | Auto DevOps feature | +|---------|-------------| +| Build | [Auto Build](stages.md#auto-build) | +| Build | [Auto Dependency Scanning](stages.md#auto-dependency-scanning) | +| Test | [Auto Test](stages.md#auto-test) | +| Test | [Auto Browser Performance Testing](stages.md#auto-browser-performance-testing) | +| 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) | +| Deploy | [Auto Review Apps](stages.md#auto-review-apps) | +| Deploy | [Auto Deploy](stages.md#auto-deploy) | +| Monitor | [Auto Monitoring](stages.md#auto-monitoring) | +| Secure | [Auto Dynamic Application Security Testing (DAST)](stages.md#auto-dast) | +| Secure | [Auto Static Application Security Testing (SAST)](stages.md#auto-sast) | +| Secure | [Auto Secret Detection](stages.md#auto-secret-detection) | ### Comparison to application platforms and PaaS @@ -80,24 +68,12 @@ If you want to build, test, and deploy your app: 1. View the [requirements for deployment](requirements.md). 1. [Enable Auto DevOps](#enable-or-disable-auto-devops). -1. Follow the [quick start guide](#quick-start). - -As Auto DevOps relies on many components, be familiar with: - -- [Continuous methodologies](../../ci/introduction/index.md) -- [Docker](https://docs.docker.com) -- [GitLab Runner](https://docs.gitlab.com/runner/) - -When deploying to a Kubernetes cluster make sure you're also familiar with: - -- [Kubernetes](https://kubernetes.io/docs/home/) -- [Helm](https://helm.sh/docs/) -- [Prometheus](https://prometheus.io/docs/introduction/overview/) +1. [Deploy your app to a cloud provider](#deploy-your-app-to-a-cloud-provider). ### Enable or disable Auto DevOps > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729) in GitLab 11.3, Auto DevOps is enabled by default. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26655) GitLab 12.7, Auto DevOps runs pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build) exists. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26655) in GitLab 12.7, Auto DevOps runs pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build) exists. Depending on your instance type, you can enable or disable Auto DevOps at the following levels: @@ -116,7 +92,7 @@ To use Auto DevOps for individual projects, you can enable it in a project-by-project basis. If you intend to use it for more projects, you can enable it for a [group](#at-the-group-level) or an [instance](#at-the-instance-level). This can save you the time of -enabling it one by one. +enabling it in each project. Prerequisites: @@ -143,9 +119,10 @@ To disable it, follow the same process and clear the > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52447) in GitLab 11.10. -When you enable Auto DevOps at group level, the subgroups and projects in that -group inherit the configuration. This saves you some time by batch-enabling it -rather than enabling individually for each subgroup or project. +When you enable Auto DevOps at the group level, the subgroups and +projects in that group inherit the configuration. You can save time by +enabling Auto DevOps for a group instead of enabling it for each +subgroup or project. When enabled for a group, you can still disable Auto DevOps for the subgroups and projects where you don't want to use it. @@ -162,7 +139,7 @@ To enable Auto DevOps for a group: 1. Select the **Default to Auto DevOps pipeline** checkbox. 1. Select **Save changes**. -To disable Auto DevOps on the group level, follow the same process and +To disable Auto DevOps at the group level, follow the same process and clear the **Default to Auto DevOps pipeline** checkbox. After enabling Auto DevOps at the group level, you can trigger the @@ -175,10 +152,9 @@ Auto DevOps pipeline for any project that belongs to that group: #### At the instance level **(FREE SELF)** -By enabling Auto DevOps in the instance level, all projects created in that -instance become enabled. This is convenient when you want to run Auto DevOps by -default for all projects. You can still disable Auto DevOps individually for -the groups and projects where you don't want to run it. +To enable Auto DevOps by default for all projects, you can enable it at the instance level. +You can still disable Auto DevOps for each group and project +where you don't want to run it. Even when disabled for an instance, group Owners and project Maintainers can still enable Auto DevOps at the group and project levels. @@ -196,24 +172,17 @@ To enable Auto DevOps for your instance: 1. Optional. Add the Auto DevOps [base domain](requirements.md#auto-devops-base-domain). 1. Select **Save changes**. -When enabled, it attempts to run Auto DevOps pipelines in every project. If the +When enabled, Auto DevOps attempts to run pipelines in every project. If the pipeline fails in a particular project, it disables itself. GitLab administrators can change this in the [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops). If a [CI/CD configuration file](../../ci/yaml/index.md) is present, -it remains unchanged and Auto DevOps doesn't affect it. +it remains unchanged and Auto DevOps does not affect it. To disable Auto DevOps in the instance level, follow the same process and clear the **Default to Auto DevOps pipeline** checkbox. -### Private registry support - -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 -simplify configuration and prevent any unforeseen issues. - -### Quick start +### Deploy your app to a cloud provider - [Use Auto DevOps to deploy to a Kubernetes cluster on Google Kubernetes Engine (GKE)](cloud_deployments/auto_devops_with_gke.md) - [Use Auto DevOps to deploy to EC2](cloud_deployments/auto_devops_with_ec2.md) @@ -221,7 +190,7 @@ simplify configuration and prevent any unforeseen issues. ## Upgrade Auto DevOps dependencies when updating GitLab -When updating GitLab, you may need to upgrade Auto DevOps dependencies to +When updating GitLab, you might need to upgrade Auto DevOps dependencies to match your new GitLab version: - [Upgrading Auto DevOps resources](upgrading_auto_deploy_dependencies.md): @@ -233,30 +202,29 @@ match your new GitLab version: - Environment variables. - [Upgrading PostgreSQL](upgrading_postgresql.md). +## Private registry support + +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 +simplify configuration and prevent any unforeseen issues. + ## Install applications behind a proxy The GitLab integration with Helm does not support installing applications when behind a proxy. -To do so, inject proxy settings into the installation pods at runtime. -For example, you can use a `PodPreset`: - -NOTE: -[PodPreset was removed in Kubernetes v1.20](https://github.com/kubernetes/kubernetes/pull/94090). - -```yaml -apiVersion: settings.k8s.io/v1alpha1 -kind: PodPreset -metadata: - name: gitlab-managed-apps-default-proxy - namespace: gitlab-managed-apps -spec: - env: - - name: http_proxy - value: "PUT_YOUR_HTTP_PROXY_HERE" - - name: https_proxy - value: "PUT_YOUR_HTTPS_PROXY_HERE" -``` +If you want to do so, you must inject proxy settings into the +installation pods at runtime. + +## Related topics + +- [Continuous methodologies](../../ci/introduction/index.md) +- [Docker](https://docs.docker.com) +- [GitLab Runner](https://docs.gitlab.com/runner/) +- [Helm](https://helm.sh/docs/) +- [Kubernetes](https://kubernetes.io/docs/home/) +- [Prometheus](https://prometheus.io/docs/introduction/overview/) ## Troubleshooting diff --git a/doc/topics/autodevops/multiple_clusters_auto_devops.md b/doc/topics/autodevops/multiple_clusters_auto_devops.md index 9c766385e66..49ded4bfb9a 100644 --- a/doc/topics/autodevops/multiple_clusters_auto_devops.md +++ b/doc/topics/autodevops/multiple_clusters_auto_devops.md @@ -1,54 +1,55 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple Kubernetes clusters for Auto DevOps **(FREE)** -When using Auto DevOps, you can deploy different environments to -different Kubernetes clusters, due to the 1:1 connection -[existing between them](../../user/project/clusters/multiple_kubernetes_clusters.md). +When using Auto DevOps, you can deploy different environments to different Kubernetes clusters. -The [Deploy Job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) -used by Auto DevOps defines 3 environment names: +The [Deploy Job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) used by Auto DevOps defines three environment names: - `review/` (every environment starting with `review/`) - `staging` - `production` -Those environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so -except for the environment scope, they must have a different deployment domain. -You must define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for each of the above -[based on the environment](../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable). +These environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so they must have different deployment domains. You must define separate [`KUBE_CONTEXT`](../../user/clusters/agent/ci_cd_workflow.md#using-the-agent-with-auto-devops) and [`KUBE_INGRESS_BASE_DOMAIN`](requirements.md#auto-devops-base-domain) variables for each of the three environments. -The following table is an example of how to configure the three different clusters: +## Deploy to different clusters -| Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` variable value | Variable environment scope | Notes | -|--------------|---------------------------|-------------------------------------------|----------------------------|---| -| review | `review/*` | `review.example.com` | `review/*` | The review cluster which runs all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, used by every environment name starting with `review/`. | -| staging | `staging` | `staging.example.com` | `staging` | Optional. The staging cluster that runs the deployments of the staging environments. You must [enable it first](customize.md#deploy-policy-for-staging-and-production-environments). | -| production | `production` | `example.com` | `production` | The production cluster which runs the production environment deployments. You can use [incremental rollouts](customize.md#incremental-rollout-to-production). | +To deploy your environments to different Kubernetes clusters: -To add a different cluster for each environment: +1. [Create Kubernetes clusters](../../user/infrastructure/clusters/connect/new_gke_cluster.md). +1. Associate the clusters to your project: + 1. [Install a GitLab Agent on each cluster](../../user/clusters/agent/index.md). + 1. [Configure each agent to access your project](../../user/clusters/agent/install/index.md#configure-your-agent). +1. [Install NGINX Ingress Controller](cloud_deployments/auto_devops_with_gke.md#install-ingress) in each cluster. Save the IP address and Kubernetes namespace for the next step. +1. [Configure the Auto DevOps CI/CD Pipeline variables](customize.md#build-and-deployment) + - Set up a `KUBE_CONTEXT` variable [for each environment](../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable). The value must point to the agent of the relevant cluster. + - Set up a `KUBE_INGRESS_BASE_DOMAIN`. You must [configure the base domain](requirements.md#auto-devops-base-domain) for each environment to point to the Ingress of the relevant cluster. + - Add a `KUBE_NAMESPACE` variable with a value of the Kubernetes namespace you want your deployments to target. You can scope the variable to multiple environments. -1. Navigate to your project's **Infrastructure > Kubernetes clusters**. -1. Create the Kubernetes clusters with their respective environment scope, as - described from the table above. -1. After creating the clusters, navigate to each cluster and - [install Ingress](cloud_deployments/auto_devops_with_gke.md#install-ingress). - Wait for the Ingress IP address to be assigned. -1. Make sure you've [configured your DNS](requirements.md#auto-devops-base-domain) with the - specified Auto DevOps domains. -1. Navigate to each cluster's page, through **Infrastructure > Kubernetes clusters**, - and add the domain based on its Ingress IP address. +For deprecated, [certificate-based clusters](../../user/infrastructure/clusters/index.md#certificate-based-kubernetes-integration-deprecated): + +1. Go to the project and select **Infrastructure > Kubernetes clusters** from the left sidebar. +1. [Set the environment scope of each cluster](../../user/project/clusters/multiple_kubernetes_clusters.md#setting-the-environment-scope). +1. For each cluster, [add a domain based on its Ingress IP address](../../user/project/clusters/gitlab_managed_clusters.md#base-domain). + +NOTE: +[Cluster environment scope is not respected when checking for active Kubernetes clusters](https://gitlab.com/gitlab-org/gitlab/-/issues/20351). For a multi-cluster setup to work with Auto DevOps, you must create a fallback cluster with **Cluster environment scope** set to `*`. You can set any of the clusters you've already added as a fallback cluster. + +### Example configurations + +| Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` value | `KUBE CONTEXT` value | Variable environment scope | Notes | +| :------------| :-------------------------| :------------------------------- | :--------------------------------- | :--------------------------|:--| +| review | `review/*` | `review.example.com` | `path/to/project:review-agent` | `review/*` | A review cluster that runs all [Review Apps](../../ci/review_apps/index.md).| +| staging | `staging` | `staging.example.com` | `path/to/project:staging-agent` | `staging` | Optional. A staging cluster that runs the deployments of the staging environments. You must [enable it first](customize.md#deploy-policy-for-staging-and-production-environments). | +| production | `production` | `example.com` | `path/to/project:production-agent` | `production` | A production cluster that runs the production environment deployments. You can use [incremental rollouts](customize.md#incremental-rollout-to-production). | + +## Test your configuration After completing configuration, test your setup by creating a merge request. Verify whether your application deployed as a Review App in the Kubernetes cluster with the `review/*` environment scope. Similarly, check the other environments. - -[Cluster environment scope isn't respected](https://gitlab.com/gitlab-org/gitlab/-/issues/20351) -when checking for active Kubernetes clusters. For multi-cluster setup to work with Auto DevOps, -create a fallback cluster with **Cluster environment scope** set to `*`. A new cluster isn't -required. You can use any of the clusters already added. diff --git a/doc/topics/autodevops/prepare_deployment.md b/doc/topics/autodevops/prepare_deployment.md index c16a6c837cd..7805f9cd9c6 100644 --- a/doc/topics/autodevops/prepare_deployment.md +++ b/doc/topics/autodevops/prepare_deployment.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Prepare Auto DevOps for deployment **(FREE)** diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md deleted file mode 100644 index a524b6e6451..00000000000 --- a/doc/topics/autodevops/quick_start_guide.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../autodevops/cloud_deployments/auto_devops_with_gke.md' -remove_date: '2022-09-18' ---- - -This document was moved to [another location](../autodevops/cloud_deployments/auto_devops_with_gke.md). - -<!-- This redirect file can be deleted after <2022-09-18>. --> -<!-- 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/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 9dffb490807..7c69e0327c8 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Requirements for Auto DevOps **(FREE)** diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 62356807854..9458d1cc6f9 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Stages of Auto DevOps **(FREE)** diff --git a/doc/topics/autodevops/troubleshooting.md b/doc/topics/autodevops/troubleshooting.md index bf3dc27c0e8..ae3cc42223f 100644 --- a/doc/topics/autodevops/troubleshooting.md +++ b/doc/topics/autodevops/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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 Auto DevOps **(FREE)** diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 5772a891b41..602bdec6140 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index 0d8d8cd6579..d43b1cae9e9 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading PostgreSQL for Auto DevOps **(FREE)** diff --git a/doc/topics/awesome_co.md b/doc/topics/awesome_co.md new file mode 100644 index 00000000000..0d725f64f3a --- /dev/null +++ b/doc/topics/awesome_co.md @@ -0,0 +1,143 @@ +--- +stage: Ecosystem +group: Foundations +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 +description: AwesomeCo test data harness created by the Test Data Working Group https://about.gitlab.com/company/team/structure/working-groups/demo-test-data/ +comments: false +--- + +# AwesomeCo + +AwesomeCo is a test data seeding harness, that can seed test data into a user or group namespace. + +AwesomeCo uses FactoryBot in the backend which makes maintenance extremely easy. When a Model is changed, +FactoryBot will already be reflected to account for the change. + +## Docker Setup + +See [AwesomeCo Docker Demo](https://gitlab.com/-/snippets/2390362) + +## GDK Setup + +```shell +$ gdk start db +ok: run: services/postgresql: (pid n) 0s, normally down +ok: run: services/redis: (pid n) 74s, normally down +$ bundle install +Bundle complete! +$ bundle exec rake db:migrate +main: migrated +ci: migrated +``` + +### Run + +The `gitlab:seed:awesome_co` Rake task takes two arguments. `:name` and `:namespace_id`. + +```shell +$ bundle exec rake "gitlab:seed:awesome_co[awesome_co,1]" +Seeding AwesomeCo for Administrator +``` + +#### `:name` + +Where `:name` is the name of the AwesomeCo. (This will reflect .rb files located in db/seeds/awesome_co/*.rb) + +#### `:namespace_id` + +Where `:namespace_id` is the ID of the User or Group Namespace + +## List of Awesome Companies + +Each company (i.e. test data template) is represented as a Ruby file (.rb) in `db/seeds/awesome_co`. + +### AwesomeCo (db/seeds/awesome_co/awesome_co.rb) + +```shell +$ bundle exec rake "gitlab:seed:awesome_co[awesome_co,:namespace_id]" +Seeding AwesomeCo for :namespace_id +``` + +AwesomeCo is an automated seeding of [this demo repository](https://gitlab.com/tech-marketing/demos/gitlab-agile-demo/awesome-co). + +## Develop + +AwesomeCo seeding uses FactoryBot definitions from `spec/factories` which ... + +1. Saves time on development +1. Are easy-to-read +1. Are easy to maintain +1. Do not rely on an API that may change in the future +1. Are always up-to-date +1. Execute on the lowest-level (`ActiveRecord`) possible to create data as quickly as possible + +> _from the [FactoryBot README](https://github.com/thoughtbot/factory_bot#readme_) : factory_bot is a fixtures replacement with a straightforward definition syntax, support for multiple build +> strategies (saved instances, unsaved instances, attribute hashes, and stubbed objects), and support for multiple factories for the same class, including factory +> inheritance + +Factories reside in `spec/factories/*` and are fixtures for Rails models found in `app/models/*`. For example, For a model named `app/models/issue.rb`, the factory will +be named `spec/factories/issues.rb`. For a model named `app/models/project.rb`, the factory will be named `app/models/projects.rb`. + +### Taxonomy of a Factory + +Factories consist of three main parts - the **Name** of the factory, the **Traits** and the **Attributes**. + +Given: `create(:iteration, :with_title, :current, title: 'My Iteration')` + +||| +|:-|:-| +| **:iteration** | This is the **Name** of the factory. The file name will be the plural form of this **Name** and reside under either `spec/factories/iterations.rb` or `ee/spec/factories/iterations.rb`. | +| **:with_title** | This is a **Trait** of the factory. [See how it's defined](https://gitlab.com/gitlab-org/gitlab/-/blob/9c2a1f98483921dd006d70fdaed316e21fc5652f/ee/spec/factories/iterations.rb#L21-23). | +| **:current** | This is a **Trait** of the factory. [See how it's defined](https://gitlab.com/gitlab-org/gitlab/-/blob/9c2a1f98483921dd006d70fdaed316e21fc5652f/ee/spec/factories/iterations.rb#L29-31). | +| **title: 'My Iteration'** | This is an **Attribute** of the factory that will be passed to the Model for creation. | + +### Examples + +In these examples, you will see an instance variable `@owner`. This is the `root` user (`User.first`). + +#### Create a Group + +```ruby +my_group = create(:group, name: 'My Group', path: 'my-group-path') +``` + +#### Create a Project + +```ruby +# create a Project belonging to a Group +my_project = create(:project, :public, name: 'My Project', namespace: my_group, creator: @owner) +``` + +#### Create an Issue + +```ruby +# create an Issue belonging to a Project +my_issue = create(:issue, title: 'My Issue', project: my_project, weight: 2) +``` + +#### Create an Iteration + +```ruby +# create an Iteration under a Group +my_iteration = create(:iteration, :with_title, :current, title: 'My Iteration', group: my_group) +``` + +### Frequently encountered issues + +#### ActiveRecord::RecordInvalid: Validation failed: Email has already been taken, Username has already been taken + +This is because, by default, our factories are written to backfill any data that is missing. For instance, when a project +is created, the project must have somebody that created it. If the owner is not specified, the factory attempts to create it. + +**How to fix** + +Check the respective Factory to find out what key is required. Usually `:author` or `:owner`. + +```ruby +# This throws ActiveRecord::RecordInvalid +create(:project, name: 'Throws Error', namespace: create(:group, name: 'Some Group')) + +# Specify the user where @owner is a [User] record +create(:project, name: 'No longer throws error', owner: @owner, namespace: create(:group, name: 'Some Group')) +create(:epic, group: create(:group), author: @owner) +``` diff --git a/doc/topics/build_your_application.md b/doc/topics/build_your_application.md index d48b8383271..35f9db4d087 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Build your application **(FREE)** diff --git a/doc/topics/cron/index.md b/doc/topics/cron/index.md index 34a51d3d535..b437541e0ea 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cron diff --git a/doc/topics/git/bisect.md b/doc/topics/git/bisect.md index e587a51ba17..a7f8b2a846c 100644 --- a/doc/topics/git/bisect.md +++ b/doc/topics/git/bisect.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/cherry_picking.md b/doc/topics/git/cherry_picking.md index d9314c3becc..ce2a1d4b954 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/feature_branch_development.md b/doc/topics/git/feature_branch_development.md index b205cedbdaa..de9f9980811 100644 --- a/doc/topics/git/feature_branch_development.md +++ b/doc/topics/git/feature_branch_development.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/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" type: how-tos --- diff --git a/doc/topics/git/feature_branching.md b/doc/topics/git/feature_branching.md index 4e9b43d66f8..73de351fde2 100644 --- a/doc/topics/git/feature_branching.md +++ b/doc/topics/git/feature_branching.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/getting_started.md b/doc/topics/git/getting_started.md index 7a836e5b659..a843d44aa8c 100644 --- a/doc/topics/git/getting_started.md +++ b/doc/topics/git/getting_started.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/git_add.md b/doc/topics/git/git_add.md index e15a1e9a60d..71f695d1657 100644 --- a/doc/topics/git/git_add.md +++ b/doc/topics/git/git_add.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/git_log.md b/doc/topics/git/git_log.md index 3988d7f7ac9..e2e9c0e8804 100644 --- a/doc/topics/git/git_log.md +++ b/doc/topics/git/git_log.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/git_rebase.md b/doc/topics/git/git_rebase.md index 1e118f98ca5..2f12201fb45 100644 --- a/doc/topics/git/git_rebase.md +++ b/doc/topics/git/git_rebase.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 description: "Introduction to Git rebase and force-push, methods to resolve merge conflicts through the command line." --- diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 1d1264fecf3..7d753374473 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/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/engineering/ux/technical-writing/#assignments +info: To 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.' --- diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index 3e78e366e00..f5dd458f625 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 6fd7f4a5207..1ab4a8a8acc 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs/index.html' --- diff --git a/doc/topics/git/lfs/migrate_to_git_lfs.md b/doc/topics/git/lfs/migrate_to_git_lfs.md index dda15845088..6e634cde8f0 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/engineering/ux/technical-writing/#assignments +info: To 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: "How to migrate an existing Git repository to Git LFS with BFG." --- @@ -15,7 +15,7 @@ instead of the method documented below. Using Git LFS can help you to reduce the size of your Git repository and improve its performance. -However, simply adding the large files that are already in your repository to Git LFS +However, adding the large files that are already in your repository to Git LFS doesn't actually reduce the size of your repository because the files are still referenced by previous commits. diff --git a/doc/topics/git/merge_conflicts.md b/doc/topics/git/merge_conflicts.md index 03b7c03c02a..91b608ab705 100644 --- a/doc/topics/git/merge_conflicts.md +++ b/doc/topics/git/merge_conflicts.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- 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 0ed7b2b5e03..e1e4300f42c 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md index eeae0d78638..ed80ab71c53 100644 --- a/doc/topics/git/partial_clone.md +++ b/doc/topics/git/partial_clone.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/topics/git/rollback_commits.md b/doc/topics/git/rollback_commits.md index 478dce179d2..65c4f1e5007 100644 --- a/doc/topics/git/rollback_commits.md +++ b/doc/topics/git/rollback_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/stash.md b/doc/topics/git/stash.md index 638ab559bd3..6ef72e300ed 100644 --- a/doc/topics/git/stash.md +++ b/doc/topics/git/stash.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/subtree.md b/doc/topics/git/subtree.md index 0bf89668405..1d624b45348 100644 --- a/doc/topics/git/subtree.md +++ b/doc/topics/git/subtree.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/tags.md b/doc/topics/git/tags.md index d3237fda968..ab196f409f7 100644 --- a/doc/topics/git/tags.md +++ b/doc/topics/git/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tags **(FREE)** diff --git a/doc/topics/git/terminology.md b/doc/topics/git/terminology.md index f64e614c253..ac097396bef 100644 --- a/doc/topics/git/terminology.md +++ b/doc/topics/git/terminology.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git terminology diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index 484f3a100bf..e585b860b16 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/topics/git/unstage.md b/doc/topics/git/unstage.md index b5f7c01de24..142a80a9ad9 100644 --- a/doc/topics/git/unstage.md +++ b/doc/topics/git/unstage.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index 13a40dd58ca..26ad155054b 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index 034c822671d..ffd9f36b369 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/gitlab_flow.html' --- diff --git a/doc/topics/offline/index.md b/doc/topics/offline/index.md index 13207c8c612..56b523c9c6f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 c00c9621756..bb2f651786c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Getting started with an offline GitLab Installation **(FREE SELF)** diff --git a/doc/topics/plan_and_track.md b/doc/topics/plan_and_track.md index 13cb3f8923b..cf5dfe488db 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Plan and track work **(FREE)** diff --git a/doc/topics/release_your_application.md b/doc/topics/release_your_application.md index 31fc9b4dbb9..6f1c7bb4a40 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy and release your application **(FREE)** diff --git a/doc/topics/set_up_organization.md b/doc/topics/set_up_organization.md index b6cacf0b14e..526e36b9ce0 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Set up your organization **(FREE)** diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md index 1b4762052c0..92e96a059dc 100644 --- a/doc/tutorials/index.md +++ b/doc/tutorials/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorials page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Learn GitLab with tutorials @@ -16,10 +16,10 @@ and running quickly. | Topic | Description | Good for beginners | |-------|-------------|--------------------| | <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Introduction to GitLab](https://youtu.be/_4SmIyQ5eis?t=90) (59m 51s) | Walk through recommended processes and example workflows for using GitLab. | **{star}** | -| [GitLab 101](https://gitlab.edcast.com/pathways/ECL-ce65e759-d9e7-459f-83d0-1765459395d2) | Learn the basics of GitLab in this certification course. | **{star}** | +| [GitLab 101](https://levelup.gitlab.com/learn/course/gitlab101) | Learn the basics of GitLab in this certification course. | **{star}** | | <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Use GitLab for DevOps](https://www.youtube.com/watch?v=7q9Y1Cv-ib0) (12m 34s) | Use GitLab through the entire DevOps lifecycle, from planning to monitoring. | **{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}** | -| [GitLab 201](https://gitlab.edcast.com/pathways/ECL-44010cf6-7a9c-4b9b-b684-fa08508a3252) | Go beyond the basics to learn more about using GitLab for your work. | | +| [GitLab 201](https://levelup.gitlab.com/learn/course/gitlab-201-certification) | Go beyond the basics to learn more about using GitLab for your work. | | | <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). | | | [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. | | | <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Structure a multi-team organization](https://www.youtube.com/watch?v=KmASFwSap7c) (37m 37s) | Learn to use issues, milestones, epics, labels, and more to plan and manage your work. | | @@ -67,7 +67,7 @@ configure the infrastructure for your application. | Topic | Description | Good for beginners | |-------|-------------|--------------------| | [Use GitOps with GitLab](https://about.gitlab.com/blog/2022/04/07/the-ultimate-guide-to-gitops-with-gitlab/) | Learn how to provision and manage a base infrastructure, connect to a Kubernetes cluster, deploy third-party applications, and carry out other infrastructure automation tasks. | | -| [Use Auto DevOps to deploy an application](../topics/autodevops/quick_start_guide.md) | Deploy an application to Google Kubernetes Engine (GKE). | | +| [Use Auto DevOps to deploy an application](../topics/autodevops/cloud_deployments/auto_devops_with_gke.md) | Deploy an application to Google Kubernetes Engine (GKE). | | ## Publish a static website diff --git a/doc/tutorials/make_your_first_git_commit.md b/doc/tutorials/make_your_first_git_commit.md index 879257fc3b8..cb6f41bff6c 100644 --- a/doc/tutorials/make_your_first_git_commit.md +++ b/doc/tutorials/make_your_first_git_commit.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Make your first Git commit diff --git a/doc/tutorials/move_personal_project_to_a_group.md b/doc/tutorials/move_personal_project_to_a_group.md index 49ce09a2ed4..2106f6ec1c9 100644 --- a/doc/tutorials/move_personal_project_to_a_group.md +++ b/doc/tutorials/move_personal_project_to_a_group.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: For assistance with this tutorial, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +info: For assistance with this tutorial, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-other-projects-and-subjects. --- # Move your personal project to a group **(FREE SAAS)** diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index 44a7137f698..ed9b812525e 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/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Deprecations by version @@ -45,6 +45,39 @@ sole discretion of GitLab Inc. <div class="announcement-milestone"> +## Announced in 15.5 + +<div class="deprecation removal-160 breaking-change"> + +### GraphQL field `confidential` changed to `internal` on notes + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The `confidential` field for a `Note` will be deprecated and renamed to `internal`. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### vulnerabilityFindingDismiss GraphQL mutation + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The `VulnerabilityFindingDismiss` GraphQL mutation is being deprecated and will be removed in GitLab 16.0. This mutation was not used often as the Vulnerability Finding ID was not available to users (this field was [deprecated in 15.3](https://docs.gitlab.com/ee/update/deprecations.html#use-of-id-field-in-vulnerabilityfindingdismiss-mutation)). Users should instead use `VulnerabilityDismiss` to dismiss vulnerabilities in the Vulnerability Report or `SecurityFindingDismiss` for security findings in the CI Pipeline Security tab. + +</div> +</div> + +<div class="announcement-milestone"> + ## Announced in 15.4 <div class="deprecation removal-160 breaking-change"> @@ -809,6 +842,29 @@ To align with this change, API calls to list external status checks will also re </div> +<div class="deprecation removal-160 breaking-change"> + +### GraphQL API Runner will not accept `status` filter values of `active` or `paused` + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). +Review the details carefully before upgrading. + +The GitLab Runner GraphQL endpoints will stop accepting `paused` or `active` as a status value in GitLab 16.0. + +A runner's status will only relate to runner contact status, such as: `online`, `offline`. +Status values `paused` or `active` will no longer be accepted and will be replaced by the `paused` query parameter. + +When checking for paused runners, API users are advised to specify `paused: true` as the query parameter. +When checking for active runners, specify `paused: false`. + +The REST API endpoints will follow in the same direction in a future REST v5 API, however the new `paused` +status value can be used in place of `active` since GitLab 14.8. + +</div> + <div class="deprecation removal-150 breaking-change"> ### GraphQL ID and GlobalID compatibility @@ -968,40 +1024,6 @@ The `instanceStatisticsMeasurements` GraphQL node has been renamed to `usageTren <div class="deprecation removal-160 breaking-change"> -### REST API Runner will not accept `status` filter values of `active` or `paused` - -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) - -WARNING: -This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). -Review the details carefully before upgrading. - -The GitLab Runner REST endpoints will stop accepting `paused` or `active` as a status value in GitLab 16.0. - -A runner's status will only relate to runner contact status, such as: `online`, `offline`. -Status values `paused` or `active` will no longer be accepted and will be replaced by the `paused` query parameter. - -When checking for paused runners, API users are advised to specify `paused=true` as the query parameter. -When checking for active runners, specify `paused=false`. - -</div> - -<div class="deprecation removal-160 breaking-change"> - -### REST API endpoint to list group runners no longer accepts `project_type` value for `type` argument - -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) - -WARNING: -This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). -Review the details carefully before upgrading. - -The `GET /groups/:id/runners?type=project_type` endpoint will be removed in GitLab 16.0. The endpoint always returned an empty collection. - -</div> - -<div class="deprecation removal-160 breaking-change"> - ### REST and GraphQL API Runner usage of `active` replaced by `paused` Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) @@ -1010,15 +1032,16 @@ WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. -Occurrences of the `active` identifier in the GitLab Runner REST and GraphQL API endpoints will be -renamed to `paused` in GitLab 16.0, namely: +Occurrences of the `active` identifier in the GitLab Runner GraphQL API endpoints will be +renamed to `paused` in GitLab 16.0. -- GraphQL API: - - the `CiRunner` property; - - the `RunnerUpdateInput` input type for the `runnerUpdate` mutation; - - the `runners` and `Group.runners` queries. -- REST API: - - endpoints taking or returning `active` properties, such as: +- For the GraphQL API, this change affects: + - the `CiRunner` property + - the `RunnerUpdateInput` input type for the `runnerUpdate` mutation + - the `runners` and `Group.runners` queries +- In v4 of the REST API, starting in GitLab 14.8, you can use the `paused` property in place of `active` +- In v5 of the REST API, this change will affect: + - endpoints taking or returning `active` property, such as: - `GET /runners` - `GET /runners/all` - `GET /runners/:id` / `PUT /runners/:id` @@ -1026,9 +1049,7 @@ renamed to `paused` in GitLab 16.0, namely: - `GET /projects/:id/runners` / `POST /projects/:id/runners` - `GET /groups/:id/runners` -The 16.0 release of the GitLab Runner will start using the `paused` property when registering runners, and therefore -will only be compatible with GitLab 16.0 and later. Until 16.0, GitLab will accept the deprecated `active` flag from -existing runners. +The 16.0 release of GitLab Runner will start using the `paused` property when registering runners. </div> @@ -1788,55 +1809,56 @@ Administrators who need to add runners for multiple projects can register a runn </div> -<div class="deprecation removal-150 breaking-change"> +<div class="deprecation removal-160 breaking-change"> -### Known host required for GitLab Runner SSH executor +### GraphQL API Runner status will not return `paused` -Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. -In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3074), we added a configuration setting in the GitLab Runner `config.toml` file. This setting, [`[runners.ssh.disable_strict_host_key_checking]`](https://docs.gitlab.com/runner/executors/ssh.html#security), controls whether or not to use strict host key checking with the SSH executor. +The GitLab Runner GraphQL API endpoints will not return `paused` or `active` as a status in GitLab 16.0. +In a future v5 of the REST API, the endpoints for GitLab Runner will also not return `paused` or `active`. -In GitLab 15.0 and later, the default value for this configuration option will change from `true` to `false`. This means that strict host key checking will be enforced when using the GitLab Runner SSH executor. +A runner's status will only relate to runner contact status, such as: +`online`, `offline`, or `not_connected`. Status `paused` or `active` will no longer appear. + +When checking if a runner is `paused`, API users are advised to check the boolean attribute +`paused` to be `true` instead. When checking if a runner is `active`, check if `paused` is `false`. </div> -<div class="deprecation removal-160 breaking-change"> +<div class="deprecation removal-150 breaking-change"> -### Package pipelines in API payload is paginated +### Known host required for GitLab Runner SSH executor -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. -A request to the API for `/api/v4/projects/:id/packages` returns a paginated result of packages. Each package lists all of its pipelines in this response. This is a performance concern, as it's possible for a package to have hundreds or thousands of associated pipelines. +In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3074), we added a configuration setting in the GitLab Runner `config.toml` file. This setting, [`[runners.ssh.disable_strict_host_key_checking]`](https://docs.gitlab.com/runner/executors/ssh.html#security), controls whether or not to use strict host key checking with the SSH executor. -In milestone 16.0, we will remove the `pipelines` attribute from the API response. +In GitLab 15.0 and later, the default value for this configuration option will change from `true` to `false`. This means that strict host key checking will be enforced when using the GitLab Runner SSH executor. </div> <div class="deprecation removal-160 breaking-change"> -### REST and GraphQL API Runner status will not return `paused` +### Package pipelines in API payload is paginated -Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) WARNING: This is a [breaking change](https://docs.gitlab.com/ee/development/deprecation_guidelines/). Review the details carefully before upgrading. -The GitLab Runner REST and GraphQL API endpoints will not return `paused` or `active` as a status in GitLab 16.0. - -A runner's status will only relate to runner contact status, such as: -`online`, `offline`, or `not_connected`. Status `paused` or `active` will no longer appear. +A request to the API for `/api/v4/projects/:id/packages` returns a paginated result of packages. Each package lists all of its pipelines in this response. This is a performance concern, as it's possible for a package to have hundreds or thousands of associated pipelines. -When checking if a runner is `paused`, API users are advised to check the boolean attribute -`paused` to be `true` instead. When checking if a runner is `active`, check if `paused` is `false`. +In milestone 16.0, we will remove the `pipelines` attribute from the API response. </div> diff --git a/doc/update/index.md b/doc/update/index.md index bffecf58304..06609f03952 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading GitLab **(FREE SELF)** @@ -392,6 +392,8 @@ The following table, while not exhaustive, shows some examples of the supported upgrade paths. Additional steps between the mentioned versions are possible. We list the minimally necessary steps only. +For a dynamic view of examples of supported upgrade paths, try the [Upgrade Path tool](https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/). The Upgrade Path tool is maintained by the [GitLab Support team](https://about.gitlab.com/handbook/support/#about-the-support-team). Share feedback and help improve the tool by raising an issue or MR in the [upgrade-path project](https://gitlab.com/gitlab-com/support/toolbox/upgrade-path). + | Target version | Your version | Supported upgrade path | Note | | -------------- | ------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `15.1.0` | `14.6.2` | `14.6.2` -> `14.9.5` -> `14.10.5` -> `15.0.2` -> `15.1.0` | Three intermediate versions are required: `14.9` and `14.10`, `15.0`, then `15.1.0`. | @@ -477,7 +479,7 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap ### 15.3.0 -- [Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). +- [Incorrect deletion of object storage files on Geo secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/371397) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). - LFS transfers can [redirect to the primary from secondary site mid-session](https://gitlab.com/gitlab-org/gitlab/-/issues/371571) causing failed pull and clone requests when [Geo proxying](../administration/geo/secondary_proxy/index.md) is enabled. Geo proxying is enabled by default in GitLab 15.1 and later. See [Geo: LFS transfer redirect to primary from secondary site mid-session issue in GitLab 15.1.0 to 15.3.2](#geo-lfs-transfers-redirect-to-primary-from-secondary-site-mid-session-in-gitlab-1510-to-1532) for more details. ### 15.2.0 @@ -498,7 +500,7 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap 1. Add `gitaly['runtime_dir'] = '<PATH_WITH_EXEC_PERM>'` to `/etc/gitlab/gitlab.rb` and specify a location without `noexec` set. 1. Run `sudo gitlab-ctl reconfigure`. -- [Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). +- [Incorrect deletion of object storage files on Geo secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/371397) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). - LFS transfers can [redirect to the primary from secondary site mid-session](https://gitlab.com/gitlab-org/gitlab/-/issues/371571) causing failed pull and clone requests when [Geo proxying](../administration/geo/secondary_proxy/index.md) is enabled. Geo proxying is enabled by default in GitLab 15.1 and later. See [Geo: LFS transfer redirect to primary from secondary site mid-session issue in GitLab 15.1.0 to 15.3.2](#geo-lfs-transfers-redirect-to-primary-from-secondary-site-mid-session-in-gitlab-1510-to-1532) for more details. ### 15.1.0 @@ -518,7 +520,7 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap - Unauthenticated requests to the [`ciConfig` GraphQL field](../api/graphql/reference/index.md#queryciconfig) are no longer supported. Before you upgrade to GitLab 15.1, add an [access token](../api/index.md#authentication) to your requests. The user creating the token must have [permission](../user/permissions.md) to create pipelines in the project. -- [Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). +- [Incorrect deletion of object storage files on Geo secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/371397) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). - LFS transfers can [redirect to the primary from secondary site mid-session](https://gitlab.com/gitlab-org/gitlab/-/issues/371571) causing failed pull and clone requests when [Geo proxying](../administration/geo/secondary_proxy/index.md) is enabled. Geo proxying is enabled by default in GitLab 15.1 and later. See [Geo: LFS transfer redirect to primary from secondary site mid-session issue in GitLab 15.1.0 to 15.3.2](#geo-lfs-transfers-redirect-to-primary-from-secondary-site-mid-session-in-gitlab-1510-to-1532) for more details. ### 15.0.0 @@ -534,7 +536,7 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap Gitaly. The previous implementation in GitLab Shell was removed in GitLab 15.0. With this change, global server hooks are stored only inside a subdirectory named after the hook type. Global server hooks can no longer be a single hook file in the root of the custom hooks directory. For example, you must use `<custom_hooks_dir>/<hook_name>.d/*` rather than `<custom_hooks_dir>/<hook_name>`. -- [Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). +- [Incorrect deletion of object storage files on Geo secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/371397) can occur in certain situations. See [Geo: Incorrect object storage LFS file deletion on secondary site issue in GitLab 15.0.0 to 15.3.2](#geo-incorrect-object-storage-lfs-file-deletion-on-secondary-sites-in-gitlab-1500-to-1532). - The `FF_GITLAB_REGISTRY_HELPER_IMAGE` [feature flag](../administration/feature_flags.md#enable-or-disable-the-feature) is removed and helper images are always pulled from GitLab Registry. ### 14.10.0 @@ -1183,7 +1185,7 @@ Read more [in the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/364763). ### Geo: Incorrect object storage LFS file deletion on secondary sites in GitLab 15.0.0 to 15.3.2 -[Incorrect deletion of object storage files on Geo secondary sites]((https://gitlab.com/gitlab-org/gitlab/-/issues/371397)) +[Incorrect deletion of object storage files on Geo secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/371397) can occur in GitLab 15.0.0 to 15.3.2 in the following situations: - GitLab-managed object storage replication is disabled, and LFS objects are created while importing a project with object storage enabled. diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index 8ac2791c82b..14914eee27c 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from MySQL to PostgreSQL **(FREE SELF)** diff --git a/doc/update/package/convert_to_ee.md b/doc/update/package/convert_to_ee.md index 2bf6d2c580b..7ebb860746b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 f48ba31568f..7b48f1f4045 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 06a56f49cc1..e0a4a388f56 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 b7c148045bd..6e153d5132d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index 03bdf161756..8169645e278 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a GitLab upgrade plan **(FREE SELF)** @@ -42,7 +42,7 @@ to ensure the major components of GitLab are working: ``` 1. In GitLab UI, check that: - - Users can log in. + - Users can sign in. - The project list is visible. - Project issues and merge requests are accessible. - Users can clone repositories from GitLab. @@ -122,7 +122,7 @@ to your instance and then upgrade it for any relevant features you're using. - [Convert from GitLab Community Edition to Enterprise Edition](package/convert_to_ee.md) - What version should you upgrade to: - [Determine what upgrade path](index.md#upgrade-paths) to follow. - - Account for any [version-specific update instructions](index.md#version-specific-upgrading-instructions). + - Account for any [version-specific update instructions](index.md#version-specific-upgrading-instructions) for both the current version and the destination version. - Account for any [version-specific changes](package/index.md#version-specific-changes). - Check the [OS compatibility with the target GitLab version](../administration/package_information/supported_os.md). - Due to background migrations, plan to pause before any further upgrades. diff --git a/doc/update/removals.md b/doc/update/removals.md index 9b5596d67f2..392259176bb 100644 --- a/doc/update/removals.md +++ b/doc/update/removals.md @@ -1,7 +1,7 @@ --- stage: none group: none -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" --- # Removals by version diff --git a/doc/update/restore_after_failure.md b/doc/update/restore_after_failure.md index 06da66088eb..cc0b188a0f8 100644 --- a/doc/update/restore_after_failure.md +++ b/doc/update/restore_after_failure.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Restoring from backup after a failed upgrade **(FREE SELF)** diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index 55561abc009..9bb88755686 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 4f54e69d8c9..bb9199560f9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments comments: false --- diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md index d3102ca4591..a645eb220ad 100644 --- a/doc/update/upgrading_postgresql_using_slony.md +++ b/doc/update/upgrading_postgresql_using_slony.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Upgrading PostgreSQL Using Slony **(FREE SELF)** diff --git a/doc/update/with_downtime.md b/doc/update/with_downtime.md index c6ad854fd0f..dfe64a3c2a9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 29bb1c4bcb4..aebd27f84a9 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Zero downtime upgrades **(FREE SELF)** @@ -313,7 +313,7 @@ node throughout the process. - If you're using PgBouncer: - You must bypass PgBouncer and connect directly to the database leader + You must [bypass PgBouncer](../administration/postgresql/pgbouncer.md#procedure-for-bypassing-pgbouncer) and connect directly to the database leader before running migrations. Rails uses an advisory lock when attempting to run a migration to prevent @@ -699,7 +699,7 @@ sudo touch /etc/gitlab/skip-auto-reconfigure 1. If you're using PgBouncer: - You must bypass PgBouncer and connect directly to the database leader + You must [bypass PgBouncer](../administration/postgresql/pgbouncer.md#procedure-for-bypassing-pgbouncer) and connect directly to the database leader before running migrations. Rails uses an advisory lock when attempting to run a migration to prevent diff --git a/doc/user/admin_area/analytics/dev_ops_reports.md b/doc/user/admin_area/analytics/dev_ops_reports.md index b4471a4602a..2d19c0a0058 100644 --- a/doc/user/admin_area/analytics/dev_ops_reports.md +++ b/doc/user/admin_area/analytics/dev_ops_reports.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DevOps Reports **(FREE SELF)** diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 9147a48aa8e..4304e612e4a 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -1,19 +1,25 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance-level analytics **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. -Administrators have access to instance-wide analytics: +Instance-level analytics provide insights into the feature and data usage of your entire instance. -1. On the top bar, select **Main menu > Admin**. -1. On the left sidebar, select **Analytics**. +## View instance-level analytics + +Prerequisite: + +- You must have administrator access for your instance. -There are several kinds of statistics: +To view instance-level analytics: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Analytics**, then one of the available analytics: -- [DevOps Reports](dev_ops_reports.md): Provides an overview of your entire instance's feature usage. -- [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. + - [DevOps Reports](dev_ops_reports.md): Provides an overview of your entire instance's feature usage. + - [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how the data is changing. diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index f21ee627f7f..a240a1ff524 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Usage Trends **(FREE SELF)** diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index fbc2f8d1827..5513fa3585d 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- @@ -30,7 +30,7 @@ supported by many email clients. ## Favicon By default, the favicon (used by the browser as the tab icon, as well as the CI status icon) -uses the GitLab logo, but this can be customized with any icon desired. It must be a +uses the GitLab logo. This can be customized with any icon desired. It must be a 32x32 `.png` or `.ico` image. After you select and upload an icon, select **Update appearance settings** at the bottom @@ -41,13 +41,13 @@ of the page to activate it in the GitLab instance. You can add a small header message, a small footer message, or both, to the interface of your GitLab instance. These messages appear on all projects and pages of the instance, including the sign in / sign up page. The default color is white text on -an orange background, but this can be customized by clicking on **Customize colors**. +an orange background, but this can be customized by selecting **Customize colors**. Limited [Markdown](../markdown.md) is supported, such as bold, italics, and links, for example. Other Markdown features, including lists, images, and quotes are not supported as the header and footer messages can only be a single line. -If desired, you can select **Enable header and footer in emails** to have the text of +You can select **Enable header and footer in emails** to have the text of the header and footer added to all emails sent by the GitLab instance. After you add a message, select **Update appearance settings** at the bottom of the page @@ -71,7 +71,7 @@ You can add also add a [customized help message](settings/help_page.md) below th ## New project pages -You can add a new project guidelines message to the **New project page** within GitLab. +You can add a new project guidelines message to the **New project page** in GitLab. You can make full use of [Markdown](../markdown.md) in the description: The message is displayed below the **New Project** message, on the left side @@ -84,8 +84,7 @@ which brings you to the new project page so you can review the change. ## Libravatar [Libravatar](https://www.libravatar.org) is supported by GitLab for avatar images, but you must -[manually enable Libravatar support on the GitLab instance](../../administration/libravatar.md) -in order to use the service. +[manually enable Libravatar support on the GitLab instance](../../administration/libravatar.md) to use the service. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index b508b71ddac..e5d0a6e297e 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 02c4cd05b23..df53ef0696f 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 0c03652bfb5..551ed667250 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index f646d9f95fd..3a1ecac6ee6 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/email_from_gitlab.md b/doc/user/admin_area/email_from_gitlab.md index 09643fc290e..c1d3521d60c 100644 --- a/doc/user/admin_area/email_from_gitlab.md +++ b/doc/user/admin_area/email_from_gitlab.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/geo_sites.md b/doc/user/admin_area/geo_sites.md index fecc0e7c541..093ed84f41a 100644 --- a/doc/user/admin_area/geo_sites.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Geo sites Admin Area **(PREMIUM SELF)** diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 207b7e6f2d8..e6ddb810933 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -270,10 +270,12 @@ To [Create a new group](../group/manage.md#create-a-group) select **New group**. ### Administering Topics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.4. +- > [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. -You can administer all [topics](../project/working_with_projects.md#explore-topics) in the -GitLab instance from the Admin Area's Topics page. +[Topics](../project/working_with_projects.md#explore-topics) are used to categorize and find similar projects. + +You can administer all topics in the GitLab instance from the Admin Area's Topics page. To access the Topics page: @@ -295,7 +297,7 @@ insensitive and applies partial matching. NOTE: The assigned topics are visible only to everyone with access to the project, -but everyone can see which topics exist at all on the GitLab instance. +but everyone can see which topics exist on the GitLab instance. Do not include sensitive information in the name of a topic. ### Administering Jobs @@ -351,10 +353,8 @@ You can also filter runners by status, type, and tag. To filter: #### Bulk delete runners -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370241) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `admin_runners_bulk_delete`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `admin_runners_bulk_delete`. On GitLab.com, this feature is not available but can be enabled by GitLab.com administrators. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370241) in GitLab 15.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/353981) in GitLab 15.5. You can delete multiple runners at the same time. diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index 93114186e75..524546d447c 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index a5338aa35b8..5211a18201b 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Activate GitLab Enterprise Edition (EE) **(PREMIUM SELF)** diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md index 352d79ee381..e6186fb9805 100644 --- a/doc/user/admin_area/license_file.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To 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 promote the workflow described in license.md, this page is not included in global left nav. --> @@ -24,6 +24,9 @@ Otherwise, to add your license: 1. Select the **Terms of Service** checkbox. 1. Select **Add license**. +NOTE: +For GitLab versions 14.1.x or newer, you can access the **Add License** page directly from the URL, `<YourGitLabURL>/admin/license/new`. + ## Add your license file during installation You can import a license file when you install GitLab. @@ -71,7 +74,9 @@ and issue creation. Your instance becomes read-only and an expiration message displays to all administrators. You have a 14-day grace period before this occurs. -To resume functionality, activate a new subscription. +To resume functionality, [renew your subscription](../../subscriptions/self_managed/index.md#renew-a-subscription). + +If the license has been expired for more than 30 days, you must purchase a [new subscription](../../subscriptions/self_managed/index.md) to resume functionality. To go back to Free features, [delete all expired licenses](#remove-a-license). @@ -138,3 +143,7 @@ rules apply: For example, if you purchase a license for 100 users, you can have 110 users when you add your license. However, if you have 111 users, you must purchase more users before you can add the license. + +### `Start GitLab Ultimate trial` still displays after adding license + +To fix this issue, restart [Puma or your entire GitLab instance](../../administration/restart_gitlab.md). diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 38b177766cf..b2f24091d7c 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 6d632a6bdb6..ace1c6be5f8 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -83,7 +83,7 @@ by removing them in LDAP, or directly from the Admin Area. To do this: A blocked user: -- Cannot log in. +- Cannot sign in. - Cannot access Git repositories or the API. - Does not receive any notifications from GitLab. - Cannot use [slash commands](../../integration/slash_commands.md). @@ -171,19 +171,20 @@ Users can also be deactivated using the [GitLab API](../../api/users.md#deactiva > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320875) in GitLab 14.0. > - Customizable time period [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336747) in GitLab 15.4 +> - The lower limit for inactive period set to 90 days [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/100793) in GitLab 15.5 Administrators can enable automatic deactivation of users who either: - Were created more than a week ago and have not signed in. -- Have no activity for a specified period of time (defaults to 90 days). +- Have no activity for a specified period of time (default and minimum is 90 days). To do this: 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. -1. Under **Dormant users**, check **Deactivate dormant users after 90 days of inactivity**. -1. Under **Period of inactivity (days)**, enter a period of time before deactivation. +1. Under **Dormant users**, check **Deactivate dormant users after a period of inactivity**. +1. Under **Days of inactivity before deactivation**, enter the number of days before deactivation. Minimum value is 90 days. 1. Select **Save changes**. When this feature is enabled, GitLab runs a job once a day to deactivate the dormant users. diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index 092a49dc7e9..f16cb219f2b 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Batched background migrations **(FREE SELF)** diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 84c7fa3c419..e6f9c045329 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Health Check **(FREE SELF)** @@ -15,7 +15,7 @@ traffic until the system is ready or restart the container as needed. ## IP allowlist To access monitoring resources, the requesting client IP needs to be included in the allowlist. -For details, see [how to add IPs to the allowlist for the monitoring endpoints](../../../administration/monitoring/ip_whitelist.md). +For details, see [how to add IPs to the allowlist for the monitoring endpoints](../../../administration/monitoring/ip_allowlist.md). ## Using the endpoints locally diff --git a/doc/user/admin_area/reporting/git_abuse_rate_limit.md b/doc/user/admin_area/reporting/git_abuse_rate_limit.md index 11b0e2403aa..432205d8fa2 100644 --- a/doc/user/admin_area/reporting/git_abuse_rate_limit.md +++ b/doc/user/admin_area/reporting/git_abuse_rate_limit.md @@ -1,7 +1,7 @@ --- stage: Anti-Abuse group: Anti-Abuse -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Git abuse rate limit **(ULTIMATE SELF)** diff --git a/doc/user/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md index 670b0521732..5c305eff4fa 100644 --- a/doc/user/admin_area/reporting/spamcheck.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Spamcheck anti-spam service **(FREE SELF)** @@ -61,7 +61,7 @@ token as the API key. ## Running Spamcheck over TLS -Spamcheck service on its own can not communicate directly over TLS with GitLab. +Spamcheck service on its own cannot communicate directly over TLS with GitLab. However, Spamcheck can be deployed behind a reverse proxy which performs TLS termination. In such a scenario, GitLab can be made to communicate with Spamcheck over TLS by specifying `tls://` scheme for the external Spamcheck URL diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 16295f340d8..af2f6640f8e 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -53,7 +53,7 @@ The following is an example of the **Abuse Reports** page: ### Blocking users -A blocked user cannot log in or access any repositories, but all of their data +A blocked user cannot sign in or access any repositories, but all of their data remains. Blocking a user: diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index e8f80cfb40f..cd1f20a2f4e 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -288,6 +288,21 @@ When this ability is disabled, GitLab administrators can still use the [Admin Area](../index.md#administering-users) or the [API](../../../api/users.md#user-modification) to update usernames. +## Prevent users from creating top-level groups + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367754) in GitLab 15.5. + +By default, new users can create top-level groups. GitLab administrators can prevent users from creating top-level groups: + +- In GitLab 15.5 and later, using either: + - The GitLab UI using the steps in this section. + - 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 top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. Clear the **Allow users to create top-level groups** checkbox. + ## Troubleshooting ### 413 Request Entity Too Large diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index dab3c78d9d1..afc9a006b39 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -70,7 +70,9 @@ runner settings: To view the rendered details: -1. On the top bar, select **Main menu > Projects** or **Main menu > Groups** and find your project or group. +1. On the top bar, select **Main menu**, and: + - For a project, select ***Projects** and find your project. + - For a group, select **Groups** and find your group. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Runners**. @@ -242,7 +244,7 @@ To enable or disable the banner: > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/352316) from GitLab Premium to GitLab Ultimate in 15.0. NOTE: -An alternative [compliance solution](../../project/settings/index.md#compliance-pipeline-configuration) +An alternative [compliance solution](../../group/manage.md#configure-a-compliance-pipeline) is available. We recommend this alternative solution because it provides greater flexibility, allowing required pipelines to be assigned to specific compliance framework labels. @@ -326,10 +328,8 @@ To set the maximum file size: ## Prevent users from registering runners -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22225) in GitLab 14.1. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../feature_flags.md) named `runner_registration_control`. On GitLab.com, this feature is not available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22225) in GitLab 14.1. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/368008) in GitLab 15.5. GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI. diff --git a/doc/user/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md index 7298d55b051..279cac95fc9 100644 --- a/doc/user/admin_area/settings/deprecated_api_rate_limits.md +++ b/doc/user/admin_area/settings/deprecated_api_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -37,7 +37,7 @@ To override the general user and IP rate limits for requests to deprecated API e 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Deprecated API Rate Limits**. -1. Select the check boxes for the types of rate limits you want to enable: +1. Select the checkboxes for the types of rate limits you want to enable: - **Unauthenticated API request rate limit** - **Authenticated API request rate limit** 1. _If you enabled unauthenticated API request rate limits:_ diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 96fab153e85..6a7c01ff98b 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Email **(FREE SELF)** diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 9db85eb6ea8..62d3d713616 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # External authorization control **(FREE SELF)** diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md index 963bca096a4..e5f5064304c 100644 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ b/doc/user/admin_area/settings/files_api_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -33,7 +33,7 @@ To override the general user and IP rate limits for requests to the Repository f 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Files API Rate Limits**. -1. Select the check boxes for the types of rate limits you want to enable: +1. Select the checkboxes for the types of rate limits you want to enable: - **Unauthenticated API request rate limit** - **Authenticated API request rate limit** 1. _If you enabled unauthenticated API request rate limits:_ diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index b7d3d8bfa20..08f3e8c09b2 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Federated Learning of Cohorts (FLoC) **(FREE SELF)** diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md index 519bbbef4e4..e0476f1e333 100644 --- a/doc/user/admin_area/settings/git_lfs_rate_limits.md +++ b/doc/user/admin_area/settings/git_lfs_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index dcf7574136a..d18fe0d74cd 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Gitaly timeouts **(FREE SELF)** diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 38161d0607c..a4072f8680b 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md index cfe4f49388e..acf82360042 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits for imports and exports of project and groups **(FREE SELF)** diff --git a/doc/user/admin_area/settings/incident_management_rate_limits.md b/doc/user/admin_area/settings/incident_management_rate_limits.md index f9e91d26db5..295569dafee 100644 --- a/doc/user/admin_area/settings/incident_management_rate_limits.md +++ b/doc/user/admin_area/settings/incident_management_rate_limits.md @@ -2,7 +2,7 @@ type: reference stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Incident management rate limits **(ULTIMATE SELF)** diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 7a63f2059ba..1bdacf486a2 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 0d63fe5db7f..b74f4f68230 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/user/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md index 62cddd2781c..7e0c3482e3e 100644 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ b/doc/user/admin_area/settings/package_registry_rate_limits.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 58afc6a104c..5be9081d9b2 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project integration management **(FREE)** @@ -122,7 +122,7 @@ Resetting a group-level default setting removes integrations that use default se 1. Navigate to **Project > Settings > Integrations**. 1. Choose the integration you want to enable or update. -1. From the drop-down, select **Use default settings**. +1. From the dropdown list, select **Use default settings**. 1. Ensure the toggle is set to **Enable integration**. 1. Select **Save changes**. @@ -130,6 +130,6 @@ Resetting a group-level default setting removes integrations that use default se 1. Navigate to project or group's **Settings > Integrations**. 1. Choose the integration you want to enable or update. -1. From the drop-down, select **Use custom settings**. +1. From the dropdown list, select **Use custom settings**. 1. Ensure the toggle is set to **Enable integration** and enter all required settings. 1. Select **Save changes**. diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index e686c65fe9a..4080ee6a540 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index cd982bb4aa3..0c3f299e9ec 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- 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 index 8d08da8246a..3c6fd4b1e45 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on issue creation **(FREE SELF)** 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 index f55c2f3bd4a..8465dccdbf3 100644 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on note creation **(FREE SELF)** 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 index ba383d74701..820f7eaf854 100644 --- a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on pipeline creation **(FREE SELF)** 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 index 9792fd1000d..f61c381a4fb 100644 --- a/doc/user/admin_area/settings/rate_limit_on_users_api.md +++ b/doc/user/admin_area/settings/rate_limit_on_users_api.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Rate limits on Users API **(FREE SELF)** 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 index cb3ca0fe756..7e262c45f48 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/sidekiq_job_limits.md b/doc/user/admin_area/settings/sidekiq_job_limits.md index c1990572aee..7a437d877ca 100644 --- a/doc/user/admin_area/settings/sidekiq_job_limits.md +++ b/doc/user/admin_area/settings/sidekiq_job_limits.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index bdffe87b75c..320768e6e5a 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign-in restrictions **(FREE SELF)** diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index a0ec964e8db..28fb188731b 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index d26ace161bb..28fe352c684 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 59c100dc016..fbd282ed5ad 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index ad018abf809..fb027b462df 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -1,7 +1,7 @@ --- stage: Analytics group: Product Intelligence -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Usage statistics **(FREE SELF)** 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 index 86676e4a63e..7431fc329d1 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -109,7 +109,7 @@ attached into the response headers. | `RateLimit-Observed` | `67` | Number of requests associated to the client in the time window. | | `RateLimit-Remaining` | `0` | Remaining quota in the time window. The result of `RateLimit-Limit` - `RateLimit-Observed`. | | `RateLimit-Reset` | `1609844400` | [Unix time](https://en.wikipedia.org/wiki/Unix_time)-formatted time when the request quota is reset. | -| `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3.1)-formatted date and time when the request quota is reset. | +| `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | [RFC2616](https://www.rfc-editor.org/rfc/rfc2616#section-3.3.1)-formatted date and time when the request quota is reset. | | `Retry-After` | `30` | Remaining duration **in seconds** until the quota is reset. This is a [standard HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | ## Use an HTTP header to bypass rate limiting diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 87c24f04a1c..d3132ae03c6 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index 816e629f496..c6d4f0b8e00 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cohorts **(FREE SELF)** diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index b92d68222f5..de9275b8599 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CI/CD analytics **(FREE)** diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index dd985b6b090..86f1e24429b 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -1,8 +1,8 @@ --- 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: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 41547430e88..56adbff9f59 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Analyze GitLab usage **(FREE)** @@ -77,8 +77,13 @@ To retrieve metrics for deployment frequency, use the [GraphQL](../../api/graphq ### Lead time for changes -Lead time for changes measures the time to deliver a feature once it has been developed, -as described in [Measuring DevOps Performance](https://devops.com/measuring-devops-performance/). +DORA Lead time for changes measures the time to successfully deliver a feature into production. +This metric reflects the efficiency of CI/CD pipelines. + +In GitLab, Lead time for changes calculates the median time it takes for a merge request to get merged into production. +We measure "FROM code committed TO code successfully running in production" without adding the "coding_time" to the calculation. + +Over time, the lead time for changes should decrease, while your team's performance should increase. Lead time for changes displays in several charts: @@ -88,6 +93,9 @@ Lead time for changes displays in several charts: To retrieve metrics for lead time for changes, use the [GraphQL](../../api/graphql/reference/index.md) or the [REST](../../api/dora/metrics.md) APIs. +- The definition of lead time for change can vary widely, which often creates confusion within the industry. +- "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 issue to move from the moment it's requested (Issue created) to the time it's fulfilled and delivered (Issue closed). + ### Time to restore service Time to restore service measures how long it takes an organization to recover from a failure in production. diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 86ae45a02b8..71ce13a725e 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -1,8 +1,8 @@ --- type: reference -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue analytics for projects **(PREMIUM)** diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 4f40575a4ef..1d1127c3d9f 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -1,8 +1,8 @@ --- 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: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request analytics **(PREMIUM)** diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index f0841dc979b..08bb579fd0a 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Productivity analytics **(PREMIUM)** diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 7723da7397d..b434221b887 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository analytics for projects **(FREE)** diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index d5756c5f822..ab68c897da8 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Value stream analytics for projects **(FREE)** 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 bc987c56fe8..445bcfb0444 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 8e371ed4dc6..d542c2d4be5 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -1093,6 +1093,7 @@ profile increases as the number of tests increases. | `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | | `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `2`. | | `FUZZAPI_IMAGE_SUFFIX` | Specify a container image suffix. Defaults to none. | +| `FUZZAPI_API_PORT` | Specify the communication port number used by API Fuzzing engine. Defaults to `5500`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367734) in GitLab 15.5. | | `FUZZAPI_TARGET_URL` | Base URL of API testing target. | | `FUZZAPI_CONFIG` | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/276395) in GitLab 13.12, replaced with default `.gitlab/gitlab-api-fuzzing-config.yml`. API Fuzzing configuration file. | |[`FUZZAPI_PROFILE`](#api-fuzzing-profiles) | Configuration profile to use during testing. Defaults to `Quick-10`. | @@ -1109,7 +1110,6 @@ profile increases as the number of tests increases. |[`FUZZAPI_GRAPHQL_SCHEMA`](#graphql-schema) | A URL or filename for a GraphQL schema in JSON format. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352780) in GitLab 15.4. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. The support for comma-separated (`,`) files was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356312) in GitLab 15.1. | -|[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. | |[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | |[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | |[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | @@ -1386,7 +1386,7 @@ variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.8. -By default the output of the overrides command is hidden. If the overrides command returns a non zero exit code, the command is displayed as part of your job output. Optionally, you can set the variable `FUZZAPI_OVERRIDES_CMD_VERBOSE` to any value in order to display overrides command output as it is generated. This is useful when testing your overrides script, but should be disabled afterwards as it slows down testing. +By default the output of the overrides command is hidden. If the overrides command returns a non zero exit code, the command is displayed as part of your job output. Optionally, you can set the variable `FUZZAPI_OVERRIDES_CMD_VERBOSE` to any value to display overrides command output as it is generated. This is useful when testing your overrides script, but should be disabled afterwards as it slows down testing. It is also possible to write messages from your script to a log file that is collected when the job completes or fails. The log file must be created in a specific location and follow a naming convention. @@ -2226,6 +2226,43 @@ If the issue is occurring with versions v1.6.196 or greater, contact Support and 1. The `gl-api-security-scanner.log` file available as a job artifact. In the right-hand panel of the job details page, select the **Browse** button. 1. The `apifuzzer_fuzz` job definition from your `.gitlab-ci.yml` file. +### `Failed to start session with scanner. Please retry, and if the problem persists reach out to support.` + +The API Fuzzing engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `apifuzzer_fuzz` job. A common cause for this issue is that the background component cannot use the selected port as it's already in use. This error can occur intermittently if timing plays a part (race condition). This issue occurs most often with Kubernetes environments when other services are mapped into the container causing port conflicts. + +Before proceeding with a solution, it is important to confirm that the error message was produced because the port was already taken. To confirm this was the cause: + +1. Go to the job console. + +1. Look for the artifact `gl-api-security-scanner.log`. You can either download all artifacts by selecting **Download** and then search for the file, or directly start searching by selecting **Browse**. + +1. Open the file `gl-api-security-scanner.log` in a text editor. + +1. If the error message was produced because the port was already taken, you should see in the file a message like the following: + +- In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/367734): + + ```log + Failed to bind to address http://127.0.0.1:5500: address already in use. + ``` + +- In GitLab 15.4 and earlier: + + ```log + Failed to bind to address http://[::]:5000: address already in use. + ``` + +The text `http://[::]:5000` in the previous message could be different in your case, for instance it could be `http://[::]:5500` or `http://127.0.0.1:5500`. As long as the remaining parts of the error message are the same, it is safe to assume the port was already taken. + +If you did not find evidence that the port was already taken, check other troubleshooting sections which also address the same error message shown in the job console output. If there are no more options, feel free to [get support or request an improvement](#get-support-or-request-an-improvement) through the proper channels. + +Once you have confirmed the issue was produced because the port was already taken. Then, [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/367734) introduced the configuration variable `FUZZAPI_API_PORT`. This configuration variable allows setting a fixed port number for the scanner background component. + +**Solution** + +1. Ensure your `.gitlab-ci.yml` file defines the configuration variable `FUZZAPI_API_PORT`. +1. Update the value of `FUZZAPI_API_PORT` to any available port number greater than 1024. We recommend checking that the new value is not in used by GitLab. See the full list of ports used by GitLab in [Package defaults](../../../administration/package_information/defaults.md#ports) + ### `Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema` At the start of an API Fuzzing job the OpenAPI Specification is validated against the [published schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas). This error is shown when the provided OpenAPI Specification has validation errors. Errors can be introduced when creating an OpenAPI Specification manually, and also when the schema is generated. diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md deleted file mode 100644 index e7a59d70b25..00000000000 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../clusters/agent/vulnerabilities.md' -remove_date: '2022-08-19' ---- - -This document was moved to [another location](../../clusters/agent/vulnerabilities.md). - -<!-- This redirect file can be deleted after <2022-08-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 (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/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 32a523a1871..5eb1b93eb76 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Security Configuration **(FREE)** @@ -19,12 +19,23 @@ The Security Configuration page lists the following for the security testing and - Whether or not it is available. - A configuration button or a link to its configuration guide. -The status of each security control is determined by the project's latest default branch -[CI pipeline](../../../ci/pipelines/index.md). -If a job with the expected security report artifact exists in the pipeline, the feature's status is -_enabled_. +To determine the status of each security control, GitLab checks for a [CI/CD pipeline](../../../ci/pipelines/index.md) +in the most recent commit on the default branch. -If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), +If GitLab finds a CI/CD pipeline, then it inspects each job in the `.gitlab-ci.yml` file. + +- If a job defines an [`artifacts:reports` keyword](../../../ci/yaml/artifacts_reports.md) + for a security scanner, then GitLab considers the security scanner enabled and shows the **Enabled** status. +- If no jobs define an `artifacts:reports` keyword for a security scanner, then GitLab considers + the security scanner disabled and shows the **Not enabled** status. + +If GitLab does not find a CI/CD pipeline, then it considers all security scanners disabled and shows the **Not enabled** status. + +Failed pipelines and jobs are included in this process. If a scanner is configured but the job fails, +that scanner is still considered enabled. This process also determines the scanners and statuses +returned through the [API](../../../api/graphql/reference/index.md#securityscanners). + +If the latest pipeline uses [Auto DevOps](../../../topics/autodevops/index.md), all security features are configured by default. To view a project's security configuration: diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 961ccf6b563..f6bd6157a28 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Container Scanning **(FREE)** @@ -446,7 +446,7 @@ automatically set to `$CI_REGISTRY_IMAGE/$CI_DEFAULT_BRANCH:$CI_APPLICATION_TAG` ### Using a custom SSL CA certificate authority -You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: +You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: ```yaml container_scanning: diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index bec242a0426..c04c07f561d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Coverage-guided fuzz testing **(ULTIMATE)** @@ -337,14 +337,14 @@ To use coverage fuzzing in an offline environment: After a vulnerability is found, you can [address it](../vulnerabilities/index.md). The merge request widget lists the vulnerability and contains a button for downloading the fuzzing -artifacts. By clicking one of the detected vulnerabilities, you can see its details. +artifacts. By selecting one of the detected vulnerabilities, you can see its details.  You can also view the vulnerability from the [Security Dashboard](../security_dashboard/index.md), which shows an overview of all the security vulnerabilities in your groups, projects, and pipelines. -Clicking the vulnerability opens a modal that provides additional information about the +Selecting the vulnerability opens a modal that provides additional information about the vulnerability: <!-- vale gitlab.Acronyms = NO --> diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index 6f076bbe3f9..bbe97081a55 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # CVE ID request **(FREE SAAS)** diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index e8373b0c0b7..5a4acc78728 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -19,7 +19,7 @@ ensuring DAST coverage. The browser-based scanner works by loading the target application into a specially-instrumented Chromium browser. A snapshot of the page is taken before a search to find any actions that a user -might perform, such as clicking on a link or filling in a form. For each action found, the +might perform, such as selecting on a link or filling in a form. For each action found, the browser-based scanner executes it, takes a new snapshot, and determines what in the page changed from the previous snapshot. Crawling continues by taking more snapshots and finding subsequent actions. The benefit of scanning by following user actions in a browser is that the crawler can @@ -64,7 +64,7 @@ The browser-based crawler can be configured using CI/CD variables. | `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | | `DAST_BROWSER_EXCLUDED_ELEMENTS` | selector | `a[href='2.html'],css:.no-follow` | Comma-separated list of selectors that are ignored when scanning. | | `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | -| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | +| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, selecting a link, or filling a form. | | `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | | `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com, we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but are likely to produce little benefit after five to seven instances. | | `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | @@ -193,3 +193,14 @@ The modules that can be configured for logging are as follows: | `NAVDB` | Used for persistence mechanisms to store navigation entries. | | `REPT` | Used for generating reports. | | `STAT` | Used for general statistics while running the scan. | + +### Artifacts + +DAST's browser-based analyzer generates artifacts that can help you understand how the scanner works. +Using the latest version of the DAST [template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml) these artifacts are exposed for download by default. + +The list of artifacts includes the following files: + +- `gl-dast-debug-auth-report.html` +- `gl-dast-debug-crawl-report.html` +- `gl-dast-crawl-graph.svg` diff --git a/doc/user/application_security/dast/checks/1004.1.md b/doc/user/application_security/dast/checks/1004.1.md index 40139f2aa8a..737e9dcfd62 100644 --- a/doc/user/application_security/dast/checks/1004.1.md +++ b/doc/user/application_security/dast/checks/1004.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sensitive cookie without HttpOnly attribute diff --git a/doc/user/application_security/dast/checks/16.1.md b/doc/user/application_security/dast/checks/16.1.md index 157b2b96ed4..c225e3ce368 100644 --- a/doc/user/application_security/dast/checks/16.1.md +++ b/doc/user/application_security/dast/checks/16.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Missing Content-Type header diff --git a/doc/user/application_security/dast/checks/16.10.md b/doc/user/application_security/dast/checks/16.10.md index 67368d80022..9d6a7f85e20 100644 --- a/doc/user/application_security/dast/checks/16.10.md +++ b/doc/user/application_security/dast/checks/16.10.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Content-Security-Policy violations diff --git a/doc/user/application_security/dast/checks/16.2.md b/doc/user/application_security/dast/checks/16.2.md index 484460b6642..a317b9418a1 100644 --- a/doc/user/application_security/dast/checks/16.2.md +++ b/doc/user/application_security/dast/checks/16.2.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/engineering/ux/technical-writing/#assignments +info: To 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 header exposes version information @@ -41,4 +41,4 @@ the `Server` header. - [CWE](https://cwe.mitre.org/data/definitions/16.html) - [Apache ServerTokens](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) - [NGINX server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) -- [IIS 10 Remove Server Header](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/security/requestfiltering/#attributes) +- [IIS 10 Remove Server Header](https://learn.microsoft.com/en-us/iis/configuration/system.webserver/security/requestfiltering/#attributes) diff --git a/doc/user/application_security/dast/checks/16.3.md b/doc/user/application_security/dast/checks/16.3.md index e4fc2468dae..d9e6f6f8d92 100644 --- a/doc/user/application_security/dast/checks/16.3.md +++ b/doc/user/application_security/dast/checks/16.3.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # X-Powered-By header exposes version information diff --git a/doc/user/application_security/dast/checks/16.4.md b/doc/user/application_security/dast/checks/16.4.md index 1f72a80cb29..e6b4ba8627f 100644 --- a/doc/user/application_security/dast/checks/16.4.md +++ b/doc/user/application_security/dast/checks/16.4.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # X-Backend-Server header exposes server information diff --git a/doc/user/application_security/dast/checks/16.5.md b/doc/user/application_security/dast/checks/16.5.md index 28bb9f7ee4b..285cc753523 100644 --- a/doc/user/application_security/dast/checks/16.5.md +++ b/doc/user/application_security/dast/checks/16.5.md @@ -1,14 +1,14 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # AspNet header exposes version information ## Description -The target website returns AspNet header(s) and version information of this website. By +The target website returns AspNet headers and version information of this website. By exposing these values attackers may attempt to identify if the target software is vulnerable to known vulnerabilities, or catalog known sites running particular versions to exploit in the future when a vulnerability is identified in the particular version. diff --git a/doc/user/application_security/dast/checks/16.6.md b/doc/user/application_security/dast/checks/16.6.md index ddd3a10c5f8..c6705b2ec7f 100644 --- a/doc/user/application_security/dast/checks/16.6.md +++ b/doc/user/application_security/dast/checks/16.6.md @@ -1,14 +1,14 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # AspNetMvc header exposes version information ## Description -The target website returns AspNet header(s) along with version information of this website. By +The target website returns AspNet headers along with version information of this website. By exposing these values attackers may attempt to identify if the target software is vulnerable to known vulnerabilities. Or catalog known sites running particular versions to exploit in the future when a vulnerability is identified in the particular version. diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md index a052149ee4d..cef13c9663f 100644 --- a/doc/user/application_security/dast/checks/16.7.md +++ b/doc/user/application_security/dast/checks/16.7.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Strict-Transport-Security header missing or invalid diff --git a/doc/user/application_security/dast/checks/16.8.md b/doc/user/application_security/dast/checks/16.8.md index c9beba4544e..07bd2a6842f 100644 --- a/doc/user/application_security/dast/checks/16.8.md +++ b/doc/user/application_security/dast/checks/16.8.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Content-Security-Policy analysis diff --git a/doc/user/application_security/dast/checks/16.9.md b/doc/user/application_security/dast/checks/16.9.md index c3e4431e415..b0ba502b578 100644 --- a/doc/user/application_security/dast/checks/16.9.md +++ b/doc/user/application_security/dast/checks/16.9.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Content-Security-Policy-Report-Only analysis diff --git a/doc/user/application_security/dast/checks/200.1.md b/doc/user/application_security/dast/checks/200.1.md index fcd329c3f2b..c7c1e938678 100644 --- a/doc/user/application_security/dast/checks/200.1.md +++ b/doc/user/application_security/dast/checks/200.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of sensitive information to an unauthorized actor (private IP address) diff --git a/doc/user/application_security/dast/checks/209.1.md b/doc/user/application_security/dast/checks/209.1.md index f2713a70afd..181595a279e 100644 --- a/doc/user/application_security/dast/checks/209.1.md +++ b/doc/user/application_security/dast/checks/209.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Generation of error message containing sensitive information diff --git a/doc/user/application_security/dast/checks/209.2.md b/doc/user/application_security/dast/checks/209.2.md index 2060bb1802b..9906347f7b9 100644 --- a/doc/user/application_security/dast/checks/209.2.md +++ b/doc/user/application_security/dast/checks/209.2.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Generation of database error message containing sensitive information diff --git a/doc/user/application_security/dast/checks/287.1.md b/doc/user/application_security/dast/checks/287.1.md index 06b7e7b4b2e..d3d16d47677 100644 --- a/doc/user/application_security/dast/checks/287.1.md +++ b/doc/user/application_security/dast/checks/287.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Insecure authentication over HTTP (Basic Authentication) diff --git a/doc/user/application_security/dast/checks/287.2.md b/doc/user/application_security/dast/checks/287.2.md index 2215b72f47a..9da22c66f84 100644 --- a/doc/user/application_security/dast/checks/287.2.md +++ b/doc/user/application_security/dast/checks/287.2.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Insecure authentication over HTTP (Digest Authentication) diff --git a/doc/user/application_security/dast/checks/319.1.md b/doc/user/application_security/dast/checks/319.1.md index d598fb70ce3..6c68344505a 100644 --- a/doc/user/application_security/dast/checks/319.1.md +++ b/doc/user/application_security/dast/checks/319.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mixed Content diff --git a/doc/user/application_security/dast/checks/352.1.md b/doc/user/application_security/dast/checks/352.1.md index 4daba908331..46e3bb32ebe 100644 --- a/doc/user/application_security/dast/checks/352.1.md +++ b/doc/user/application_security/dast/checks/352.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Absence of anti-CSRF tokens diff --git a/doc/user/application_security/dast/checks/359.1.md b/doc/user/application_security/dast/checks/359.1.md index 076ab2da0d5..f7d9069731c 100644 --- a/doc/user/application_security/dast/checks/359.1.md +++ b/doc/user/application_security/dast/checks/359.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of Private Personal Information (PII) to an unauthorized actor (credit card) diff --git a/doc/user/application_security/dast/checks/359.2.md b/doc/user/application_security/dast/checks/359.2.md index 2c59b5e321f..d5428718171 100644 --- a/doc/user/application_security/dast/checks/359.2.md +++ b/doc/user/application_security/dast/checks/359.2.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of Private Personal Information (PII) to an unauthorized actor (United States social security number) diff --git a/doc/user/application_security/dast/checks/548.1.md b/doc/user/application_security/dast/checks/548.1.md index 1da2ce58247..b6907db5928 100644 --- a/doc/user/application_security/dast/checks/548.1.md +++ b/doc/user/application_security/dast/checks/548.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of information through directory listing @@ -42,4 +42,4 @@ indexing. - [CWE](https://cwe.mitre.org/data/definitions/548.html) - [Apache Options](https://httpd.apache.org/docs/2.4/mod/core.html#options) - [NGINX autoindex](https://nginx.org/en/docs/http/ngx_http_autoindex_module.html) -- [IIS directoryBrowse element](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/directorybrowse) +- [IIS directoryBrowse element](https://learn.microsoft.com/en-us/iis/configuration/system.webserver/directorybrowse) diff --git a/doc/user/application_security/dast/checks/598.1.md b/doc/user/application_security/dast/checks/598.1.md index 817e20ec413..21a28705c4e 100644 --- a/doc/user/application_security/dast/checks/598.1.md +++ b/doc/user/application_security/dast/checks/598.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use of GET request method with sensitive query strings (session ID) diff --git a/doc/user/application_security/dast/checks/598.2.md b/doc/user/application_security/dast/checks/598.2.md index 05d04b71cf0..2b7204b58df 100644 --- a/doc/user/application_security/dast/checks/598.2.md +++ b/doc/user/application_security/dast/checks/598.2.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use of GET request method with sensitive query strings (password) diff --git a/doc/user/application_security/dast/checks/598.3.md b/doc/user/application_security/dast/checks/598.3.md index be17fdcaef6..9a2e507af18 100644 --- a/doc/user/application_security/dast/checks/598.3.md +++ b/doc/user/application_security/dast/checks/598.3.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use of GET request method with sensitive query strings (Authorization header details) diff --git a/doc/user/application_security/dast/checks/601.1.md b/doc/user/application_security/dast/checks/601.1.md index c51b00cdd36..f9ca304dea8 100644 --- a/doc/user/application_security/dast/checks/601.1.md +++ b/doc/user/application_security/dast/checks/601.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # URL redirection to untrusted site ('open redirect') diff --git a/doc/user/application_security/dast/checks/614.1.md b/doc/user/application_security/dast/checks/614.1.md index d5c7476716f..00f51ceea06 100644 --- a/doc/user/application_security/dast/checks/614.1.md +++ b/doc/user/application_security/dast/checks/614.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sensitive cookie without Secure attribute diff --git a/doc/user/application_security/dast/checks/693.1.md b/doc/user/application_security/dast/checks/693.1.md index d3f4c72c676..7dc09d3f2d7 100644 --- a/doc/user/application_security/dast/checks/693.1.md +++ b/doc/user/application_security/dast/checks/693.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Missing X-Content-Type-Options: nosniff diff --git a/doc/user/application_security/dast/checks/798.1.md b/doc/user/application_security/dast/checks/798.1.md index 819ae92cfdc..2697cd1b1ec 100644 --- a/doc/user/application_security/dast/checks/798.1.md +++ b/doc/user/application_security/dast/checks/798.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Adafruit API Key diff --git a/doc/user/application_security/dast/checks/798.10.md b/doc/user/application_security/dast/checks/798.10.md index 14723c81f17..ceee9c28fd1 100644 --- a/doc/user/application_security/dast/checks/798.10.md +++ b/doc/user/application_security/dast/checks/798.10.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Asana Client Secret diff --git a/doc/user/application_security/dast/checks/798.100.md b/doc/user/application_security/dast/checks/798.100.md index 07bd24211c7..2c14dab9f30 100644 --- a/doc/user/application_security/dast/checks/798.100.md +++ b/doc/user/application_security/dast/checks/798.100.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Sendbird Access Token diff --git a/doc/user/application_security/dast/checks/798.101.md b/doc/user/application_security/dast/checks/798.101.md index ea102147100..e4c277c1bb5 100644 --- a/doc/user/application_security/dast/checks/798.101.md +++ b/doc/user/application_security/dast/checks/798.101.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token SendGrid API token diff --git a/doc/user/application_security/dast/checks/798.102.md b/doc/user/application_security/dast/checks/798.102.md index 8a40475190a..303010d4bc5 100644 --- a/doc/user/application_security/dast/checks/798.102.md +++ b/doc/user/application_security/dast/checks/798.102.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Sendinblue API token diff --git a/doc/user/application_security/dast/checks/798.103.md b/doc/user/application_security/dast/checks/798.103.md index 3d91f7f3b80..0524a50be7b 100644 --- a/doc/user/application_security/dast/checks/798.103.md +++ b/doc/user/application_security/dast/checks/798.103.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Sentry Access Token diff --git a/doc/user/application_security/dast/checks/798.104.md b/doc/user/application_security/dast/checks/798.104.md index 316998615ff..6e806e8cf6e 100644 --- a/doc/user/application_security/dast/checks/798.104.md +++ b/doc/user/application_security/dast/checks/798.104.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Shippo API token diff --git a/doc/user/application_security/dast/checks/798.105.md b/doc/user/application_security/dast/checks/798.105.md index 20618a9d555..162d8533320 100644 --- a/doc/user/application_security/dast/checks/798.105.md +++ b/doc/user/application_security/dast/checks/798.105.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Shopify access token diff --git a/doc/user/application_security/dast/checks/798.106.md b/doc/user/application_security/dast/checks/798.106.md index 4f552302e85..177803b9196 100644 --- a/doc/user/application_security/dast/checks/798.106.md +++ b/doc/user/application_security/dast/checks/798.106.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Shopify custom access token diff --git a/doc/user/application_security/dast/checks/798.107.md b/doc/user/application_security/dast/checks/798.107.md index 2a5961b3905..5241a6e9d09 100644 --- a/doc/user/application_security/dast/checks/798.107.md +++ b/doc/user/application_security/dast/checks/798.107.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Shopify private app access token diff --git a/doc/user/application_security/dast/checks/798.108.md b/doc/user/application_security/dast/checks/798.108.md index 23968bcf660..c6863ac4757 100644 --- a/doc/user/application_security/dast/checks/798.108.md +++ b/doc/user/application_security/dast/checks/798.108.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Shopify shared secret diff --git a/doc/user/application_security/dast/checks/798.109.md b/doc/user/application_security/dast/checks/798.109.md index 57d6823d8a9..bfb82e6640f 100644 --- a/doc/user/application_security/dast/checks/798.109.md +++ b/doc/user/application_security/dast/checks/798.109.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Slack token diff --git a/doc/user/application_security/dast/checks/798.11.md b/doc/user/application_security/dast/checks/798.11.md index b12f86ba800..fd54560db79 100644 --- a/doc/user/application_security/dast/checks/798.11.md +++ b/doc/user/application_security/dast/checks/798.11.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Atlassian API token diff --git a/doc/user/application_security/dast/checks/798.110.md b/doc/user/application_security/dast/checks/798.110.md index 8ac7a8a4be2..7a68284fae4 100644 --- a/doc/user/application_security/dast/checks/798.110.md +++ b/doc/user/application_security/dast/checks/798.110.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Slack Webhook diff --git a/doc/user/application_security/dast/checks/798.111.md b/doc/user/application_security/dast/checks/798.111.md index ff05dcfe55b..0804613ee48 100644 --- a/doc/user/application_security/dast/checks/798.111.md +++ b/doc/user/application_security/dast/checks/798.111.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Stripe diff --git a/doc/user/application_security/dast/checks/798.112.md b/doc/user/application_security/dast/checks/798.112.md index 4f5f89dab9c..2570e39357a 100644 --- a/doc/user/application_security/dast/checks/798.112.md +++ b/doc/user/application_security/dast/checks/798.112.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Square Access Token diff --git a/doc/user/application_security/dast/checks/798.113.md b/doc/user/application_security/dast/checks/798.113.md index 3f8d1a88ec0..c445a9f48b0 100644 --- a/doc/user/application_security/dast/checks/798.113.md +++ b/doc/user/application_security/dast/checks/798.113.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Squarespace Access Token diff --git a/doc/user/application_security/dast/checks/798.114.md b/doc/user/application_security/dast/checks/798.114.md index 0b8235af8c7..7afe862231d 100644 --- a/doc/user/application_security/dast/checks/798.114.md +++ b/doc/user/application_security/dast/checks/798.114.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token SumoLogic Access ID diff --git a/doc/user/application_security/dast/checks/798.115.md b/doc/user/application_security/dast/checks/798.115.md index 052502ea962..dc305c61c30 100644 --- a/doc/user/application_security/dast/checks/798.115.md +++ b/doc/user/application_security/dast/checks/798.115.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token SumoLogic Access Token diff --git a/doc/user/application_security/dast/checks/798.116.md b/doc/user/application_security/dast/checks/798.116.md index 7b1f0eb907d..54d97f90b47 100644 --- a/doc/user/application_security/dast/checks/798.116.md +++ b/doc/user/application_security/dast/checks/798.116.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Travis CI Access Token diff --git a/doc/user/application_security/dast/checks/798.117.md b/doc/user/application_security/dast/checks/798.117.md index 5cd9817795a..ff4b1299d32 100644 --- a/doc/user/application_security/dast/checks/798.117.md +++ b/doc/user/application_security/dast/checks/798.117.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Twilio API Key diff --git a/doc/user/application_security/dast/checks/798.118.md b/doc/user/application_security/dast/checks/798.118.md index a74233429df..dc4121e23ba 100644 --- a/doc/user/application_security/dast/checks/798.118.md +++ b/doc/user/application_security/dast/checks/798.118.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Twitch API token diff --git a/doc/user/application_security/dast/checks/798.119.md b/doc/user/application_security/dast/checks/798.119.md index 80fada87b1c..df470195454 100644 --- a/doc/user/application_security/dast/checks/798.119.md +++ b/doc/user/application_security/dast/checks/798.119.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Twitter API Key diff --git a/doc/user/application_security/dast/checks/798.12.md b/doc/user/application_security/dast/checks/798.12.md index 6f8d0c83a94..8cfe5f1cf2f 100644 --- a/doc/user/application_security/dast/checks/798.12.md +++ b/doc/user/application_security/dast/checks/798.12.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token AWS diff --git a/doc/user/application_security/dast/checks/798.120.md b/doc/user/application_security/dast/checks/798.120.md index 639b5c6ffc2..986af1901a4 100644 --- a/doc/user/application_security/dast/checks/798.120.md +++ b/doc/user/application_security/dast/checks/798.120.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Twitter API Secret diff --git a/doc/user/application_security/dast/checks/798.121.md b/doc/user/application_security/dast/checks/798.121.md index e574760baa2..c2301d49bbb 100644 --- a/doc/user/application_security/dast/checks/798.121.md +++ b/doc/user/application_security/dast/checks/798.121.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Twitter Access Token diff --git a/doc/user/application_security/dast/checks/798.122.md b/doc/user/application_security/dast/checks/798.122.md index 9acb82a6062..442c1bd09ba 100644 --- a/doc/user/application_security/dast/checks/798.122.md +++ b/doc/user/application_security/dast/checks/798.122.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Twitter Access Secret diff --git a/doc/user/application_security/dast/checks/798.123.md b/doc/user/application_security/dast/checks/798.123.md index 5d5c9df5f40..b21c00fb547 100644 --- a/doc/user/application_security/dast/checks/798.123.md +++ b/doc/user/application_security/dast/checks/798.123.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Twitter Bearer Token diff --git a/doc/user/application_security/dast/checks/798.124.md b/doc/user/application_security/dast/checks/798.124.md index 4900ca44ba4..3d1e7875848 100644 --- a/doc/user/application_security/dast/checks/798.124.md +++ b/doc/user/application_security/dast/checks/798.124.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Typeform API token diff --git a/doc/user/application_security/dast/checks/798.125.md b/doc/user/application_security/dast/checks/798.125.md index 1111ef91491..41217655721 100644 --- a/doc/user/application_security/dast/checks/798.125.md +++ b/doc/user/application_security/dast/checks/798.125.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Yandex API Key diff --git a/doc/user/application_security/dast/checks/798.126.md b/doc/user/application_security/dast/checks/798.126.md index 6253f9a4a92..bfb48d4e3eb 100644 --- a/doc/user/application_security/dast/checks/798.126.md +++ b/doc/user/application_security/dast/checks/798.126.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Yandex AWS Access Token diff --git a/doc/user/application_security/dast/checks/798.127.md b/doc/user/application_security/dast/checks/798.127.md index 86bb9613f16..8df930ffb07 100644 --- a/doc/user/application_security/dast/checks/798.127.md +++ b/doc/user/application_security/dast/checks/798.127.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Yandex Access Token diff --git a/doc/user/application_security/dast/checks/798.128.md b/doc/user/application_security/dast/checks/798.128.md index 0db8cdd8005..2bee2604870 100644 --- a/doc/user/application_security/dast/checks/798.128.md +++ b/doc/user/application_security/dast/checks/798.128.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Zendesk Secret Key diff --git a/doc/user/application_security/dast/checks/798.13.md b/doc/user/application_security/dast/checks/798.13.md index 8cf2f7c2895..83e45dedecb 100644 --- a/doc/user/application_security/dast/checks/798.13.md +++ b/doc/user/application_security/dast/checks/798.13.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Bitbucket Client ID diff --git a/doc/user/application_security/dast/checks/798.14.md b/doc/user/application_security/dast/checks/798.14.md index 85b88660b5a..eb800c510c8 100644 --- a/doc/user/application_security/dast/checks/798.14.md +++ b/doc/user/application_security/dast/checks/798.14.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Bitbucket Client Secret diff --git a/doc/user/application_security/dast/checks/798.15.md b/doc/user/application_security/dast/checks/798.15.md index 51f2fae0021..f9e01799b63 100644 --- a/doc/user/application_security/dast/checks/798.15.md +++ b/doc/user/application_security/dast/checks/798.15.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Bittrex Access Key diff --git a/doc/user/application_security/dast/checks/798.16.md b/doc/user/application_security/dast/checks/798.16.md index 872a97e70ea..92fbb490d12 100644 --- a/doc/user/application_security/dast/checks/798.16.md +++ b/doc/user/application_security/dast/checks/798.16.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Bittrex Secret Key diff --git a/doc/user/application_security/dast/checks/798.17.md b/doc/user/application_security/dast/checks/798.17.md index 9e11af3bfe8..a020c55d2be 100644 --- a/doc/user/application_security/dast/checks/798.17.md +++ b/doc/user/application_security/dast/checks/798.17.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Beamer API token diff --git a/doc/user/application_security/dast/checks/798.18.md b/doc/user/application_security/dast/checks/798.18.md index 71caa0a53ba..16b7e384462 100644 --- a/doc/user/application_security/dast/checks/798.18.md +++ b/doc/user/application_security/dast/checks/798.18.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Codecov Access Token diff --git a/doc/user/application_security/dast/checks/798.19.md b/doc/user/application_security/dast/checks/798.19.md index 6cfbab0e9d1..6ec04f2a011 100644 --- a/doc/user/application_security/dast/checks/798.19.md +++ b/doc/user/application_security/dast/checks/798.19.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Coinbase Access Token diff --git a/doc/user/application_security/dast/checks/798.2.md b/doc/user/application_security/dast/checks/798.2.md index 766f4c75973..18fe524cb08 100644 --- a/doc/user/application_security/dast/checks/798.2.md +++ b/doc/user/application_security/dast/checks/798.2.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Adobe Client ID (OAuth Web) diff --git a/doc/user/application_security/dast/checks/798.20.md b/doc/user/application_security/dast/checks/798.20.md index 83651142912..22d750dfdfb 100644 --- a/doc/user/application_security/dast/checks/798.20.md +++ b/doc/user/application_security/dast/checks/798.20.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Clojars API token diff --git a/doc/user/application_security/dast/checks/798.21.md b/doc/user/application_security/dast/checks/798.21.md index 93bf588c84b..e38a540a253 100644 --- a/doc/user/application_security/dast/checks/798.21.md +++ b/doc/user/application_security/dast/checks/798.21.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Confluent Access Token diff --git a/doc/user/application_security/dast/checks/798.22.md b/doc/user/application_security/dast/checks/798.22.md index 7a8abbce7ba..55d39c47428 100644 --- a/doc/user/application_security/dast/checks/798.22.md +++ b/doc/user/application_security/dast/checks/798.22.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Confluent Secret Key diff --git a/doc/user/application_security/dast/checks/798.23.md b/doc/user/application_security/dast/checks/798.23.md index f5460e98079..967e41d656d 100644 --- a/doc/user/application_security/dast/checks/798.23.md +++ b/doc/user/application_security/dast/checks/798.23.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Contentful delivery API token diff --git a/doc/user/application_security/dast/checks/798.24.md b/doc/user/application_security/dast/checks/798.24.md index 7a01197a6b8..65db9b1f5d7 100644 --- a/doc/user/application_security/dast/checks/798.24.md +++ b/doc/user/application_security/dast/checks/798.24.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Databricks API token diff --git a/doc/user/application_security/dast/checks/798.25.md b/doc/user/application_security/dast/checks/798.25.md index c5dcee20f61..db7a22c31e2 100644 --- a/doc/user/application_security/dast/checks/798.25.md +++ b/doc/user/application_security/dast/checks/798.25.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Datadog Access Token diff --git a/doc/user/application_security/dast/checks/798.26.md b/doc/user/application_security/dast/checks/798.26.md index bfa5cb0588e..989a9787c04 100644 --- a/doc/user/application_security/dast/checks/798.26.md +++ b/doc/user/application_security/dast/checks/798.26.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Discord API key diff --git a/doc/user/application_security/dast/checks/798.27.md b/doc/user/application_security/dast/checks/798.27.md index 1210d91e741..f17f6bf1c56 100644 --- a/doc/user/application_security/dast/checks/798.27.md +++ b/doc/user/application_security/dast/checks/798.27.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Discord client ID diff --git a/doc/user/application_security/dast/checks/798.28.md b/doc/user/application_security/dast/checks/798.28.md index 5f4718d8eb7..6d063c39d2b 100644 --- a/doc/user/application_security/dast/checks/798.28.md +++ b/doc/user/application_security/dast/checks/798.28.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Discord client secret diff --git a/doc/user/application_security/dast/checks/798.29.md b/doc/user/application_security/dast/checks/798.29.md index 90371a157a0..5c082b2aac0 100644 --- a/doc/user/application_security/dast/checks/798.29.md +++ b/doc/user/application_security/dast/checks/798.29.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Doppler API token diff --git a/doc/user/application_security/dast/checks/798.3.md b/doc/user/application_security/dast/checks/798.3.md index 43d69b77337..e6cfb13d114 100644 --- a/doc/user/application_security/dast/checks/798.3.md +++ b/doc/user/application_security/dast/checks/798.3.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Adobe Client Secret diff --git a/doc/user/application_security/dast/checks/798.30.md b/doc/user/application_security/dast/checks/798.30.md index db62b30b84b..618d2cdafdd 100644 --- a/doc/user/application_security/dast/checks/798.30.md +++ b/doc/user/application_security/dast/checks/798.30.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Dropbox API secret diff --git a/doc/user/application_security/dast/checks/798.31.md b/doc/user/application_security/dast/checks/798.31.md index 8f03ba780e4..d35e9c91f0f 100644 --- a/doc/user/application_security/dast/checks/798.31.md +++ b/doc/user/application_security/dast/checks/798.31.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Dropbox long lived API token diff --git a/doc/user/application_security/dast/checks/798.32.md b/doc/user/application_security/dast/checks/798.32.md index d2ed4af9177..30e38c36959 100644 --- a/doc/user/application_security/dast/checks/798.32.md +++ b/doc/user/application_security/dast/checks/798.32.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Dropbox short lived API token diff --git a/doc/user/application_security/dast/checks/798.33.md b/doc/user/application_security/dast/checks/798.33.md index 5a264cf4286..536faefdb51 100644 --- a/doc/user/application_security/dast/checks/798.33.md +++ b/doc/user/application_security/dast/checks/798.33.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Droneci Access Token diff --git a/doc/user/application_security/dast/checks/798.34.md b/doc/user/application_security/dast/checks/798.34.md index a9b02b75230..5323a026257 100644 --- a/doc/user/application_security/dast/checks/798.34.md +++ b/doc/user/application_security/dast/checks/798.34.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Duffel API token diff --git a/doc/user/application_security/dast/checks/798.35.md b/doc/user/application_security/dast/checks/798.35.md index 5d35baec9bb..16aa601674e 100644 --- a/doc/user/application_security/dast/checks/798.35.md +++ b/doc/user/application_security/dast/checks/798.35.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Dynatrace API token diff --git a/doc/user/application_security/dast/checks/798.36.md b/doc/user/application_security/dast/checks/798.36.md index e2e0f10f842..24827bc66fa 100644 --- a/doc/user/application_security/dast/checks/798.36.md +++ b/doc/user/application_security/dast/checks/798.36.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token EasyPost API token diff --git a/doc/user/application_security/dast/checks/798.37.md b/doc/user/application_security/dast/checks/798.37.md index 089dc8b3ecc..4f3ca41e0ea 100644 --- a/doc/user/application_security/dast/checks/798.37.md +++ b/doc/user/application_security/dast/checks/798.37.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token EasyPost test API token diff --git a/doc/user/application_security/dast/checks/798.38.md b/doc/user/application_security/dast/checks/798.38.md index 886cfcc701b..b8a6ea5b237 100644 --- a/doc/user/application_security/dast/checks/798.38.md +++ b/doc/user/application_security/dast/checks/798.38.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Etsy Access Token diff --git a/doc/user/application_security/dast/checks/798.39.md b/doc/user/application_security/dast/checks/798.39.md index 78a66d15b89..1cad4237cfe 100644 --- a/doc/user/application_security/dast/checks/798.39.md +++ b/doc/user/application_security/dast/checks/798.39.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Facebook diff --git a/doc/user/application_security/dast/checks/798.4.md b/doc/user/application_security/dast/checks/798.4.md index 2ff5db46d83..30e0c34c960 100644 --- a/doc/user/application_security/dast/checks/798.4.md +++ b/doc/user/application_security/dast/checks/798.4.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Age secret key diff --git a/doc/user/application_security/dast/checks/798.40.md b/doc/user/application_security/dast/checks/798.40.md index e6691bb7b3a..7ea8df02055 100644 --- a/doc/user/application_security/dast/checks/798.40.md +++ b/doc/user/application_security/dast/checks/798.40.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Fastly API key diff --git a/doc/user/application_security/dast/checks/798.41.md b/doc/user/application_security/dast/checks/798.41.md index b4d097a9014..8e5eb3e8f43 100644 --- a/doc/user/application_security/dast/checks/798.41.md +++ b/doc/user/application_security/dast/checks/798.41.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Finicity Client Secret diff --git a/doc/user/application_security/dast/checks/798.42.md b/doc/user/application_security/dast/checks/798.42.md index 30c380d13a5..5ff876021ef 100644 --- a/doc/user/application_security/dast/checks/798.42.md +++ b/doc/user/application_security/dast/checks/798.42.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Finicity API token diff --git a/doc/user/application_security/dast/checks/798.43.md b/doc/user/application_security/dast/checks/798.43.md index be984f7119a..44a8e5d44b1 100644 --- a/doc/user/application_security/dast/checks/798.43.md +++ b/doc/user/application_security/dast/checks/798.43.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Flickr Access Token diff --git a/doc/user/application_security/dast/checks/798.44.md b/doc/user/application_security/dast/checks/798.44.md index 183cb49b2e7..5cebcb5c93d 100644 --- a/doc/user/application_security/dast/checks/798.44.md +++ b/doc/user/application_security/dast/checks/798.44.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Finnhub Access Token diff --git a/doc/user/application_security/dast/checks/798.46.md b/doc/user/application_security/dast/checks/798.46.md index 5bf658ff610..c71eacbee34 100644 --- a/doc/user/application_security/dast/checks/798.46.md +++ b/doc/user/application_security/dast/checks/798.46.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Flutterwave Secret Key diff --git a/doc/user/application_security/dast/checks/798.47.md b/doc/user/application_security/dast/checks/798.47.md index a6c7b974b7f..24cf3a02121 100644 --- a/doc/user/application_security/dast/checks/798.47.md +++ b/doc/user/application_security/dast/checks/798.47.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Flutterwave Encryption Key diff --git a/doc/user/application_security/dast/checks/798.48.md b/doc/user/application_security/dast/checks/798.48.md index 523232cb00c..f8778c2b0ba 100644 --- a/doc/user/application_security/dast/checks/798.48.md +++ b/doc/user/application_security/dast/checks/798.48.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Frame.io API token diff --git a/doc/user/application_security/dast/checks/798.49.md b/doc/user/application_security/dast/checks/798.49.md index ab7f39c2376..7ea3a65fbfa 100644 --- a/doc/user/application_security/dast/checks/798.49.md +++ b/doc/user/application_security/dast/checks/798.49.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Freshbooks Access Token diff --git a/doc/user/application_security/dast/checks/798.5.md b/doc/user/application_security/dast/checks/798.5.md index 6d55dcf54df..03afbecb820 100644 --- a/doc/user/application_security/dast/checks/798.5.md +++ b/doc/user/application_security/dast/checks/798.5.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Airtable API Key diff --git a/doc/user/application_security/dast/checks/798.50.md b/doc/user/application_security/dast/checks/798.50.md index f0d864db119..0542a00ff71 100644 --- a/doc/user/application_security/dast/checks/798.50.md +++ b/doc/user/application_security/dast/checks/798.50.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token GoCardless API token diff --git a/doc/user/application_security/dast/checks/798.52.md b/doc/user/application_security/dast/checks/798.52.md index 0c4ea4a540b..78864a51172 100644 --- a/doc/user/application_security/dast/checks/798.52.md +++ b/doc/user/application_security/dast/checks/798.52.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token GitHub Personal Access Token diff --git a/doc/user/application_security/dast/checks/798.53.md b/doc/user/application_security/dast/checks/798.53.md index 62a548be627..37ef66ec726 100644 --- a/doc/user/application_security/dast/checks/798.53.md +++ b/doc/user/application_security/dast/checks/798.53.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token GitHub OAuth Access Token diff --git a/doc/user/application_security/dast/checks/798.54.md b/doc/user/application_security/dast/checks/798.54.md index d29677899a5..bf8ab699f9d 100644 --- a/doc/user/application_security/dast/checks/798.54.md +++ b/doc/user/application_security/dast/checks/798.54.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token GitHub App Token diff --git a/doc/user/application_security/dast/checks/798.55.md b/doc/user/application_security/dast/checks/798.55.md index 4c3bd9147c0..0e7528ba008 100644 --- a/doc/user/application_security/dast/checks/798.55.md +++ b/doc/user/application_security/dast/checks/798.55.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token GitHub Refresh Token diff --git a/doc/user/application_security/dast/checks/798.56.md b/doc/user/application_security/dast/checks/798.56.md index 563ea1f91a8..6c9e4bbfd9a 100644 --- a/doc/user/application_security/dast/checks/798.56.md +++ b/doc/user/application_security/dast/checks/798.56.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token GitLab Personal Access Token diff --git a/doc/user/application_security/dast/checks/798.57.md b/doc/user/application_security/dast/checks/798.57.md index 25b32953ebd..d0c700c8662 100644 --- a/doc/user/application_security/dast/checks/798.57.md +++ b/doc/user/application_security/dast/checks/798.57.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Gitter Access Token diff --git a/doc/user/application_security/dast/checks/798.58.md b/doc/user/application_security/dast/checks/798.58.md index 056bcb0820a..86396d00ba1 100644 --- a/doc/user/application_security/dast/checks/798.58.md +++ b/doc/user/application_security/dast/checks/798.58.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token HashiCorp Terraform user/org API token diff --git a/doc/user/application_security/dast/checks/798.59.md b/doc/user/application_security/dast/checks/798.59.md index b7e6b4fa32b..471ece22913 100644 --- a/doc/user/application_security/dast/checks/798.59.md +++ b/doc/user/application_security/dast/checks/798.59.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Heroku API Key diff --git a/doc/user/application_security/dast/checks/798.6.md b/doc/user/application_security/dast/checks/798.6.md index ce6ee95bede..cfdfa706c15 100644 --- a/doc/user/application_security/dast/checks/798.6.md +++ b/doc/user/application_security/dast/checks/798.6.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Algolia API Key diff --git a/doc/user/application_security/dast/checks/798.60.md b/doc/user/application_security/dast/checks/798.60.md index f471411440b..bdfe162e615 100644 --- a/doc/user/application_security/dast/checks/798.60.md +++ b/doc/user/application_security/dast/checks/798.60.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token HubSpot API Token diff --git a/doc/user/application_security/dast/checks/798.61.md b/doc/user/application_security/dast/checks/798.61.md index 061bf8f7360..c359dd9cc90 100644 --- a/doc/user/application_security/dast/checks/798.61.md +++ b/doc/user/application_security/dast/checks/798.61.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Intercom API Token diff --git a/doc/user/application_security/dast/checks/798.62.md b/doc/user/application_security/dast/checks/798.62.md index 9c0f312b161..0d34ab89508 100644 --- a/doc/user/application_security/dast/checks/798.62.md +++ b/doc/user/application_security/dast/checks/798.62.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Kraken Access Token diff --git a/doc/user/application_security/dast/checks/798.63.md b/doc/user/application_security/dast/checks/798.63.md index 51668619025..e065750150d 100644 --- a/doc/user/application_security/dast/checks/798.63.md +++ b/doc/user/application_security/dast/checks/798.63.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Kucoin Access Token diff --git a/doc/user/application_security/dast/checks/798.64.md b/doc/user/application_security/dast/checks/798.64.md index 12d20f96a42..12cd11d8d79 100644 --- a/doc/user/application_security/dast/checks/798.64.md +++ b/doc/user/application_security/dast/checks/798.64.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Kucoin Secret Key diff --git a/doc/user/application_security/dast/checks/798.65.md b/doc/user/application_security/dast/checks/798.65.md index eb1dac62037..f2ebfb988b2 100644 --- a/doc/user/application_security/dast/checks/798.65.md +++ b/doc/user/application_security/dast/checks/798.65.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Launchdarkly Access Token diff --git a/doc/user/application_security/dast/checks/798.66.md b/doc/user/application_security/dast/checks/798.66.md index 8f20f9fa339..c83eaba8d29 100644 --- a/doc/user/application_security/dast/checks/798.66.md +++ b/doc/user/application_security/dast/checks/798.66.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Linear API Token diff --git a/doc/user/application_security/dast/checks/798.67.md b/doc/user/application_security/dast/checks/798.67.md index 7554c077376..8b39f42d090 100644 --- a/doc/user/application_security/dast/checks/798.67.md +++ b/doc/user/application_security/dast/checks/798.67.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Linear Client Secret diff --git a/doc/user/application_security/dast/checks/798.68.md b/doc/user/application_security/dast/checks/798.68.md index c633b949185..54a2e418cd2 100644 --- a/doc/user/application_security/dast/checks/798.68.md +++ b/doc/user/application_security/dast/checks/798.68.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token LinkedIn Client ID diff --git a/doc/user/application_security/dast/checks/798.69.md b/doc/user/application_security/dast/checks/798.69.md index b34c2f01be6..0a341f494fc 100644 --- a/doc/user/application_security/dast/checks/798.69.md +++ b/doc/user/application_security/dast/checks/798.69.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token LinkedIn Client secret diff --git a/doc/user/application_security/dast/checks/798.7.md b/doc/user/application_security/dast/checks/798.7.md index 43aba566471..2989c68a311 100644 --- a/doc/user/application_security/dast/checks/798.7.md +++ b/doc/user/application_security/dast/checks/798.7.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Alibaba AccessKey ID diff --git a/doc/user/application_security/dast/checks/798.70.md b/doc/user/application_security/dast/checks/798.70.md index b7c1816481b..cfd1660bd7f 100644 --- a/doc/user/application_security/dast/checks/798.70.md +++ b/doc/user/application_security/dast/checks/798.70.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Lob API Key diff --git a/doc/user/application_security/dast/checks/798.72.md b/doc/user/application_security/dast/checks/798.72.md index 48b2cffbbda..c89fb2bf8c6 100644 --- a/doc/user/application_security/dast/checks/798.72.md +++ b/doc/user/application_security/dast/checks/798.72.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Mailchimp API key diff --git a/doc/user/application_security/dast/checks/798.74.md b/doc/user/application_security/dast/checks/798.74.md index 9a4b909bf4b..94d17b2c1be 100644 --- a/doc/user/application_security/dast/checks/798.74.md +++ b/doc/user/application_security/dast/checks/798.74.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Mailgun private API token diff --git a/doc/user/application_security/dast/checks/798.75.md b/doc/user/application_security/dast/checks/798.75.md index 4c1cfd78003..e2a764bf826 100644 --- a/doc/user/application_security/dast/checks/798.75.md +++ b/doc/user/application_security/dast/checks/798.75.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Mailgun webhook signing key diff --git a/doc/user/application_security/dast/checks/798.77.md b/doc/user/application_security/dast/checks/798.77.md index 7b1becf4c19..f79b6645b26 100644 --- a/doc/user/application_security/dast/checks/798.77.md +++ b/doc/user/application_security/dast/checks/798.77.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Mattermost Access Token diff --git a/doc/user/application_security/dast/checks/798.78.md b/doc/user/application_security/dast/checks/798.78.md index 8d366d44c9d..b2c73b54562 100644 --- a/doc/user/application_security/dast/checks/798.78.md +++ b/doc/user/application_security/dast/checks/798.78.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token MessageBird API token diff --git a/doc/user/application_security/dast/checks/798.8.md b/doc/user/application_security/dast/checks/798.8.md index e6dfe1aa1cc..3b99bae1f4e 100644 --- a/doc/user/application_security/dast/checks/798.8.md +++ b/doc/user/application_security/dast/checks/798.8.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Alibaba Secret Key diff --git a/doc/user/application_security/dast/checks/798.80.md b/doc/user/application_security/dast/checks/798.80.md index c0a893264b0..9a18a21d5d1 100644 --- a/doc/user/application_security/dast/checks/798.80.md +++ b/doc/user/application_security/dast/checks/798.80.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Netlify Access Token diff --git a/doc/user/application_security/dast/checks/798.81.md b/doc/user/application_security/dast/checks/798.81.md index abf40705e7f..fef989c0bbf 100644 --- a/doc/user/application_security/dast/checks/798.81.md +++ b/doc/user/application_security/dast/checks/798.81.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token New Relic user API Key diff --git a/doc/user/application_security/dast/checks/798.82.md b/doc/user/application_security/dast/checks/798.82.md index 519555546b6..23ebba1641e 100644 --- a/doc/user/application_security/dast/checks/798.82.md +++ b/doc/user/application_security/dast/checks/798.82.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token New Relic user API ID diff --git a/doc/user/application_security/dast/checks/798.83.md b/doc/user/application_security/dast/checks/798.83.md index 85bdd534390..3f36e78cfda 100644 --- a/doc/user/application_security/dast/checks/798.83.md +++ b/doc/user/application_security/dast/checks/798.83.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token New Relic ingest browser API token diff --git a/doc/user/application_security/dast/checks/798.84.md b/doc/user/application_security/dast/checks/798.84.md index 74ebb4fcaf1..69f4c1249b4 100644 --- a/doc/user/application_security/dast/checks/798.84.md +++ b/doc/user/application_security/dast/checks/798.84.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token npm access token diff --git a/doc/user/application_security/dast/checks/798.86.md b/doc/user/application_security/dast/checks/798.86.md index 940a46b7658..700ed99ebc5 100644 --- a/doc/user/application_security/dast/checks/798.86.md +++ b/doc/user/application_security/dast/checks/798.86.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Okta Access Token diff --git a/doc/user/application_security/dast/checks/798.87.md b/doc/user/application_security/dast/checks/798.87.md index 8246bafc993..3fb1fe4a857 100644 --- a/doc/user/application_security/dast/checks/798.87.md +++ b/doc/user/application_security/dast/checks/798.87.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Plaid Client ID diff --git a/doc/user/application_security/dast/checks/798.88.md b/doc/user/application_security/dast/checks/798.88.md index 57b029857ba..6d143dce5fa 100644 --- a/doc/user/application_security/dast/checks/798.88.md +++ b/doc/user/application_security/dast/checks/798.88.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Plaid Secret key diff --git a/doc/user/application_security/dast/checks/798.89.md b/doc/user/application_security/dast/checks/798.89.md index 466044834dd..123f2730b30 100644 --- a/doc/user/application_security/dast/checks/798.89.md +++ b/doc/user/application_security/dast/checks/798.89.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Plaid API Token diff --git a/doc/user/application_security/dast/checks/798.9.md b/doc/user/application_security/dast/checks/798.9.md index 12c725cfd08..a86f8241bf7 100644 --- a/doc/user/application_security/dast/checks/798.9.md +++ b/doc/user/application_security/dast/checks/798.9.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Asana Client ID diff --git a/doc/user/application_security/dast/checks/798.90.md b/doc/user/application_security/dast/checks/798.90.md index e0008af4918..884fca83dd3 100644 --- a/doc/user/application_security/dast/checks/798.90.md +++ b/doc/user/application_security/dast/checks/798.90.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token PlanetScale password diff --git a/doc/user/application_security/dast/checks/798.91.md b/doc/user/application_security/dast/checks/798.91.md index be54e99360f..bfccaf3262d 100644 --- a/doc/user/application_security/dast/checks/798.91.md +++ b/doc/user/application_security/dast/checks/798.91.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token PlanetScale API token diff --git a/doc/user/application_security/dast/checks/798.92.md b/doc/user/application_security/dast/checks/798.92.md index 07ae24151f5..ceec84a3fe8 100644 --- a/doc/user/application_security/dast/checks/798.92.md +++ b/doc/user/application_security/dast/checks/798.92.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token PlanetScale OAuth token diff --git a/doc/user/application_security/dast/checks/798.93.md b/doc/user/application_security/dast/checks/798.93.md index 661f460bf27..1d67a889d1a 100644 --- a/doc/user/application_security/dast/checks/798.93.md +++ b/doc/user/application_security/dast/checks/798.93.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Postman API token diff --git a/doc/user/application_security/dast/checks/798.94.md b/doc/user/application_security/dast/checks/798.94.md index 4aeb15fee23..aedeabce11c 100644 --- a/doc/user/application_security/dast/checks/798.94.md +++ b/doc/user/application_security/dast/checks/798.94.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Private Key diff --git a/doc/user/application_security/dast/checks/798.95.md b/doc/user/application_security/dast/checks/798.95.md index 13374aa67e0..fa34f58a48e 100644 --- a/doc/user/application_security/dast/checks/798.95.md +++ b/doc/user/application_security/dast/checks/798.95.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Pulumi API token diff --git a/doc/user/application_security/dast/checks/798.96.md b/doc/user/application_security/dast/checks/798.96.md index cb61bd38950..de93a54ec63 100644 --- a/doc/user/application_security/dast/checks/798.96.md +++ b/doc/user/application_security/dast/checks/798.96.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token PyPI upload token diff --git a/doc/user/application_security/dast/checks/798.97.md b/doc/user/application_security/dast/checks/798.97.md index 93f03a692d7..d3035b05bbb 100644 --- a/doc/user/application_security/dast/checks/798.97.md +++ b/doc/user/application_security/dast/checks/798.97.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Rubygem API token diff --git a/doc/user/application_security/dast/checks/798.98.md b/doc/user/application_security/dast/checks/798.98.md index aab4cb9c5ed..08460c09520 100644 --- a/doc/user/application_security/dast/checks/798.98.md +++ b/doc/user/application_security/dast/checks/798.98.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token RapidAPI Access Token diff --git a/doc/user/application_security/dast/checks/798.99.md b/doc/user/application_security/dast/checks/798.99.md index 90c8aeda7ab..b43bf291cc0 100644 --- a/doc/user/application_security/dast/checks/798.99.md +++ b/doc/user/application_security/dast/checks/798.99.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exposure of confidential secret or token Sendbird Access ID diff --git a/doc/user/application_security/dast/checks/829.1.md b/doc/user/application_security/dast/checks/829.1.md index ca3d99c2bc9..f18634b72d9 100644 --- a/doc/user/application_security/dast/checks/829.1.md +++ b/doc/user/application_security/dast/checks/829.1.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Inclusion of Functionality from Untrusted Control Sphere diff --git a/doc/user/application_security/dast/checks/829.2.md b/doc/user/application_security/dast/checks/829.2.md index e6fada117f8..19490afe676 100644 --- a/doc/user/application_security/dast/checks/829.2.md +++ b/doc/user/application_security/dast/checks/829.2.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Invalid Sub-Resource Integrity values detected diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 387682318e6..9466734f9cf 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DAST browser-based crawler vulnerability checks **(ULTIMATE)** diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 4e87f1898cc..194761797de 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 0f446ddee3e..6d1b7beefc7 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -71,7 +71,7 @@ on how to configure Review Apps for DAST. #### Docker Services -If your application utilizes Docker containers you have another option for deploying and scanning with DAST. +If your application uses Docker containers you have another option for deploying and scanning with DAST. After your Docker build job completes and your image is added to your container registry, you can use the image as a [service](../../../ci/services/index.md). @@ -480,7 +480,7 @@ When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: - `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either use `DAST_WEBSITE` to build the URLs to scan - Spidering is disabled when `DAST_PATHS` or `DAST_PATHS_FILE` are defined -- `DAST_PATHS_FILE` and `DAST_PATHS` can not be used together +- `DAST_PATHS_FILE` and `DAST_PATHS` cannot be used together - The `DAST_PATHS` variable has a limit of about 130kb. If you have a list or paths greater than this, use `DAST_PATHS_FILE`. @@ -637,11 +637,11 @@ including a large number of false positives. | `DAST_AUTH_VERIFICATION_SELECTOR` <sup>2</sup> | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo`. | | `DAST_AUTH_VERIFICATION_URL` <sup>1,2</sup> | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. Example: `"http://example.com/loggedin_page"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | -| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that are clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | +| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that are selected prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | | `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | -| `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when selected submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | | `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | @@ -660,7 +660,7 @@ including a large number of false positives. | `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | | `DAST_SPIDER_MINS` <sup>1</sup> | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | -| `DAST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. For example, `css:button[type='submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when selected submits the login form or the password form of a multi-page login process. For example, `css:button[type='submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. | | `DAST_USE_AJAX_SPIDER` <sup>1</sup> | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_USERNAME` <sup>1,2</sup> | string | The username to authenticate to in the website. Example: `admin` | @@ -744,6 +744,17 @@ scan is run, it may perform *any* function that the authenticated user can. This includes actions like modifying and deleting data, submitting forms, and following links. Only run an authenticated scan against a test server. +### SSO + +DAST can authenticate to websites making use of SSO, with the following restrictions: + +- DAST cannot bypass a CAPTCHA if the authentication flow includes one. +- DAST cannot handle multi-factor authentication like one-time passwords (OTP) by using SMS or authenticator apps. +- DAST must get a cookie, or a local or session storage, with a sufficiently random value. + +The [authentication debug output](index.md#configure-the-authentication-debug-output) can be helpful for troubleshooting SSO authentication +with DAST. + ### Log in using automatic detection of the login form By providing a `DAST_USERNAME`, `DAST_PASSWORD`, and `DAST_AUTH_URL`, DAST attempts to authenticate to the @@ -754,10 +765,10 @@ Automatic detection is "best-effort", and depending on the application being sca Login process: 1. The `DAST_AUTH_URL` is loaded into the browser, and any forms on the page are located. - 1. If a form contains a username and password field, `DAST_USERNAME` and `DAST_PASSWORD` is inputted into the respective fields, the form submit button is clicked and the user is logged in. + 1. If a form contains a username and password field, `DAST_USERNAME` and `DAST_PASSWORD` is inputted into the respective fields, the form submit button is selected and the user is logged in. 1. If a form contains only a username field, it is assumed that the login form is multi-step. - 1. The `DAST_USERNAME` is inputted into the username field and the form submit button is clicked. - 1. The subsequent pages loads where it is expected that a form exists and contains a password field. If found, `DAST_PASSWORD` is inputted, form submit button is clicked and the user is logged in. + 1. The `DAST_USERNAME` is inputted into the username field and the form submit button is selected. + 1. The subsequent pages loads where it is expected that a form exists and contains a password field. If found, `DAST_PASSWORD` is inputted, form submit button is selected and the user is logged in. ### Log in using explicit selection of the login form @@ -768,10 +779,10 @@ Most applications benefit from this approach to authentication. Login process: 1. The `DAST_AUTH_URL` is loaded into the browser, and any forms on the page are located. - 1. If the `DAST_FIRST_SUBMIT_FIELD` is not defined, then `DAST_USERNAME` is inputted into `DAST_USERNAME_FIELD`, `DAST_PASSWORD` is inputted into `DAST_PASSWORD_FIELD`, `DAST_SUBMIT_FIELD` is clicked and the user is logged in. + 1. If the `DAST_FIRST_SUBMIT_FIELD` is not defined, then `DAST_USERNAME` is inputted into `DAST_USERNAME_FIELD`, `DAST_PASSWORD` is inputted into `DAST_PASSWORD_FIELD`, `DAST_SUBMIT_FIELD` is selected and the user is logged in. 1. If the `DAST_FIRST_SUBMIT_FIELD` is defined, then it is assumed that the login form is multi-step. - 1. The `DAST_USERNAME` is inputted into the `DAST_USERNAME_FIELD` field and the `DAST_FIRST_SUBMIT_FIELD` is clicked. - 1. The subsequent pages loads where the `DAST_PASSWORD` is inputted into the `DAST_PASSWORD_FIELD` field, the `DAST_SUBMIT_FIELD` is clicked and the user is logged in. + 1. The `DAST_USERNAME` is inputted into the `DAST_USERNAME_FIELD` field and the `DAST_FIRST_SUBMIT_FIELD` is selected. + 1. The subsequent pages loads where the `DAST_PASSWORD` is inputted into the `DAST_PASSWORD_FIELD` field, the `DAST_SUBMIT_FIELD` is selected and the user is logged in. ### Verifying successful login @@ -1159,7 +1170,7 @@ A site profile contains: - **Password**: The password used to authenticate to the website. - **Username form field**: The name of username field at the sign-in HTML form. - **Password form field**: The name of password field at the sign-in HTML form. - - **Submit form field**: The `id` or `name` of the element that when clicked submits the sign-in HTML form. + - **Submit form field**: The `id` or `name` of the element that when selected submits the sign-in HTML form. When an API site type is selected, a [host override](#host-override) is used to ensure the API being scanned is on the same host as the target. This is done to reduce the risk of running an active scan against the wrong API. diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index 63163167a6c..05c6b74fbcd 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index f15dce37123..eae32f789b8 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -1039,6 +1039,7 @@ can be added, removed, and modified by creating a custom configuration. | `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | | `DAST_API_VERSION` | Specify DAST API container version. Defaults to `2`. | | `DAST_API_IMAGE_SUFFIX` | Specify a container image suffix. Defaults to none. | +| `DAST_API_API_PORT` | Specify the communication port number used by DAST API engine. Defaults to `5500`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367734) in GitLab 15.5. | | `DAST_API_TARGET_URL` | Base URL of API testing target. | |[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | @@ -1333,13 +1334,13 @@ variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.8. -By default the output of the overrides command is hidden. If the overrides command returns a non zero exit code, the command is displayed as part of your job output. Optionally, you can set the variable `DAST_API_OVERRIDES_CMD_VERBOSE` to any value in order to display overrides command output as it is generated. This is useful when testing your overrides script, but should be disabled afterwards as it slows down testing. +By default the output of the overrides command is hidden. If the overrides command returns a non zero exit code, the command is displayed as part of your job output. Optionally, you can set the variable `DAST_API_OVERRIDES_CMD_VERBOSE` to any value to display overrides command output as it is generated. This is useful when testing your overrides script, but should be disabled afterwards as it slows down testing. It is also possible to write messages from your script to a log file that is collected when the job completes or fails. The log file must be created in a specific location and following a naming convention. Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during normal running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. -Following our example, we provided `renew_token.py` in the environment variable `DAST_API_OVERRIDES_CMD`. Please notice two things in the script: +Following our example, we provided `renew_token.py` in the environment variable `DAST_API_OVERRIDES_CMD`. Notice two things in the script: - Log file is saved in the location indicated by the environmental variable `CI_PROJECT_DIR`. - Log filename should match `gl-*.log`. @@ -2064,7 +2065,7 @@ A bug exists in versions of the DAST API analyzer prior to v1.6.196 that can cau The version information can be found in the job details for the `dast_api` job. -If the issue is occurring with versions v1.6.196 or greater, please contact Support and provide the following information: +If the issue is occurring with versions v1.6.196 or greater, contact Support and provide the following information: 1. Reference this troubleshooting section and ask for the issue to be escalated to the Dynamic Analysis Team. 1. The full console output of the job. @@ -2085,13 +2086,50 @@ The DAST API engine outputs an error message when it cannot establish a connecti - Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the DAST API CI/CD template. We recommend this method instead of manually setting a value. - If removing the variable is not possible, check to see if this value has changed in the latest version of the [DAST API CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. +### `Failed to start session with scanner. Please retry, and if the problem persists reach out to support.` + +The DAST API engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `dast_api` job. A common cause for this issue is that the background component cannot use the selected port as it's already in use. This error can occur intermittently if timing plays a part (race condition). This issue occurs most often with Kubernetes environments when other services are mapped into the container causing port conflicts. + +Before proceeding with a solution, it is important to confirm that the error message was produced because the port was already taken. To confirm this was the cause: + +1. Go to the job console. + +1. Look for the artifact `gl-api-security-scanner.log`. You can either download all artifacts by selecting **Download** and then search for the file, or directly start searching by selecting **Browse**. + +1. Open the file `gl-api-security-scanner.log` in a text editor. + +1. If the error message was produced because the port was already taken, you should see in the file a message like the following: + +- In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/367734): + + ```log + Failed to bind to address http://127.0.0.1:5500: address already in use. + ``` + +- In GitLab 15.4 and earlier: + + ```log + Failed to bind to address http://[::]:5000: address already in use. + ``` + +The text `http://[::]:5000` in the previous message could be different in your case, for instance it could be `http://[::]:5500` or `http://127.0.0.1:5500`. As long as the remaining parts of the error message are the same, it is safe to assume the port was already taken. + +If you did not find evidence that the port was already taken, check other troubleshooting sections which also address the same error message shown in the job console output. If there are no more options, feel free to [get support or request an improvement](#get-support-or-request-an-improvement) through the proper channels. + +Once you have confirmed the issue was produced because the port was already taken. Then, [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/367734) introduced the configuration variable `DAST_API_API_PORT`. This configuration variable allows setting a fixed port number for the scanner background component. + +**Solution** + +1. Ensure your `.gitlab-ci.yml` file defines the configuration variable `DAST_API_API_PORT`. +1. Update the value of `DAST_API_API_PORT` to any available port number greater than 1024. We recommend checking that the new value is not in used by GitLab. See the full list of ports used by GitLab in [Package defaults](../../../administration/package_information/defaults.md#ports) + ### `Application cannot determine the base URL for the target API` The DAST API engine outputs an error message when it cannot determine the target API after inspecting the OpenAPI document. This error message is shown when the target API has not been set in the `.gitlab-ci.yml` file, it is not available in the `environment_url.txt` file, and it could not be computed using the OpenAPI document. There is a order of precedence in which the DAST API engine tries to get the target API when checking the different sources. First, it will try to use the `DAST_API_TARGET_URL`. If the environment variable has not been set, then the DAST API engine will attempt to use the `environment_url.txt` file. If there is no file `environment_url.txt`, then the DAST API engine will use the OpenAPI document contents and the URL provided in `DAST_API_OPENAPI` (if a URL is provided) to try to compute the target API. -The best-suited solution will depend on whether or not your target API changes for each deployment. In static environments, the target API is the same for each deployment, in this case please refer to the [static environment solution](#static-environment-solution). If the target API changes for each deployment a [dynamic environment solution](#dynamic-environment-solutions) should be applied. +The best-suited solution will depend on whether or not your target API changes for each deployment. In static environments, the target API is the same for each deployment, in this case refer to the [static environment solution](#static-environment-solution). If the target API changes for each deployment a [dynamic environment solution](#dynamic-environment-solutions) should be applied. #### Static environment solution @@ -2188,10 +2226,10 @@ DAST API uses the specified media types in the OpenAPI document to generate requ ## Get support or request an improvement -To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). +To get support for your particular problem, use the [getting help channels](https://about.gitlab.com/get-help/). The [GitLab issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues) is the right place for bugs and feature proposals about API Security and DAST API. -Please use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Please refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. +Use `~"Category:API Security"` [label](../../../development/contributing/issue_workflow.md#labels) when opening a new issue regarding DAST API to ensure it is quickly reviewed by the right people. Refer to our [review response SLO](https://about.gitlab.com/handbook/engineering/workflow/code-review/#review-response-slo) to understand when you should receive a response. [Search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues) for similar entries before submitting your own, there's a good chance somebody else had the same issue or feature proposal. Show your support with an award emoji and or join the discussion. @@ -2203,7 +2241,7 @@ When experiencing a behavior not working as expected, consider providing context - Scanner log file available as a job artifact named `gl-api-security-scanner.log`. WARNING: -**Sanitize data attached to a support issue**. Please remove sensitive information, including: credentials, passwords, tokens, keys, and secrets. +**Sanitize data attached to a support issue**. Remove sensitive information, including: credentials, passwords, tokens, keys, and secrets. ## Glossary diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 03c97c85dbc..9fffdec2612 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency list **(ULTIMATE)** @@ -48,7 +48,7 @@ can also be sorted by name or by the packager that installed them. ### Vulnerabilities -If a dependency has known vulnerabilities, view them by clicking the arrow next to the +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. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index a59399f7e8d..e4466dffd56 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Scanning Analyzers **(ULTIMATE)** diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 7aabbdd3194..a3c6c46b081 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Scanning **(ULTIMATE)** @@ -48,7 +48,7 @@ possible, we encourage you to use all of our security scanning tools: then performs a build to fetch upstream dependency information. In the case of containers, Dependency Scanning uses the compatible manifest and reports only these declared software dependencies (and those installed as a sub-dependency). - Dependency Scanning can not detect software dependencies that are pre-bundled + Dependency Scanning cannot detect software dependencies that are pre-bundled into the container's base image. To identify pre-bundled dependencies, enable [Container Scanning](../container_scanning/index.md) language scanning using the [`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` variable](../container_scanning/index.md#report-language-specific-findings). @@ -94,7 +94,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae WARNING: Dependency Scanning does not support run-time installation of compilers and interpreters. -If you need it, please explain why by filling out [the survey](https://docs.google.com/forms/d/e/1FAIpQLScKo7xEYA65rOjPTGIufAyfjPGnCALSJZoTxBlvskfFMEOZMw/viewform). +If you need it, explain why by filling out [the survey](https://docs.google.com/forms/d/e/1FAIpQLScKo7xEYA65rOjPTGIufAyfjPGnCALSJZoTxBlvskfFMEOZMw/viewform). ## Supported languages and package managers @@ -187,7 +187,12 @@ table.supported-languages ul { <td>Go</td> <td>All versions</td> <td><a href="https://go.dev/">Go</a></td> - <td><code>go.sum</code></td> + <td> + <ul> + <li><code>go.mod</code></li> + <li><code>go.sum</code></li> + </ul> + </td> <td>Y</td> </tr> <tr> @@ -237,7 +242,7 @@ table.supported-languages ul { <td>.NET</td> <td rowspan="2">All versions</td> <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> - <td rowspan="2"><a href="https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> + <td rowspan="2"><a href="https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> <td rowspan="2">Y</td> </tr> <tr> @@ -297,7 +302,7 @@ table.supported-languages ul { <a id="notes-regarding-supported-languages-and-package-managers-2"></a> <p> Although Gradle with Java 8 is supported, there are other issues such that Android project builds are not supported at this time. - Please see the backlog issue <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336866">Android support for Dependency + See the backlog issue <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336866">Android support for Dependency Scanning (gemnasium-maven)</a> for more details. Also, Gradle is not supported when <a href="https://docs.gitlab.com/ee/development/fips_compliance.html#enable-fips-mode">FIPS mode</a> is enabled. </p> </li> @@ -353,12 +358,24 @@ The following package managers use lockfiles that GitLab analyzers are capable o | 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) | -| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/default/go.sum) | +| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | | NuGet | v1 | [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 | [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) | | yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | | Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v3/qa/fixtures/python-poetry/default/poetry.lock) | +<!-- markdownlint-disable MD044 --> +<ol> + <li> + <a id="notes-regarding-parsing-lockfiles-1"></a> + <p> + Dependency Scanning will only parse <code>go.sum</code> if it's unable to generate the build list + used by the Go project. + </p> + </li> +</ol> +<!-- markdownlint-enable MD044 --> + #### Obtaining dependency information by running a package manager to generate a parsable file To support the following package managers, the GitLab analyzers proceed in two steps: @@ -374,6 +391,7 @@ To support the following package managers, the GitLab analyzers proceed in two s | setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L224-247) | | pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L77-91) | | Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L168-191)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.22.0/spec/image_spec.rb#L143-166) | +| Go | [1.17](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/7dc7a892b564abfcb160189f46b2ae6415e0dffa/build/gemnasium/alpine/Dockerfile#L88-91) | [1.17](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/7dc7a892b564abfcb160189f46b2ae6415e0dffa/build/gemnasium/alpine/Dockerfile#L88-91)<sup><strong><a href="#exported-dependency-information-notes-4">4</a></strong></sup> | <!-- markdownlint-disable MD044 --> <ol> @@ -416,6 +434,13 @@ To support the following package managers, the GitLab analyzers proceed in two s This test confirms that if a <code>Pipfile.lock</code> file is found, it will be used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. </p> </li> + <li> + <a id="exported-dependency-information-notes-4"></a> + <p> + Because of the implementation of <code>go build</code>, the Go build process requires network access, a pre-loaded modcache via <code>go mod download</code>, or vendored dependencies. For more information, + refer to the Go documentation on <a href="https://pkg.go.dev/cmd/go#hdr-Compile_packages_and_dependencies">compiling packages and dependencies</a>. + </p> + </li> </ol> <!-- markdownlint-enable MD044 --> @@ -432,7 +457,7 @@ When a supported dependency file is detected, all dependencies, including transi ### How multiple files are processed NOTE: -If you've run into problems while scanning multiple files, please contribute a comment to +If you've run into problems while scanning multiple files, contribute a comment to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337056). #### Python @@ -474,6 +499,12 @@ The following analyzers are executed, each of which have different behavior when From GitLab 14.8 the `gemnasium` analyzer scans supported JavaScript projects for vendored libraries (that is, those checked into the project but not managed by the package manager). +#### Go + +When scanning a Go project, gemnasium invokes a builder and attempts to generate a [build list](https://go.dev/ref/mod#glos-build-list) using +[Minimal Version Selection](https://go.dev/ref/mod#glos-minimal-version-selection). If a non-fatal error is encountered, the build process signals +that the execution should proceed and falls back to parsing the available `go.sum` file. + #### PHP, Go, C, C++, .NET, C#, Ruby, JavaScript The analyzer for these languages supports multiple lockfiles. @@ -616,11 +647,15 @@ The following variables are used for configuring specific analyzers (used for a | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | | `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. | -| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. **Warning:** Please read [the following security consideration](#python-projects) when using this environment variable. | +| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. **Warning:** Read [the following security consideration](#python-projects) when using this environment variable. | | `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | | `DS_INCLUDE_DEV_DEPENDENCIES` | `gemnasium` | `"true"` | When set to `"false"`, development dependencies and their vulnerabilities are not reported. Only NPM and Poetry projects are supported. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227861) in GitLab 15.1. | +| `GOOS` | `gemnasium` | `"linux"` | The operating system for which to compile Go code. | +| `GOARCH` | `gemnasium` | `"amd64"` | The architecture of the processor for which to compile Go code. | +| `GOFLAGS` | `gemansium` | | The flags passed to the `go build` tool. | +| `GOPRIVATE` | `gemnasium` | | A list of glob patterns and prefixes to be fetched from source. Read the Go private modules [documentation](https://go.dev/ref/mod#private-modules) for more information. | #### Other variables @@ -650,7 +685,7 @@ or [contributing to the code](../../../development/index.md) to enable it to be ### Using a custom SSL CA certificate authority -You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: +You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: ```yaml variables: @@ -895,12 +930,11 @@ include: merge cyclonedx sboms: stage: merge-cyclonedx-sboms - image: alpine:latest + image: + name: cyclonedx/cyclonedx-cli:0.24.0 + entrypoint: [""] script: - - wget https://github.com/CycloneDX/cyclonedx-cli/releases/download/v0.22.0/cyclonedx-linux-musl-x64 -O /usr/local/bin/cyclonedx-cli - - chmod 755 /usr/local/bin/cyclonedx-cli - - apk --update add --no-cache icu-dev libstdc++ - - find * -name "gl-sbom-*.cdx.json" -exec cyclonedx-cli merge --input-files {} --output-file gl-sbom-all.cdx.json + + - find . -name "gl-sbom-*.cdx.json" -exec /cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" + artifacts: paths: - gl-sbom-all.cdx.json @@ -913,7 +947,7 @@ this information is removed from the resulting merged file. ## Versioning and release process -Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). +Check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). ## Contributing to the vulnerability database @@ -957,7 +991,7 @@ registry.gitlab.com/security-products/gemnasium-python:3 ``` The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Please consult your IT staff to find an accepted and approved +**your network security policy**. Consult your IT staff to find an accepted and approved process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) with new definitions, and you may be able to make occasional updates on your own. @@ -1039,7 +1073,7 @@ ensure that it can reach your private repository. Here is an example configurati 1. Fetch the certificate from your repository URL and add it to the project: ```shell - echo -n | openssl s_client -connect pypi.example.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt + printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt ``` 1. Point `setup.py` at the newly downloaded certificate: @@ -1109,6 +1143,13 @@ version number). ## Troubleshooting +### Increase log verbosity + +When a [job log](../../../ci/jobs/index.md#expand-and-collapse-job-log-sections) +doesn't contain enough information about a dependency-scanning failure, +[set `SECURE_LOG_LEVEL` to `debug`](#configuring-dependency-scanning) +and check the resulting, more verbose log. + ### Working around missing support for certain languages or package managers As noted in the ["Supported languages" section](#supported-languages-and-package-managers) @@ -1269,3 +1310,44 @@ gemnasium-python-dependency_scanning: before_script: - apt-get update && apt-get install -y libpq-dev ``` + +### 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, you'll need to 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 will contain 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 index 4d424acf9c3..76d2227b86b 100644 --- a/doc/user/application_security/generate_test_vulnerabilities/index.md +++ b/doc/user/application_security/generate_test_vulnerabilities/index.md @@ -2,27 +2,31 @@ 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Generate test vulnerabilities -You can generate test vulnerabilities when you work on the [Vulnerability Report](../vulnerability_report/index.md). +You can generate test vulnerabilities for the [Vulnerability Report](../vulnerability_report/index.md) to test GitLab +vulnerability management features without running a pipeline. +1. Login in to GitLab. 1. Go to `/-/profile/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. Open a terminal and go to the `gitlab/qa` directory. +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. +1. Run `bundle install` 1. Run the following command: ```shell -GITLAB_QA_ACCESS_TOKEN=<your_personal_access_token> GITLAB_URL="http://localhost:3000" bundle exec rake vulnerabilities:setup\[<your_project_id>,<vulnerability_count>\] --trace +GITLAB_QA_ACCESS_TOKEN=<your_personal_access_token> GITLAB_URL="<address:port>" bundle exec rake vulnerabilities:setup\[<your_project_id>,<vulnerability_count>\] --trace ``` Make sure you do the following: - Replace `<your_personal_access_token>` with the token you generated in step one. -- Double check the `GITLAB_URL`. It should point to the running local instance. -- Replace `<your_project_id>` with the ID you obtained in step two. +- Double check the `GITLAB_URL`. It should point to address and port of your GitLab instance, for example `http://localhost:3000` if you are running GDK +- Replace `<your_project_id>` with the ID you obtained in step three above. - Replace `<vulnerability_count>` with the number of vulnerabilities you'd like to generate. -The script creates the specified amount of vulnerabilities in the project. +The script creates the specified number of placeholder vulnerabilities in the project. diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index ee7864b5ce9..b6213a98f91 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Get started with GitLab application security **(ULTIMATE)** @@ -14,7 +14,7 @@ The following steps will help you get the most from GitLab application security 1. Enable [Secret Detection](secret_detection/index.md) and [Dependency Scanning](dependency_scanning/index.md) to identify any leaked secrets and vulnerable packages in your codebase. - - For all security scanners, enable them by updating your `[.gitlab-ci.yml](../../ci/yaml/gitlab_ci_yaml.md)` directly on your `default` branch. This creates a baseline scan of your `default` branch, which is necessary for + - For all security scanners, enable them by updating your [`.gitlab-ci.yml`](../../ci/yaml/gitlab_ci_yaml.md) directly on your `default` branch. This creates a baseline scan of your `default` branch, which is necessary for feature branch scans to be compared against. This allows [merge requests](../project/merge_requests/index.md) to display only newly-introduced vulnerabilities. Otherwise, merge requests will display every vulnerability in the branch, regardless of whether it was introduced by a change in the branch. @@ -36,7 +36,7 @@ The following steps will help you get the most from GitLab application security remediating existing vulnerabilities and preventing the introduction of new ones. 1. Enable other scan types such as [SAST](sast/index.md), [DAST](dast/index.md), [Fuzz testing](coverage_fuzzing/index.md), or [Container Scanning](container_scanning/index.md). -1. Use [Compliance Pipelines](../../user/project/settings/index.md#compliance-pipeline-configuration) +1. Use [Compliance Pipelines](../group/manage.md#configure-a-compliance-pipeline) or [Scan Execution Policies](policies/scan-execution-policies.md) to enforce required scan types and ensure separation of duties between security and engineering. 1. Consider enabling [Review Apps](../../development/testing_guide/review_apps.md) to allow for DAST diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 1b9cdb11ea3..150c2b732d8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure as Code (IaC) Scanning @@ -43,7 +43,7 @@ GitLab IaC scanning supports a variety of IaC configuration files. Our IaC secur | OpenAPI | [KICS](https://kics.io/) | 14.5 | | Terraform <sup>2</sup> | [KICS](https://kics.io/) | 14.5 | -1. IaC scanning can analyze Azure Resource Manager templates in JSON format. If you write templates in the [Bicep](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview) language, you must use [the bicep CLI](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-cli) to convert your Bicep files into JSON before GitLab IaC scanning can analyze them. +1. IaC scanning can analyze Azure Resource Manager templates in JSON format. If you write templates in the [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview) language, you must use [the bicep CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-cli) to convert your Bicep files into JSON before GitLab IaC scanning can analyze them. 1. Terraform modules in a custom registry are not scanned for vulnerabilities. You can follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/357004) for the proposed feature. ### Supported distributions diff --git a/doc/user/application_security/img/secure_tools_and_cicd_stages.png b/doc/user/application_security/img/secure_tools_and_cicd_stages.png Binary files differnew file mode 100644 index 00000000000..3dbfd835baf --- /dev/null +++ b/doc/user/application_security/img/secure_tools_and_cicd_stages.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index fbd617351da..809fa5f3764 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secure your application **(ULTIMATE)** @@ -32,6 +32,25 @@ schedule. Coverage includes: - Vulnerabilities in a running web application. - Infrastructure as code configuration. +Each of the GitLab application security tools is relevant to specific stages of the feature development workflow. + +- Commit + - SAST + - Secret Detection + - IaC Scanning + - Dependency Scanning + - License Scanning + - Coverage-guided Fuzz Testing +- Build + - Container Scanning +- Test + - API Security + - DAST +- Deploy + - Operational Container Scanning + + + ### Source code analysis Source code analysis occurs on every code commit. Details of vulnerabilities detected are provided @@ -48,7 +67,7 @@ Analysis of the web application occurs on every code commit. As part of the CI/C application is built, deployed to a test environment, and subjected to the following tests: - Test for known application vectors - [Dynamic Application Security Testing (DAST)](dast/index.md). -- Analysis of APIs for known attack vectors - [DAST API](dast_api/index.md). +- Analysis of APIs for known attack vectors - [API Security](dast_api/index.md). - Analysis of web APIs for unknown bugs and vulnerabilities - [API fuzzing](api_fuzzing/index.md). ### Dependency analysis @@ -66,7 +85,7 @@ For more details, see [Dependency Scanning compared to Container Scanning](dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning). Additionally, dependencies in operational container images can be analyzed for vulnerabilities -on a regular schedule or cadence. For more details, see [Cluster Image Scanning](cluster_image_scanning/index.md). +on a regular schedule or cadence. For more details, see [Operational Container Scanning](../../user/clusters/agent/vulnerabilities.md). ### Infrastructure analysis @@ -152,6 +171,28 @@ does not use the `SECURE_ANALYZERS_PREFIX` variable. To override its Docker imag the instructions for [Running container scanning in an offline environment](container_scanning/index.md#running-container-scanning-in-an-offline-environment). +### Use security scanning tools with merge request pipelines + +By default, the application security jobs are configured to run for branch pipelines only. +To use them with [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md), +you must reference the [`latest` templates](../../development/cicd/templates.md). + +All `latest` security templates support merge request pipelines. + +For example, to run both SAST and Dependency Scanning: + +```yaml +include: + - template: Jobs/Dependency-Scanning.latest.gitlab-ci.yml + - template: Jobs/SAST.latest.gitlab-ci.yml +``` + +NOTE: +Mixing `latest` and `stable` security templates can cause both MR and branch pipelines to run. We recommend choosing `latest` or `stable` for all security scanners. + +NOTE: +Latest templates can receive breaking changes in any release. + ## Default behavior of GitLab security scanning tools ### Secure jobs in your pipeline @@ -446,7 +487,7 @@ Security and compliance teams must ensure that security scans: GitLab provides two methods of accomplishing this, each with advantages and disadvantages. -- [Compliance framework pipelines](../project/settings/index.md#compliance-pipeline-configuration) +- [Compliance framework pipelines](../group/manage.md#configure-a-compliance-pipeline) are recommended when: - Scan execution enforcement is required for any scanner that uses a GitLab template, such as SAST IaC, DAST, Dependency Scanning, @@ -486,6 +527,7 @@ Feedback is welcome on our vision for [unifying the user experience for these tw <!-- 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. --> + ### Secure job failing with exit code 1 WARNING: diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 7344695886a..2db8e9522db 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Offline environments **(ULTIMATE SELF)** @@ -131,7 +131,7 @@ to be able to use the `docker` command inside the jobs. This runner can be insta a bastion, and used only for this specific project. WARNING: -This template does not include updates for the container scanning analyzer. Please see +This template does not include updates for the container scanning analyzer. See [Container scanning offline directions](../container_scanning/index.md#running-container-scanning-in-an-offline-environment). #### Scheduling the updates diff --git a/doc/user/application_security/policies/img/scan_execution_policy_rule_mode_v15_5.png b/doc/user/application_security/policies/img/scan_execution_policy_rule_mode_v15_5.png Binary files differnew file mode 100644 index 00000000000..5ae7c2e065a --- /dev/null +++ b/doc/user/application_security/policies/img/scan_execution_policy_rule_mode_v15_5.png diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png Binary files differdeleted file mode 100644 index 04768d2e18a..00000000000 --- a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png +++ /dev/null diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 9b86ef7316a..b1315329071 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Policies **(ULTIMATE)** @@ -135,7 +135,7 @@ See [Scan result policies](scan-result-policies.md). ## Roadmap -See the [Category Direction page](https://about.gitlab.com/direction/protect/security_orchestration/) +See the [Category Direction page](https://about.gitlab.com/direction/govern/security_policies/security_policy_management/) for more information on the product direction of security policies within GitLab. ## Troubleshooting diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index f2fc52a2de8..41d25dfa8c8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Scan execution policies **(ULTIMATE)** @@ -9,13 +9,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Group-level security policies were [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4425) in GitLab 15.2. > - Group-level security policies were [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/356258) in GitLab 15.4. -Group, sub-group, or project owners can use scan execution policies to require that security scans run on a specified -schedule or with the project (or multiple projects if the policy is defined at a group or sub-group level) pipeline. Required scans are injected into the CI pipeline as new jobs +Group, subgroup, or project owners can use scan execution policies to require that security scans run on a specified +schedule or with the project (or multiple projects if the policy is defined at a group or subgroup level) pipeline. Required scans are injected into the CI pipeline as new jobs with a long, random job name. In the unlikely event of a job name collision, the security policy job overwrites any pre-existing job in the pipeline. If a policy is created at the group-level, it will apply to every child -project or sub-group. A group-level policy cannot be edited from a child project or sub-group. +project or subgroup. A group-level policy cannot be edited from a child project or subgroup. -This feature has some overlap with [compliance framework pipelines](../../project/settings/index.md#compliance-pipeline-configuration), +This feature has some overlap with [compliance framework pipelines](../../group/manage.md#configure-a-compliance-pipeline), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on the similarities and differences between these features, see [Enforce scan execution](../index.md#enforce-scan-execution). @@ -29,7 +29,7 @@ an error appears that states `chosen stage does not exist`. ## Scan execution policy editor NOTE: -Only group, sub-group, or project Owners have the [permissions](../../permissions.md#project-members-permissions) +Only group, subgroup, or project Owners have the [permissions](../../permissions.md#project-members-permissions) to select Security Policy Project. Once your policy is complete, save it by selecting **Create via merge request** @@ -43,9 +43,7 @@ Most policy changes take effect as soon as the merge request is merged. Any chan 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. - - -The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. + ## Scan execution policies schema @@ -90,13 +88,39 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | +| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [cluster image scanning](../../clusters/agent/vulnerabilities.md) will run. The object key is the name of the Kubernetes cluster configured for your project in GitLab. You can use the optional value of the object to select and scan specific Kubernetes resources. | GitLab supports the following types of CRON syntax for the `cadence` field: - A daily cadence of once per hour at a specified hour, for example: `0 18 * * *` - A weekly cadence of once per week on a specified day and at a specified hour, for example: `0 13 * * 0` -It is possible that other elements of the CRON syntax will work in the cadence field, however, GitLab does not officially test or support them. +Other elements of the CRON syntax may work in the cadence field, however, GitLab does not officially test or support them. The CRON expression is evaluated in UTC by default. If you have a self-managed GitLab instance and have [changed the server timezone](../../../administration/timezone.md), the CRON expression is evaluated with the new timezone. + +### `agent` schema + +Use this schema to define `agents` objects in the [`schedule` rule type](#schedule-rule-type). + +| Field | Type | Possible values | Description | +|--------------|---------------------|--------------------------|-------------| +| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces will be scanned. | + +#### Policy example + +```yaml +- name: Enforce Container Scanning in cluster connected through gitlab-agent for production and staging namespaces + enabled: true + rules: + - type: schedule + cadence: '0 10 * * *' + agents: + gitlab-agent: + namespaces: + - 'production' + - 'staging' + actions: + - scan: container_scanning +``` ## `scan` action type @@ -105,7 +129,7 @@ rule in the defined policy are met. | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| -| `scan` | `string` | `dast`, `secret_detection`, `sast`, `container_scanning`, `cluster_image_scanning` | The action's type. | +| `scan` | `string` | `dast`, `secret_detection`, `sast`, `container_scanning` | The action's type. | | `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.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/index.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. | @@ -126,9 +150,8 @@ Note the following: - A secret detection scan runs in `normal` 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. -- A container scanning and cluster image scanning scans configured for the `pipeline` rule type ignores the cluster defined in the `clusters` object. - They use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. - A cluster with a name provided in the `clusters` object must be created and configured for the project. +- 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. - The SAST scan uses the default template and runs in a [child pipeline](../../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines). ## Example security policies project @@ -186,8 +209,6 @@ In this example: and `Site Profile D`. - Secret detection, container scanning, and SAST scans run for every pipeline executed on the `main` branch. The SAST scan runs with the `SAST_EXCLUDED_ANALYZER` variable set to `"brakeman"`. -- Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities - from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. ## Example for scan execution policy editor diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 78a97b36e92..45b715a52b8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Scan result policies **(ULTIMATE)** diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index ec8e8e6fd93..b7932aae35c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAST analyzers **(FREE)** diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index 919a3565d88..a0742eb79a7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customize rulesets **(ULTIMATE)** @@ -166,7 +166,7 @@ Configure a passthrough these parameters: | `type` | One of `file`, `raw`, `git` or `url`. | | `target` | The target file that contains the data written by the passthrough evaluation. If no value is provided, a random target file is generated. | | `mode` | `overwrite`: if `target` exists, overwrites the file; `append`: append to file instead. The default is `overwrite`. | -| `ref` | This option only applies to the `git` passthrough type and contains the name of the branch or the SHA to be used. | +| `ref` | This option only applies to the `git` passthrough type and contains the name of the branch or the SHA to be used. When using a branch name, specify it in the form `refs/heads/<branch>`, not `refs/remotes/<remote_name>/<branch>`. | | `subdir` | This option only applies to the `git` passthrough type and can be used to only consider a certain subdirectory of the source Git repository. | | `value` | For the `file` `url` and `git` types, `value` defines the source location of the file/Git repository; for the `raw` type, `value` carries the raw content to be passed through. | | `validator` | Can be used to explicitly invoke validators (`xml`, `yaml`, `json`, `toml`) on the target files after the application of a passthrough. Per default, no validator is set. | @@ -237,7 +237,7 @@ target directory with a total `timeout` of 60 seconds. Several passthrouh types generate a configuration for the target analyzer: - Two `git` passthrough sections pull the head of branch - `refs/remotes/origin/test` from the `myrules` Git repository, and revision + `refs/heads/test` from the `myrules` Git repository, and revision `97f7686` from the `sast-rules` Git repository. From the `sast-rules` Git repository, only data from the `go` subdirectory is considered. - The `sast-rules` entry has a higher precedence because it appears later in @@ -262,7 +262,7 @@ Afterwards, Semgrep is invoked with the final configuration located under [[semgrep.passthrough]] type = "git" value = "https://gitlab.com/user/myrules.git" - ref = "refs/remotes/origin/test" + ref = "refs/heads/test" [[semgrep.passthrough]] type = "git" @@ -309,7 +309,7 @@ It does not explicitly store credentials in the configuration file. To reduce th [[semgrep.passthrough]] type = "git" value = "$GITURL" - ref = "refs/remotes/origin/main" + ref = "refs/heads/main" ``` ### Configure the append mode for passthroughs diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index c9bfecffecc..6b8bc1933a3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Static Application Security Testing (SAST) **(FREE)** @@ -138,7 +138,7 @@ The following analyzers have multi-project support: #### Enable multi-project support for Security Code Scan Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of -the repository. For details on the Solution format, see the Microsoft reference [Solution (`.sln`) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). +the repository. For details on the Solution format, see the Microsoft reference [Solution (`.sln`) file](https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). ### Supported distributions @@ -357,7 +357,7 @@ Support for more languages and analyzers is tracked in [this epic](https://gitla ### Using CI/CD variables to pass credentials for private repositories -Some analyzers require downloading the project's dependencies in order to +Some analyzers require downloading the project's dependencies to perform the analysis. In turn, such dependencies may live in private Git repositories and thus require credentials like username and password to download them. Depending on the analyzer, such credentials can be provided to @@ -503,7 +503,7 @@ From highest to lowest severity, the logging levels are: #### Custom Certificate Authority To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle -of CA certs that you want to trust in the SAST environment. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: +of CA certs that you want to trust in the SAST environment. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: ```yaml variables: @@ -680,7 +680,7 @@ registry.gitlab.com/security-products/spotbugs:2 ``` The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Please consult your IT staff to find an accepted and approved +**your network security policy**. Consult your IT staff to find an accepted and approved process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) with new definitions, and you may be able to make occasional updates on your own. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index fe029b26ce5..df6bb19ac25 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secret Detection **(FREE)** @@ -120,6 +120,10 @@ To enable Secret Detection using a merge request: Pipelines now include a Secret Detection job, and the results are included in the merge request widget. +## Responding to a leaked secret + +If the scanner detects a secret we recommend you rotate it immediately. [Purging a file from the repository's history](../../project/repository/reducing_the_repo_size_using_git.md#purge-files-from-repository-history) may not be effective in removing all references to the file. Also, the secret remains in any forks of the repository. + ## Configure scan settings The Secret Detection scan settings can be changed through [CI/CD variables](#available-cicd-variables) @@ -150,6 +154,18 @@ secret_detection: SECRET_DETECTION_HISTORIC_SCAN: "true" ``` +### Ignoring Secrets + +You might want to add a fake secret to your code base. For instance, you can use a fake secret as an example in your documentation or test suite. + +In these cases, Secret Detection can ignore the fake secret and not report it as a vulnerability. To ignore a secret, add `gitleaks:allow` as a comment to the line that contains the secret. + +For example: + +```ruby + "A personal token for GitLab will look like glpat-JUST20LETTERSANDNUMB" #gitleaks:allow +``` + ### Available CI/CD variables Secret Detection can be customized by defining available CI/CD variables: @@ -294,6 +310,11 @@ To create a custom configuration, you can use passthrough chains. Passthroughs c to build more complex configurations. For more details, see [SAST Customize ruleset](../sast/customize_rulesets.md). +Only the following passthrough types are supported by the `secrets` analyzer: + +- `file` +- `raw` + In the `secret-detection-ruleset.toml` file, do one of the following: - Define a custom ruleset, for example: @@ -384,7 +405,7 @@ of CA certificates that you trust. Do this either in the `.gitlab-ci.yml` file, variable, or as a CI/CD variable. - In the `.gitlab-ci.yml` file, the `ADDITIONAL_CA_CERT_BUNDLE` value must contain the - [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). + [text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1). For example: diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index 9771658da4e..8dbe459d4af 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Secret Detection post-processing and revocation **(FREE SAAS)** diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 967e8da58a9..af98fc783e7 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Security Dashboards and Security Center **(ULTIMATE)** diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index d50cce3b4e8..085a762fffa 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -1,20 +1,21 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- -# Secure and Protect terminology **(FREE)** +# Secure and Govern terminology **(FREE)** -This terminology list for GitLab Secure and Protect aims to: +The glossary of terms aims to achieve the following: -- Promote a ubiquitous language for discussing application security. -- Improve the effectiveness of communication regarding GitLab application security features. -- Get new contributors up to speed faster. +- Promote a ubiquitous language that can be used everywhere - with customers, on issues, in Slack, in code. +- Improve the effectiveness of communication between team members. +- Reduce the potential for miscommunication. +- Bring new team members and community contributors up to speed faster, reducing the time to productivity. -This document defines application security terms in the specific context of GitLab Secure and -Protect features. Terms may therefore have different meanings outside that context. +The definitions of the terms outlined in this document are in the context of the GitLab +products. Therefore, a term may have a different meaning to users outside of GitLab. ## Terms @@ -28,9 +29,7 @@ an artifact after the job is complete. GitLab ingests this report, allowing user manage found vulnerabilities. For more information, see [Security Scanner Integration](../../../development/integrations/secure.md). Many GitLab analyzers follow a standard approach using Docker to run a wrapped scanner. For example, -the Docker image `bandit-sast` is an analyzer that wraps the scanner `Bandit`. You can optionally -use the [Common library](https://gitlab.com/gitlab-org/security-products/analyzers/common) -to assist in building an Analyzer. +the image `semgrep` is an analyzer that wraps the scanner `Semgrep`. ### Attack surface @@ -44,6 +43,12 @@ The set of meaningful test cases that are generated while the fuzzer is running. test case produces new coverage in the tested program. It's advised to re-use the corpus and pass it to subsequent runs. +### CNA + +[CVE](#cve) Numbering Authorities (CNAs) are organizations from around the world that are authorized by +the [Mitre Corporation](https://cve.mitre.org/) to assign [CVE](#cve)s to vulnerabilities in products or +services within their respective scope. [GitLab is a CNA](https://about.gitlab.com/security/cve/). + ### CVE Common Vulnerabilities and Exposures (CVE®) is a list of common identifiers for publicly known @@ -63,6 +68,11 @@ architecture. If left unaddressed, weaknesses could result in systems, networks, vulnerable to attack. The CWE List and associated classification taxonomy serve as a language that you can use to identify and describe these weaknesses in terms of CWEs. +### Deduplication + +When a category's process deems findings to be the same, or if they are similar enough that a noise reduction is +required, only one finding is kept and the others are eliminated. Read more about the [deduplication process](../vulnerability_report/pipeline.md#deduplication-process). + ### Duplicate finding A legitimate finding that is reported multiple times. This can occur when different scanners @@ -86,6 +96,13 @@ applications, and infrastructure. Findings are all potential vulnerability items scanners identify in MRs/feature branches. Only after merging to default does a finding become a [vulnerability](#vulnerability). +### Grouping + +A flexible and non-destructive way to visually organize vulnerabilities in groups when there are multiple findings +that are likely related but do not qualify for deduplication. For example, you can include findings that should be +evaluated together, would be fixed by the same action, or come from the same source. Grouping behavior for vulnerabilities is +under development and tracked in issue [267588](https://gitlab.com/gitlab-org/gitlab/-/issues/267588). + ### Insignificant finding A legitimate finding that a particular customer doesn't care about. @@ -93,16 +110,18 @@ A legitimate finding that a particular customer doesn't care about. ### Location fingerprint A finding's location fingerprint is a text value that's unique for each location on the attack -surface. Each Secure product defines this according to its type of attack surface. For example, SAST +surface. Each security product defines this according to its type of attack surface. For example, SAST incorporates file path and line number. -### Package managers +### Package managers and package types + +#### Package managers -A Package manager is a system that manages your project dependencies. +A package manager is a system that manages your project dependencies. The package manager provides a method to install new dependencies (also referred to as "packages"), manage where packages are stored on your file system, and offer capabilities for you to publish your own packages. -### Package types +#### Package types Each package manager, platform, type, or ecosystem has its own conventions and protocols to identify, locate, and provision software packages. @@ -200,9 +219,26 @@ table.package-managers-and-types ul { A page that displays findings discovered in the associated CI pipeline. +### Post-filter + +Post-filters help reduce noise in the scanner results and automate manual tasks. You can specify criteria that updates +or modifies vulnerability data based on scanner results. For example, you can flag findings as likely False Positives +and automatically resolve vulnerabilities that are no longer detected. These are not permanent actions and can be changed. + +Support for automatically resolving findings is tracked in epic [7478](https://gitlab.com/groups/gitlab-org/-/epics/7478) and +support for cheap scan is proposed in issue [349926](https://gitlab.com/gitlab-org/gitlab/-/issues/349926). + +### Pre-filter + +An irreversible action that is done to filter out target(s) before analysis occurs. This is usually provided to allow +the user to reduce scope and noise as well as speed up the analysis. This should not be done if a record is needed as +we currently do not store anything related to the skipped/excluded code or assets. + +Examples: `DS_EXCLUDED_PATHS` should `Exclude files and directories from the scan based on the paths provided.` + ### Primary identifier -A finding's primary identifier is a value unique to that finding. The external type and external ID +A finding's primary identifier is a value that is unique to each finding. The external type and external ID of the finding's [first identifier](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/v2.4.0-rc1/dist/sast-report-format.json#L228) combine to create the value. @@ -218,15 +254,19 @@ once it's imported into the database. ### Scan type (report type) -The type of scan. This must be one of the following: +Describes the type of scan. This must be one of the following: +- `api_fuzzing` - `cluster_image_scanning` - `container_scanning` +- `coverage_fuzzing` - `dast` - `dependency_scanning` - `sast` - `secret_detection` +This list is subject to change as scanners are added. + ### Scanner Software that can scan for vulnerabilities. The resulting scan report is typically not in the @@ -235,9 +275,12 @@ Software that can scan for vulnerabilities. The resulting scan report is typical ### Secure product A group of features related to a specific area of application security with first-class support by -GitLab. Products include Container Scanning, Dependency Scanning, Dynamic Application Security -Testing (DAST), Secret Detection, Static Application Security Testing (SAST), and Fuzz Testing. Each -of these products typically include one or more analyzers. +GitLab. + +Products include Container Scanning, Dependency Scanning, Dynamic Application Security +Testing (DAST), Secret Detection, Static Application Security Testing (SAST), and Fuzz Testing. + +Each of these products typically include one or more analyzers. ### Secure report format @@ -267,6 +310,7 @@ is listed as GitLab. A flaw that has a negative impact on the security of its environment. Vulnerabilities describe the error or weakness, and don't describe where the error is located (see [finding](#finding)). + Each vulnerability maps to a unique finding. Vulnerabilities exist in the default branch. Findings (see [finding](#finding)) are all potential vulnerability items scanners identify in MRs/feature branches. Only after merging to default does a finding become a vulnerability. @@ -280,8 +324,9 @@ When a [report finding](#report-finding) is stored to the database, it becomes a Deals with the responsibility of matching findings across scans so that a finding's life cycle can be understood. Engineers and security teams use this information to decide whether to merge code -changes, and to see unresolved findings and when they were introduced. Vulnerabilities are tracked -by comparing the location fingerprint, primary identifier, and report type. +changes, and to see unresolved findings and when they were introduced. + +Vulnerabilities are tracked by comparing the location fingerprint, primary identifier, and report type. ### Vulnerability occurrence diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 91793272cce..9ddb1bb51e2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability Page **(ULTIMATE)** @@ -103,7 +103,7 @@ To create a Jira issue for a vulnerability: 1. On the left sidebar, select **Security & Compliance > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create Jira issue**. -1. If you're not already logged in to Jira, log in. +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. diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index aed86cd93aa..36f9578f999 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability severity levels **(ULTIMATE)** @@ -56,7 +56,9 @@ the following tables: | GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |------------------------------------------------------------------------------------------|------------------------------|----------------------------|-------------------------------------| -| [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | +| [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating <sup>1</sup> | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | + +1. The CVSS v3.1 rating is used to calculate the severity level. If it's not available, the CVSS v2.0 rating is used instead. ## Container Scanning diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index ba448d410ea..59851fd192c 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Vulnerability Report **(ULTIMATE)** @@ -174,7 +174,7 @@ To change the status of vulnerabilities in the table: ## Dismissing a vulnerability When you evaluate a vulnerability and decide it requires no more action, you can mark it -as **Dismissed**. Dismissed vulnerabilities don't appear in the merge request security widget +as **Dismissed**. Dismissed vulnerabilities do not appear in the merge request security widget when detected in future scans. When a vulnerability is dismissed, a record is made of: @@ -191,7 +191,7 @@ If a vulnerability is dismissed in error, reverse the dismissal by changing its By default, vulnerabilities are sorted by severity level, with the highest-severity vulnerabilities listed at the top. -To sort vulnerabilities by the date each vulnerability was detected, click the "Detected" column header. +To sort vulnerabilities by the date each vulnerability was detected, select the "Detected" column header. ## Export vulnerability details @@ -199,7 +199,7 @@ To sort vulnerabilities by the date each vulnerability was detected, click the " > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) to the group-level Vulnerability Report in GitLab 13.1. You can export details of the vulnerabilities listed in the Vulnerability Report. The export format -is CSV (comma separated values). Note that all vulnerabilities are included because filters don't +is CSV (comma separated values). Note that all vulnerabilities are included because filters do not apply to the export. Fields included are: @@ -232,7 +232,7 @@ computer. NOTE: It may take several minutes for the download to start if your project contains -thousands of vulnerabilities. Don't close the page until the download finishes. +thousands of vulnerabilities. Do not close the page until the download finishes. ## Dismiss a vulnerability diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 7faf273515c..9e20e4f6f78 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # View vulnerabilities in a pipeline diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 8de777672ff..3ceecf88c5e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # AsciiDoc **(FREE)** diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index e4fcdcd4653..d0aa9fa6119 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Award emoji **(FREE)** diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md deleted file mode 100644 index 1b99fcf9739..00000000000 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'ci_cd_workflow.md' -remove_date: '2022-07-20' ---- - -This document was moved to [another location](ci_cd_workflow.md). - -<!-- This redirect file can be deleted after <2022-07-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 -->
\ No newline at end of file diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 7a6c6dc8cd6..7a3c09687a5 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitLab CI/CD with a Kubernetes cluster **(FREE)** @@ -156,9 +156,24 @@ deploy: # ... rest of your job configuration ``` +### Using the agent with Auto DevOps + +If Auto DevOps is enabled, you must define the `KUBE_CONTEXT` CI/CD variable. Set the value of `KUBE_CONTEXT` to the context of the agent you want to use in your Auto DevOps pipeline jobs (`<PATH_TO_AGENT_CONFIG_REPOSITORY>:<AGENT_NAME>`). + +You can also use different agents for different Auto DevOps jobs. For instance, you can use one agent for `staging` jobs and a different agent for `production` jobs. To use multiple agents, define a unique CI/CD variable for each agent. + +For example: + +1. Add two [environment-scoped CI/CD variables](../../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable) and name both `KUBE_CONTEXT`. +1. Set the `environment` of the first variable to `staging`. Set the value of the variable to `<PATH_TO_AGENT_CONFIGURATION_PROJECT>:<STAGING_AGENT_NAME>`. +1. Set the `environment` of the second variable to `production`. Set the value of the variable to `<PATH_TO_AGENT_CONFIGURATION_PROJECT>:<PRODUCTION_AGENT_NAME>`. + +When the `staging` job runs, it will connect to the cluster via the agent named `<STAGING_AGENT_NAME>`, and when the `production` job runs it will connect to the cluster via the agent named `<PRODUCTION_AGENT_NAME>`. + ## Restrict project and group access by using impersonation **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/357934) in GitLab 15.5 to add impersonation support for environment tiers. By default, your CI/CD job inherits all the permissions from the service account used to install the agent in the cluster. @@ -191,16 +206,17 @@ impersonation credentials in the following way: - `gitlab:ci_job` to identify all requests coming from CI jobs. - The list of IDs of groups the project is in. - The project ID. - - The slug of the environment this job belongs to. + - The slug and tier of the environment this job belongs to. Example: for a CI job in `group1/group1-1/project1` where: - Group `group1` has ID 23. - Group `group1/group1-1` has ID 25. - Project `group1/group1-1/project1` has ID 150. - - Job running in a prod environment. + - Job running in the `prod` environment, which has the `production` environment tier. - Group list would be `[gitlab:ci_job, gitlab:group:23, gitlab:group:25, gitlab:project:150, gitlab:project_env:150:prod]`. + Group list would be `[gitlab:ci_job, gitlab:group:23, gitlab:group_env_tier:23:production, gitlab:group:25, + gitlab:group_env_tier:25:production, gitlab:project:150, gitlab:project_env:150:prod, gitlab:project_env_tier:150:production]`. - `Extra` carries extra information about the request. The following properties are set on the impersonated identity: @@ -213,6 +229,7 @@ impersonation credentials in the following way: | `agent.gitlab.com/ci_job_id` | Contains the CI job ID. | | `agent.gitlab.com/username` | Contains the username of the user the CI job is running as. | | `agent.gitlab.com/environment_slug` | Contains the slug of the environment. Only set if running in an environment. | +| `agent.gitlab.com/environment_tier` | Contains the tier of the environment. Only set if running in an environment. | Example `config.yaml` to restrict access by the CI/CD job's identity: @@ -260,6 +277,7 @@ See the [official Kubernetes documentation for details](https://kubernetes.io/do ## Related topics - [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters) +- [Configure Auto DevOps](../../../topics/autodevops/cloud_deployments/auto_devops_with_gke.md#configure-auto-devops) ## Troubleshooting diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 67439788ef7..c0d4a5e088f 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using GitOps with a Kubernetes cluster **(FREE)** diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md index bdc2664e7ba..af9f80618b5 100644 --- a/doc/user/clusters/agent/gitops/helm.md +++ b/doc/user/clusters/agent/gitops/helm.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Using Helm charts to update a Kubernetes cluster (Alpha) **(FREE)** @@ -13,7 +13,7 @@ with your charts and values. To do this, you use the pull-based GitOps features Kubernetes. This feature is in Alpha and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/7938) -to track future work. Please tell us about your use cases by leaving comments in the epic. +to track future work. Tell us about your use cases by leaving comments in the epic. NOTE: This feature is Alpha. In future releases, to accommodate new features, the configuration format might change without notice. @@ -58,7 +58,7 @@ gitops: | Keyword | Description | |--|--| -| `charts` | List of charts you want to be applied in your cluster. Charts are applied concurrently. All charts must be in the same directory. | +| `charts` | List of charts you want to be applied in your cluster. Charts are applied concurrently. | | `release_name` | Required. Name of the release to use when applying the chart. | | `id` | Required. ID of the project where Helm chart is committed. No authentication mechanisms are currently supported. | | `path` | Optional. Path of the chart in the project repository. Root of the repository is used by default. This is the directory with the `Chart.yaml` file. | @@ -69,7 +69,6 @@ gitops: Drift happens when the current configuration of an infrastructure resource differs from its desired configuration. Typically, drift is caused by manually editing resources directly, rather than by editing the code that describes the desired state. Minimizing the risk of drift helps to ensure configuration consistency and successful operations. -mechanism. Minimizing the risk of drift helps to ensure configuration consistency and successful operations. In GitLab, the agent for Kubernetes regularly compares the desired state from the chart source with the actual state from the Kubernetes cluster. Deviations from the desired state are fixed at every check. These checks diff --git a/doc/user/clusters/agent/gitops/secrets_management.md b/doc/user/clusters/agent/gitops/secrets_management.md index cf520c881bf..dc1cbe3009d 100644 --- a/doc/user/clusters/agent/gitops/secrets_management.md +++ b/doc/user/clusters/agent/gitops/secrets_management.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Managing Kubernetes secrets in a GitOps workflow diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index eb62a733d36..7fdf0bb2bf0 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connecting a Kubernetes cluster with GitLab @@ -91,7 +91,7 @@ Read about how to [migrate to the agent for Kubernetes](../../infrastructure/clu - [GitOps examples and learning materials](gitops.md#related-topics) - [GitLab CI/CD workflow](ci_cd_workflow.md) - [Install the agent](install/index.md) -- [Work with the agent](repository.md) +- [Work with the agent](work_with_agent.md) - [Troubleshooting](troubleshooting.md) - [Guided explorations for a production ready GitOps setup](https://gitlab.com/groups/guided-explorations/gl-k8s-agent/gitops/-/wikis/home#gitlab-agent-for-kubernetes-gitops-working-examples) - [CI/CD for Kubernetes examples and learning materials](ci_cd_workflow.md#related-topics) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 0240fbb45f0..19628419784 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Installing the agent for Kubernetes **(FREE)** @@ -48,7 +48,7 @@ For configuration settings, the agent uses a YAML file in the GitLab project. Yo To create an agent configuration file: 1. Choose a name for your agent. The agent name follows the - [DNS label standard from RFC 1123](https://tools.ietf.org/html/rfc1123). The name must: + [DNS label standard from RFC 1123](https://www.rfc-editor.org/rfc/rfc1123). The name must: - Be unique in the project. - Contain at most 63 characters. @@ -110,6 +110,9 @@ in your cluster. You can either: If you do not know which one to choose, we recommend starting with Helm. +NOTE: +To connect to multiple clusters, you must configure, register, and install an agent in each cluster. Make sure to give each agent a unique name. + #### Install the agent with Helm To install the agent on your cluster using Helm: diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md deleted file mode 100644 index 8f3a8830202..00000000000 --- a/doc/user/clusters/agent/repository.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'work_with_agent.md' -remove_date: '2022-07-19' ---- - -This document was moved to [another location](work_with_agent.md). - -<!-- This redirect file can be deleted after <2022-07-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/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 0596755ec74..0c26c533cc3 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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 the GitLab agent for Kubernetes diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index 2d20675b68b..dcb3276deb5 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Operational Container Scanning **(ULTIMATE)** diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index b28f7546379..566eae8e24e 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Working with the agent for Kubernetes **(FREE)** @@ -67,13 +67,13 @@ The agent has two loggers: - A general purpose logger, which defaults to `info`. - A gRPC logger, which defaults to `error`. -One can change their log levels by using a top-level `observability` section in the [agent configuration file](install/index.md#configure-your-agent), for example setting the levels to `debug` and `warning`: +You can change your log levels by using a top-level `observability` section in the [agent configuration file](install/index.md#configure-your-agent), for example setting the levels to `debug` and `warn`: ```yaml observability: logging: level: debug - grpc_level: warning + grpc_level: warn ``` When `grpc_level` is set to `info` or below, there will be a lot of gRPC logs. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md deleted file mode 100644 index 7b5ea7d12fd..00000000000 --- a/doc/user/clusters/applications.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -stage: Configure -group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-08-22' -redirect_to: '../../update/removals.md#managed-cluster-applicationsgitlab-ciyml' ---- - -# GitLab Managed Apps (removed) **(FREE)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333610) in GitLab 15.0. -Use the [cluster management project template](management_project_template.md) instead. diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 3dcec32b90c..75bc9e23c0f 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cluster cost management (DEPRECATED) **(ULTIMATE)** diff --git a/doc/user/clusters/create/index.md b/doc/user/clusters/create/index.md index b3d2b9f23fa..0721cea965a 100644 --- a/doc/user/clusters/create/index.md +++ b/doc/user/clusters/create/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create Kubernetes clusters diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md deleted file mode 100644 index 16615f88e25..00000000000 --- a/doc/user/clusters/crossplane.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -stage: Configure -group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-08-22' -redirect_to: '../../update/removals.md#managed-cluster-applicationsgitlab-ciyml' ---- - -# Crossplane configuration (removed) **(FREE)** - -This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) -in GitLab 14.5. and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333610) -in GitLab 15.0. Use [crossplane](https://crossplane.io/) directly instead. diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 96f41531576..98292cf9103 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cluster Environments (DEPRECATED) **(PREMIUM)** diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index c7597896575..c5e56fcd3a7 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cluster integrations (DEPRECATED) **(FREE)** @@ -88,11 +88,11 @@ Prometheus as long as you meet the requirements above. To enable the Prometheus integration for your cluster: 1. Go to the cluster's page: - - For a [project-level cluster](../project/clusters/index.md), navigate to your project's + - For a [project-level cluster](../project/clusters/index.md), go to your project's **Infrastructure > Kubernetes clusters**. - - For a [group-level cluster](../group/clusters/index.md), navigate to your group's + - For a [group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes** page. - - For an [instance-level cluster](../instance/clusters/index.md), navigate to your instance's + - For an [instance-level cluster](../instance/clusters/index.md), go to your instance's **Kubernetes** page. 1. Select the **Integrations** tab. 1. Check the **Enable Prometheus integration** checkbox. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 62f70faa630..df338e8fcee 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Cluster management project (DEPRECATED) **(FREE)** diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index cd71be321cc..bdd11f11f9c 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage cluster applications **(FREE)** 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 ce39e13d928..a86a84fe9ae 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate from GitLab Managed Apps to Cluster Management Projects (DEPRECATED) **(FREE)** diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index 96cb3f3ef38..ac4b20b5166 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance report **(ULTIMATE)** @@ -72,7 +72,7 @@ The following is a list of violations that are either: When you select a row, a drawer is shown that provides further details about the merge request: -- Project name and [compliance framework label](../../project/settings/index.md#compliance-frameworks), +- Project name and [compliance framework label](../../project/settings/index.md#add-a-compliance-framework-to-a-project), if the project has one assigned. - Link to the merge request. - The merge request's branch path in the format `[source] into [target]`. diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index c6c4834228b..7981ab44bf9 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Compliance **(ULTIMATE)** diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 19b01e4d854..fb5ce37c563 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # License compliance **(ULTIMATE)** @@ -100,7 +100,7 @@ To enable License Compliance in your project's pipeline, either: (provided by [Auto DevOps](../../../topics/autodevops/index.md)). - Include the [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) in your `.gitlab-ci.yml` file. -Please note that License Compliance is not supported when GitLab is run with FIPS mode enabled. +License Compliance is not supported when GitLab is run with FIPS mode enabled. ### Include the License Scanning template @@ -556,8 +556,8 @@ license_scanning: #### Using private NuGet registries If you have a private NuGet registry you can add it as a source -by adding it to the [`packageSources`](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) -section of a [`nuget.config`](https://docs.microsoft.com/en-us/nuget/reference/nuget-config-file) file. +by adding it to the [`packageSources`](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file#package-source-sections) +section of a [`nuget.config`](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file) file. For example: @@ -656,7 +656,7 @@ registry.gitlab.com/security-products/license-finder:latest ``` The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Please consult your IT staff to find an accepted and approved +**your network security policy**. Consult your IT staff to find an accepted and approved process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../../application_security/index.md#vulnerability-scanner-maintenance) with new definitions, so consider if you are able to make periodic updates yourself. @@ -869,30 +869,61 @@ A full list of variables can be found in [CI/CD variables](#available-cicd-varia To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: ```shell -$ docker run --entrypoint='' registry.gitlab.com/security-products/license-finder:4 /bin/bash -lc 'asdf list' +$ docker run --entrypoint='' -ti --rm registry.gitlab.com/security-products/license-finder:4 \ + /bin/bash -c 'dpkg -i /opt/toolcache/*.deb && asdf list' +... +dotnet-core + 3.1.302 +elixir + 1.10.4 golang - 1.14 + 1.15.5 + 1.16.2 gradle - 6.3 +No versions installed java - adopt-openjdk-11.0.7+10 - adopt-openjdk-8u242-b08 + 11 + 14 + 15 + 8 maven - 3.6.3 +No versions installed nodejs - 10.20.1 - 12.16.3 + 10.21.0 + 12.18.2 + 14.17.1 php - 7.4.5 + 7.4.8 python 2.7.18 - 3.8.2 + 3.3.7 + 3.4.10 + 3.5.9 + 3.6.11 + 3.7.7 + 3.8.5 ruby + 2.4.10 + 2.4.5 + 2.4.9 + 2.5.8 + 2.6.0 + 2.6.1 + 2.6.2 + 2.6.3 + 2.6.4 + 2.6.5 2.6.6 -sbt - 1.3.8 + 2.7.0 + 2.7.1 + 2.7.2 +rust + 1.45.0 ``` +It might take more than 10 minutes to run the command above. +This is because it installs every single tool version available in the Docker image. + To interact with the `license_scanning` runtime environment use the following command: ```shell diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 79f18e3abf1..d7ab2195e2d 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -1,7 +1,7 @@ --- stage: Plan group: Certify -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Customer relations management (CRM) **(FREE)** @@ -186,7 +186,7 @@ When you use the `/add_contacts` or `/remove_contacts` quick actions, follow the The root group is the topmost group in the group hierarchy. -When you move an issue, project, or group **within the same group hierarchy**, +When you move an issue, project, or group **in the same group hierarchy**, issues retain their contacts. When you move an issue or project and the **root group changes**, diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index ed0bcec9f49..13d5b27ad41 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -177,7 +177,7 @@ You can add an internal note **to an issue or an epic**. It's then visible only Keep in mind: - Replies to internal notes are also internal. -- You can not turn an internal note into a regular comment. +- You cannot turn an internal note into a regular comment. Prerequisites: @@ -315,7 +315,7 @@ At the top of the page, the number of unresolved threads is updated: If you have multiple unresolved threads in a merge request, you can create an issue to resolve them separately. In the merge request, at the top of the page, -click the ellipsis icon button (**{ellipsis_v}**) in the threads control and then select **Create issue to resolve all threads**: +select the ellipsis icon button (**{ellipsis_v}**) in the threads control and then select **Create issue to resolve all threads**:  diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index e288be87474..cc4bfdb01de 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -1,7 +1,7 @@ --- stage: none group: Development -info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" description: "Understand what 'GitLab features deployed behind flags' means." layout: 'feature_flags' --- diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index 60091449256..3fbfb2e1aa7 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -1,31 +1,14 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Free user limit **(FREE SAAS)** -From October 19, 2022, namespaces in GitLab.com on the Free tier -will be limited to five (5) members per [namespace](namespace/index.md). -This limit applies to top-level private groups. +From October 19, 2022, a five-user limit will apply to top-level [namespaces](namespace/index.md) with private visibility on GitLab SaaS. These limits will roll out gradually, and impacted users will be notified in GitLab.com at least 60 days before the limit is applied. -On the transition date, if your namespace has six or more unique members: - -- Five members will keep a status of `Active`. -- Remaining members will get a status of `Over limit` and lose access to the - group. -- Members invited through a group or project invitation outside of the namespace - will be removed. You can add these members back by inviting them through their - username or email address on the **Members** page for your group or project. - -## How active members are determined - -On the transition date, we'll automatically select the members who keep their `Active` status -in the following order, until we reach a total of five: - -1. Members with the Owner or Maintainer role. -1. The most recently active members. +When the five-user limit is applied, top-level private namespaces exceeding the user limit are placed in a read-only state. These namespaces cannot write new data to repositories, Git Large File Storage (LFS), packages, or registries. ## Manage members in your namespace @@ -43,7 +26,7 @@ Prerequisite: 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://about.gitlab.com/free-trial/). +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. ## Related topics diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 62b685ea4f4..d3d50ee1a8f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab.com settings **(FREE SAAS)** @@ -146,22 +146,22 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/index.md). Any settings or feature limits not listed here are using the defaults listed in the related documentation. -| Setting | GitLab.com | Default (self-managed) | -|:-------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Artifacts maximum size (compressed) | 1 GB | See [Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size) | -| Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | See [Default artifacts expiration](../admin_area/settings/continuous_integration.md#default-artifacts-expiration) | -| Scheduled Pipeline Cron | `*/5 * * * *` | See [Pipeline schedules advanced configuration](../../administration/cicd.md#change-maximum-scheduled-pipeline-frequency) | -| Maximum jobs in active pipelines | `500` for Free tier, `1000` for all trial tiers, and unlimited otherwise. | See [Number of jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | -| Maximum CI/CD subscriptions to a project | `2` | See [Number of CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | -| Maximum number of pipeline triggers in a project | `25000` for Free tier, Unlimited for all paid tiers | See [Limit the number of pipeline triggers](../../administration/instance_limits.md#limit-the-number-of-pipeline-triggers) | -| Maximum pipeline schedules in projects | `10` for Free tier, `50` for all paid tiers | See [Number of pipeline schedules](../../administration/instance_limits.md#number-of-pipeline-schedules) | -| Maximum pipelines per schedule | `24` for Free tier, `288` for all paid tiers | See [Limit the number of pipelines created by a pipeline schedule per day](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day) | -| Maximum number of schedule rules defined for each security policy project | Unlimited for all paid tiers | See [Number of schedule rules defined for each security policy project](../../administration/instance_limits.md#limit-the-number-of-schedule-rules-defined-for-security-policy-project) | -| Scheduled job archiving | 3 months (from June 22, 2020). Jobs created before that date were archived after September 22, 2020. | Never | -| Maximum test cases per [unit test report](../../ci/testing/unit_test_reports.md) | `500000` | Unlimited | -| Maximum registered runners | Free tier: `50` per-group / `50` per-project<br/>All paid tiers: `1000` per-group / `1000` per-project | See [Number of registered runners per scope](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | -| Limit of dotenv variables | Free tier: `50` / Premium tier: `100` / Ultimate tier: `150` | See [Limit dotenv variables](../../administration/instance_limits.md#limit-dotenv-variables) | -| Authorization token duration (minutes) | `15` | To set a custom value, in the Rails console, run `ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)`, where `<integer>` is the desired number of minutes. | +| Setting | GitLab.com | Default (self-managed) | +|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|------------------------| +| Artifacts maximum size (compressed) | 1 GB | See [Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size). | +| Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | See [Default artifacts expiration](../admin_area/settings/continuous_integration.md#default-artifacts-expiration). | +| Scheduled Pipeline Cron | `*/5 * * * *` | See [Pipeline schedules advanced configuration](../../administration/cicd.md#change-maximum-scheduled-pipeline-frequency). | +| Maximum jobs in active pipelines | `500` for Free tier, `1000` for all trial tiers, and unlimited otherwise. | See [Number of jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines). | +| Maximum CI/CD subscriptions to a project | `2` | See [Number of CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project). | +| Maximum number of pipeline triggers in a project | `25000` for Free tier, Unlimited for all paid tiers | See [Limit the number of pipeline triggers](../../administration/instance_limits.md#limit-the-number-of-pipeline-triggers). | +| Maximum pipeline schedules in projects | `10` for Free tier, `50` for all paid tiers | See [Number of pipeline schedules](../../administration/instance_limits.md#number-of-pipeline-schedules). | +| Maximum pipelines per schedule | `24` for Free tier, `288` for all paid tiers | See [Limit the number of pipelines created by a pipeline schedule per day](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day). | +| Maximum number of schedule rules defined for each security policy project | Unlimited for all paid tiers | See [Number of schedule rules defined for each security policy project](../../administration/instance_limits.md#limit-the-number-of-schedule-rules-defined-for-security-policy-project). | +| Scheduled job archiving | 3 months (from June 22, 2020). Jobs created before that date were archived after September 22, 2020. | Never. | +| Maximum test cases per [unit test report](../../ci/testing/unit_test_reports.md) | `500000` | Unlimited. | +| Maximum registered runners | Free tier: `50` per-group / `50` per-project<br/>All paid tiers: `1000` per-group / `1000` per-project | See [Number of registered runners per scope](../../administration/instance_limits.md#number-of-registered-runners-per-scope). | +| Limit of dotenv variables | Free tier: `50` / Premium tier: `100` / Ultimate tier: `150` | See [Limit dotenv variables](../../administration/instance_limits.md#limit-dotenv-variables). | +| Authorization token duration (minutes) | `15` | To set a custom value, in the Rails console, run `ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)`, where `<integer>` is the desired number of minutes. | ## Package registry limits @@ -249,10 +249,13 @@ The limit varies depending on your plan and the number of seats in your subscrip |----------------------|-------------------------| | Number of webhooks | `100` per project, `50` per group | | Maximum payload size | 25 MB | +| Timeout | 10 seconds | -For self-managed instance limits, see -[Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit) -and [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks). +For self-managed instance limits, see: + +- [Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit). +- [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks). +- [Webhook timeout](../../administration/instance_limits.md#webhook-timeout). ## Runner SaaS diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index bdef13af3f9..395ed3c91c7 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group access and permissions @@ -19,14 +19,14 @@ Group push rules allow group maintainers to set In GitLab 15.4 and later, to configure push rules for a group: -1. On the left sidebar, select **Push rules**. +1. On the left sidebar, select **Settings > Repository**. +1. Expand the **Pre-defined push rules** section. 1. Select the settings you want. 1. Select **Save Push Rules**. In GitLab 15.3 and earlier, to configure push rules for a group: -1. On the left sidebar, select **Settings > Repository** page. -1. Expand the **Pre-defined push rules** section. +1. On the left sidebar, select **Push rules**. 1. Select the settings you want. 1. Select **Save Push Rules**. diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 17a5551adbf..c6cc828302f 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -2,7 +2,7 @@ type: reference stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE)** diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 7750782a623..280781a4cad 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,8 +1,8 @@ --- type: reference -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Contribution Analytics **(PREMIUM)** diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 43587dd54ef..7f77c2147e1 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom group-level project templates **(PREMIUM)** diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index bb18c69f7ae..67263f15f06 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -1,7 +1,7 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group DevOps Adoption **(ULTIMATE)** diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index a8bbb0575b3..78cc65f1923 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epic boards **(PREMIUM)** diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index f2cb437ffda..da6e675f0eb 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -1,18 +1,16 @@ --- 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Epics **(PREMIUM)** -> Single-level epics were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. +When [issues](../../project/issues/index.md) share a theme across projects and +milestones, you can manage them by using epics. -When [issues](../../project/issues/index.md) share a theme across projects and milestones, -you can manage them by using epics. - -You can also create child epics, and assign start and end dates, -which creates a visual roadmap for you to view progress. +You can also create child epics and assign start and end dates, which creates +a visual roadmap for you to view progress. Use epics: @@ -37,6 +35,22 @@ graph TD Also, read more about possible [planning hierarchies](../planning_hierarchy/index.md). +### Child issues from different group hierarchies + +<!-- When feature flag is removed, integrate this info as a sentence in +https://docs.gitlab.com/ee/user/group/epics/manage_epics.html#add-an-existing-issue-to-an-epic --> + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371081) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `epic_issues_from_different_hierarchies`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/373304) in GitLab 15.5. + +FLAG: +On self-managed GitLab, by default this feature is unavailable. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `epic_issues_from_different_hierarchies`. +On GitLab.com, this feature is available. + +You can add issues from a different group hierarchy to an epic. +To do it, paste the issue URL when +[adding an existing issue](manage_epics.md#add-an-existing-issue-to-an-epic). + ## Roadmap in epics **(ULTIMATE)** If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 89699661efa..4049ac2e9a1 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked epics **(ULTIMATE)** diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 26826ec5832..0a12f551588 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage epics **(PREMIUM)** @@ -213,6 +213,16 @@ To view epics in a group: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Epics**. +### Who can view an epic + +Whether you can view an epic depends on the [group visibility level](../../public_access.md) and +the epic's [confidentiality status](#make-an-epic-confidential): + +- Public group and a non-confidential epic: You don't have to be a member of the group. +- Private group and non-confidential epic: You must have at least the Guest role for the group. +- Confidential epic (regardless of group visibility): You must have at least the Reporter + role for the group. + ### Cached epic count > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299540) in GitLab 13.11 [with a flag](../../../administration/feature_flags.md) named `cached_sidebar_open_epics_count`. Enabled by default. @@ -329,8 +339,8 @@ automatically added to the epic. #### Add an existing issue to an epic -Existing issues that belong to a project in an epic's group, or any of the epic's -subgroups, are eligible to be added to the epic. Newly added issues appear at the top of the list of +You can add existing issues to an epic, including issues in a project in an epic's group, or any of +the epic's subgroups. Newly added issues appear at the top of the list of issues in the **Epics and Issues** tab. An epic contains a list of issues and an issue can be associated with at most one epic. @@ -339,7 +349,7 @@ current parent. Prerequisites: -- You must have at least the Reporter role for the epic's group. +- You must be able to [view the epic](#who-can-view-an-epic). - You must be able to [edit the issue](../../project/issues/managing_issues.md#edit-an-issue). To add an existing issue to an epic: @@ -356,14 +366,13 @@ To add an existing issue to an epic: #### Create an issue from an epic -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5419) in GitLab 12.7. - Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts. Prerequisites: -- You must have at least the Reporter role for the epic's group. +- You must be able to [view the epic](#who-can-view-an-epic). +- You must have at least the Reporter role for the project. To create an issue from an epic: @@ -479,6 +488,8 @@ When you add an epic that's already linked to a parent epic, the link to its cur Epics can contain multiple nested child epics, up to a total of seven levels deep. +Maximum number of direct child epics is 100. + ### Add a child epic to an epic Prerequisites: diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 21b389581ae..ee50cfcf182 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -1,19 +1,19 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating groups **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 for group resources [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default. -> - Group resources [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. +> - Group items [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 for project resources [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. FLAG: -On self-managed GitLab, by default [migrating group resources](#migrated-group-resources) is available. To hide the +On self-managed GitLab, by default [migrating group items](#migrated-group-items) is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `bulk_import`. -On self-managed GitLab, by default [migrating project resources](#migrated-project-resources) is not available. To show +On self-managed GitLab, by default [migrating project items](#migrated-project-items) is not available. To show this feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. On GitLab.com, migrating group resources is available but migrating project resources is not available. @@ -33,8 +33,8 @@ another GitLab instance. Migrating groups using the method documented here autom When you migrate a group, you connect to your GitLab instance and then choose groups to import. Not all the data is migrated. See: -- [Migrated group resources](#migrated-group-resources). -- [Migrated project resources](#migrated-project-resources). +- [Migrated group items](#migrated-group-items). +- [Migrated project items](#migrated-project-items). Leave feedback about group migration in [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). @@ -79,10 +79,17 @@ Migration importer page. The remote groups you have the Owner role for are liste For information on automating user, group, and project import API calls, see [Automate group and project import](../../project/import/index.md#automate-group-and-project-import). -## Migrated group resources +## Migrated group items -Only the following resources are migrated to the target instance. Any other items are **not** -migrated: +The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/import_export.yml) +file for groups lists many of the items migrated when migrating groups using group migration. View this file in the branch +for your version of GitLab to see the list of items relevant to you. For example, +[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/group/import_export.yml). + +Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../custom_project_templates.md) and +[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. + +Items that are migrated to the target instance include: - Badges ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292431) in 13.11) - Board Lists @@ -92,6 +99,7 @@ migrated: - Finisher - Group Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9) - Iterations ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292428) in 13.10) +- Iterations cadences ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96570) in 15.4) - Members ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299415) in 13.9) Group members are associated with the imported group if: - The user already exists in the target GitLab instance and @@ -101,24 +109,36 @@ migrated: - Namespace Settings - Releases - Milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339422) in GitLab 15.0). -- Sub-Groups +- Subgroups - Uploads -## Migrated project resources +Any other items are **not** migrated. + +## Migrated project items > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. FLAG: On self-managed GitLab, migrating project resources are not available by default. To make them available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. On GitLab.com, migrating project resources are not available. +The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) +file for projects lists many of the items migrated when migrating projects using group migration. View this file in the branch +for your version of GitLab to see the list of items relevant to you. For example, +[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). + +Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and +[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. + - Projects ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4) - Auto DevOps ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339410) in GitLab 14.6) - Branches (including protected branches) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339414) in GitLab 14.7) - CI Pipelines ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339407) in GitLab 14.6) - Designs ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339421) in GitLab 15.1) - Issues ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267946) in GitLab 14.4) + - Issue iteration ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96184) in 15.4) - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource iteration events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339419) in GitLab 14.4) - LFS Objects ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339405) in GitLab 14.8) - Members ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341886) in GitLab 14.8) diff --git a/doc/user/group/index.md b/doc/user/group/index.md index c7d92af8ee8..62659938d91 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Groups **(FREE)** diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png Binary files differdeleted file mode 100644 index ff18a3e86a5..00000000000 --- a/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png +++ /dev/null diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart_v15_4.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart_v15_4.png Binary files differnew file mode 100644 index 00000000000..f7963c170e1 --- /dev/null +++ b/doc/user/group/insights/img/insights_example_stacked_bar_chart_v15_4.png diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 0cde0f1f133..b4bca919498 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,18 +1,19 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Insights for groups **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. -Configure Insights to explore data about you group's activity, such as +Configure insights to explore data about you group's activity, such as triage hygiene, issues created or closed in a given period, and average time for merge requests to be merged. +You can also create custom insights reports that are relevant for your group. -## View your group's Insights +## View group insights Prerequisites: @@ -20,22 +21,49 @@ Prerequisites: - You must have access to a project to view information about its merge requests and issues, and permission to view them if they are confidential. -To access your group's Insights: +To access your group's insights: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Insights**. - +## Interact with insights charts -## Configure your Insights +You can interact with the insights charts to view details about your group's activity. -GitLab reads Insights from the + + +### Display different reports + +To display one of the available reports on the insights page, from the **Select report** dropdown list, +select the report you want to display. + +### View bar chart annotations + +To view annotations, hover over each bar in the chart. + +### Zoom in on chart + +Insights display data from the last 90 days. You can zoom in to display data only from a subset of the 90-day range. + +To do this, select the pause icons (**{status-paused}**) and slide them along the horizontal axis: + +- To select a later start date, slide the left pause icon to the right. +- To select an earlier end date, slide the right pause icon to the left. + +### Exclude dimensions from charts + +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. + +## Configure group insights + +GitLab reads insights from the [default configuration file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml). -You can also create custom Insights charts that are more relevant for your group. -To customize your Insights: +To configure group insights: -1. Create a new file [`.gitlab/insights.yml`](../../project/insights/index.md#writing-your-gitlabinsightsyml) +1. Create a new file [`.gitlab/insights.yml`](../../project/insights/index.md#configure-project-insights) in a project that belongs to your group. 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 26d77edd89b..4764625ff83 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue analytics for groups **(PREMIUM)** diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 4cc879ef32d..a6435ae2aa3 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Iterations **(PREMIUM)** @@ -13,8 +13,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) in GitLab 14.6. [Feature flag `group_iterations`](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) removed. Iterations are a way to track issues over a period of time. This allows teams -to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) -for tracking over different time periods. +to track velocity and volatility metrics. For tracking over different time periods, you can use iterations [milestones](../../project/milestones/index.md). +You can create and manage various [iteration cadences](#iteration-cadences). For example, you can use: @@ -24,15 +24,51 @@ For example, you can use: In GitLab, iterations are similar to milestones, with a few differences: - Iterations are only available to groups. -- A group can only have one active iteration at a time. +- Iterations are grouped into iteration cadences. - Iterations require both a start and an end date. -- Iteration date ranges cannot overlap. +- Iteration date ranges cannot overlap within an iteration cadence. -## View the iterations list +## Iteration cadences + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1 [with a flag](../../../administration/feature_flags.md), named `iteration_cadences`. Disabled by default. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/354977) in GitLab 15.0: All scheduled iterations must start on the same day of the week as the cadence start day. Start date of cadence cannot be edited after the first iteration starts. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.0. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.4: A new automation start date can be selected for cadence. Upcoming iterations will be scheduled to start on the same day of the week as the changed start date. Iteration cadences can be manually managed by turning off the automatic scheduling feature. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.5. Feature flag `iteration_cadences` removed. + +Iteration cadences are containers for iterations and can be used to automate iteration scheduling. +You can use them to automate creating iterations every 1, 2, 3, or 4 weeks. You can also +configure iteration cadences to automatically roll over incomplete issues to the next iteration. + +### Create an iteration cadence + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. + +Prerequisites: + +- You must have at least the Reporter role for a group. + +To create an iteration cadence: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Iterations**. +1. Select **New iteration cadence**. +1. Enter the title and description of the iteration cadence. +1. To manually manage the iteration cadence, clear the **Enable automatic scheduling** checkbox and skip the next step. +1. Complete the required fields to use automatic scheduling. + - Select the automation start date of the iteration cadence. Iterations will be scheduled to + begin on the same day of the week as the day of the week of the start date. + - From the **Duration** dropdown list, select how many weeks each iteration should last. + - From the **Upcoming iterations** dropdown list, select how many upcoming iterations should be + created and maintained by GitLab. + - Optional. To move incomplete issues to the next iteration, select **Roll over issues**. +1. Select **Create cadence**. The cadence list page opens. + +If you want to manually manage the created cadence, read [Manual Iteration Management](#manual-iteration-management). -To view the iterations list: +### View the iterations list -1. On the top bar, select **Main menu > Projects** and find your project. +1. On the top bar, select **Main menu > Groups** and find your group. 1. Select **Issues > Iterations**. To view all the iterations in a cadence, ordered by descending date, select that iteration cadence. @@ -46,61 +82,132 @@ by going to 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). -## Create an iteration +### Edit an iteration cadence -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 14.10. -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. +Prerequisites: + +- You must have at least the Developer role for a group. + +To edit an iteration cadence: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Iterations**. +1. Select **Edit iteration cadence**. + +When you use automatic scheduling and edit the **Automation start date** field, +you must set a new start date that doesn't overlap with the existing +current or past iterations. + +Editing **Upcoming iterations** is a non-destructive action. +If ten upcoming iterations already exist, changing the number under **Upcoming iterations** to `2` +doesn't delete the eight existing upcoming iterations. -WARNING: -Manual iteration management is in its end-of-life process. Creating an iteration is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) -in GitLab 14.10, and is planned for removal in GitLab 16.0. +#### Turn on and off automatic scheduling for an iteration cadence + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Iterations**. +1. Next to the cadence for which you want to turn on or off automatic scheduling, select the + three-dot menu (**{ellipsis_v}**) **> Edit cadence**. +1. Select or clear the **Enable automatic scheduling** checkbox. +1. If you're turning on automatic scheduling, + complete the required fields **Duration**, **Upcoming iterations**, and **Automation start date**. + + For **Automation start date**, you can select any date that doesn't overlap with the existing open iterations. + If you have upcoming iterations, the automatic scheduling adjusts them appropriately to fit + your chosen duration. +1. Select **Save changes**. + +#### Example of turning on automatic scheduling for a manual iteration cadence + +Suppose it's Friday, April 15, and you have three iteration in a manual iteration cadence: + +- Monday, April 4 - Friday, April 8 (closed) +- Tuesday, April 12 - Friday, April 15 (ongoing) +- Tuesday, May 3 - Friday, May 6 (upcoming) + +The earliest possible **Automation start date** you can choose +is Saturday, April 16 in this scenario, because April 15 overlaps with +the ongoing iteration. + +If you select Monday, April 18 as the automation start date to +automate scheduling iterations every week up to two upcoming iterations, +after the conversion you have the following iterations: + +- Monday, April 4 - Friday, April 8 (closed) +- Tuesday, April 12 - Friday, April 15 (ongoing) +- Monday, April 18 - Sunday, April 24 (upcoming) +- Monday, April 25 - Sunday, May 1 (upcoming) + +Your existing upcoming iteration "Tuesday, April 12 - Friday, April 15" +is changed to "April 18 - Sunday, April 24". + +An additional upcoming iteration "April 25 - Sunday, May 1" is scheduled +to satisfy the requirement that there are at least two upcoming iterations scheduled. + +### Delete an iteration cadence + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. Prerequisites: - You must have at least the Reporter role for a group. -To create an iteration: +Deleting an iteration cadence also deletes all iterations within that cadence. + +To delete an iteration cadence: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues > Iterations**. +1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete. +1. Select **Delete cadence**. + +## Manual iteration management + +If you don't want your iterations to be scheduled by iteration cadences, +you can also create and manage them manually. + +### Create an iteration + +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. + +Prerequisites: + +- You must have at least the Reporter role for a group. +- [Automatic scheduling must be disabled](#turn-on-and-off-automatic-scheduling-for-an-iteration-cadence) for the iteration cadence. + +To create an iteration: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Issues > 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. -## Edit an iteration +### Edit an iteration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in GitLab 13.2. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 14.10. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. -WARNING: -Editing all attributes, with the exception of `description` is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) -in GitLab 14.10, and is planned for removal in GitLab 16.0. -In the future only editing an iteration's `description` will be allowed. - Prerequisites: - You must have at least the Reporter role for a group. +- [Automatic scheduling must be disabled](#turn-on-and-off-automatic-scheduling-for-an-iteration-cadence) for the iteration cadence. To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit**. -## Delete an iteration +### Delete an iteration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292268) in GitLab 14.3. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) in GitLab 14.10. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. -WARNING: -Manual iteration management is in its end-of-life process. Deleting an iteration is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/356069) -in GitLab 14.10, and is planned for removal in GitLab 16.0. - Prerequisites: - You must have at least the Reporter role for a group. +- [Automatic scheduling must be disabled](#turn-on-and-off-automatic-scheduling-for-an-iteration-cadence) for the iteration cadence. To delete an iteration, select the three-dot menu (**{ellipsis_v}**) > **Delete**. -## Add an issue to an iteration +### Add an issue to an iteration > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. @@ -176,116 +283,3 @@ To group issues by label: 1. Select the labels you want to group by in the labels dropdown. You can also search for labels by typing in the search input. 1. Select any area outside the label dropdown list. The page is now grouped by the selected labels. - -## Iteration cadences - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1 [with a flag](../../../administration/feature_flags.md), named `iteration_cadences`. Disabled by default. -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/354977) in GitLab 15.0: All scheduled iterations must start on the same day of the week as the cadence start day. Start date of cadence cannot be edited after the first iteration starts. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.0. -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.4: A new automation start date can be selected for cadence. Upcoming iterations will be scheduled to start on the same day of the week as the changed start date. Iteration cadences can be manually managed by turning off the automatic scheduling feature. - -Iteration cadences automate iteration scheduling. You can use them to -automate creating iterations every 1, 2, 3, or 4 weeks. You can also -configure iteration cadences to automatically roll over incomplete issues to the next iteration. - -### Create an iteration cadence - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. - -Prerequisites: - -- You must have at least the Reporter role for a group. - -To create an iteration cadence: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. -1. Select **New iteration cadence**. -1. Enter the title and description of the iteration cadence. -1. To manually manage the iteration cadence, clear the **Enable automatic scheduling** checkbox and skip the next step. -1. Complete the required fields to use automatic scheduling. - - Select the automation start date of the iteration cadence. Iterations will be scheduled to - begin on the same day of the week as the day of the week of the start date. - - From the **Duration** dropdown list, select how many weeks each iteration should last. - - From the **Upcoming iterations** dropdown list, select how many upcoming iterations should be - created and maintained by GitLab. - - Optional. To move incomplete issues to the next iteration, select **Roll over issues**. -1. Select **Create cadence**. The cadence list page opens. - -### Edit an iteration cadence - -Prerequisites: - -- You must have at least the Developer role for a group. - -To edit an iteration cadence: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. -1. Select **Edit iteration cadence**. - -When you are using automatic scheduling and edit the **Automation start date** field, -you must set a new start date that doesn't overlap with the existing -current or past iterations. - -Editing **Upcoming iterations** is a non-destructive action. -If ten upcoming iterations already exist, changing the number under **Upcoming iterations** to `2` -doesn't delete the eight existing upcoming iterations. - -#### Turn on automatic scheduling for manual iterations cadence - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. -1. Select the three-dot menu (**{ellipsis_v}**) > **Edit cadence** for the cadence for which you want to enable automatic scheduling. -1. Check the **Enable automatic scheduling** checkbox. -1. Complete the required fields **Duration**, **Upcoming iterations**, and **Automation start date**. -For **Automation start date**, you can select any date that doesn't overlap with the existing open iterations. -If you have upcoming iterations, the automatic scheduling adjusts them appropriately to fit -your chosen duration. -1. Select **Save changes**. - -When you want to manage your iterations cadence manually again, edit your cadence and uncheck the **Enable automatic scheduling** checkbox. - -#### Example of turning on automatic scheduling for manual iterations cadence - -Suppose it's Friday, April 15, and you have three iteration in a manual iterations cadence: - -- Monday, April 4 - Friday, April 8 (closed) -- Tuesday, April 12 - Friday, April 15 (ongoing) -- Tuesday, May 3 - Friday, May 6 (upcoming) - -The earliest possible **Automation start date** you can choose -is Saturday, April 16 in this scenario, because April 15 overlaps with -the ongoing iteration. - -If you select Monday, April 18 as the automation start date to -automate scheduling iterations every week up to two upcoming iterations, -after the conversion you have the following iterations: - -- Monday, April 4 - Friday, April 8 (closed) -- Tuesday, April 12 - Friday, April 15 (ongoing) -- Monday, April 18 - Sunday, April 24 (upcoming) -- Monday, April 25 - Sunday, May 1 (upcoming) - -Your existing upcoming iteration "Tuesday, April 12 - Friday, April 15" -is changed to "April 18 - Sunday, April 24". - -An additional upcoming iteration "April 25 - Sunday, May 1" is scheduled -to satisfy the requirement that there are at least two upcoming iterations scheduled. - -### Delete an iteration cadence - -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/343889) the minimum user role from Developer to Reporter in GitLab 15.0. - -Prerequisites: - -- You must have at least the Reporter role for a group. - -Deleting an iteration cadence also deletes all iterations within that cadence. - -To delete an iteration cadence: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Issues > Iterations**. -1. Select the three-dot menu (**{ellipsis_v}**) > **Delete cadence** for the cadence you want to delete. -1. Select **Delete cadence**. diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index ca9ff0d7b3e..f11d9035a52 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage groups @@ -127,6 +127,11 @@ To find members in a group, you can sort, filter, or search. Filter a group to find members. By default, all members in the group and subgroups are displayed. +In lists of group members, entries can display the following badges: + +- **SAML**, to indicate the member has a [SAML account](saml_sso/index.md) connected to them. +- **Enterprise**, to indicate that [SCIM created the account](saml_sso/scim_setup.md). + 1. On the top bar, select **Main menu > Groups** and find your group. 1. Above the list of members, in the **Filter members** box, enter filter criteria. - To view members in the group only, select **Membership = Direct**. @@ -158,6 +163,10 @@ 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: + +- You must have the Owner role. + 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Members**. 1. Select **Invite members**. @@ -376,6 +385,214 @@ To enable delayed deletion of projects in a group: NOTE: In GitLab 13.11 and above the group setting for delayed project deletion is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md) inheritance can be overridden, unless enforced by an ancestor. +## Compliance frameworks **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. + +You can create a compliance framework that is a label to identify that your project has certain compliance +requirements or needs additional oversight. The label can optionally enforce +[compliance pipeline configuration](#configure-a-compliance-pipeline) to the projects on which it is +[applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). + +Group owners can create, edit, and delete compliance frameworks: + +1. On the top bar, select **Main menu > Groups > View all groups** and find your group. +1. On the left sidebar, select **Settings** > **General**. +1. Expand the **Compliance frameworks** section. +1. Create, edit, or delete compliance frameworks. + +### Configure a compliance pipeline **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../administration/feature_flags.md). +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. + +Group owners can configure a compliance pipeline in a project separate to other projects. By default, the compliance +pipeline configuration (`.gitlab-ci.yml` file) is run instead of the pipeline configuration of labeled projects. + +However, the compliance pipeline configuration can reference the `.gitlab-ci.yml` file of the labeled projects so that: + +- The compliance pipeline can also run jobs of labeled project pipelines. This allows for centralized control of + pipeline configuration. +- Jobs and variables defined in the compliance pipeline can't be changed by variables in the labeled project's + `.gitlab-ci.yml` file. + +See [example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from +labeled project pipeline configuration. + +To configure a compliance pipeline: + +1. On the top bar, select **Main menu > Groups > View all groups** and find your group. +1. On the left sidebar, select **Settings** > **General**. +1. Expand the **Compliance frameworks** section. +1. In **Compliance pipeline configuration (optional)**, add the path to the compliance framework configuration. Use the + `path/file.y[a]ml@group-name/project-name` format. For example: + + - `.compliance-ci.yml@gitlab-org/gitlab`. + - `.compliance-ci.yaml@gitlab-org/gitlab`. + +This configuration is inherited by projects where the compliance framework label is +[applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). In projects with the applied compliance +framework label, the compliance pipeline configuration is run instead of the labeled project's own pipeline configuration. + +The user running the pipeline in the labeled project must at least have the Reporter role on the compliance project. + +When used to enforce scan execution, this feature has some overlap with +[scan execution policies](../application_security/policies/scan-execution-policies.md). We have not +[unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on +the similarities and differences between these features, see [Enforce scan execution](../application_security/index.md#enforce-scan-execution). + +#### Example configuration + +The following example `.compliance-gitlab-ci.yml` includes the `include` keyword to ensure labeled project pipeline +configuration is also executed. + +```yaml +# Allows compliance team to control the ordering and interweaving of stages/jobs. +# Stages without jobs defined will remain hidden. +stages: + - pre-compliance + - build + - test + - pre-deploy-compliance + - deploy + - post-compliance + +variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml + FOO: sast + +sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml + variables: + FOO: sast + image: ruby:2.6 + stage: pre-compliance + rules: + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success + allow_failure: false + before_script: + - "# No before scripts." + script: + - echo "running $FOO" + after_script: + - "# No after scripts." + +sanity check: + image: ruby:2.6 + stage: pre-deploy-compliance + rules: + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success + allow_failure: false + before_script: + - "# No before scripts." + script: + - echo "running $FOO" + after_script: + - "# No after scripts." + +audit trail: + image: ruby:2.7 + stage: post-compliance + rules: + - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" + when: never + - when: always # or when: on_success + allow_failure: false + before_script: + - "# No before scripts." + script: + - echo "running $FOO" + after_script: + - "# No after scripts." + +include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) + project: '$CI_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch +``` + +##### CF pipelines in Merge Requests originating in project forks + +When an MR originates in a fork, the branch to be merged usually only exists in the fork. +When creating such an MR against a project with CF pipelines, the above snippet will fail with a +`Project <project-name> reference <branch-name> does not exist!` error message. +This is because in the context of the target project, `$CI_COMMIT_REF_NAME` evaluates to a non-existing branch name. + +To get the correct context, use `$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` instead of `$CI_PROJECT_PATH`. +This variable is only availabe in +[merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). + +For example, for a configuration that supports both branch pipelines, as well as merge request pipelines originating in project forks, +you need to [combine both `include` directives with `rules:if`](../../ci/yaml/includes.md#use-rules-with-include): + +```yaml +include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) + - project: '$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_REF_NAME' + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' + - project: '$CI_PROJECT_PATH' + file: '$CI_CONFIG_PATH' + ref: '$CI_COMMIT_REF_NAME' + rules: + - if: $CI_PIPELINE_SOURCE != 'merge_request_event' +``` + +### Ensure compliance jobs are always run + +Compliance pipelines [use GitLab CI/CD](../../ci/index.md) to give you an incredible amount of flexibility +for defining any sort of compliance jobs you like. Depending on your goals, these jobs +can be configured to be: + +- Modified by users. +- Non-modifiable. + +Generally, if a value in a compliance job: + +- Is set, it cannot be changed or overridden by project-level configurations. +- Is not set, a project-level configuration may set. + +Either might be wanted or not depending on your use case. + +There are a few best practices for ensuring that these jobs are always run exactly +as you define them and that downstream, project-level pipeline configurations +cannot change them: + +- Add [a `rules:when:always` block](../../ci/yaml/index.md#when) to each of your compliance jobs. This ensures they are + 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. + - 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. +- Explicitly set any relevant GitLab pre-defined [job keywords](../../ci/yaml/index.md#job-keywords). + This ensures that your job uses the settings you intend and that they are not overridden by + project-level pipelines. + +### Avoid parent and child pipelines in GitLab 14.7 and earlier + +NOTE: +This advice does not apply to GitLab 14.8 and later because [a fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78878) added +compatibility for combining compliance pipelines, and parent and child pipelines. + +Compliance pipelines start on the run of _every_ pipeline in a labeled project. This means that if a pipeline in the labeled project +triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. + +Therefore, in projects with compliance frameworks, we recommend replacing +[parent-child pipelines](../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) with the following: + +- Direct [`include`](../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. +- Child pipelines placed in another project that are run using the [trigger API](../../ci/triggers/index.md) rather than the parent-child + pipeline feature. + +This alternative ensures the compliance pipeline does not re-start the parent pipeline. + ## Disable email notifications > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23585) in GitLab 12.2. @@ -560,9 +777,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 top bar, select **Main menu > Groups > View all groups**. -1. Select **Your Groups**. -1. Find the group and select it. +1. On the top bar, select **Main menu > Groups > View all groups** and find your group. 1. On the left sidebar, select **Group information > Activity**. To view the activity feed in Atom format, select the @@ -590,3 +805,45 @@ To find and store an array of groups based on an SQL query in the [rails console Group.find_by_sql("SELECT * FROM namespaces WHERE name LIKE '%oup'") => [#<Group id:3 @test-group>, #<Group id:4 @template-group/template-subgroup>] ``` + +### Transfer subgroup to another location using Rails console + +If transferring a group doesn't work through the UI or API, you may want to attempt the transfer 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, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +```ruby +user = User.find_by_username('<username>') +group = Group.find_by_name("<group_name>") +## Set parent_group = nil to make the subgroup a top-level group +parent_group = Group.find_by(id: "<group_id>") +service = ::Groups::TransferService.new(group, user) +service.execute(parent_group) +``` + +### Find groups pending deletion using Rails console + +If you need to find all the groups that are pending deletion, you can use the following command in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +Group.all.each do |g| + if g.marked_for_deletion? + puts "Group ID: #{g.id}" + puts "Group name: #{g.name}" + puts "Group path: #{g.full_path}" + end +end +``` + +### Delete a group using Rails console + +At times, a group deletion may get stuck. If needed, in a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session), +you can attempt to delete a group using the following command: + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +```ruby +GroupDestroyWorker.new.perform(group_id, user_id) +``` diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md index 6ffc47923f2..baa2a4d6046 100644 --- a/doc/user/group/planning_hierarchy/index.md +++ b/doc/user/group/planning_hierarchy/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Planning hierarchies **(PREMIUM)** diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index f130ecb61dc..0a4d7f5eae4 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 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repositories analytics for groups **(PREMIUM)** diff --git a/doc/user/group/roadmap/img/roadmap_blocked_icon_v15_5.png b/doc/user/group/roadmap/img/roadmap_blocked_icon_v15_5.png Binary files differnew file mode 100644 index 00000000000..52130672e5a --- /dev/null +++ b/doc/user/group/roadmap/img/roadmap_blocked_icon_v15_5.png diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 10ca6d139ad..28431cb6b9a 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Roadmap **(PREMIUM)** @@ -146,6 +146,16 @@ the timeline header represent the days of the week. The timeline bar indicates the approximate position of an epic or milestone based on its start and due dates. +## Blocked epics **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33587) in GitLab 15.5: View blocking epics when hovering over the “blocked” icon. + +If an epic is [blocked by another epic](../epics/linked_epics.md#blocking-epics), an icon appears next to its title to indicate its blocked status. + +When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. + + + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index d09a8524247..aef39f587ef 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -9,7 +9,7 @@ type: reference These are notes and screenshots regarding Group SAML and SCIM that the GitLab Support Team sometimes uses while troubleshooting, but which do not fit into the official documentation. GitLab is making this public, so that anyone can make use of the Support team's collected knowledge. -Please refer to the GitLab [Group SAML](index.md) docs for information on the feature and how to set it up. +Refer to the GitLab [Group SAML](index.md) documentation for information on the feature and how to set it up. When troubleshooting a SAML configuration, GitLab team members will frequently start with the [SAML troubleshooting section](index.md#troubleshooting). diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 322b417d466..3a50470ce50 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAML Group Sync **(PREMIUM)** diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index d33cde0a6b1..fa6f378e811 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,8 +1,7 @@ --- -type: reference, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SAML SSO for GitLab.com groups **(PREMIUM SAAS)** @@ -32,8 +31,8 @@ If required, you can find [a glossary of common terms](../../../integration/saml See [specific identity provider documentation](#providers) for more details. 1. Configure the SAML response to include a [NameID](#nameid) that uniquely identifies each user. 1. Configure the required [user attributes](#user-attributes), ensuring you include the user's email address. -1. While the default is enabled for most SAML providers, please ensure the app is set to have service provider - initiated calls in order to link existing GitLab accounts. +1. While the default is enabled for most SAML providers, ensure the app is set to have service provider + initiated calls to link existing GitLab accounts. 1. Once the identity provider is set up, move on to [configuring GitLab](#configure-gitlab).  @@ -122,12 +121,22 @@ It can also help to compare the XML response from your provider with our [exampl > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Enabled on GitLab.com. -With this option enabled, users must access GitLab using your group GitLab single sign-on URL to access group resources. -Users can't be added as new members manually. -Users with the Owner role can use the standard sign in process to make necessary changes to top-level group settings. +SSO is enforced when users access groups and projects in the organization's group hierarchy. Users can view other groups and projects without SSO sign in. + +When SAML SSO is enabled, SSO is enforced for each user with an existing SAML identity. +A user has a SAML identity if one or both of the following are true: + +- They have signed in to GitLab by using their GitLab group's single sign-on URL. +- They were provisioned by SCIM. -SSO enforcement does not affect sign in or access to any resources outside of the group. Users can view which groups and projects they are a member of without SSO sign in. +Users without SAML identities are not required to use SSO unless explicit enforcement is enabled. + +When the **Enforce SSO-only authentication for web activity for this group** option is enabled, all users must access GitLab by using their GitLab group's single sign-on URL to access group resources, +regardless of whether they have an existing SAML identity. +Users also cannot be added as new members manually. +Users with the Owner role can use the standard sign in process to make necessary changes to top-level group settings. However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO. If it's been more than 1 day since the last sign-in, GitLab @@ -157,17 +166,17 @@ When SSO is enforced, users are not immediately revoked. If the user: The SAML standard means that you can use a wide range of identity providers with GitLab. Your identity provider might have relevant documentation. It can be generic SAML documentation or specifically targeted for GitLab. -When [configuring your identity provider](#configure-your-identity-provider), please consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. +When [configuring your identity provider](#configure-your-identity-provider), consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. For providers not listed below, you can refer to the [instance SAML notes on configuring an identity provider](../../../integration/saml.md#notes-on-configuring-your-identity-provider) for additional guidance on information your identity provider may require. GitLab provides the following information for guidance only. -If you have any questions on configuring the SAML app, please contact your provider's support. +If you have any questions on configuring the SAML app, contact your provider's support. ### Azure setup notes -Follow the Azure documentation on [configuring single sign-on to applications](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) with the notes below for consideration. +Follow the Azure documentation on [configuring single sign-on to applications](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) with the notes below for consideration. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). @@ -225,7 +234,7 @@ See our [example configuration page](example_saml_config.md#google-workspace). ### Okta setup notes -Please follow the Okta documentation on [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/) with the notes below for consideration. +Follow the Okta documentation on [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/) with the notes below for consideration. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ). @@ -237,13 +246,16 @@ For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & S | GitLab single sign-on URL | Login page URL (under **Application Login Page** settings) | | Identity provider single sign-on URL | Identity Provider Single Sign-On URL | -Under Okta's **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**. +Under the Okta **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**. For NameID, the following settings are recommended; for SCIM, the following settings are required: - **Application username** (NameID) set to **Custom** `user.getInternalProperty("id")`. - **Name ID Format** set to **Persistent**. +The Okta GitLab application available in the App Catalog only supports [SCIM](scim_setup.md). Support +for SAML is proposed in issue [216173](https://gitlab.com/gitlab-org/gitlab/-/issues/216173). + ### OneLogin setup notes OneLogin supports their own [GitLab (SaaS)](https://onelogin.service-now.com/support?id=kb_article&sys_id=92e4160adbf16cd0ca1c400e0b961923&kb_category=50984e84db738300d5505eea4b961913) @@ -296,7 +308,7 @@ To migrate users to a new email domain, users must: > SAML user provisioning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. -Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). +Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). When a user tries to sign in with Group SSO, GitLab attempts to find or create a user based on the following: @@ -383,8 +395,8 @@ convert the information to XML. An example SAML response is shown here. By default, users provisioned with SAML or SCIM are sent a verification email to verify their identity. Instead, you can [configure GitLab with a custom domain](../../project/pages/custom_domains_ssl_tls_certification/index.md) and GitLab -will automatically confirm user accounts. Users will still receive an enterprise user welcome email. -Confirmation is bypassed for users: +automatically confirms user accounts. Users still receive an enterprise user welcome email. Confirmation is bypassed for +users: - That are provisioned with SAML or SCIM. - That have an email address that belongs to the verified domain. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index a67b2fbe02e..55990336a50 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,14 +1,11 @@ --- -type: howto, reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure SCIM for GitLab.com groups **(PREMIUM SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10. - You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically: - Create users. @@ -18,7 +15,7 @@ GitLab SAML SSO SCIM doesn't support updating users. When SCIM is enabled for a GitLab group, membership of that group is synchronized between GitLab and an identity provider. -The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). +The [internal GitLab SCIM API](../../../development/internal_api/index.md#scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). ## Configure GitLab @@ -48,8 +45,12 @@ Other providers can work with GitLab but they have not been tested and are not s ### Configure Azure Active Directory +Prerequisites: + +- [GitLab is configured](#configure-gitlab). + The SAML application created during [single sign-on](index.md) set up for -[Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) +[Azure Active Directory](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) must be set up for SCIM. For an example, see [example configuration](example_saml_config.md#scim-mapping). To configure Azure Active Directory for SCIM: @@ -60,7 +61,7 @@ To configure Azure Active Directory for SCIM: - **SCIM API endpoint URL** in GitLab for the **Tenant URL** field. - **Your SCIM token** in GitLab for the **Secret Token** field. 1. Select **Test Connection**. If the test is successful, save your configuration before continuing, or see the - [troubleshooting](#troubleshooting) information. + [troubleshooting](troubleshooting.md) information. 1. Select **Save**. After saving, **Settings** and **Mappings** sections appear. @@ -120,49 +121,52 @@ attributes and modify them accordingly. In particular, the `objectId` source att target attribute. If a mapping is not listed in the table, use the Azure Active Directory defaults. For a list of required attributes, -refer to the [SCIM API documentation](../../../api/scim.md). +refer to the [internal SCIM API](../../../development/internal_api/index.md#scim-api) documentation. ### Configure Okta -Before you start this section: +The SAML application created during [single sign-on](index.md) set up for Okta must be set up for SCIM. -- Check that you are using Okta [Lifecycle Management](https://www.okta.com/products/lifecycle-management/) product. This product tier is required to use SCIM on Okta. To check which Okta product you are using, check your signed Okta contract, contact your Okta AE, CSM, or Okta support. -- Complete the [GitLab configuration](#configure-gitlab) process. -- Complete the setup for SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/), as described in the [Okta setup notes](index.md#okta-setup-notes). -- Check that your Okta SAML setup matches our documentation exactly, especially the NameID configuration. Otherwise, the Okta SCIM app may not work properly. +Prerequisites: + +- You must use the Okta [Lifecycle Management](https://www.okta.com/products/lifecycle-management/) product. This + product tier is required to use SCIM on Okta. +- [GitLab is configured](#configure-gitlab). +- SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/) set up as + described in the [Okta setup notes](index.md#okta-setup-notes). +- Your Okta SAML setup matches the [configuration steps exactly](index.md), especially the NameID configuration. -After the above steps are complete: +To configure Okta for SCIM: 1. Sign in to Okta. 1. Ensure you are in the Admin Area by selecting the **Admin** button located in the top right. The button is not visible from the Admin Area. 1. In the **Application** tab, select **Browse App Catalog**. -1. Search for **GitLab**, find and select the 'GitLab' application. +1. Search for **GitLab**, find and select the **GitLab** application. 1. On the GitLab application overview page, select **Add**. -1. Under **Application Visibility** select both checkboxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users. +1. Under **Application Visibility** select both checkboxes. Currently the GitLab application does not support SAML + authentication so the icon should not be shown to users. 1. Select **Done** to finish adding the application. 1. In the **Provisioning** tab, select **Configure API integration**. 1. Select **Enable API integration**. - - For **Base URL** enter the URL obtained from the GitLab SCIM configuration page - - For **API Token** enter the SCIM token obtained from the GitLab SCIM configuration page -1. Select 'Test API Credentials' to verify configuration. -1. Select **Save** to apply the settings. + - For **Base URL**, paste the URL you copied from **SCIM API endpoint URL** on the GitLab SCIM configuration page. + - For **API Token**, paste the SCIM token you copied from **Your SCIM token** on the GitLab SCIM + configuration page. +1. To verify the configuration, select **Test API Credentials**. +1. Select **Save**. 1. After saving the API integration details, new settings tabs appear on the left. Select **To App**. 1. Select **Edit**. 1. Select the **Enable** checkbox for both **Create Users** and **Deactivate Users**. 1. Select **Save**. -1. Assign users in the **Assignments** tab. Assigned users are created and - managed in your GitLab group. +1. Assign users in the **Assignments** tab. Assigned users are created and managed in your GitLab group. -#### Okta Known Issues +### Configure OneLogin -The Okta GitLab application currently only supports SCIM. Continue -using the separate Okta [SAML SSO](index.md) configuration along with the new SCIM -application described above. An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/216173) to add SAML support to the Okta GitLab application. +Prerequisites: -### Configure OneLogin +- [GitLab is configured](#configure-gitlab). -As the developers of this app, OneLogin provides a "GitLab (SaaS)" app in their catalog, which includes a SCIM integration. -Please reach out to OneLogin if you encounter issues. +OneLogin provides a **GitLab (SaaS)** app in their catalog, which includes a SCIM integration. Contact OneLogin if you +encounter issues. ## User access and linking setup @@ -199,11 +203,11 @@ New users and existing users on subsequent visits can access the group through t  -For role information, please see the [Group SAML page](index.md#user-access-and-management) +For role information, see the [Group SAML page](index.md#user-access-and-management) ### Blocking access -To rescind access to the top-level group, all sub-groups, and projects, remove or deactivate the user +To rescind access to the top-level group, all subgroups, and projects, remove or deactivate the user on the identity provider. After the identity provider performs a sync, based on its configured schedule, the user's membership is revoked and they lose access. NOTE: @@ -215,125 +219,3 @@ graph TD B -->|No| C[Nothing to do] B -->|Yes| D[GitLab removes user from GitLab group] ``` - -## Troubleshooting - -This section contains possible solutions for problems you might encounter. - -### How come I can't add a user after I removed them? - -As outlined in the [Blocking access section](#blocking-access), when you remove a user, they are removed from the group. However, their account is not deleted. - -When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists. - -Solution: Have a user sign in directly to GitLab, then [manually link](#user-access-and-linking-setup) their account. - -### How do I diagnose why a user is unable to sign in - -Ensure that the user has been added to the SCIM app. - -If you receive "User is not linked to a SAML account", then most likely the user already exists in GitLab. Have the user follow the [User access and linking setup](#user-access-and-linking-setup) instructions. - -The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users cannot sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. - -This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. - -It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](troubleshooting.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](troubleshooting.md). - -### How do I verify user's SAML NameId matches the SCIM externalId - -Admins can use the Admin Area to [list SCIM identities for a user](../../admin_area/index.md#user-identities). - -Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. - -A possible alternative is to use the [SCIM API](../../../api/scim.md#get-a-list-of-scim-provisioned-users) to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. - -To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools). - -### Update or fix mismatched SCIM externalId and SAML NameId - -Whether the value was changed or you need to map to a different field, ensure `id`, `externalId`, and `NameId` all map to the same field. - -If the GitLab `externalId` doesn't match the SAML NameId, it needs to be updated in order for the user to sign in. Ideally your identity provider is configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. - -Be cautious if you revise the fields used by your SCIM identity provider, typically `id` and `externalId`. -We use these IDs to look up users. If the identity provider does not know the current values for these fields, -that provider may create duplicate users. - -If the `externalId` for a user is not correct, and also doesn't match the SAML NameID, -you can address the problem in the following ways: - -- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](troubleshooting.md#message-saml-authentication-failed-user-has-already-been-taken) section. -- You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on. -- It may be possible to use the [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) to manually correct the `externalId` stored for users to match the SAML `NameId`. - To look up a user, you need to know the desired value that matches the `NameId` as well as the current `externalId`. - -It is important not to update these to incorrect values, since this causes users to be unable to sign in. It is also important not to assign a value to the wrong user, as this causes users to get signed into the wrong account. - -### I need to change my SCIM app - -Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#change-the-saml-app) section. - -Alternatively, users can be removed from the SCIM app which de-links all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). - -### The SCIM app is throwing `"User has already been taken","status":409` error message - -Changing the SAML or SCIM configuration or provider can cause the following problems: - -| Problem | Solution | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | -| SCIM identity mismatch between GitLab and the identity provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-scim-provisioned-user) to update the SCIM `id` for the user on GitLab.com. | - -### Search Rails logs for SCIM requests - -GitLab.com administrators can search for SCIM requests in the `api_json.log` using the `pubsub-rails-inf-gprd-*` index in [Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html#using-kibana). Use the following filters based on the [SCIM API](../../../api/scim.md): - -- `json.path`: `/scim/v2/groups/<group-path>` -- `json.params.value`: `<externalId>` - -In a relevant log entry, the `json.params.value` shows the values of SCIM parameters GitLab receives. These values can be used to verify if SCIM parameters configured in an -identity provider's SCIM app are communicated to GitLab as intended. For example, we can use these values as a definitive source on why an account was provisioned with a certain -set of details. This information can help where an account was SCIM provisioned with details that appear to be incongruent with what might have been configured within an identity -provider's SCIM app. - -### Azure - -#### How do I verify my SCIM configuration is correct? - -Review the following: - -- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. -- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. - -Review the following SCIM parameters for sensible values: - -- `userName` -- `displayName` -- `emails[type eq "work"].value` - -#### Testing Azure connection: invalid credentials - -When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. - -#### (Field) can't be blank sync error - -When checking the Audit Events for the Provisioning, you can sometimes see the -error `Namespace can't be blank, Name can't be blank, and User can't be blank.` - -This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. - -As a workaround, try an alternate mapping: - -1. Follow the Azure mapping instructions from above. -1. Delete the `name.formatted` target attribute entry. -1. Change the `displayName` source attribute to have `name.formatted` target attribute. - -#### Failed to match an entry in the source and target systems Group 'Group-Name' - -Group provisioning in Azure can fail with the `Failed to match an entry in the source and target systems Group 'Group-Name'` error message, -and the error response can include a HTML result of the GitLab URL `https://gitlab.com/users/sign_in`. - -This error is harmless and occurs because Group provisioning was turned on but GitLab SCIM integration does not support it nor require it. To -remove the error, follow the instructions in the Azure configuration guide to disable the option -[`Synchronize Azure Active Directory Groups to AppName`](#configure-azure-active-directory). diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index 177f33228c0..bde5ed1762a 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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 SAML **(FREE)** @@ -39,7 +39,7 @@ To generate a SAML Response: console. - Firefox: Select the SAML-tracer icon located on the browser toolbar. 1. Go to the GitLab single sign-on URL for the group in the same browser tab with the SAML tracer open. -1. Select **Authorize** or attempt to log in. A SAML response is displayed in the tracer console that resembles this +1. Select **Authorize** or attempt to sign in. A SAML response is displayed in the tracer console that resembles this [example SAML response](index.md#example-saml-response). 1. Within the SAML tracer, select the **Export** icon to save the response in JSON format. @@ -76,6 +76,19 @@ In a relevant log entry, the `json.params` should provide a valid response with: - `"key": "RelayState"` with `"value": "/group-path"`, and - `"key": "group_id"` with `"value": "group-path"`. +You should also check the decoded SAML response with the following filters +in case the customer has [configured SAML Group Sync](group_sync.md): + +- `json.class`: `GroupSamlGroupSyncWorker` +- `json.args`: `<user ID> or <group ID>` + +In the relevant log entry, the: + +- `json.args` are in the form `<userID>, <group ID>, + [group link ID 1, group link ID 2, ..., group link ID N]`. +- `json.extra.group_saml_group_sync_worker.stats.*` fields show how many times + this run of group sync `added`, `removed` or `changed` the user's membership. + In some cases, if the SAML response is lengthy, you may receive a `"key": "truncated"` with `"value":"..."`. In these cases, use one of the [SAML debugging tools](#saml-debugging-tools), or for SAML SSO for groups, a group owner can get a copy of the SAML response from when they select @@ -175,7 +188,7 @@ initiated by the service provider and not only the identity provider. A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account). -To resolve this problem, the user should check they are using the correct GitLab password to log in. The user first needs +To resolve this problem, the user should check they are using the correct GitLab password to sign in. The user first needs to [reset their password](https://gitlab.com/users/password/new) if both: - The account was provisioned by SCIM. @@ -191,7 +204,7 @@ For self-managed, administrators can use the [users API](../../../api/users.md) When using SAML for groups, group members of a role with the appropriate permissions can make use of the [members API](../../../api/members.md) to view group SAML identity information for members of the group. -This can then be compared to the NameID being sent by the identity provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match in order to identify users. +This can then be compared to the NameID being sent by the identity provider by decoding the message with a [SAML debugging tool](#saml-debugging-tools). We require that these match to identify users. ### Stuck in a login "loop" @@ -202,7 +215,7 @@ For GitLab.com, alternatively, when users need to [link SAML to their existing G ### Users receive a 404 **(PREMIUM SAAS)** Because SAML SSO for groups is a paid feature, your subscription expiring can result in a `404` error when you're signing in using SAML SSO on GitLab.com. -If all users are receiving a `404` when attempting to log in using SAML, confirm +If all users are receiving a `404` when attempting to sign in using SAML, confirm [there is an active subscription](../../../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) being used in this SAML SSO namespace. If you receive a `404` during setup when using "verify configuration", make sure you have used the correct diff --git a/doc/user/group/saml_sso/troubleshooting_scim.md b/doc/user/group/saml_sso/troubleshooting_scim.md new file mode 100644 index 00000000000..6f8aed4b386 --- /dev/null +++ b/doc/user/group/saml_sso/troubleshooting_scim.md @@ -0,0 +1,129 @@ +--- +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting SCIM **(PREMIUM SAAS)** + +This section contains possible solutions for problems you might encounter. + +## How come I can't add a user after I removed them? + +As outlined in the [Blocking access section](scim_setup.md#blocking-access), when you remove a user, they are removed from the group. However, their account is not deleted. + +When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists. + +Solution: Have a user sign in directly to GitLab, then [manually link](scim_setup.md#user-access-and-linking-setup) their account. + +## How do I diagnose why a user is unable to sign in + +Ensure that the user has been added to the SCIM app. + +If you receive "User is not linked to a SAML account", then most likely the user already exists in GitLab. Have the user follow the [User access and linking setup](scim_setup.md#user-access-and-linking-setup) instructions. + +The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users cannot sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. + +This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. + +It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](troubleshooting.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](troubleshooting.md). + +## How do I verify user's SAML NameId matches the SCIM externalId + +Administrators can use the Admin Area to [list SCIM identities for a user](../../admin_area/index.md#user-identities). + +Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. + +A possible alternative is to use the [SCIM API](../../../api/scim.md) to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. + +To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](troubleshooting.md#saml-debugging-tools). + +## Update or fix mismatched SCIM externalId and SAML NameId + +Whether the value was changed or you need to map to a different field, ensure `id`, `externalId`, and `NameId` all map to the same field. + +If the GitLab `externalId` doesn't match the SAML NameId, it needs to be updated in order for the user to sign in. Ideally your identity provider is configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. + +Be cautious if you revise the fields used by your SCIM identity provider, typically `id` and `externalId`. +We use these IDs to look up users. If the identity provider does not know the current values for these fields, +that provider may create duplicate users. + +If the `externalId` for a user is not correct, and also doesn't match the SAML NameID, +you can address the problem in the following ways: + +- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](troubleshooting.md#message-saml-authentication-failed-user-has-already-been-taken) section. +- You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on. +- Use the [SCIM API](../../../api/scim.md) to manually correct the `externalId` stored for users to match the SAML `NameId`. + To look up a user, you need to know the desired value that matches the `NameId` as well as the current `externalId`. + +It is important not to update these to incorrect values, since this causes users to be unable to sign in. It is also important not to assign a value to the wrong user, as this causes users to get signed into the wrong account. + +## I need to change my SCIM app + +Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#change-the-saml-app) section. + +Alternatively, users can be removed from the SCIM app which de-links all removed users. Sync can then be turned on for the new SCIM app to [link existing users](scim_setup.md#user-access-and-linking-setup). + +## The SCIM app is throwing `"User has already been taken","status":409` error message + +Changing the SAML or SCIM configuration or provider can cause the following problems: + +| Problem | Solution | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | +| SCIM identity mismatch between GitLab and the identity provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using the [SCIM API](../../../api/scim.md) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md) to update the SCIM `id` for the user on GitLab.com. | + +## Search Rails logs for SCIM requests + +GitLab.com administrators can search for SCIM requests in the `api_json.log` using the `pubsub-rails-inf-gprd-*` index in +[Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html#using-kibana). Use the following filters based on the internal +[SCIM API](../../../development/internal_api/index.md#scim-api): + +- `json.path`: `/scim/v2/groups/<group-path>` +- `json.params.value`: `<externalId>` + +In a relevant log entry, the `json.params.value` shows the values of SCIM parameters GitLab receives. These values can be used to verify if SCIM parameters configured in an +identity provider's SCIM app are communicated to GitLab as intended. For example, we can use these values as a definitive source on why an account was provisioned with a certain +set of details. This information can help where an account was SCIM provisioned with details that appear to be incongruent with what might have been configured within an identity +provider's SCIM app. + +## Azure + +### How do I verify my SCIM configuration is correct? + +Review the following: + +- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. +- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. + +Review the following SCIM parameters for sensible values: + +- `userName` +- `displayName` +- `emails[type eq "work"].value` + +### Testing Azure connection: invalid credentials + +When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. + +### (Field) can't be blank sync error + +When checking the Audit Events for the Provisioning, you can sometimes see the +error `Namespace can't be blank, Name can't be blank, and User can't be blank.` + +This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. + +As a workaround, try an alternate mapping: + +1. Follow the Azure mapping instructions from above. +1. Delete the `name.formatted` target attribute entry. +1. Change the `displayName` source attribute to have `name.formatted` target attribute. + +### Failed to match an entry in the source and target systems Group 'Group-Name' + +Group provisioning in Azure can fail with the `Failed to match an entry in the source and target systems Group 'Group-Name'` error message, +and the error response can include a HTML result of the GitLab URL `https://gitlab.com/users/sign_in`. + +This error is harmless and occurs because Group provisioning was turned on but GitLab SCIM integration does not support it nor require it. To +remove the error, follow the instructions in the Azure configuration guide to disable the option +[`Synchronize Azure Active Directory Groups to AppName`](scim_setup.md#configure-azure-active-directory). diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index eb9c6af9edf..158e1654c6e 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -48,6 +48,9 @@ You cannot use group access tokens to create other group, project, or personal a Group access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. +NOTE: +Group access tokens are not FIPS compliant and creation and use are disabled when [FIPS mode](../../../development/fips_compliance.md) is enabled. + ## Create a group access token using UI > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. @@ -137,14 +140,14 @@ The scope determines the actions you can perform when you authenticate with a gr |:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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` | Allows 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` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). | -| `read_repository` | Allows read access (pull) to all repositories within a group. | -| `write_repository` | Allows read and write access (pull and push) to all repositories within a group. | +| `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. | ## Enable or disable group access token creation -To enable or disable group access token creation for all sub-groups in a top-level group: +To enable or disable group access token creation for all subgroups in a top-level group: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 7a398c7d086..cec17688902 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating groups using file exports (deprecated) **(FREE)** @@ -48,7 +48,15 @@ sure these users exist before importing the desired groups. ### Exported contents -The following items are exported: +The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/import_export.yml) +file for groups lists many of the items exported and imported when migrating groups using file exports. View this file in the branch +for your version of GitLab to see the list of items relevant to you. For example, +[`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/group/import_export.yml). + +Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../custom_project_templates.md) and +[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. + +Items that are exported include: - Milestones - Labels @@ -60,8 +68,9 @@ The following items are exported: - Events - [Wikis](../../project/wiki/group.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9) +- Iterations cadences ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95372) in 15.4) -The following items are **not** exported: +Items that are **not** exported include: - Projects - Runner tokens diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 657ef361bd5..58f5e476f26 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Subgroups **(FREE)** @@ -201,7 +201,7 @@ role on an ancestor group, add the user to the subgroup again with a higher role ## 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 sub-group are not notified by mentions. Mentioning works the same as for projects and groups, and you can choose the group +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. <!-- ## Troubleshooting diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 9078874d32c..fcf4189aa32 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -1,8 +1,8 @@ --- type: reference -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Value stream analytics for groups **(PREMIUM)** @@ -28,7 +28,7 @@ Value stream analytics is also available for [projects](../../analytics/value_st > - 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 -Prerequisite: +Prerequisites: - You must have at least the Reporter role to view value stream analytics for groups. - You must create a [custom value stream](#create-a-value-stream-with-gitlab-default-stages). Value stream analytics only shows custom value streams created for your group. @@ -68,7 +68,9 @@ The table shows a list of related workflow items for the selected stage. Based o The **Overview** dashboard in value stream analytics shows key metrics and DORA metrics of group performance. Based on the filter you select, the dashboard automatically aggregates DORA metrics and displays the current status of the value stream. Select a DORA metric to view its chart. -To view deployment metrics, you must have a +Prerequisite: + +- To view deployment metrics, you must have a [production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments). To view the DORA metrics and key metrics: @@ -248,7 +250,7 @@ You can change the name of a project environment in your GitLab CI/CD configurat > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 -When you create a value stream, you can use GitLab default stages and hide or re-order them to customize. You can also +When you create a value stream, you can use GitLab default stages and hide or re-order them. You can also create custom stages in addition to those provided in the default template. 1. On the top bar, select **Main menu > Groups** and find your group. diff --git a/doc/user/index.md b/doc/user/index.md index af106b85ce9..81561d23c7b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use GitLab **(FREE)** diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index af728cb5c21..9325f11b0c7 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect a cluster to GitLab **(FREE)** diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md index f9feef6329c..998548e3a5e 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 126968baee7..164b426fd24 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 a23a9e7a6e5..d04b14bf80f 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a Google GKE cluster diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index fc3b86776f0..6bd44c7a0f7 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tracking cluster resources managed by GitLab **(FREE)** diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index 9c8bcd9289c..14fd4917141 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Kubernetes clusters **(FREE)** diff --git a/doc/user/infrastructure/clusters/manage/clusters_health.md b/doc/user/infrastructure/clusters/manage/clusters_health.md index 0eefae3f550..4f63f3e4e2a 100644 --- a/doc/user/infrastructure/clusters/manage/clusters_health.md +++ b/doc/user/infrastructure/clusters/manage/clusters_health.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Clusters health (DEPRECATED) **(FREE)** 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 5f77b7e402a..8b75d54d352 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install cert-manager with a cluster management project **(FREE)** diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md deleted file mode 100644 index 7ab99ab3875..00000000000 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -stage: Monitor -group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-08-22' -redirect_to: '../../index.md' ---- - -# Install Elastic Stack with a cluster management project (removed) **(FREE)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346485) in GitLab 14.8 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/360182) in 15.0. 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 7983a640577..bf86fdb5a8f 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install Ingress with a cluster management project **(FREE)** 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 ef7c4637607..4c68ec42712 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install GitLab Runner with a cluster management project **(FREE)** 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 31a22a240d9..72a44ef2a21 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Install Vault with a cluster management project **(FREE)** @@ -88,7 +88,7 @@ server: After you have successfully installed Vault, you must [initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault) and obtain the initial root token. You need access to your Kubernetes cluster that -Vault has been deployed into in order to do this. To initialize the Vault, get a +Vault has been deployed into to do this. To initialize the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done by using the `kubectl` command line tool). After you have a shell into the pod, run the `vault operator init` command: diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index abdb7c58d82..b2b5da61a81 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: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate to the GitLab agent for Kubernetes **(FREE)** @@ -26,7 +26,7 @@ you can use the [CI/CD workflow](../../clusters/agent/ci_cd_workflow.md). This workflow uses an agent to connect to your cluster. The agent: - Is not exposed to the internet. -- Does not require full cluster-admin access to GitLab. +- Does not require full [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) access to GitLab. NOTE: The certificate-based integration was used for popular GitLab features like diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index d5eabb9ba46..c2285ecc773 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure as Code with Terraform and GitLab **(FREE)** @@ -19,7 +19,7 @@ Terraform to define resources that you can version, reuse, and share: ## Integrate your project with Terraform -> SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. +> IaC Scanning was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. The integration with GitLab and Terraform happens through GitLab CI/CD. Use an `include` attribute to add the Terraform template to your project and @@ -35,7 +35,7 @@ All templates: - Use the [GitLab-managed Terraform state](terraform_state.md) as the Terraform state storage backend. - Trigger four pipeline stages: `test`, `validate`, `build`, and `deploy`. - Run Terraform commands: `test`, `validate`, `plan`, and `plan-json`. It also runs the `apply` only on the default branch. -- Run the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually). +- Check for security problems using [IaC Scanning](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually). ### Latest Terraform template diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index 0fea05a3f03..7b4a7cd6b95 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform integration in merge requests **(FREE)** @@ -85,7 +85,7 @@ To manually configure a GitLab Terraform Report artifact:  -1. Clicking the **View Full Log** button in the widget takes you directly to the +1. Selecting the **View Full Log** button in the widget takes you directly to the plan output present in the pipeline logs:  diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index d4fea6b7dba..9cb3fdd7aaf 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab-managed Terraform state **(FREE)** diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index 3286b550507..a1eecb909fb 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To 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 the Terraform integration with GitLab diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 73e57ea3d59..811e4ad6ad6 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure management **(FREE)** diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 27aa3479b88..eb703328270 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Instance-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE SELF)** diff --git a/doc/user/markdown.md b/doc/user/markdown.md index d61190fbd31..1a743ae99bb 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Flavored Markdown (GLFM) **(FREE)** @@ -1764,6 +1764,7 @@ If JSON is invalid, an error occurs. ## References +- The [GitLab Flavored Markdown (GLFM) Specification Guide](../development/gitlab_flavored_markdown/index.md) is a developer-facing document that describes in detail the various goals, tools, implementations, and terms related to the GLFM specification. - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). - The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard Markdown. diff --git a/doc/user/namespace/index.md b/doc/user/namespace/index.md index 138b0a355ad..36e048868ad 100644 --- a/doc/user/namespace/index.md +++ b/doc/user/namespace/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Namespaces diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 0a7e9d6395b..0a65ea0f64d 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Operations Dashboard **(PREMIUM)** @@ -13,11 +13,6 @@ To access the dashboard, on the top bar, select **Main menu > Operations**. ## Adding a project to the dashboard -NOTE: -For GitLab.com, you can add your project to the Operations Dashboard for free if -your project is public. If your project is private, the group it belongs to must -have a [GitLab Premium](https://about.gitlab.com/pricing/) plan. - To add a project to the dashboard: 1. Ensure your alerts populate the `gitlab_environment_name` label on the alerts you set up in Prometheus. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 84f544ec4ad..5eafb74a144 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Composer packages in the Package Registry **(FREE)** diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index ed106685b62..cd5ce9a1135 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Conan packages in the Package Registry **(FREE)** diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index bfbc400f4dd..1ac38979950 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Container Registry **(FREE)** @@ -101,12 +101,14 @@ registry.example.com/mynamespace/myproject/my/image:rc1 ## Authenticate with the Container Registry -To authenticate with the Container Registry, you can use: +To authenticate with the Container Registry, you can use a: -- A [personal access token](../../profile/personal_access_tokens.md). -- A [deploy token](../../project/deploy_tokens/index.md). +- [Personal access token](../../profile/personal_access_tokens.md). +- [Deploy token](../../project/deploy_tokens/index.md). +- [Project access token](../../project/settings/project_access_tokens.md). +- [Group access token](../../group/settings/group_access_tokens.md). -Both of these require the minimum scope to be: +All of these require the minimum scope to be: - For read (pull) access, `read_registry`. - For write (push) access, `write_registry` & `read_registry`. @@ -397,10 +399,10 @@ To delete images from within GitLab: 1. From the **Container Registry** page, you can select what you want to delete, by either: - - Deleting the entire repository, and all the tags it contains, by clicking + - Deleting the entire repository, and all the tags it contains, by selecting the red **{remove}** **Trash** icon. - Navigating to the repository, and deleting tags individually or in bulk - by clicking the red **{remove}** **Trash** icon next to the tag you want + by selecting the red **{remove}** **Trash** icon next to the tag you want to delete. 1. In the dialog box, select **Remove tag**. @@ -601,7 +603,7 @@ You can then tag the manifest list with `mygroup/myapp:1.0.0`. ### Troubleshoot as a GitLab server administrator Troubleshooting the GitLab Container Registry, most of the times, requires -you to log in to GitLab server with administrator access. +you to sign in to GitLab server with administrator access. [Read how to troubleshoot the Container Registry](../../../administration/packages/container_registry.md#troubleshooting). @@ -711,7 +713,7 @@ Follow [this issue](https://gitlab.com/gitlab-org/container-registry/-/issues/55 GitLab is [migrating to the next generation of the Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/5523). During the migration, you may encounter difficulty deleting tags. If you encounter an error, it's likely that your image repository is in the process of being migrated. -Please wait a few minutes and try again. +Wait a few minutes and try again. ### `unauthorized: authentication required` when pushing large images 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 76e3da9538f..ff89e5f361f 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,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce Container Registry data transfers **(FREE)** 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 b3dd8da9b41..9c981aeac53 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce Container Registry Storage **(FREE)** @@ -11,27 +11,26 @@ Container registries become large over time without cleanup. When a large number - Fetching the list of available tags or images becomes slower. - They take up a large amount of storage space on the server. -We recommend deleting unnecessary images and tags, and setting up a [cleanup policy](#cleanup-policy) +We recommend deleting unnecessary images and tags and setting up a [cleanup policy](#cleanup-policy) to automatically manage your container registry usage. ## Check Container Registry Storage Use The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. -This page includes the Container Registry usage but is currently only available on GitLab.com. +This page includes the Container Registry usage, which is only available on GitLab.com. Measuring usage is only possible on the new version of the GitLab Container Registry backed by a -metadata database. We are completing the [upgrade and migration of the GitLab.com Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/5523) -first and only then will work on [making this available to self-managed installs](https://gitlab.com/groups/gitlab-org/-/epics/5521). +metadata database. Support for improvements is proposed in epic [5523](https://gitlab.com/groups/gitlab-org/-/epics/5523). +You cannot use the Container Registry in self-managed instances, but epic [5521](https://gitlab.com/groups/gitlab-org/-/epics/5521) proposes to change this behavior. Image layers stored in the Container Registry are deduplicated at the root namespace level. -Therefore, if you tag the same 500MB image twice (either in the same repository or across distinct -repositories under the same root namespace), it will only count towards the root namespace usage -once. Similarly, if a given image layer is shared across multiple images, be those under the same -container repository, project, group, or across different ones, that layer will count only once -towards the root namespace usage. +If you tag the same image more than once in the same repository or across distinct +repositories under the same root namespace, it is only counted once. +If an image layer is shared across multiple images, in the same +container repository, project, group, or across different repositories, it is only counted once. Only layers that are referenced by tagged images are accounted for. Untagged images and any layers -referenced exclusively by them are subject to [online garbage collection](index.md#delete-images) -and automatically deleted after 24 hours if they remain unreferenced during that period. +referenced exclusively by them are subject to [online garbage collection](index.md#delete-images). +Untagged images are automatically deleted after 24 hours if they remain unreferenced during that period. Image layers are stored on the storage backend in the original (usually compressed) format. This means that the measured size for any given image layer should match the size displayed on the @@ -39,7 +38,6 @@ corresponding [image manifest](https://github.com/opencontainers/image-spec/blob ## Cleanup policy -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8. > - [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. @@ -56,7 +54,7 @@ Cleanup policies can be run on all projects, with these exceptions: - For self-managed GitLab instances, the project must have been created in GitLab 12.8 or later. However, an administrator can enable the cleanup policy - for all projects (even those created before 12.8) in + for all projects (even those created before GitLab 12.8) in [GitLab application settings](../../../api/settings.md#change-application-settings) by setting `container_expiration_policies_enable_historic_entries` to true. Alternatively, you can execute the following command in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): @@ -65,7 +63,7 @@ Cleanup policies can be run on all projects, with these exceptions: ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true) ``` - There are performance risks with enabling it for all projects, especially if you + Enabling cleanup policies on all project can impact performance, especially if you are using an [external registry](#use-with-external-container-registries). WARNING: @@ -77,7 +75,7 @@ GitLab.com that don't have a container image. The cleanup policy collects all tags in the Container Registry and excludes tags until only the tags to be deleted remain. -The cleanup policy searches for images based on the tag name. Support for the full path [has not yet been implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/281071), but would allow you to clean up dynamically-named tags. +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). The cleanup policy: @@ -92,9 +90,9 @@ The cleanup policy: 1. Finally, the remaining tags in the list are deleted from the Container Registry. WARNING: -On GitLab.com, the execution time for the cleanup policy is limited, and some of the tags may remain in -the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included, -so it may take multiple runs for all tags to be deleted. +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. +It may take multiple runs for all tags to be deleted. WARNING: GitLab self-managed installations support third-party container registries that comply with the @@ -139,7 +137,7 @@ Cleanup policies use regex patterns to determine which tags should be preserved Regex patterns are automatically surrounded with `\A` and `\Z` anchors. Do not include any `\A`, `\Z`, `^` or `$` token in the regex patterns as they are not necessary. -Here are examples of regex patterns you may want to use: +Here are some examples of regex patterns you can use: - Match all tags: @@ -147,7 +145,7 @@ Here are examples of regex patterns you may want to use: .* ``` - This is the default value for the expiration regex. + This pattern is the default value for the expiration regex. - Match tags that start with `v`: @@ -255,9 +253,8 @@ When using an [external container registry](../../../administration/packages/con running a cleanup policy on a project may have some performance risks. If a project runs a policy to remove thousands of tags the GitLab background jobs may get backed up or fail completely. -It is recommended you only enable container cleanup -policies for projects that were created before GitLab 12.8 if you are confident the number of tags -being cleaned up is minimal. +For projects created before GitLab 12.8, we recommend you enable container cleanup policies +only if the number of tags being cleaned up is minimal. ## More Container Registry storage reduction options @@ -302,17 +299,16 @@ There can be different reasons behind this: - 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, 15 minutes is the - value currently in use for GitLab.com. Be aware that by extending this value you increase the + console, where `<integer>` is the desired number of minutes. For reference, the expiration delay + is set to 15 minutes on GitLab.com. If you increase this value you increase the time required to revoke permissions. -If the previous fixes didn't work or you are on earlier versions of GitLab, you can generate a list -of the tags that you want to delete, and then use that list to delete the tags. To do this, follow -these steps: +Alternatively, you can generate a list of tags to delete, and use that list to delete +the tags. To create the list and delete the tags: 1. Run the following shell script. The command just before the `for` loop ensures that `list_o_tags.out` is always reinitialized when starting the loop. After running this command, all - the tags' names will be in the `list_o_tags.out` file: + the tags' names are written to the `list_o_tags.out` file: ```shell # Get a list of all tags in a certain container repository while considering [pagination](../../../api/index.md#pagination) @@ -331,9 +327,8 @@ these steps: This set of commands creates a `/tmp/list_o_tags.out` file listing all tags with a `created_at` date of older than one month. -1. Remove from the `list_o_tags.out` file any tags that you want to keep. Here are some example - `sed` commands for this. Note that these commands are simply examples. You may change them to - best suit your needs: +1. Remove any tags that you want to keep from the `list_o_tags.out` file. For example, you can use `sed` to + parse the file and remove the tags. ```shell # Remove the `latest` tag from the file diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 4143ab0881f..90fc0bc3bb1 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Debian packages in the Package Registry **(FREE)** diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 1310f8eedaa..3fb22437eb0 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Dependency Proxy **(FREE)** @@ -74,7 +74,7 @@ you must authenticate against the Dependency Proxy. Follow the [instructions for using images from a private registry](../../../ci/docker/using_docker_images.md#access-an-image-from-a-private-container-registry), but instead of using `registry.example.com:5000`, use your GitLab domain with no port `gitlab.example.com`. -For example, to manually log in: +For example, to manually sign in: ```shell docker login gitlab.example.com --username my_username --password my_password @@ -84,7 +84,7 @@ 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 [group deploy token](../../../user/project/deploy_tokens/index.md#group-deploy-token) with the scope set to `read_registry` and `write_registry`. +- A [group deploy token](../../../user/project/deploy_tokens/index.md) with the scope set to `read_registry` and `write_registry`. 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. @@ -109,7 +109,7 @@ Proxy. > - Automatic runner authentication, when using the Dependency Proxy to pull the image for the job, was [added](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27302) in GitLab 13.9. > - The prefix for group names containing uppercase letters was [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54559) in GitLab 13.10. -Runners log in to the Dependency Proxy automatically. To pull through +Runners sign in to the Dependency Proxy automatically. To pull through the Dependency Proxy, use one of the [predefined variables](../../../ci/variables/predefined_variables.md): - `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` pulls through the top-level group. 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 fecf60feeef..1239d1a97ae 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: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce Dependency Proxy Storage **(FREE)** diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 312a2c119d6..930e0760eb3 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 -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Generic Packages Repository **(FREE)** diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 733fd383a04..6f6dc084720 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 -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Go proxy for GitLab **(FREE)** diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index 720e274aee5..217d3d57416 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: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Harbor Registry **(FREE)** @@ -19,7 +19,7 @@ You can view the Harbor Registry for a project or group. You can search, sort, and filter images on this page. You can share a filtered view by copying the URL from your browser. At the project level, you can see **CLI Commands** in the upper right corner, where you can copy -corresponding commands to log in, build images, and push images. **CLI Commands** is not shown at +corresponding commands to sign in, build images, and push images. **CLI Commands** is not shown at the group level. NOTE: @@ -31,7 +31,7 @@ To download and run a Harbor image hosted in the GitLab Harbor Registry: 1. Copy the link to your container image: 1. Go to your project or group's **Packages and registries > Harbor Registry** and find the image you want. - 1. Click the **Copy** icon next to the image name. + 1. Select the **Copy** icon next to the image name. 1. Use the command to run the container image you want. @@ -41,7 +41,7 @@ To view the list of tags associated with a specific artifact: 1. Go to your project or group. 1. Go to **Packages and registries > Harbor Registry**. -1. Click the image name to view its artifacts. +1. Select the image name to view its artifacts. 1. Select the artifact you want. This brings up the list of tags. You can view the tag count and the time published. @@ -62,7 +62,7 @@ To view these commands, go to your project's **Packages and registries > Harbor To remove the Harbor Registry for a project: 1. Go to your project/group's **Settings > Integrations** page. -1. Click **Harbor** under **Active integrations**. +1. Select **Harbor** under **Active integrations**. 1. Clear the **Active** checkbox under **Enable integration**. 1. Select **Save changes**. diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index f64a269938f..521f04226df 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Helm charts in the Package Registry **(FREE)** @@ -100,7 +100,7 @@ upload: ## Install a package NOTE: -When requesting a package, GitLab considers only the 300 most recent packages created. +When requesting a package, GitLab considers only the 1000 most recent packages created. For each package, only the most recent package file is returned. To install the latest version of a chart, use the following command: diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 86cfa8986bb..84a10943879 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Packages and Registries **(FREE)** diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index 48cc7b9dea9..8129b42905a 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Infrastructure Registry **(FREE)** diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 957374245d2..ec56255999a 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Maven packages in the Package Repository **(FREE)** @@ -168,7 +168,7 @@ published to the GitLab Package Registry. Enter selection (default: Groovy) [1..2] ``` -1. Enter `1` to create a new Java Library project that is described in Groovy DSL. The output should be: +1. Enter `1` to create a new Java Library project that is described in Groovy DSL, or `2` to create one that is described in Kotlin DSL. The output should be: ```plaintext Select test framework: @@ -286,7 +286,7 @@ To authenticate to the Package Registry, you need either a personal access token In [your `GRADLE_USER_HOME` directory](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home), create a file `gradle.properties` with the following content: -```groovy +```properties gitLabPrivateToken=REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN ``` @@ -310,6 +310,24 @@ repositories { } ``` +Or add it to your `build.gradle.kts` file if you are using Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven") + name = "GitLab" + credentials(HttpHeaderCredentials::class) { + name = "Private-Token" + value = findProperty("gitLabPrivateToken") as String? + } + authentication { + create("header", HttpHeaderAuthentication::class) + } + } +} +``` + ### Authenticate with a deploy token in Gradle To authenticate with a deploy token, add a `repositories` section to your @@ -332,6 +350,24 @@ repositories { } ``` +Or add it to your `build.gradle.kts` file if you are using Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven") + name = "GitLab" + credentials(HttpHeaderCredentials::class) { + name = "Deploy-Token" + value = "<deploy-token>" + } + authentication { + create("header", HttpHeaderAuthentication::class) + } + } +} +``` + ### Authenticate with a CI job token in Gradle To authenticate with a CI job token, add a `repositories` section to your @@ -354,6 +390,24 @@ repositories { } ``` +Or add it to your `build.gradle.kts` file if you are using Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("$CI_API_V4_URL/groups/<group>/-/packages/maven") + name = "GitLab" + credentials(HttpHeaderCredentials::class) { + name = "Job-Token" + value = System.getenv("CI_JOB_TOKEN") + } + authentication { + create("header", HttpHeaderAuthentication::class) + } + } +} +``` + ## Use the GitLab endpoint for Maven packages To use the GitLab endpoint for Maven packages, choose an option: @@ -397,7 +451,7 @@ in Maven should look like this: </distributionManagement> ``` -The corresponding section in Gradle would be: +The corresponding section in Gradle Groovy DSL would be: ```groovy repositories { @@ -408,6 +462,17 @@ repositories { } ``` +In Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven") + name = "GitLab" + } +} +``` + - The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). - The `PROJECT_ID` is your project ID, which you can view on your project's home page. - Replace `gitlab.example.com` with your domain name. @@ -454,7 +519,7 @@ the `distributionManagement` section: </distributionManagement> ``` -For Gradle, the corresponding `repositories` section would look like: +For Gradle, the corresponding `repositories` section in Groovy DSL would look like: ```groovy repositories { @@ -465,6 +530,17 @@ repositories { } ``` +In Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven") + name = "GitLab" + } +} +``` + - For the `id`, use what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). - For `GROUP_ID`, use your group ID, which you can view on your group's home page. - For `PROJECT_ID`, use your project ID, which you can view on your project's home page. @@ -513,7 +589,7 @@ You still need a project-specific URL in the `distributionManagement` section. </distributionManagement> ``` -The corresponding repositories section in Gradle would look like: +The corresponding repositories section in Gradle Groovy DSL would look like: ```groovy repositories { @@ -524,6 +600,17 @@ repositories { } ``` +In Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/packages/maven") + name = "GitLab" + } +} +``` + - The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). - The `PROJECT_ID` is your project ID, which you can view on your project's home page. - Replace `gitlab.example.com` with your domain name. @@ -566,6 +653,8 @@ To publish a package by using Gradle: 1. Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section: + In Groovy DSL: + ```groovy plugins { id 'java' @@ -573,8 +662,19 @@ To publish a package by using Gradle: } ``` + In Kotlin DSL: + + ```kotlin + plugins { + java + `maven-publish` + } + ``` + 1. Add a `publishing` section: + In Groovy DSL: + ```groovy publishing { publications { @@ -597,6 +697,31 @@ To publish a package by using Gradle: } ``` + In Kotlin DSL: + + ```kotlin + publishing { + publications { + create<MavenPublication>("library") { + from(components["java"]) + } + } + repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven") + credentials(HttpHeaderCredentials::class) { + name = "Private-Token" + value = + findProperty("gitLabPrivateToken") as String? // the variable resides in $GRADLE_USER_HOME/gradle.properties + } + authentication { + create("header", HttpHeaderAuthentication::class) + } + } + } + } + ``` + 1. Replace `PROJECT_ID` with your project ID, which can be found on your project's home page. 1. Run the publish task: @@ -703,6 +828,14 @@ dependencies { } ``` +Or to `build.gradle.kts` if you are using Kotlin DSL: + +```kotlin +dependencies { + implementation("com.mycompany.mydepartment:my-project:1.0-SNAPSHOT") +} +``` + ### Request forwarding to Maven Central > [Introduced](<https://gitlab.com/gitlab-org/gitlab/-/issues/362657>) behind a [feature flag](../../feature_flags.md), disabled by default in GitLab 15.4 diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 678f5681890..44266559999 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # npm packages in the Package Registry **(FREE)** diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 5b1e5bbd304..d4b87d70447 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # NuGet packages in the Package Registry **(FREE)** @@ -15,8 +15,8 @@ packages whenever you need to use them as a dependency. The Package Registry works with: -- [NuGet CLI](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference) -- [.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/) +- [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/) - [Visual Studio](https://visualstudio.microsoft.com/vs/) For documentation of the specific API endpoints that these @@ -342,7 +342,7 @@ When publishing packages: Prerequisites: -- [A NuGet package created with NuGet CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package). +- [A NuGet package created with NuGet CLI](https://learn.microsoft.com/en-us/nuget/create-packages/creating-a-package). - Set a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). Publish a package by running this command: @@ -358,7 +358,7 @@ nuget push <package_file> -Source <source_name> Prerequisites: -- [A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). +- [A NuGet package created with .NET CLI](https://learn.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). - Set a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). Publish a package by running this command: diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index fe19c549536..2d8cb46f933 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Package Registry **(FREE)** @@ -53,7 +53,7 @@ For most package types, the following credential types are valid: - [Project deploy token](../../project/deploy_tokens/index.md): allows access to all packages in a project. Good for granting and revoking project access to many users. -- [Group deploy token](../../project/deploy_tokens/index.md#group-deploy-token): +- [Group deploy token](../../project/deploy_tokens/index.md): allows access to all packages in a group and its subgroups. Good for granting and revoking access to a large number of packages to sets of users. - [Job token](../../../ci/jobs/ci_job_token.md): 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 d85992fe05d..e6996d9dc3e 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce Package Registry Storage **(FREE)** @@ -71,9 +71,9 @@ To access these project settings, you must be at least a maintainer on the relat ### Available rules -- `Number of duplicated assets to keep`. The number of duplicated assets to keep. Some package formats allow you +- `Number of duplicated assets to keep`: The number of duplicated assets to keep. Some package formats allow you to upload more than one copy of an asset. You can limit the number of duplicated assets to keep and automatically - delete the oldest assets once the limit is reached. + delete the oldest assets once the limit is reached. Unique filenames, such as those produced by Maven snapshots, are not considered when evaluating the number of duplicated assets to keep. ### Set cleanup limits to conserve resources diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 302c88bf46f..fb1b9ce78ab 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # PyPI packages in the Package Registry **(FREE)** @@ -426,7 +426,7 @@ the three characters, such as `my-package`, `my_package`, and `my....package`. ## Troubleshooting -To improve performance, PyPI caches files related to a package. Note that PyPI doesn't remove data by +To improve performance, the pip command caches files related to a package. Note that pip doesn't remove data by itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with this command: diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 682a3e2ecf1..f21b210f4f5 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Ruby gems in the Package Registry **(FREE)** @@ -76,7 +76,7 @@ https://gitlab.example.com/api/v4/projects/<project_id>/packages/rubygems: '<you ### Authenticate with a CI job token To work with RubyGems commands within [GitLab CI/CD](../../../ci/index.md), -you can use `CI_JOB_TOKEN` instead of a personal access token or deploy token. +you can use the [`CI_JOB_TOKEN`](../../../ci/jobs/ci_job_token.md) predefined environment variable instead of a personal access token or deploy token. For example: diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 0a3de25bf7d..6dd118c39b4 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Terraform module registry **(FREE)** diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 12978ad72a5..25c64c93b73 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Store all of your packages in one GitLab project **(FREE)** diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md index ab10e746302..5606e257ea8 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 -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monorepo package management workflows **(FREE)** @@ -40,7 +40,7 @@ and by doing one of the following: If you follow the instructions, you can publish `MyProject` by running `npm publish` from the root directory. -Publishing `Foo` is almost exactly the same. Simply follow the same steps while in the `Foo` +Publishing `Foo` is almost exactly the same. Follow the same steps while in the `Foo` directory. `Foo` needs its own `package.json` file, which you can add manually by using `npm init`. `Foo` also needs its own configuration settings. Since you are publishing to the same place, if you used `npm config set` to set the registry for the parent project, then no additional setup is diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 9a4590d9478..102abf2b427 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Permissions and roles **(FREE)** @@ -91,6 +91,7 @@ The following table lists project permissions available for each role: | [Issue boards](project/issue_board.md):<br>Create or delete lists | | ✓ | ✓ | ✓ | ✓ | | [Issue boards](project/issue_board.md):<br>Move issues between lists | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Add Labels | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add to epic | | ✓ (*23*) | ✓ (*23*) | ✓ (*23*) | ✓ (*23*) | | [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create (*18*) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -165,7 +166,7 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*7*) | ✓ (*7*) | | [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Assign project to a [compliance framework](project/settings/index.md#compliance-frameworks) | | | | | ✓ | +| [Projects](project/index.md):<br>Assign project to a [compliance framework](project/settings/index.md#add-a-compliance-framework-to-a-project) | | | | | ✓ | | [Projects](project/index.md):<br>Archive project | | | | | ✓ | | [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | | [Projects](project/index.md):<br>Delete project | | | | | ✓ | @@ -246,6 +247,7 @@ The following table lists project permissions available for each role: 20. 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). 21. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests. 22. 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. +23. You must have permission to [view the epic](group/epics/manage_epics.md#who-can-view-an-epic). <!-- markdownlint-enable MD029 --> @@ -379,6 +381,7 @@ The following table lists group permissions available for each role: | Action | Guest | Reporter | Developer | Maintainer | Owner | |-----------------------------------------------------------------------------------------|-------|----------|-----------|------------|-------| +| Add an issue to an [epic](group/epics/index.md) | ✓ (7) | ✓ (7) | ✓ (7) | ✓ (7) | ✓ (7) | | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -445,6 +448,7 @@ The following table lists group permissions available for each role: 4. Developers can push commits to the default branch of a new project only if the [default branch protection](group/manage.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". 5. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. 6. Users can only view events based on their individual actions. +7. You must have permission to [view the epic](group/epics/manage_epics.md#who-can-view-an-epic) and edit the issue. <!-- markdownlint-enable MD029 --> diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index e3f7d47038d..f2636fdaa68 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Creating users **(FREE SELF)** diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index d2e0c1ad834..5e2908a26e1 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deleting a user account **(FREE)** diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 02567958356..3dc768f6606 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Two-factor authentication **(FREE)** @@ -452,11 +452,10 @@ This error occurs in the following scenarios: [enforce 2FA for all users](../../../security/two_factor_authentication.md#enforce-2fa-for-all-users) setting. - You do not have 2FA enabled, but an administrator has disabled the [password authentication enabled for Git over HTTP(S)](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled) - setting. If LDAP is: - - Configured, an [LDAP password](../../../administration/auth/ldap/index.md) - or a [personal access token](../personal_access_tokens.md) - must be used to authenticate Git requests over HTTP(S). - - Not configured, you must use a [personal access token](../personal_access_tokens.md). + setting. You can authenticate Git requests: + - Over HTTP(S) using a [personal access token](../personal_access_tokens.md). + - In your browser using [Git Credential Manager](#git-credential-manager). + - If you have configured LDAP, over HTTP(S) using an [LDAP password](../../../administration/auth/ldap/index.md). ### Error: "invalid pin code" diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index b30ee002758..d0600e5e80d 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/profile/img/unknown_sign_in_email_v14_0.png b/doc/user/profile/img/unknown_sign_in_email_v14_0.png Binary files differdeleted file mode 100644 index 62634739b78..00000000000 --- a/doc/user/profile/img/unknown_sign_in_email_v14_0.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index e4cf905bbce..66f6b4b52de 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -2,7 +2,7 @@ type: index, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # User account **(FREE)** @@ -25,19 +25,6 @@ To access your user settings: 1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. -## Change your password - -To change your password: - -1. On the top bar, in the top-right corner, select your avatar. -1. Select **Edit profile**. -1. On the left sidebar, select **Password**. -1. In the **Current password** text box, enter your current password. -1. In the **New password** and **Password confirmation** text box, enter your new password. -1. Select **Save password**. - -If you don't know your current password, select the **I forgot my password** link. A password reset email is sent to the account's **primary** email address. - ## Change your username Your username has a unique [namespace](../namespace/index.md), @@ -223,12 +210,12 @@ To set the busy status indicator, either: - Set it directly: 1. On the top bar, in the top-right corner, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. - 1. Select the **Busy** checkbox. + 1. Select the **Set yourself as busy** checkbox. - Set it on your profile: 1. On the top bar, in the top-right corner, select your avatar. 1. Select **Edit profile**. - 1. In the **Current status** section, select the **Busy** checkbox. + 1. In the **Current status** section, select the **Set yourself as busy** checkbox. The busy status is displayed in the user interface. @@ -330,6 +317,9 @@ GitLab tracks user contribution activity. You can follow or unfollow other users - The small popover that appears when you hover over a user's name ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76050) in GitLab 15.0). +In [GitLab 15.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/360755), +the maximum number of users you can follow is 300. + To view a user's activity in a top-level Activity view: 1. From a user's profile, select **Follow**. @@ -472,7 +462,10 @@ Without the `config.extend_remember_period` flag, you would be forced to sign in - [Create users](account/create_accounts.md) - [Sign in to your GitLab account](../../topics/authentication/index.md) -- [Receive emails for sign-ins from unknown IP addresses or devices](unknown_sign_in_notification.md) +- [Change your password](user_passwords.md) +- Receive emails for: + - [Sign-ins from unknown IP addresses or devices](notifications.md#notifications-for-unknown-sign-ins) + - [Attempted sign-ins using wrong two-factor authentication codes](notifications.md#notifications-for-attempted-sign-in-using-wrong-two-factor-authentication-codes) - Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth) - Manage [personal access tokens](personal_access_tokens.md) to access your account via API and authorized applications - Manage [SSH keys](../ssh.md) to access your account via SSH diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 1b737f14f68..7942ee38be9 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/notifications.html' 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Notification emails **(FREE)** @@ -286,6 +286,36 @@ By default, you don't receive notifications for issues, merge requests, or epics To always receive notifications on your own issues, merge requests, and so on, turn on [notifications about your own activity](#global-notification-settings). +## Notifications for unknown sign-ins + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27211) in GitLab 13.0. + +NOTE: +This feature is enabled by default for self-managed instances. Administrators may disable this feature +through the [Sign-in restrictions](../admin_area/settings/sign_in_restrictions.md#email-notification-for-unknown-sign-ins) section of the UI. +The feature is always enabled on GitLab.com. + +When a user successfully signs in from a previously unknown IP address or device, +GitLab notifies the user by email. In this way, GitLab proactively alerts users of potentially +malicious or unauthorized sign-ins. + +GitLab uses several methods to identify a known sign-in. All methods must fail for a notification email to be sent. + +- Last sign-in IP: The current sign-in IP address is checked against the last sign-in + IP address. +- Current active sessions: If the user has an existing active session from the + same IP address. See [Active Sessions](active_sessions.md). +- Cookie: After successful sign in, an encrypted cookie is stored in the browser. + This cookie is set to expire 14 days after the last successful sign in. + +## Notifications for attempted sign-in using wrong two-factor authentication codes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374740) in GitLab 15.5. + +GitLab sends you an email notification if it detects an attempt to sign in to your account using a wrong two-factor +authentication (2FA) code. This can help you detect that a bad actor gained access to your username and password, and is trying +to brute force 2FA. + ## Notifications on designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217095) in GitLab 13.6. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 2fd18f583a4..c7fe68c0609 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -2,7 +2,7 @@ type: concepts, howto stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Personal access tokens **(FREE)** @@ -45,6 +45,9 @@ For examples of how you can use a personal access token to authenticate with the Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/index.md#impersonation-tokens). Use impersonation tokens to automate authentication as a specific user. +NOTE: +Personal access tokens are not FIPS compliant and creation and use are disabled when [FIPS mode](../../development/fips_compliance.md) is enabled. + ## Create a personal access token > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348660) in GitLab 15.3, default expiration of 30 days is populated in the UI. @@ -102,14 +105,14 @@ A personal access token can perform actions based on the assigned scopes. | Scope | Access | |--------------------|--------| -| `api` | Read-write for the complete API, including all groups and projects, the Container Registry, and the Package Registry. | -| `read_user` | Read-only for endpoints under `/users`. Essentially, access to any of the `GET` requests in the [Users API](../../api/users.md). | -| `read_api` | Read-only for the complete 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` | Read-only (pull) for the repository through `git clone`. | -| `write_repository` | Read-write (pull, push) for the repository through `git clone`. | -| `read_registry` | Read-only (pull) for [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` | Read-write (push) for [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` | API actions as any user in the system (if the authenticated user is an administrator). | +| `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. | ## When personal access tokens expire diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 31ab802a8b8..6849918886a 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -51,7 +51,7 @@ See the epic for: - A list of known issues. - Our planned direction and next steps. -If you find an issue that isn't listed, please leave a comment on the epic or create a +If you find an issue that isn't listed, leave a comment on the epic or create a new issue. Dark mode is available as a navigation theme, for MVC and compatibility reasons. @@ -201,7 +201,7 @@ To set your time preference: NOTE: This feature is experimental, and choosing absolute times might break certain layouts. -Please open an issue if you notice that using absolute times breaks a layout. +Open an issue if you notice that using absolute times breaks a layout. ## Integrations diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index 37bde3ce846..3bdcd36a34e 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -1,32 +1,11 @@ --- -stage: Manage -group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'notifications.md' +remove_date: '2023-01-15' --- -# Email notification for unknown sign-ins **(FREE)** +This document was moved to [another location](notifications.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27211) in GitLab 13.0. - -NOTE: -This feature is enabled by default for self-managed instances. Administrators may disable this feature -through the [Sign-in restrictions](../admin_area/settings/sign_in_restrictions.md#email-notification-for-unknown-sign-ins) section of the UI. -The feature is always enabled on GitLab.com. - -When a user successfully signs in from a previously unknown IP address or device, -GitLab notifies the user by email. In this way, GitLab proactively alerts users of potentially -malicious or unauthorized sign-ins. - -There are several methods used to identify a known sign-in. All methods must fail -for a notification email to be sent. - -- Last sign-in IP: The current sign-in IP address is checked against the last sign-in - IP address. -- Current active sessions: If the user has an existing active session from the - same IP address. See [Active Sessions](active_sessions.md). -- Cookie: After successful sign in, an encrypted cookie is stored in the browser. - This cookie is set to expire 14 days after the last successful sign in. - -## Example email - - +<!-- This redirect file can be deleted after <2023-01-15>. --> +<!-- 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/profile/user_passwords.md b/doc/user/profile/user_passwords.md new file mode 100644 index 00000000000..04d149c9709 --- /dev/null +++ b/doc/user/profile/user_passwords.md @@ -0,0 +1,76 @@ +--- +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# User passwords **(FREE)** + +If you use a password to sign in to GitLab, a strong password is very important. A weak or guessable password makes it +easier for unauthorized people to log into your account. + +Some organizations require you to meet certain requirements when choosing a password. + +Improve the security of your account with [two-factor authentication](account/two_factor_authentication.md) + +## Choose your password + +You can choose a password when you [create a user account](account/create_accounts.md). + +If you register your account using an external authentication and +authorization provider, you do not need to choose a password. GitLab +[sets a random, unique, and secure password for you](../../security/passwords_for_integrated_authentication_methods.md). + +## Change your password + +You can change your password. GitLab enforces [password requirements](#password-requirements) when you choose your new +password. + +1. On the top bar, in the top-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Password**. +1. In the **Current password** text box, enter your current password. +1. In the **New password** and **Password confirmation** text box, enter your new password. +1. Select **Save password**. + +If you don't know your current password, select the **I forgot my password** link. A password reset email is sent to the +account's **primary** email address. + +## Password requirements + +Your passwords must meet a set of requirements when: + +- You choose a password during registration. +- You choose a new password using the forgotten password reset flow. +- You change your password proactively. +- You change your password after it expires. +- An an administrator creates your account. +- An administrator updates your account. + +By default GitLab enforces the following password requirements: + +- Minimum and maximum password lengths. For example, + see [the settings for GitLab.com](../gitlab_com/index.md#password-requirements). +- Disallowing [weak passwords](#block-weak-passwords). + +Self-managed installations can configure the following additional password requirements: + +- [Password minimum and maximum length limits](../../security/password_length_limits.md). +- [Password complexity requirements](../admin_area/settings/sign_up_restrictions.md#password-complexity-requirements). + +## Block weak passwords + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23610) in GitLab 15.4 [with a flag](../../administration/feature_flags.md) named `block_weak_passwords`, weak passwords aren't accepted. Disabled by default. + +FLAG: +On self-managed GitLab, by default blocking weak passwords is not available. To make it available, ask an administrator +to [enable the feature flag](../../administration/feature_flags.md) named `block_weak_passwords`. On GitLab.com, this +feature is available but can be configured by GitLab.com administrators only. + +GitLab disallows weak passwords. Your password is considered weak when it: + +- Matches one of 4500+ known, breached passwords. +- Contains part of your name, username, or email address. +- Contains a predictable word (for example, `gitlab` or `devops`). + +Weak passwords are rejected with the error message: **Password must not contain commonly used combinations of words and letters**. diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index aa8c21fc781..e0c1ceb7ec5 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 description: "Autocomplete characters in Markdown fields." --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index cf0ff4ed8b9..d43af92e9c6 100644 --- a/doc/user/project/badges.md +++ b/doc/user/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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Badges **(FREE)** diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index aac704e2cdd..3e6a9acc304 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Canary Deployments **(FREE)** diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index d9339291328..b3d381c3148 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect EKS clusters through cluster certificates (DEPRECATED) **(FREE)** diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index d7137c18a03..363197107f9 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect existing clusters through cluster certificates (DEPRECATED) **(FREE)** @@ -244,8 +244,8 @@ You may also experience this error if your certificate is not valid. To check th subject alternative names contain the correct domain for your cluster's API, run this command: ```shell -echo | openssl s_client -showcerts -connect kubernetes.example.com:443 2>/dev/null | +echo | openssl s_client -showcerts -connect kubernetes.example.com:443 -servername kubernetes.example.com 2>/dev/null | openssl x509 -inform pem -noout -text ``` -The `-connect` argument expects a `host:port` combination. For example, `https://kubernetes.example.com` would be `kubernetes.example.com:443`. +The `-connect` argument expects a `host:port` combination. For example, `https://kubernetes.example.com` would be `kubernetes.example.com:443`. The `-servername` argument expects a domain without any URI, for example `kubernetes.example.com`. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 6ed02838e9b..7b010bf4478 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Connect GKE clusters through cluster certificates (DEPRECATED) **(FREE)** @@ -66,7 +66,7 @@ cluster certificates: - **Main menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, select **Google GKE**. -1. Connect your Google account if you haven't done already by clicking the +1. Connect your Google account if you haven't done already by selecting the **Sign in with Google** button. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 2fba00ae940..523a6fd65f6 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Add a cluster using cluster certificates (DEPRECATED) **(FREE)** diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 43ceb3673d8..c9b3596d92f 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Access controls with cluster certificates (RBAC or ABAC) (DEPRECATED) **(FREE)** diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 0a574b9afe2..e8acf5a2727 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy to a Kubernetes cluster with cluster certificates (DEPRECATED) **(FREE)** diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 3b85d29fb4a..b2a4bd85de4 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab-managed clusters (DEPRECATED) **(FREE)** diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 940b58103f5..94513fc7124 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project-level Kubernetes clusters (certificate-based) (DEPRECATED) **(FREE)** diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index bd87ab1024d..51e4f1c2db2 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,8 +1,8 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-18-10' +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2022-10-18' redirect_to: '../../clusters/agent/index.md' --- diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 149df5248c8..95d3bf6e121 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple clusters per project with cluster certificates (DEPRECATED) **(FREE)** diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 94b5f6f52b9..c4ca82f7db4 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Runbooks **(FREE)** @@ -153,7 +153,7 @@ the components outlined above and the pre-loaded demo runbook. ``` 1. After JupyterHub has been installed successfully, open the **Jupyter Hostname** - in your browser. Select **Sign in with GitLab** button to log in to + in your browser. Select **Sign in with GitLab** button to sign in to JupyterHub and start the server. Authentication is enabled for any user of the GitLab instance with OAuth2. This button redirects you to a page at GitLab requesting authorization for JupyterHub to use your GitLab account. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md deleted file mode 100644 index 93bc41dc24c..00000000000 --- a/doc/user/project/clusters/serverless/aws.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -stage: Configure -group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-08-22' -redirect_to: '../../../../update/removals.md#gitlab-serverless' ---- - -# Deploying AWS Lambda function using GitLab CI/CD (removed) **(FREE)** - -This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/6) in GitLab 14.3 and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86267) in GitLab 15.0. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md deleted file mode 100644 index 432caa8476f..00000000000 --- a/doc/user/project/clusters/serverless/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -stage: Configure -group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -remove_date: '2022-08-22' -redirect_to: '../../../../update/removals.md#gitlab-serverless' ---- - -# Serverless (removed) **(FREE)** - -This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/6) in GitLab 14.3 and [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86267) in GitLab 15.0. diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 860ebfbed14..d5f9c225cde 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index fd2df96308c..aeeacd495a7 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Code Owners **(PREMIUM)** @@ -335,8 +335,10 @@ If you update the `CODEOWNERS` file, close the merge request and create a new on ### User not shown as possible approver -A user might not show as an approver on the Code Owner merge request approval rules. +A user might not show as an approver on the Code Owner merge request approval rules +if any of these conditions are true: -This result occurs when a rule prevents the specific user from approving the merge request. -Check the project -[merge request approval setting](merge_requests/approvals/settings.md#edit-merge-request-approval-settings). +- A rule prevents the specific user from approving the merge request. + Check the project [merge request approval](merge_requests/approvals/settings.md#edit-merge-request-approval-settings) settings. +- A Code Owner group has a visibility of **private**, and the current user is not a + member of the Code Owner group. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 63010610605..a68f9550ebf 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -118,7 +118,7 @@ To display the deploy boards for a specific [environment](../../ci/environments/ NOTE: Matching based on the Kubernetes `app` label was removed in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020). - To migrate, please apply the required annotations (see above) and + To migrate, apply the required annotations (see above) and re-deploy your application. If you are using Auto DevOps, this will be done automatically and no action is necessary. @@ -130,7 +130,7 @@ Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Deployments > Environments**. Deploy boards are visible by default. You can explicitly select -the triangle next to their respective environment name in order to hide them. +the triangle next to their respective environment name to hide them. ### Example manifest file diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index f424ec529b2..58f7d3198b2 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy keys **(FREE)** @@ -156,3 +156,38 @@ There are a few scenarios where a deploy key will fail to push to a All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. We recommend you create a service account, and associate a deploy key to the service account, for projects using deploy keys. + +#### Identify deploy keys associated with non-member and blocked users + +If you need to find the keys that belong to a non-member or blocked user, +you can use [the Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) to identify unusable deploy keys using a script similar to the following: + +```ruby +ghost_user_id = User.ghost.id + +DeployKeysProject.with_write_access.find_each do |deploy_key_mapping| + project = deploy_key_mapping.project + deploy_key = deploy_key_mapping.deploy_key + user = deploy_key.user + + access_checker = Gitlab::DeployKeyAccess.new(deploy_key, container: project) + + # can_push_for_ref? tests if deploy_key can push to default branch, which is likely to be protected + can_push = access_checker.can_do_action?(:push_code) + can_push_to_default = access_checker.can_push_for_ref?(project.repository.root_ref) + + next if access_checker.allowed? && can_push && can_push_to_default + + if user.nil? || user.id == ghost_user_id + username = 'none' + state = '-' + else + username = user.username + user_state = user.state + end + + puts "Deploy key: #{deploy_key.id}, Project: #{project.full_path}, Can push?: " + (can_push ? 'YES' : 'NO') + + ", Can push to default branch #{project.repository.root_ref}?: " + (can_push_to_default ? 'YES' : 'NO') + + ", User: #{username}, User state: #{user_state}" +end +``` diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png Binary files differdeleted file mode 100644 index 4ab6a45aee1..00000000000 --- a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png +++ /dev/null diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 04a2eeacffb..aab72d4859e 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Deploy tokens **(FREE)** @@ -11,217 +11,222 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** to **Settings > Repository** in GitLab 12.10.1. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. -Deploy tokens allow you to download (`git clone`) or push and pull packages and -container registry images of a project without having a user and a password. +You can use a deploy token to enable authentication of deployment tasks, independent of a user +account. In most cases you use a deploy token from an external host, like a build server or CI/CD +server. -Deploy tokens can be managed only by users with the Maintainer role. +With a deploy token, automated tasks can: -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 details, see -[Authenticate with the registry](../../packages/package_registry/index.md#authenticate-with-the-registry). +- Clone Git repositories. +- Pull from and push to a GitLab container registry. +- Pull from and push to a GitLab package registry. -Deploy tokens are tied to the project and stay enabled even when the user who created the token is removed from the project. +A deploy token is a pair of values: -If you have a key pair, you might want to use [deploy keys](../../project/deploy_keys/index.md) -instead. +- **username**: `username` in the HTTP authentication framework. The default username format is + `gitlab+deploy-token-{n}`. You can specify a custom username when you create the deploy token. +- **token**: `password` in the HTTP authentication framework. -## Creating a Deploy token +You can use a deploy token for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) +to the following endpoints: -You can create as many deploy tokens as you need from the settings of your -project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). +- GitLab Package Registry public API. +- [Git commands](https://git-scm.com/docs/gitcredentials#_description). -1. Sign in to your GitLab account. -1. On the top bar, select **Main menu > Projects** or **Main menu > Groups** to find your project or group. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Deploy tokens**. -1. Choose a name, and optionally, an expiration date and username for the token. -1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). -1. Select **Create deploy token**. +You can create deploy tokens at either the project or group level: -Save the deploy token somewhere safe. After you leave or refresh -the page, **you can't access it again**. +- **Project deploy token**: Permissions apply only to the project. +- **Group deploy token**: Permissions apply to all projects in the group. - +By default, a deploy token does not expire. You can optionally set an expiry date when you create +it. Expiry occurs at midnight UTC on that date. -## Deploy token expiration +## Scope -Deploy tokens expire at midnight UTC on the date you define. +A deploy token's scope determines the actions it can perform. -## Revoking a deploy token +| Scope | Description | +|--------------------------|--------------------------------------------------------------------------------------------------------------| +| `read_repository` | Read-only access to the repository using `git clone`. | +| `read_registry` | Read-only access to the images in the project's [container registry](../../packages/container_registry/index.md). | +| `write_registry` | Write access (push) to the project's [container registry](../../packages/container_registry/index.md). | +| `read_package_registry` | Read-only access to the project's package registry. | +| `write_package_registry` | Write access to the project's package registry. | -To revoke a deploy token: +## GitLab deploy token -1. On the top bar, select **Main menu > Projects** or **Main menu > Groups** to find your project or group. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Deploy tokens**. -1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. +> - Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default. +> - [Feature flag `ci_variable_for_group_gitlab_deploy_token`](https://gitlab.com/gitlab-org/gitlab/-/issues/363621) removed in GitLab 15.4. -## Limiting scopes of a deploy token +A GitLab deploy token is a special type of deploy token. If you create a deploy token named +`gitlab-deploy-token`, the deploy token is automatically exposed to the CI/CD jobs as variables, for +use in a CI/CD pipeline: -Deploy tokens can be created with different scopes that allow various actions -that a given token can perform. The available scopes are depicted in the -following table along with GitLab version it was introduced in: +- `CI_DEPLOY_USER`: Username +- `CI_DEPLOY_PASSWORD`: Token -| Scope | Description | Introduced in GitLab Version | -|--------------------------|-------------|------------------------------| -| `read_repository` | Allows read-access to the repository through `git clone` | -- | -| `read_registry` | Allows read-access to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | -- | -| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | 12.10 | -| `read_package_registry` | Allows read access to the package registry. | 13.0 | -| `write_package_registry` | Allows write access to the package registry. | 13.0 | +For example, to use a GitLab token to log in to your GitLab container registry: -## Deploy token custom username +```shell +docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY +``` -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29639) in GitLab 12.1. +NOTE: +In GitLab 15.0 and earlier, the special handling for the `gitlab-deploy-token` deploy token does not +work for group deploy tokens. To make a group deploy token available for CI/CD jobs, set the +`CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD` CI/CD variables in **Settings > CI/CD > Variables** to the +name and token of the group deploy token. -The default username format is `gitlab+deploy-token-{n}`. Some tools or -platforms may not support this format; in this case you can specify a custom -username to be used when creating the deploy token. +### GitLab public API -## Usage +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 +[Authenticate with the registry](../../packages/package_registry/index.md#authenticate-with-the-registry). -### Git clone a repository +## Create a deploy token -To download a repository using a deploy token: +Create a deploy token to automate deployment tasks that can run independently of a user account. -1. Create a deploy token with `read_repository` as a scope. -1. Take note of your `username` and `token`. -1. `git clone` the project using the deploy token: +Prerequisites: - ```shell - git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git - ``` +- You must have at least the Maintainer role for the project or group. -Replace `<username>` and `<deploy_token>` with the proper values. +1. On the top bar, select **Main menu**, and: + - For a project deploy token, select **Projects** and find your project. + - For a group deploy token, select **Groups** and find your group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy tokens**. +1. Complete the fields, and select the desired [scopes](#scope). +1. Select **Create deploy token**. -### Read Container Registry images +Record the deploy token's values. After you leave or refresh the page, **you cannot access it +again**. -To read the container registry images, you must: +## Revoke a deploy token -1. Create a deploy token with `read_registry` as a scope. -1. Take note of your `username` and `token`. -1. Sign in to the GitLab Container Registry using the deploy token: +Revoke a token when it's no longer required. -```shell -docker login -u <username> -p <deploy_token> registry.example.com -``` +Prerequisites: -Replace `<username>` and `<deploy_token>` with the proper values. You can now -pull images from your Container Registry. +- You must have at least the Maintainer role for the project or group. -### Push Container Registry images +To revoke a deploy token: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. +1. On the top bar, select **Main menu**, and: + - For a project deploy token, select **Projects** and find your project. + - For a group deploy token, select **Groups** and find your group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy tokens**. +1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke**. -To push the container registry images, you must: +## Clone a repository -1. Create a deploy token with `write_registry` as a scope. -1. Take note of your `username` and `token`. -1. Sign in to the GitLab Container Registry using the deploy token: +You can use a deploy token to clone a repository. - ```shell - docker login -u <username> -p <deploy_token> registry.example.com - ``` +Prerequisites: -Replace `<username>` and `<deploy_token>` with the proper values. You can now -push images to your Container Registry. +- A deploy token with the `read_repository` scope. -### Read or pull packages +Example of using a deploy token to clone a repository: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. +```shell +git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git +``` -To pull packages in the GitLab package registry, you must: +## Pull images from a container registry -1. Create a deploy token with `read_package_registry` as a scope. -1. Take note of your `username` and `token`. -1. For the [package type of your choice](../../packages/index.md), follow the - authentication instructions for deploy tokens. +You can use a deploy token to pull images from a container registry. -Example request publishing a NuGet package using a deploy token: +Prerequisites: -```shell -nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName deploy-token-username -Password 12345678asdf +- A deploy token with the `read_registry` scope. -nuget push mypkg.nupkg -Source GitLab +Example of using a deploy token to pull images from a container registry: + +```shell +docker login -u <username> -p <deploy_token> registry.example.com +docker pull $CONTAINER_TEST_IMAGE ``` -### Push or upload packages +## Push images to a container registry -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. +You can use a deploy token to push images to a container registry. -To upload packages in the GitLab package registry, you must: +Prerequisites: -1. Create a deploy token with `write_package_registry` as a scope. -1. Take note of your `username` and `token`. -1. For the [package type of your choice](../../packages/index.md), follow the - authentication instructions for deploy tokens. +- A deploy token with the `write_registry` scope. -### Group deploy token +Example of using a deploy token to push an image to a container registry: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21765) in GitLab 12.9. +```shell +docker login -u <username> -p <deploy_token> registry.example.com +docker push $CONTAINER_TEST_IMAGE +``` -A deploy token created at the group level can be used across all projects that -belong either to the specific group or to one of its subgroups. +## Pull packages from a package registry -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Group Deploy Tokens](https://youtu.be/8kxTJvaD9ks). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -The Group deploy tokens UI is now accessible under **Settings > Repository**, -not **Settings > CI/CD** as indicated in the video. +You can use a deploy token to pull packages from a package registry. -To use a group deploy token: +Prerequisites: -1. [Create](#creating-a-deploy-token) a deploy token for a group. -1. Use it the same way you use a project deploy token when - [cloning a repository](#git-clone-a-repository). +- A deploy token with the `read_package_registry` scope. -The scopes applied to a group deploy token (such as `read_repository`) -apply consistently when cloning the repository of related projects. +For the [package type of your choice](../../packages/index.md), follow the authentication +instructions for deploy tokens. -### Pull images from the Dependency Proxy +Example of installing a NuGet package from a GitLab registry: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280586) in GitLab 14.2. +```shell +nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token> +nuget install mypkg.nupkg +``` -To pull images from the Dependency Proxy, you must: +## Push packages to a package repository -1. Create a group deploy token with both `read_registry` and `write_registry` scopes. -1. Take note of your `username` and `token`. -1. Follow the Dependency Proxy [authentication instructions](../../packages/dependency_proxy/index.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -### GitLab deploy token +You can use a deploy token to push packages to a GitLab package registry. -> - Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default. -> - [Feature flag `ci_variable_for_group_gitlab_deploy_token`](https://gitlab.com/gitlab-org/gitlab/-/issues/363621) removed in GitLab 15.4. +Prerequisites: + +- A deploy token with the `write_package_registry` scope. -There's a special case when it comes to deploy tokens. If a user creates one -named `gitlab-deploy-token`, the username and token of the deploy token is -automatically exposed to the CI/CD jobs as CI/CD variables: `CI_DEPLOY_USER` -and `CI_DEPLOY_PASSWORD`, respectively. +For the [package type of your choice](../../packages/index.md), follow the authentication +instructions for deploy tokens. -After you create the token, you can sign in to the Container Registry by using -those variables: +Example of publishing a NuGet package to a package registry: ```shell -docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY +nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token> +nuget push mypkg.nupkg -Source GitLab ``` -NOTE: -In GitLab 15.0 and earlier, the special handling for the `gitlab-deploy-token` deploy token -does not work for group deploy tokens. To make the group-level deploy token available -for CI/CD jobs, the `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD` CI/CD variables must be -set in **Settings > CI/CD > Variables** to the name and token of the group deploy token. +## Pull images from the dependency proxy + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280586) in GitLab 14.2. + +You can use a deploy token to pull images from the dependency proxy. + +Prerequisites: + +- A deploy token with `read_registry` and `write_registry` scopes. + +Follow the dependency proxy [authentication instructions](../../packages/dependency_proxy/index.md). ## Troubleshooting -### Group deploy tokens and LFS +### Error: `api error: Repository or object not found:` -A bug -[prevents Group Deploy Tokens from cloning LFS objects](https://gitlab.com/gitlab-org/gitlab/-/issues/235398). -If you receive `404 Not Found` errors and this error, -use a Project Deploy Token to work around the bug: +When using a group deploy token to clone from LFS objects, you might get `404 Not Found` responses +and this error message. This occurs because of a bug, documented in +[issue 235398](https://gitlab.com/gitlab-org/gitlab/-/issues/235398). ```plaintext api error: Repository or object not found: https://<URL-with-token>.git/info/lfs/objects/batch Check that it exists and that you have proper access to it ``` + +The workaround is to use a project deploy token. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4050fa34026..40c36236932 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/engineering/ux/technical-writing/#assignments +info: To 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 templates **(FREE)** @@ -192,7 +192,7 @@ Here is an example of a bug report template: ## Example Project -(If possible, please create an example project here on GitLab.com that exhibits the problematic +(If possible, create an example project here on GitLab.com that exhibits the problematic behavior, and link to it here in the bug report. If you are using an older version of GitLab, this will also determine whether the bug has been fixed in a more recent version) @@ -207,7 +207,7 @@ in a more recent version) ## Relevant logs and/or screenshots -(Paste any relevant logs - please use code blocks (```) to format console output, logs, and code, as +(Paste any relevant logs - use code blocks (```) to format console output, logs, and code, as it's very hard to read otherwise.) ## Possible fixes diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index f1b9bde6cd0..6d0d444497e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # File Locking **(FREE)** diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index f2e4b65e3d4..1feb17b19c8 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 1d62cd00b31..22ff234ac81 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index dff5a602e8a..3f1a2dcfe2b 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from Bitbucket Cloud to GitLab **(FREE)** diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index b6241dbbdb0..1f34c6d4ad9 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from Bitbucket Server **(FREE)** diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 2d9f92c38e4..1dc62cbbe35 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from ClearCase **(FREE)** diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index c150e124ac8..f8bbb2354fe 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from CVS **(FREE)** diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 3458c7fe4a7..f6395fd9234 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from FogBugz to GitLab **(FREE)** diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index db55330f806..46e6b6d377d 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from Gitea to GitLab **(FREE)** diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index c04f734e8bb..03f6fd20b0a 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your project from GitHub to GitLab **(FREE)** @@ -118,6 +118,23 @@ If you are not using the GitHub integration, you can still perform an authorizat 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. +### Select additional items to import + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/373705) in GitLab 15.5. + +To make imports as fast as possible, the following items aren't imported from GitHub by default: + +- Issue and pull request events. For example, _opened_ or _closed_, _renamed_, and _labeled_ or _unlabeled_. +- All comments. In regular import of large repositories some comments might get skipped due to limitation of GitHub API. +- Markdown attachments from repository comments, release posts, issue descriptions, and pull request descriptions. These can include + images, text, or binary attachments. If not imported, links in Markdown to attachments break after you remove the attachments from GitHub. + +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**. +- **Import Markdown attachments**. + ### Select which repositories to import After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and @@ -178,8 +195,15 @@ The following items of a project are imported: - Milestones. - Labels. - Release note descriptions. -- Release note attachments. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15620) in GitLab 15.4 with `github_importer_attachments_import` - [feature flag](../../../administration/feature_flags.md) disabled by default. +- Attachments for: + - Release notes. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15620) in GitLab 15.4. + - Comments and notes. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. + - Issue description. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. + - Merge Request description. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18052) in GitLab 15.5. + + All attachment imports are disabled by default behind + `github_importer_attachments_import` [feature flag](../../../administration/feature_flags.md). From GitLab 15.5, can be imported + [as an additional item](#select-additional-items-to-import). The feature flag was removed. - Pull request review comments. - Regular issue and pull request comments. - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md). @@ -189,35 +213,32 @@ The following items of a project are imported: - Diff Notes suggestions ([GitLab.com and GitLab 14.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)). - Issue events and pull requests events. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7673) in GitLab 15.4 with `github_importer_issue_events_import` [feature flag](../../../administration/feature_flags.md) disabled by default. + From GitLab 15.5, can be imported [as an additional item](#select-additional-items-to-import). The feature flag was removed. References to pull requests and issues are preserved. Each imported repository maintains visibility level unless that [visibility level is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), in which case it defaults to the default project visibility. +### Branch protection rules + +Supported GitHub branch protection rules are mapped to GitLab branch protection rules or project-wide GitLab settings when they are imported: + +- GitHub rule **Require conversation resolution before merging** for the project's default branch is mapped to the [**All threads must be resolved** GitLab setting](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371110) in GitLab 15.5. +- GitHub rule **Require a pull request before merging** is mapped to the **No one** option in the **Allowed to push** list of the branch protection rule. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370951) in GitLab 15.5. +- GitHub rule **Require signed commits** for the project's default branch is mapped to the **Reject unsigned commits** GitLab setting. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/370949) in GitLab 15.5. +- Support for GitHub rule **Require status checks to pass before merging** was proposed in issue [370948](https://gitlab.com/gitlab-org/gitlab/-/issues/370948). However, this rule cannot be translated during project import into GitLab due to technical difficulties. +You can still create [status checks](../merge_requests/status_checks.md) in GitLab yourself. + ## Alternative way to import notes and diff notes When GitHub Importer runs on extremely large projects not all notes & diff notes can be imported due to GitHub API `issues_comments` & `pull_requests_comments` endpoints limitation. Not all pages can be fetched due to the following error coming from GitHub API: `In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse.`. -An alternative approach for importing notes and diff notes is available behind a feature flag. +An [alternative approach](#select-additional-items-to-import) for importing comments is available. Instead of using `issues_comments` and `pull_requests_comments`, use individual resources `issue_comments` and `pull_request_comments` instead to pull notes from one object at a time. This allows us to carry over any missing comments, however it increases the number of network requests required to perform the import, which means its execution takes a longer time. -To use the alternative way of importing notes, the `github_importer_single_endpoint_notes_import` feature flag must be enabled on the group project is being imported into. - -Start a [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session). - -```ruby -group = Group.find_by_full_path('my/group/fullpath') - -# Enable -Feature.enable(:github_importer_single_endpoint_notes_import, group) - -# Disable -Feature.disable(:github_importer_single_endpoint_notes_import, group) -``` - ## Reduce GitHub API request objects per page Some GitHub API endpoints may return a 500 or 502 error for project imports from large repositories. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 8d30a9c7f52..795cb964423 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import a project from GitLab.com to your private GitLab instance **(FREE)** diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 72d533efd1b..1b5a658d209 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate projects to a GitLab instance **(FREE)** diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 8fb495cd0db..c8b717d0421 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import your Jira project issues to GitLab **(FREE)** diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index f04048980e7..ea26613639d 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import multiple repositories by uploading a manifest file **(FREE)** @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab allows you to import all the required Git repositories based on a manifest file like the one used by the [Android repository](https://android.googlesource.com/platform/manifest/+/2d6f081a3b05d8ef7a2b1b52b0d536b2b74feab4/default.xml). -This feature can be very handy when you need to import a project with many +Use the manifest to import a project with many repositories like the Android Open Source Project (AOSP). ## Requirements diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index aa256e07b30..ca50a32836e 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrating from Perforce Helix **(FREE)** diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 96b38b49960..49f12ca2ba6 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import Phabricator tasks into a GitLab project **(FREE SELF)** diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index d64bea2bb41..d6f4f862b95 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Import project from repository by URL **(FREE)** diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index d6bcb0a2018..1687d621e2e 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Migrate from Subversion to GitLab **(FREE)** diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 910be690d0b..3625355340b 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -9,7 +9,7 @@ type: concepts Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes -[Team Foundation Version Control](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/what-is-tfvc?view=azure-devops) +[Team Foundation Version Control](https://learn.microsoft.com/en-us/azure/devops/repos/tfvc/what-is-tfvc?view=azure-devops) (TFVC), a centralized version control system similar to Git. In this document, we focus on the TFVC to Git migration. @@ -28,7 +28,7 @@ The main differences between TFVC and Git are: For more information, see: -- Microsoft's [comparison of Git and TFVC](https://docs.microsoft.com/en-us/azure/devops/repos/tfvc/comparison-git-tfvc?view=azure-devops). +- Microsoft's [comparison of Git and TFVC](https://learn.microsoft.com/en-us/azure/devops/repos/tfvc/comparison-git-tfvc?view=azure-devops). - The Wikipedia [comparison of version control software](https://en.wikipedia.org/wiki/Comparison_of_version_control_software). ## Why migrate diff --git a/doc/user/project/index.md b/doc/user/project/index.md index e4ae0c4b29b..78a6e8d565f 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Organize work with projects **(FREE)** diff --git a/doc/user/project/insights/img/project_insights.png b/doc/user/project/insights/img/project_insights.png Binary files differdeleted file mode 100644 index 83674c94110..00000000000 --- a/doc/user/project/insights/img/project_insights.png +++ /dev/null diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 81293fb1645..2874bf98736 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,64 +1,68 @@ --- -stage: Manage +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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Insights **(ULTIMATE)** +# Insights for projects **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. +Configure project insights to explore data such as: -Configure the Insights that matter for your projects to explore data such as -triage hygiene, issues created/closed per a given period, average time for merge -requests to be merged and much more. +- Issues created and closed during a specified period. +- Average time for merge requests to be merged. +- Triage hygiene. - +Insights are also available for [groups](../../group/insights/index.md). -NOTE: -This feature is [also available at the group level](../../group/insights/index.md). +## View project insights -## View your project's Insights +Prerequisites: -You can access your project's Insights by clicking the **Analytics > Insights** -link in the left sidebar. +- You must have: + - Access to a project to view information about its merge requests and issues. + - Permission to view confidential merge requests and issues in the project. -## Configure your Insights +To view project insights: -Insights are configured using a YAML file called `.gitlab/insights.yml` within -a project. That file is used in the project's Insights page. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Insights**. +1. To view a report, select the **Select report** dropdown list. -See [Writing your `.gitlab/insights.yml`](#writing-your-gitlabinsightsyml) below -for details about the content of this file. +## Configure project insights -NOTE: -After the configuration file is created, you can also -[use it for your project's group](../../group/insights/index.md#configure-your-insights). +Prerequisites: -NOTE: -If the project doesn't have any configuration file, it attempts to use -the group configuration if possible. If the group doesn't have any -configuration, the default configuration is used. +- Depending on your project configuration, you must have at least the Developer role. -## Permissions +Project insights are configured with the [`.gitlab/insights.yml`](#insights-configuration-file) file in the project. If a project doesn't have a configuration file, it uses the [group configuration](../../group/insights/index.md#configure-group-insights). -If you have access to view a project, then you have access to view their -Insights. +The `.gitlab/insights.yml` file is a YAML file where you define: -NOTE: -Issues or merge requests that you don't have access to (because you don't have -access to the project they belong to, or because they are confidential) are -filtered out of the Insights charts. +- The structure and order of charts in a report. +- The style of charts displayed in the report of your project or group. + +To configure project insights, either: + +- Create a `.gitlab/insights.yml` file locally in the root directory of your project, and push your changes. +- Create a `.gitlab/insights.yml` file in the UI: + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. Above the file list, select the branch you want to commit to, select the plus icon, then select **New file**. + 1. In the **File name** text box, enter `.gitlab/insights.yml`. + 1. In the large text box, update the file contents. + 1. Select **Commit changes**. -You may also consult the [group permissions table](../../permissions.md#group-members-permissions). +After you create the configuration file, you can also +[use it for the project's group](../../group/insights/index.md#configure-group-insights). -## Writing your `.gitlab/insights.yml` +## Insights configuration file -The `.gitlab/insights.yml` file defines the structure and order of the Insights -charts displayed in each Insights page of your project or group. +In the `.gitlab/insights.yml` file: -Each page has a unique key and a collection of charts to fetch and display. +- [Configuration parameters](#insights-configuration-parameters) define the chart behavior. +- Each report has a unique key and a collection of charts to fetch and display. +- Each chart definition is made up of a hash composed of key-value pairs. -For example, here's a single definition for Insights that displays one page with one chart: +The following example shows a single definition that displays one report with one chart. ```yaml bugsCharts: @@ -78,30 +82,9 @@ bugsCharts: period_limit: 24 ``` -Each chart definition is made up of a hash composed of key-value pairs. +## Insights configuration parameters -For example, here's single chart definition: - -```yaml -- title: "Monthly bugs created" - description: "Open bugs created per month" - type: bar - query: - data_source: issuables - params: - issuable_type: issue - issuable_state: opened - filter_labels: - - bug - group_by: month - period_limit: 24 -``` - -## Configuration parameters - -A chart is defined as a list of parameters that define the chart's behavior. - -The following table lists available parameters for charts: +The following table lists the chart parameters: | Keyword | Description | |:---------------------------------------------------|:------------| @@ -110,15 +93,11 @@ The following table lists available parameters for charts: | [`type`](#type) | The type of chart: `bar`, `line` or `stacked-bar`. | | [`query`](#query) | A hash that defines the data source and filtering conditions for the chart. | -## Parameter details - -The following are detailed explanations for parameters used to configure -Insights charts. - ### `title` -`title` is the title of the chart as it displays on the Insights page. -For example: +Use `title` to update the chart title. The title displays on the insights report. + +**Example:** ```yaml monthlyBugsCreated: @@ -127,8 +106,9 @@ monthlyBugsCreated: ### `description` -The `description` text is displayed above the chart, but below the title. It's used -to give extra details regarding the chart, for example: +Use `description` to add a description of the chart. The description displays above the chart, below the title. + +**Example:** ```yaml monthlyBugsCreated: @@ -138,33 +118,32 @@ monthlyBugsCreated: ### `type` -`type` is the chart type. - -For example: - -```yaml -monthlyBugsCreated: - title: "Monthly bugs created" - type: bar -``` +Use `type` to define the chart type. -Supported values are: +**Supported values:** -| Name | Example | +| Name | Example: | | ----- | ------- | | `bar` |  | | `bar` (time series, that is when `group_by` is used) |  | | `line` |  | | `stacked-bar` |  | -NOTE: -The `dora` data source supports the `bar` and `line` chart types. +The `dora` data source supports the `bar` and `line` [chart types](#type). + +**Example:** + +```yaml +monthlyBugsCreated: + title: "Monthly bugs created" + type: bar +``` ### `query` -`query` allows to define the data source and various filtering conditions for the chart. +Use `query` to define the data source and filtering conditions for the chart. -Example: +**Example:** ```yaml monthlyBugsCreated: @@ -212,46 +191,46 @@ monthlyBugsCreated: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 15.3. -The `data_source` parameter was introduced to allow visualizing data from different data sources. +Use `data_source` to define the data source that exposes the data. -Supported values are: +**Supported values:** - `issuables`: Exposes merge request or issue data. -- `dora`: Exposes DORA metrics data. +- `dora`: Exposes DORA metrics. -#### `Issuable` query parameters +#### `issuable` query parameters ##### `query.params.issuable_type` -Defines the type of "issuable" you want to create a chart for. +Use `query.params.issuable_type` to define the type of issuable to create a chart for. -Supported values are: +**Supported values:** - `issue`: The chart displays issues' data. - `merge_request`: The chart displays merge requests' data. ##### `query.params.issuable_state` -Filter by the current state of the queried "issuable". +Use `query.params.issuable_state` to filter by the current state of the queried issuable. By default, the `opened` state filter is applied. -Supported values are: +**Supported values:** -- `opened`: Open issues / merge requests. -- `closed`: Closed Open issues / merge requests. -- `locked`: Issues / merge requests that have their discussion locked. +- `opened`: Open issues or merge requests. +- `closed`: Closed issues or merge requests. +- `locked`: Issues or merge requests that have their discussion locked. - `merged`: Merged merge requests. -- `all`: Issues / merge requests in all states +- `all`: Issues or merge requests in all states. ##### `query.params.filter_labels` -Filter by labels currently applied to the queried "issuable". +Use `query.params.filter_labels` to filter by labels applied to the queried issuable. -By default, no labels filter is applied. All the defined labels must be -currently applied to the "issuable" in order for it to be selected. +By default, no label filter is applied. All defined labels must +be applied to the issuable for it to be selected. -Example: +**Example:**: ```yaml monthlyBugsCreated: @@ -269,12 +248,13 @@ monthlyBugsCreated: ##### `query.params.collection_labels` -Group "issuable" by the configured labels. +Use `query.params.collection_labels` to group issuables by the configured labels. +Grouping is not applied by default. -By default, no grouping is done. When using this keyword, you need to -set `type` to either `line` or `stacked-bar`. +When using this parameter, you must +set `type` to `line` or `stacked-bar`. -Example: +**Example:** ```yaml weeklyBugsBySeverity: @@ -296,9 +276,9 @@ weeklyBugsBySeverity: ##### `query.group_by` -Define the X-axis of your chart. +Use `query.group_by` to define the X-axis of the chart. -Supported values are: +**Supported values:** - `day`: Group data per day. - `week`: Group data per week. @@ -306,11 +286,10 @@ Supported values are: ##### `query.period_limit` -Define how far "issuables" are queried in the past (using the `query.period_field`). +Use `query.period_limit` to define how far back in time to query issuables (using the `query.period_field`). -The unit is related to the `query.group_by` you defined. For instance if you -defined `query.group_by: 'day'` then `query.period_limit: 365` would mean -"Gather and display data for the last 365 days". +The unit is related to the value defined in `query.group_by`. For example, if you +defined `query.group_by: 'day'`, and `query.period_limit: 365`, the chart displays data from the last 365 days. By default, default values are applied depending on the `query.group_by` you defined. @@ -323,9 +302,9 @@ you defined. #### `query.period_field` -Define the timestamp field used to group "issuables". +Use `query.period_field` to define the timestamp field by which to group issuables. -Supported values are: +**Supported values:** - `created_at` (default): Group data using the `created_at` field. - `closed_at`: Group data using the `closed_at` field (for issues only). @@ -345,7 +324,9 @@ you may see `created_at` in place of `merged_at`. `created_at` is used instead. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367248) in GitLab 15.3. -An example DORA chart definition: +Use DORA-specific queries with the `dora` data source to create a DORA chart definition. + +**Example:** ```yaml dora: @@ -377,55 +358,59 @@ dora: ##### `query.metric` -Defines which DORA metric to query. The available values are: +Use `query.metric` to define the [DORA metrics](../../../api/dora/metrics.md#the-value-field) to query. + +**Supported values:** - `deployment_frequency` (default) - `lead_time_for_changes` - `time_to_restore_service` - `change_failure_rate` -The metrics are described on the [DORA API](../../../api/dora/metrics.md#the-value-field) page. - ##### `query.group_by` -Define the X-axis of your chart. +Use `query.group_by` to define the X-axis of your chart. -Supported values are: +**Supported values:** - `day` (default): Group data per day. - `month`: Group data per month. ##### `query.period_limit` -Define how far the metrics are queried in the past (default: 15). Maximum lookback period is 180 days or 6 months. +Use `query.period_limit` to define how far the metrics are queried in the past (default: 15). The maximum period is 180 days or 6 months. ##### `query.environment_tiers` -An array of environments to include into the calculation (default: production). Available options: `production`, `staging`, `testing`, `development`, `other`. +Use `query.environment_tiers` to define an array of environments to include the calculation. -### `projects` +**Supported values:** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10904) in GitLab 12.4. +- `production`(default) +- `staging` +- `testing` +- `development` +- `other` + +### `projects` -You can limit where the "issuables" can be queried from: +Use `projects` to limit where issuables are queried from: -- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects currently under the group are used. -- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects yields no results. By default, the project itself is used. +- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-group-insights), use `projects` to define the projects from which to query issuables. By default, all projects under the group are used. +- If `.gitlab/insights.yml` is used for a project's insights, specifying other projects does not yield results. By default, the project is used. #### `projects.only` -The `projects.only` option specifies the projects which the "issuables" -should be queried from. +Use `projects.only` to specify the projects from which issuables +are queried. -Projects listed here are ignored when: +Projects listed in this parameter are ignored when: - They don't exist. - The current user doesn't have sufficient permissions to read them. -- They are outside of the group. +- They are outside the group. -In the following `insights.yml` example, we specify the projects -the queries are used on. This example is useful when setting -a group's insights: +**Example:** ```yaml monthlyBugsCreated: @@ -447,7 +432,7 @@ monthlyBugsCreated: - groupB/project # Projects outside the group will be ignored ``` -## Complete example +## Complete insights configuration example ```yaml .projectsOnly: &projectsOnly diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 07b37b5be43..97fb4e7c463 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Asana integration **(FREE)** diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 7b39f6c7162..fceec006a1a 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Atlassian Bamboo integration **(FREE)** diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index f058950e0f4..9221250e17f 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Bugzilla service **(FREE)** diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index c3794aa1a2b..24a2e3d1ebc 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom issue tracker **(FREE)** diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index dffcc780206..9439e480484 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Discord Notifications service **(FREE)** diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 37d9a86f8fa..ff255cbba51 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Enabling emails on push **(FREE)** diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 45f3653757d..d972509c0f6 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # IBM Engineering Workflow Management (EWM) Integration **(FREE)** diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 4be541d99cb..603ed8b4c05 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitHub project integration **(PREMIUM)** diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index afc379e7a07..07c99653a0e 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Slack application **(FREE SAAS)** @@ -22,7 +22,7 @@ The simplest way to enable the GitLab Slack application for your workspace is to install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from the [Slack App Directory](https://slack.com/apps). -Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/-/profile/slack/edit) +Selecting install takes you to the [GitLab Slack application landing page](https://gitlab.com/-/profile/slack/edit) where you can select a project to enable the GitLab Slack application for. ## Configuration @@ -89,3 +89,17 @@ project, you would do: In GitLab 15.0 the Slack app is updated to [Slack's new granular permissions app model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). There is no change in functionality. A reinstall is not required but recommended. + +## Troubleshooting + +When you work with the Slack app, the +[App Home](https://api.slack.com/start/overview#app_home) might not display properly. +As a workaround, ensure your app is up to date. + +To update an existing Slack integration: + +1. Go to your [chat settings](https://gitlab.com/-/profile/chat_names). +1. Next to your project, select **Slack application**. +1. Select **Reinstall Slack app**. + +Alternatively, you can [configure a new Slack integration](https://about.gitlab.com/solutions/slack/). diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index b2586383b43..1be0db223ac 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Google Chat integration **(FREE)** diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 535703ff59e..259b91fc1c7 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Harbor container registry integration **(FREE)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use Harbor as the container registry for your GitLab project. -[Harbor](https://goharbor.io/) is an open source registry that can help you manage artifacts across cloud native compute platforms, like Kubernetes and Docker. +[Harbor](https://goharbor.io/) is an open source registry that can help you manage artifacts across cloud-native compute platforms, like Kubernetes and Docker. This integration can help you if you need GitLab CI/CD and a container image repository. diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 18e827f8df8..77444570499 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Project integrations **(FREE)** diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 5f7de09cc9d..70f48e4647a 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # irker IRC Gateway **(FREE)** diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 12575e34058..39b89cd87a9 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mattermost notifications service **(FREE)** diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 28a5f2eec18..192360f5440 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mattermost slash commands **(FREE)** diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 2e6954390fb..cedb5af144f 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Microsoft Teams service **(FREE)** @@ -58,4 +58,4 @@ GitLab to send the notifications: ## Related topics -- [Setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). +- [Setting up an incoming webhook on Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 5cde17dbd83..64ee4521ce4 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Mock CI Service **(FREE)** diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md deleted file mode 100644 index 9625edcd8f9..00000000000 --- a/doc/user/project/integrations/overview.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2022-07-20' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after 2022-07-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/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md index c58f5a13613..009bb6662ff 100644 --- a/doc/user/project/integrations/pipeline_status_emails.md +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline status emails **(FREE)** diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index a0798da21f0..79a00725470 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pivotal Tracker service **(FREE)** diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index c1181169261..9bafa9734e2 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Prometheus integration **(FREE)** diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 08488c33ac7..1e9319fa7c7 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring AWS resources (DEPRECATED) **(FREE)** diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index ad2cb2681b9..b4533d83acd 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring HAProxy (DEPRECATED) **(FREE)** diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index aba14e1f3e9..4ef3a847ef1 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Prometheus Metrics library (DEPRECATED) **(FREE)** diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 9a9880a0cb6..0795c110deb 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring Kubernetes (DEPRECATED) **(FREE)** @@ -35,7 +35,7 @@ integration services must be enabled. ## Configuring Prometheus to monitor for Kubernetes metrics -Prometheus needs to be deployed into the cluster and configured properly in order to gather Kubernetes metrics. GitLab supports two methods for doing so: +Prometheus needs to be deployed into the cluster and configured properly to gather Kubernetes metrics. GitLab supports two methods for doing so: - GitLab [integrates with Kubernetes](../../clusters/index.md), and can [query a Prometheus in a connected cluster](../../../clusters/integrations.md#prometheus-cluster-integration). The in-cluster Prometheus can be configured to automatically collect application metrics from your cluster. - To configure your own Prometheus server, you can follow the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/). diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 2825066b8b0..f0a3b25f11a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring NGINX (DEPRECATED) **(FREE)** diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 4c8e648537c..99466a67417 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring NGINX Ingress Controller (DEPRECATED) **(FREE)** diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index e1eee649f0a..e26f93351a1 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Respond -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Monitoring NGINX Ingress Controller with VTS metrics (DEPRECATED) **(FREE)** diff --git a/doc/user/project/integrations/pumble.md b/doc/user/project/integrations/pumble.md index 0eb3a38bb86..f9c0c79be1b 100644 --- a/doc/user/project/integrations/pumble.md +++ b/doc/user/project/integrations/pumble.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pumble **(FREE)** diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index bc1d299dccf..e9752d7ce6c 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Redmine service **(FREE)** diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index dc6c2da0d91..d528d1a5547 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ServiceNow integration **(FREE)** diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index ea92b8b3f0b..28cb53f8bf6 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Shimo Workspace integration **(FREE)** diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index ae2e57a6d7f..9fe0c76ec4f 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Slack notifications service **(FREE)** @@ -127,3 +127,21 @@ the GitLab OpenSSL trust store is incorrect. Typical causes are: - Overriding the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`. - Accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`. + +### Bulk update to disable the Slack Notification service + +To disable notifications for all projects that have Slack integration enabled, +[start a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and use a script similar to the following: + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +```ruby +# Grab all projects that have the Slack notifications enabled +p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations s ON p.id = s.project_id WHERE s.type_new = 'Slack' AND s.active = true") + +# Disable the service on each of the projects that were found. +p.each do |project| + project.slack_service.update!(:active, false) +end +``` diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 67d6befb5fc..cb698ac0ee0 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Slack slash commands **(FREE SELF)** diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 91beefd30ab..c13f642d9e9 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Unify Circuit service **(FREE)** diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 0b487e29d26..930ca8e99b8 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webex Teams service **(FREE)** @@ -14,7 +14,7 @@ You can configure GitLab to send notifications to a Webex Teams space: ## Create a webhook for the space 1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/applications/incoming-webhooks-cisco-systems-38054-23307). -1. Select **Connect** and log in to Webex Teams, if required. +1. Select **Connect**, and sign in to Webex Teams if required. 1. Enter a name for the webhook and select the space to receive the notifications. 1. Select **ADD**. 1. Copy the **Webhook URL**. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 51049f156b8..c0f0f5a0cd4 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webhook events **(FREE)** @@ -1100,6 +1100,7 @@ Payload example: "object_kind": "pipeline", "object_attributes":{ "id": 31, + "iid": 3, "ref": "master", "tag": false, "sha": "bcbb5ec396a2c0f828686f14fac9b80b780504f2", diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 1de7440a15d..9fc9d6e2eda 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Webhooks **(FREE)** @@ -64,54 +64,34 @@ You can configure a webhook for a group or a project. ## Configure your webhook receiver endpoint -Webhook receivers should be *fast* and *stable*. -Slow and unstable receivers may be disabled temporarily to ensure system reliability. -If you are writing your own endpoint (web server) to receive GitLab webhooks, keep in mind the following: - -- Your endpoint should send its HTTP response as fast as possible. - You should aim for sub-second response times in all circumstances. - If the response takes longer than the configured timeout, GitLab assumes the - hook failed, which can lead to retries and potentially cause duplicate - events. - To customize the timeout, see - [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). -- Your endpoint should ALWAYS return a valid HTTP response. If not, - GitLab assumes the hook failed and retries it. - Most HTTP libraries take care of the response for you automatically but if - you are writing a low-level hook, this is important to remember. -- GitLab usually ignores the HTTP status code returned by your endpoint, - unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks). - -Best practices for a webhook receiver: - -- Prefer to return `200` or `201` status responses. - Only return error statuses (in the `4xx` range) to - indicate that the webhook has been misconfigured. For example, if your receiver - only supports push events, it is acceptable to return `400` if sent an issue - payload, since that is an indication that the hook has been set up - incorrectly. Alternatively, it is acceptable to ignore unrecognized event - payloads. Never return `500` status responses if the event has been handled. -- Your service should be idempotent. In some circumstances (including - timeouts), the same event may be sent twice. Be prepared to handle duplicate - events. You can reduce the chances of this by ensuring that your endpoint is +Webhook receiver endpoints should be fast and stable. +Slow and unstable receivers can be [disabled automatically](#failing-webhooks) to ensure system reliability. Webhooks that fail can lead to retries, [which cause duplicate events](#webhook-fails-or-multiple-webhook-requests-are-triggered). + +Endpoints should follow these best practices: + +- **Respond quickly with a `200` or `201` status response.** Avoid any significant processing of webhooks in the same request. + Instead, implement a queue to handle webhooks after they are received. The timeout limit for webhooks is [10 seconds on GitLab.com](../../../user/gitlab_com/index.md#other-limits). +- **Be prepared to handle duplicate events.** In [some circumstances](#webhook-fails-or-multiple-webhook-requests-are-triggered), the same event may be sent twice. To mitigate this issue, ensure your endpoint is reliably fast and stable. -- Keep response payloads as short as possible. Empty responses are - fine. GitLab does not examine the response body, and it is only - stored so you can examine it later in the logs. -- Limit the number and size of response headers. Only send headers that would - help you diagnose problems when examining the web hook logs. -- To support fast response times, perform I/O or computationally intensive - operations asynchronously. You may indicate that the webhook is - asynchronous by returning `201`. +- **Keep the response headers and body minimal.** + GitLab does not examine the response headers or body. GitLab stores them so you can examine them later in the logs to help diagnose problems. You should limit the number and size of headers returned. You can also respond to the webhook request with an empty body. +- Only return client error status responses (in the `4xx` range) to + indicate that the webhook has been misconfigured. Responses in this range can lead to your webhooks being [automatically disabled](#failing-webhooks). For example, if your receiver + only supports push events, you can return `400` if sent an issue + payload, as that is an indication that the hook has been set up + incorrectly. Alternatively, you can ignore unrecognized event + payloads. +- Never return `500` server error status responses if the event has been handled as this can cause the webhook to be [temporarily disabled](#failing-webhooks). +- Invalid HTTP responses are treated as failed requests. ### Failing webhooks -> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9. +> Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. +On GitLab.com, this feature is not available. The feature is not ready for production use. If a webhook fails repeatedly, it may be disabled automatically. @@ -234,6 +214,18 @@ Image URLs are not rewritten if: For more information about supported events for Webhooks, go to [Webhook events](webhook_events.md). +## Delivery headers + +> `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5. + +Webhook requests to your endpoint include the following headers: + +| Header | Description | Example | +| ------ | ------ | ------ | +| `User-Agent` | In the format `"Gitlab/<VERSION>"`. | `"GitLab/15.5.0-pre"` | +| `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | +| `X-Gitlab-Instance` | Hostname of the GitLab instance that sent the webhook. | `"https://gitlab.com"` | + ## Troubleshoot webhooks > **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3. @@ -271,20 +263,6 @@ To repeat the delivery with the same data, select **Resend Request**. NOTE: If you update the URL or secret token of the webhook, data is delivered to the new address. -### Webhook fails or multiple webhook requests are triggered - -When GitLab sends a webhook, it expects a response in 10 seconds by default. -If the endpoint doesn't send an HTTP response in those 10 seconds, -GitLab may assume the webhook failed and retry it. - -If your webhooks are failing or you are receiving multiple requests, -an administrator can try changing the default timeout value -by uncommenting or adding the following setting in `/etc/gitlab/gitlab.rb`: - -```ruby -gitlab_rails['webhook_timeout'] = 10 -``` - ### Unable to get local issuer certificate When SSL verification is enabled, you might get an error that GitLab cannot @@ -296,8 +274,24 @@ determined by [CAcert.org](http://www.cacert.org/). If that is not the case, consider using [SSL Checker](https://www.sslshopper.com/ssl-checker.html) to identify faults. Missing intermediate certificates are common causes of verification failure. +### Webhook fails or multiple webhook requests are triggered + +If you are receiving multiple webhook requests, the webhook might have timed out and +been retried. + +GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#other-limits). On self-managed GitLab instances, you can [change the webhook timeout limit](../../../administration/instance_limits.md#webhook-timeout). + ### Re-enable disabled webhooks +> - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default. +> - The [`web_hooks_disable_failed` flag](#failing-webhooks) must also be enabled for this feature to work. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flags](../../../administration/feature_flags.md) named `webhooks_failed_callout` and `web_hooks_disable_failed`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + If a webhook is failing, a banner displays at the top of the edit page explaining why it is disabled, and when it will be automatically re-enabled. For example: diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index e6071e7517d..fb6807aeeb0 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # YouTrack service **(FREE)** diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index 0256c52e4a3..17727ba22b1 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -1,7 +1,7 @@ --- -stage: Ecosystem +stage: Manage group: Integrations -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # ZenTao product integration **(PREMIUM)** diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 916d566bb20..1cf902d2290 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue boards **(FREE)** @@ -161,7 +161,7 @@ Cards finished by the UX team automatically appear in the **Frontend** column wh for them. NOTE: -For a broader use case, please see the blog post +For a broader use case, see the blog post [What is GitLab Flow?](https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/). For a real use case example, you can read why [Codepen decided to adopt issue boards](https://about.gitlab.com/blog/2017/01/27/codepen-welcome-to-gitlab/#project-management-everything-in-one-place) @@ -243,13 +243,13 @@ This allows you to create unique boards according to your team's need.  -You can define the scope of your board when creating it or by clicking the **Edit board** button. +You can define the scope of your board when creating it or by selecting the **Edit board** button. After a milestone, iteration, assignee, or weight is assigned to an issue board, you can no longer filter through these in the search bar. In order to do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. If you don't have editing permission in a board, you're still able to see the configuration by -clicking **View scope**. +selecting **View scope**. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of @@ -474,7 +474,7 @@ Additionally, you can also see the time tracking value. ### Create a new list -Create a new list by clicking the **Create** button in the upper right corner of the issue board. +Create a new list by selecting the **Create** button in the upper right corner of the issue board.  @@ -698,8 +698,8 @@ A few things to remember: and adds the label from the list it goes to. - An issue can exist in multiple lists if it has more than one label. - Lists are populated with issues automatically if the issues are labeled. -- Clicking the issue title inside a card takes you to that issue. -- Clicking a label inside a card quickly filters the entire issue board +- Selecting the issue title inside a card takes you to that issue. +- Selecting a label inside a card quickly filters the entire issue board and show only the issues from all lists that have that label. - For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues, start scrolling down and the next diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index ef864dc2743..c7187323850 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Associate a Zoom meeting with an issue **(FREE)** diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 5a1e66c8f7d..b1bb3f0dbf8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Confidential issues **(FREE)** diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index ed6c07f2c6d..0b5605bb767 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Crosslinking issues **(FREE)** diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index e5d698fa97a..83265d3e954 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export issues to CSV **(FREE)** @@ -15,7 +15,7 @@ notification email address as an attachment. collected from issues into a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) file, which stores tabular data in plain text. -> _CSVs are a handy way of getting data from one program to another where one +> _CSVs are a way of getting data from one program to another where one program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) <!-- vale gitlab.Spelling = NO --> diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 1ae57c9a883..d01f22d03c9 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 -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Importing issues from CSV **(FREE)** diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index bf3cd13f3f0..593557967ed 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Design Management **(FREE)** diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 2630052d806..6293fe981de 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Due dates **(FREE)** diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index a2dbc8581d9..09067b69696 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issues **(FREE)** diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 21d7fb0a764..1ba5a4415e0 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Issue weight **(PREMIUM)** diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index b4edb238479..213c615326f 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Manage issues **(FREE)** @@ -68,7 +68,7 @@ To create an issue from a group: The newly created issue opens. The project you selected most recently becomes the default for your next visit. -This can save you a lot of time and clicks, if you mostly create issues for the same project. +This can save you a lot of time, if you mostly create issues for the same project. ### From another issue or incident @@ -577,6 +577,7 @@ Or: > - Filtering by type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 13.10 [with a flag](../../../administration/feature_flags.md) named `vue_issues_list`. Disabled by default. > - Filtering by type was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 14.10. > - Filtering by type is generally available in GitLab 15.1. [Feature flag `vue_issues_list`](https://gitlab.com/gitlab-org/gitlab/-/issues/359966) removed. +> - Filtering by health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218711) in GitLab 15.5. To filter the list of issues: diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index db160b6cfe8..59555e1f675 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Multiple assignees for issues **(PREMIUM)** diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index d1e62a76103..53ad7196920 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Linked issues **(FREE)** diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 95a7e9387e8..6a1a791645e 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sorting and ordering issue lists **(FREE)** diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 13c93fadf6e..826e0b21ea7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Labels **(FREE)** @@ -448,10 +448,10 @@ To learn what happens when you sort by priority or label priority, see > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241538) in GitLab 14.10 with a [feature flag](../../administration/feature_flags.md) named `realtime_labels`, disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/357370#note_991987201) in GitLab 15.1. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/357370) in GitLab 15.5. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an -administrator to [enable the feature flag](../../administration/feature_flags.md) named `realtime_labels`. +On self-managed GitLab, to prevent updating labels in real-time, you can ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `realtime_labels`. On GitLab.com, this feature is available. Changed labels are immediately visible to other users, without refreshing the page, on the following: diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 8d8169e8454..a8f1b634127 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Members of a project **(FREE)** @@ -234,8 +234,8 @@ GitLab users can request to become a member of a project.  -An email is sent to the most recently active project maintainers. -Up to ten project maintainers are notified. +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. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index ee161deaabb..52cc9fc4f9b 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: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Share projects with other groups **(FREE)** diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md deleted file mode 100644 index c1a87f7a5d4..00000000000 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../ci/testing/accessibility_testing.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](../../../ci/testing/accessibility_testing.md). - -<!-- This redirect file can be deleted after <2022-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 --> diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index d06c8182e22..d3d95a5bf61 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Collaborate on merge requests across forks **(FREE)** diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 9f33ed6807b..ea03427161e 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/approvals/index.html' --- diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 32548215054..e09a1318981 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request approval rules **(PREMIUM)** diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 4fdf6d46b8b..a2a12b22c3b 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge request approval settings **(PREMIUM)** @@ -125,7 +125,7 @@ when more changes are added to it: 1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval settings** and - select **Remove all approvals when commits are added to the source branch**. + select **Remove all approvals**. 1. Select **Save changes**. Approvals aren't removed when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods) 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 37ecc1b8d06..ba28432e90a 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md deleted file mode 100644 index 95f749210c4..00000000000 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../ci/testing/browser_performance_testing.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](../../../ci/testing/browser_performance_testing.md). - -<!-- This redirect file can be deleted after <2022-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 --> diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 5016a33ed28..6703cbf8b03 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 2040995280e..388c6fb55ac 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md deleted file mode 100644 index 79e590cb905..00000000000 --- a/doc/user/project/merge_requests/code_quality.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../ci/testing/code_quality.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](../../../ci/testing/code_quality.md). - -<!-- This redirect file can be deleted after <2022-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 --> diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 99a1739b1a4..75c2bdffae8 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 20e0d3a1f5b..a6ae3ac80a5 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 5b17ec009e4..307998f697d 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests for confidential issues **(FREE)** diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index dc128f89fcd..902095bcbce 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 1a44126f7ff..df11d5a1d8d 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/engineering/ux/technical-writing/#assignments +info: To 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: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- @@ -10,6 +10,9 @@ disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.h There are many different ways to create a merge request. +NOTE: +Use [branch naming patterns](../repository/branches/index.md#naming) to streamline merge request creation. + ## From the merge request list You can create a merge request from the list of merge requests. @@ -93,8 +96,8 @@ You can create a merge request from your fork to contribute back to the main pro 1. On the top bar, select **Main menu > Projects** and find your project. 1. Select your fork of the repository. 1. On the left menu, go to **Merge requests**, and select **New merge request**. -1. In the **Source branch** drop-down list box, select the branch in your forked repository as the source branch. -1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. +1. In the **Source branch** dropdown list box, select the branch in your forked repository as the source branch. +1. In the **Target branch** dropdown list box, select the branch from the upstream repository as the target branch. You can set a [default target project](#set-the-default-target-project) to change the default target branch (which can be useful if you are working in a forked project). diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f997898f5a5..662189c5e40 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Export merge requests to CSV **(FREE)** diff --git a/doc/user/project/merge_requests/dependencies.md b/doc/user/project/merge_requests/dependencies.md index 5b88e69357c..d0b0ead6b87 100644 --- a/doc/user/project/merge_requests/dependencies.md +++ b/doc/user/project/merge_requests/dependencies.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 695c6d7e612..2beb7406518 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.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/engineering/ux/technical-writing/#assignments +info: To determine 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 disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/work_in_progress_merge_requests.html' --- diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md deleted file mode 100644 index c09a7c14c06..00000000000 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../ci/testing/fail_fast_testing.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](../../../ci/testing/fail_fast_testing.md). - -<!-- This redirect file can be deleted after <2022-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 --> diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md deleted file mode 100644 index 048421a3a5b..00000000000 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'methods/index.md' -remove_date: '2022-08-09' ---- - -This document was moved to [another location](methods/index.md). - -<!-- This redirect file can be deleted after <2022-08-09>. --> -<!-- 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/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 9475c0d60ab..427ab9606e8 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.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/engineering/ux/technical-writing/#assignments +info: To 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: "Getting started with merge requests." --- diff --git a/doc/user/project/merge_requests/img/dependencies_edit_inaccessible_v12_4.png b/doc/user/project/merge_requests/img/dependencies_edit_inaccessible_v12_4.png Binary files differdeleted file mode 100644 index 5ced2fa812f..00000000000 --- a/doc/user/project/merge_requests/img/dependencies_edit_inaccessible_v12_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/dependencies_view_v12_2.png b/doc/user/project/merge_requests/img/dependencies_view_v12_2.png Binary files differdeleted file mode 100644 index 3dde15292c4..00000000000 --- a/doc/user/project/merge_requests/img/dependencies_view_v12_2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 500fb95c193..e73c339e000 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -254,7 +254,7 @@ after merging does not retarget open merge requests. This improvement is For a software developer working in a team: -1. You checkout a new branch, and submit your changes through a merge request. +1. You check out a new branch, and submit your changes through a merge request. 1. You gather feedback from your team. 1. You work on the implementation optimizing code with [Code Quality reports](../../../ci/testing/code_quality.md). 1. You verify your changes with [Unit test reports](../../../ci/testing/unit_test_reports.md) in GitLab CI/CD. @@ -269,7 +269,7 @@ For a software developer working in a team: For a web developer writing a webpage for your company's website: -1. You checkout a new branch and submit a new page through a merge request. +1. You check out a new branch and submit a new page through a merge request. 1. You gather feedback from your reviewers. 1. You preview your changes with [Review Apps](../../../ci/review_apps/index.md). 1. You request your web designers for their implementation. diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md deleted file mode 100644 index 04b62c5d8fe..00000000000 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../ci/testing/load_performance_testing.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](../../../ci/testing/load_performance_testing.md). - -<!-- This redirect file can be deleted after <2022-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 --> 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 57c4ff455cb..f0359446b06 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index 68dd6477408..e72c927198e 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index a6e0740ff78..3b07f75a3a7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Revert changes **(FREE)** diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index 0988e3f0042..56fb84c8085 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -1,7 +1,7 @@ --- stage: ModelOps group: Applied ML -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 +info: To determine 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 --- @@ -9,36 +9,36 @@ type: index, reference ## How it works -Suggested Reviewers is the first user-facing GitLab machine learning (ML) powered feature. It leverages a project's contribution graph to generate suggestions. This data already exists within GitLab including merge request metadata, source code files, and GitLab user account metadata. +Suggested Reviewers is the first user-facing GitLab machine learning (ML) powered feature. It leverages a project's contribution graph to generate suggestions. This data already exists within GitLab including merge request metadata, source code files, and GitLab user account metadata. ### Enabling the feature When a Project Maintainer or Owner enables Suggested Reviewers in project settings GitLab kicks off a data extraction job for the project which leverages the Merge Request API to understand pattern of review including recency, domain experience, and frequency to suggest an appropriate reviewer. -This data extraction job can take a few hours to complete (possibly up to a day), which is largely dependent on the size of the project. The process is automated and no action is needed during this process. Once data extraction is complete, you will start getting suggestions in merge requests. +This data extraction job can take a few hours to complete (possibly up to a day), which is largely dependent on the size of the project. The process is automated and no action is needed during this process. Once data extraction is complete, you will start getting suggestions in merge requests. ### Generating suggestions -Once Suggested Reviewers is enabled and the data extraction is complete, new merge requests or new commits to existing merge requests will automatically trigger a Suggested Reviewers ML model inference and generate up to 5 suggested reviewers. These suggestions are contextual to the changes in the merge request. Additional commits to merge requests may change the reviewer suggestions which will automatically update in the reviewer dropdown. +Once Suggested Reviewers is enabled and the data extraction is complete, new merge requests or new commits to existing merge requests will automatically trigger a Suggested Reviewers ML model inference and generate up to 5 suggested reviewers. These suggestions are contextual to the changes in the merge request. Additional commits to merge requests may change the reviewer suggestions which will automatically update in the reviewer dropdown. ## Progressive enhancement -This feature is designed as a progressive enhancement to the existing GitLab Reviewers functionality. The GitLab Reviewer UI will only offer suggestions if the ML engine is able to provide a recommendation. In the event of an issue or model inference failure, the feature will gracefully degrade. At no point with the usage of Suggested Reviewers prevent a user from being able to manually set a reviewer. +This feature is designed as a progressive enhancement to the existing GitLab Reviewers functionality. The GitLab Reviewer UI will only offer suggestions if the ML engine is able to provide a recommendation. In the event of an issue or model inference failure, the feature will gracefully degrade. At no point with the usage of Suggested Reviewers prevent a user from being able to manually set a reviewer. ## Model Accuracy -Organizations use many different processes for code review. Some focus on senior engineers reviewing junior engineer's code, others have hierarchical organizational structure based reviews. Suggested Reviewers is focused on contextual reviewers based on historical merge request activity by users. While we will continue evolving the underlying ML model to better serve various code review use cases and processes Suggested Reviewers does not replace the usage of other code review features like Code Owners and [Approval Rules](../approvals/rules.md). Reviewer selection is highly subjective therefore, we do not expect Suggested Reviewers to provide perfect suggestions everytime. +Organizations use many different processes for code review. Some focus on senior engineers reviewing junior engineer's code, others have hierarchical organizational structure based reviews. Suggested Reviewers is focused on contextual reviewers based on historical merge request activity by users. While we will continue evolving the underlying ML model to better serve various code review use cases and processes Suggested Reviewers does not replace the usage of other code review features like Code Owners and [Approval Rules](../approvals/rules.md). Reviewer selection is highly subjective therefore, we do not expect Suggested Reviewers to provide perfect suggestions everytime. Through analysis of beta customer usage, we find that the Suggested Reviewers ML model provides suggestions that are adopted in 60% of cases. We will be introducing a feedback mechanism into the Suggested Reviewers feature in the future to allow users to flag bad reviewer suggestions to help improve the model. Additionally we will be offering an opt-in feature in the future which will allow the model to use your project's data for training the underlying model. ## Off by default -Suggested Reviewers is off by default and requires a Project Owner or Admin to enable the feature. +Suggested Reviewers is off by default and requires a Project Owner or Admin to enable the feature. ## Data privacy -Suggested Reviewers operates completely within the GitLab.com infrastructure providing the same level of [privacy](https://about.gitlab.com/privacy/) and [security](https://about.gitlab.com/security/) of any other feature of GitLab.com. +Suggested Reviewers operates completely within the GitLab.com infrastructure providing the same level of [privacy](https://about.gitlab.com/privacy/) and [security](https://about.gitlab.com/security/) of any other feature of GitLab.com. -No new additional data is collected to enable this feature, simply GitLab is inferencing your merge request against a trained machine learning model. The content of your source code is not used as training data. Your data also never leaves GitLab.com, all training and inference is done within GitLab.com infrastructure. +No new additional data is collected to enable this feature. GitLab is inferencing your merge request against a trained machine learning model. The content of your source code is not used as training data. Your data also never leaves GitLab.com, all training and inference is done within GitLab.com infrastructure. [Read more about the security of GitLab.com](https://about.gitlab.com/security/faq/) diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 227f38ad472..ce1fc94395c 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -25,21 +25,21 @@ review merge requests in Visual Studio Code. > [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4. -GitLab can recommend reviewers with Suggested Reviewers. Using the changes in a merge request and a project's contribution graph, machine learning powered suggestions appear in the reviewer section of the right merge request sidebar. +GitLab can recommend reviewers with Suggested Reviewers. Using the changes in a merge request and a project's contribution graph, machine learning powered suggestions appear in the reviewer section of the right merge request sidebar.  This feature is currently in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta) behind a [feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/368356). -Learn more about [how suggested reviewers works and data privacy](data_usage.md). +Learn more about [how suggested reviewers works and data privacy](data_usage.md). ### Enable suggested reviewers -Project Maintainers or Owners can enable suggested reviewers by visiting the [project settings](../../settings/index.md). +Project Maintainers or Owners can enable suggested reviewers by visiting the [project settings](../../settings/index.md). Enabling suggested reviewers will trigger GitLab to create an ML model for your project that will be used to generate reviewers. The larger your project, the longer this can take, but usually, the model will be ready to generate suggestions within a few hours. -No action is required once the feature is enabled. Once the model is ready, recommendations will populate the Reviewer dropdown in the right-hand sidebar of a merge request with new commits. +No action is required once the feature is enabled. Once the model is ready, recommendations will populate the Reviewer dropdown in the right-hand sidebar of a merge request with new commits. ## Review a merge request @@ -238,7 +238,7 @@ This can occur if Sidekiq doesn't pick up the changes fast enough. #### Sidekiq -Sidekiq didn't process the CI state change fast enough. Please wait a few +Sidekiq didn't process the CI state change fast enough. Wait a few seconds and the status should update automatically. #### Bug @@ -266,7 +266,7 @@ The merge request sidebar contains the branch reference for the source branch used to contribute changes for this merge request. To copy the branch reference into your clipboard, select the **Copy branch name** button -(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally +(**{copy-to-clipboard}**) in the right sidebar. Use it to check out the branch locally from the command line by running `git checkout <branch-name>`. ### Checkout merge requests locally through the `head` ref diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 2ff65571c8b..2d3682c62d4 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 066149afbb5..e83e17072d6 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Squash and merge **(FREE)** diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index da705a53153..d330ccdefb6 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html' --- @@ -29,6 +29,18 @@ You can configure merge request status checks for each individual project. These To learn more about use cases, feature discovery, and development timelines, see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). +## Block merges of merge requests unless all status checks have passed + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. 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, ask an administrator to +[enable the feature flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. On GitLab.com, this feature is not available. + +By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail, enable this feature +using the [project API](../../../api/projects.md#edit-project). You must also [enable the feature flag](../../../administration/feature_flags.md) named +`only_allow_merge_if_all_status_checks_passed`. + ## Lifecycle External status checks have an **asynchronous** workflow. Merge requests emit a merge request webhook payload to an external service whenever: @@ -188,7 +200,7 @@ Unable to fetch branches list, please close the form and try again An unexpected response was received from the branches retrieval API. As suggested, you should close the form and reopen again or refresh the page. This error should be temporary, although -if it persists please check the [GitLab status page](https://status.gitlab.com/) to see if there is a wider outage. +if it persists, check the [GitLab status page](https://status.gitlab.com/) to see if there is a wider outage. ### Failed to load status checks diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md deleted file mode 100644 index 53d45e6940d..00000000000 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../ci/testing/test_coverage_visualization.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](../../../ci/testing/test_coverage_visualization.md). - -<!-- This redirect file can be deleted after <2022-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 --> diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md deleted file mode 100644 index 6c0086bc429..00000000000 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../ci/testing/index.md' -remove_date: '2022-08-31' ---- - -This document was moved to [another location](../../../ci/testing/index.md). - -<!-- This redirect file can be deleted after <2022-08-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 (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/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 236ec64a4dc..6f29272f003 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Merge requests versions **(FREE)** diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index 0e179415192..a7aa86a16d4 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- @@ -54,7 +54,7 @@ Set a merge request that looks ready to merge to If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, you can preview the changes submitted to a feature branch through a merge request -on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +on a per-branch basis. You don't need to check out the branch, install, and preview locally. All your changes are available to preview by anyone with the Review Apps link. With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 0f36747a547..01eeee9d3b9 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Burndown and burnup charts **(PREMIUM)** diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 723ca17ee56..76c5e32eb2b 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Milestones **(FREE)** @@ -180,8 +180,9 @@ Prerequisites: To promote a project milestone: 1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > Milestones**. 1. Either: - - Select **Promote to Group Milestone** (**{level-up}**). + - Select **Promote to Group Milestone** (**{level-up}**) next to the milestone you want to promote. - Select the milestone title, and then select **Promote**. 1. Select **Promote Milestone**. 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 c4c30dbdab4..1d32091b294 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 @@ -2,7 +2,7 @@ type: concepts stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # DNS records overview **(FREE)** @@ -44,7 +44,7 @@ for the most popular hosting services: - [Hostgator](https://www.hostgator.com/help/article/changing-dns-records) - [Inmotion hosting](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) - [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) -- [Microsoft](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-2000-server/bb727018(v=technet.10)) +- [Microsoft](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-2000-server/bb727018(v=technet.10)) - [Namecheap](https://www.namecheap.com/support/knowledgebase/subcategory/2237/host-records-setup/) <!-- vale gitlab.Spelling = YES --> 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 03f8ecac77f..5ee1fa103a4 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 @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Custom domains and SSL/TLS certificates **(FREE)** @@ -96,7 +96,7 @@ Root domains (`example.com`) require: | `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | For projects on GitLab.com, this IP is `35.185.44.232`. -For projects living in other GitLab instances (CE or EE), please contact +For projects living in other GitLab instances (CE or EE), contact your sysadmin asking for this information (which IP address is Pages server running on your instance). 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 b5487f7a465..e9e6e5a9a3c 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 @@ -3,7 +3,7 @@ type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages integration with Let's Encrypt **(FREE)** 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 b080bee85aa..b9d2f8cb9a6 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 @@ -2,7 +2,7 @@ type: concepts stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # SSL/TLS certificates **(FREE)** @@ -39,7 +39,7 @@ Now we have a different picture. [According to Josh Aas](https://letsencrypt.org <!-- vale gitlab.rulename = YES --> -> _We've since come to realize that HTTPS is important for almost all websites. It's important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn't want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We've also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ +> _We've since come to realize that HTTPS is important for almost all websites. It's important for any website that allows people to sign in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn't want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We've also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ Therefore, the reason why certificates are so important is that they encrypt the connection between the **client** (you, your visitors) 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 58e15104815..01583dbe45d 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 @@ -2,7 +2,7 @@ type: reference, howto stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a Pages website by using a CI/CD template **(FREE)** 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 71ed3134c1e..33cf677e1be 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 @@ -2,7 +2,7 @@ type: reference, howto stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a Pages website from a forked sample **(FREE)** 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 1c3d5d722cb..e34544c96f8 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: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Create a GitLab Pages website from scratch **(FREE)** 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 92baba6b9c6..d7e304dc6f8 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: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create a Pages website from a template **(FREE)** diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 7e618fbaec8..064255c094f 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: Create group: Incubation -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tutorial: Use the GitLab UI to deploy your static site **(FREE)** diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 29712a82be1..588d94729e2 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: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages domain names, URLs, and base URLs **(FREE)** diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 1f3628b74ec..47c0885c26b 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: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages **(FREE)** diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index da024881ed6..ed154c0dfca 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Exploring GitLab Pages **(FREE)** @@ -82,7 +82,7 @@ When using Pages under the top-level domain of a GitLab instance (`*.example.io` of subdomains. If your namespace or group name contains a dot (for example, `foo.bar`) the domain `https://foo.bar.example.io` does _not_ work. -This limitation is because of the [HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages +This limitation is because of the [HTTP Over TLS protocol](https://www.rfc-editor.org/rfc/rfc2818#section-3.1). HTTP pages work as long as you don't redirect HTTP to HTTPS. ## GitLab Pages and subgroups @@ -108,7 +108,7 @@ Supposed your repository contained the following files: └── main.js ``` -Then the `.gitlab-ci.yml` example below simply moves all files from the root +Then the `.gitlab-ci.yml` example below moves all files from the root directory of the project to the `public/` directory. The `.public` workaround is so `cp` doesn't also copy `public/` to itself in an infinite loop: @@ -299,8 +299,7 @@ To fix this, verify that the user is a member of the project. ### Cannot play media content on Safari -Safari requires the web server to support the [Range request header](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/CreatingVideoforSafarioniPhone/CreatingVideoforSafarioniPhone.html#//apple_ref/doc/uid/TP40006514-SW6) -in order to play your media content. For GitLab Pages to serve +Safari requires the web server to support the [Range request header](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/CreatingVideoforSafarioniPhone/CreatingVideoforSafarioniPhone.html#//apple_ref/doc/uid/TP40006514-SW6) to play your media content. For GitLab Pages to serve HTTP Range requests, you should use the following two variables in your `.gitlab-ci.yml` file: ```yaml diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index e6446c34bf0..be1ea236c87 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Pages access control **(FREE)** diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index f9c80875cc9..b5d498402d5 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: Create group: Incubation -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the public files folder **(FREE)** @@ -51,16 +51,18 @@ rename that folder to a collision-free alternative first: ```javascript // astro.config.mjs - export default { + import { defineConfig } from 'astro/config'; + + export default defineConfig({ // GitLab Pages requires exposed files to be located in a folder called "public". // So we're instructing Astro to put the static build output in a folder of that name. - dist: 'public', + outDir: 'public', // The folder name Astro uses for static files (`public`) is already reserved // for the build output. So in deviation from the defaults we're using a folder // called `static` instead. - public: 'static', - }; + publicDir: 'static', + }); ``` ### SvelteKit diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 5d03db4bf00..96de457c7f7 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Create redirects for GitLab Pages **(FREE)** diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 9b685592c9d..f9dcf838c33 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected branches **(FREE)** diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 9b1e862af58..22ce81409a3 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Protected tags **(FREE)** diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 3eb333f5785..b31ef858d59 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Push Options **(FREE)** @@ -67,8 +67,8 @@ time as pushing changes: | `merge_request.milestone="<milestone>"` | Set the milestone of the merge request. Ex: `git push -o merge_request.milestone="3.0"`. | [14.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63960) | | `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | -| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. Accepts username or user ID.For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | +| `merge_request.assign="<user>"` | Assign users to the merge request. Accepts username or user ID. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904), support for usernames added in [15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276) | +| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. Accepts username or user ID.For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904), support for usernames added in [15.5](https://gitlab.com/gitlab-org/gitlab/-/issues/344276) | If you use a push option that requires text with spaces in it, you need to enclose it in quotes (`"`). You can omit the quotes if there are no spaces. Some examples: @@ -115,13 +115,3 @@ pipeline succeeds: ```shell git mwps origin <local-branch-name> ``` - -## Troubleshooting - -## Push options for merge request assignment ignored - -When you push a branch to GitLab, you can use push options to assign to (`merge_request.assign="<USERNAME>"`) -or unassign from (`merge_request.unassign="<USERNAME>"`) a user. If GitLab creates -the merge request successfully, but fails to assign or unassign the merge request -correctly, you can use the user ID instead. For more information, read the issue -[Push option `merge_request.(un)assign` seems to be ignored](https://gitlab.com/gitlab-org/gitlab/-/issues/325169). diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 8b8eba62cce..3471123f8b5 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab quick actions **(FREE)** @@ -20,6 +20,9 @@ by selecting buttons or dropdowns in the GitLab user interface. You can enter these commands in the descriptions or comments of issues, epics, merge requests, and commits. +Many quick actions are context-aware, requiring certain conditions be met. For example, to remove +an issue due date with `/remove_due_date`, the issue must have a due date set. + Be sure to enter each quick action on a separate line to allow GitLab to properly detect and execute the commands. @@ -77,6 +80,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | | `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | | `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | +| `/link` | **{check-circle}** Yes | ****{dotted-circle}** No | **{dotted-circle}** No | Add a link and description to [linked resources](../../operations/incident_management/linked_resources.md) in an incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/374964) in GitLab 15.5). | | `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | | `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | | `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | @@ -102,7 +106,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | | `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue. | | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | -| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | +| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | | `/spend <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). | | `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8041) in GitLab 12.7). | @@ -115,7 +119,8 @@ threads. Some quick actions might not be available to all subscription tiers. | `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3 | | `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | | `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | -| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. +| `/unassign_reviewer me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove yourself as a reviewer. | | `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | | `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 87ea95524fe..fd01dd451c2 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Releases **(FREE)** @@ -61,7 +61,6 @@ You can create a release: - [Using a job in your CI/CD pipeline](#creating-a-release-by-using-a-cicd-job). - [In the Releases page](#create-a-release-in-the-releases-page). -- [In the Tags page](#create-a-release-in-the-tags-page). - Using the [Releases API](../../../api/releases/index.md#create-a-release). We recommend creating a release as one of the last steps in your CI/CD pipeline. @@ -77,12 +76,14 @@ To create a release in the Releases page: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases** and select **New release**. -1. From the [**Tag name**](release_fields.md#tag-name) dropdown, either: +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. - Enter a new Git tag name. - 1. From the **Create from** dropdown, select a branch or commit SHA to use when creating the - new tag. + 1. From the **Create from** dropdown list, select a branch or commit SHA to use when + creating the new tag. + 1. Optional. In the **Set tag message** text box, enter a message to create an + [annotated tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags). 1. Optional. Enter additional information about the release, including: - [Title](release_fields.md#title). - [Milestones](#associate-milestones-with-a-release). @@ -91,29 +92,6 @@ To create a release in the Releases page: - [Asset links](release_fields.md#links). 1. Select **Create release**. -### Create a release in the Tags page - -To create a release in the Tags page, add release notes to either an existing or a new Git tag. - -To add release notes to a new Git tag: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Tags**. -1. Select **New tag**. -1. Optional. Enter a tag message in the **Message** text box. -1. In the **Release notes** text box, enter the release's description. - You can use Markdown and drag and drop files to this text box. -1. Select **Create tag**. - -To edit release notes of an existing Git tag: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Repository > Tags**. -1. Select **Edit release notes** (**{pencil}**). -1. In the **Release notes** text box, enter the release's description. - You can use Markdown and drag and drop files to this text box. -1. Select **Save changes**. - ### Creating a release by using a CI/CD job You can create a release directly as part of the GitLab CI/CD pipeline by using the @@ -133,7 +111,7 @@ Methods for creating a release using a CI/CD job include: You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when the `release-cli` creates a release through the API using HTTPS with custom certificates. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the -[text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1) +[text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1) or the `path/to/file` containing the certificate authority. For example, to configure this value in the `.gitlab-ci.yml` file, use the following: diff --git a/doc/user/project/releases/release_cicd_examples.md b/doc/user/project/releases/release_cicd_examples.md index bfd83a20caf..1ec82d6702e 100644 --- a/doc/user/project/releases/release_cicd_examples.md +++ b/doc/user/project/releases/release_cicd_examples.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 90363fca8b0..5af19c7cced 100644 --- a/doc/user/project/releases/release_cli.md +++ b/doc/user/project/releases/release_cli.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index 647cac9c38e..5ae1c69847d 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -1,7 +1,7 @@ --- stage: Release group: Release -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Release fields diff --git a/doc/user/project/remote_development/index.md b/doc/user/project/remote_development/index.md new file mode 100644 index 00000000000..879978f550a --- /dev/null +++ b/doc/user/project/remote_development/index.md @@ -0,0 +1,139 @@ +--- +stage: Create +group: Editor +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Remote Development **(FREE)** + +DISCLAIMER: +This page contains information related to upcoming products, features, and functionality. +It is important to note that the information presented is for informational purposes only. +Please do not rely on this information for purchasing or planning purposes. +As with all projects, the items mentioned on this page are subject to change or delay. +The development, release, and timing of any products, features, or functionality remain at the +sole discretion of GitLab Inc. + +You can use the [Web IDE](../web_ide/index.md) to commit changes to a project directly from your web browser without installing any dependencies or cloning any repositories. The Web IDE, however, lacks a native runtime environment on which you would compile code, run tests, or generate real-time feedback in the IDE. For a more complete IDE experience, you can pair the Web IDE with a Remote Development environment that has been properly configured to run as a host. + +## Connect a remote machine to the Web IDE + +Prerequisites: + +- A remote virtual machine with root access +- A domain address resolving to that machine +- Docker installation + +To connect a remote machine to the Web IDE, you must: + +1. [Generate Let's Encrypt certificates](#generate-lets-encrypt-certificates). +1. [Connect a development environment to the Web IDE](#connect-a-development-environment-to-the-web-ide). + +### Generate Let's Encrypt certificates + +To generate Let's Encrypt certificates: + +1. [Point a domain to your remote machine](#point-a-domain-to-your-remote-machine). +1. [Install Certbot](#install-certbot). +1. [Generate the certificates](#generate-the-certificates). + +#### Point a domain to your remote machine + +To point a domain to your remote machine, create an `A` record from `example.remote.gitlab.dev` to `1.2.3.4`. + +#### Install Certbot + +[Certbot](https://certbot.eff.org/) is a free and open-source software tool that automatically uses Let's Encrypt certificates on manually administrated websites to enable HTTPS. + +To install Certbot, run the following command: + +```shell +sudo apt-get update +sudo apt-get install certbot +``` + +#### Generate the certificates + +```shell +export EMAIL="YOUR_EMAIL@example.com" +export DOMAIN="example.remote.gitlab.dev" + +certbot -d "${DOMAIN}" \ + -m "${EMAIL}" \ + --config-dir ~/.certbot/config \ + --logs-dir ~/.certbot/logs \ + --work-dir ~/.certbot/work \ + --manual \ + --preferred-challenges dns certonly +``` + +### Connect a development environment to the Web IDE + +To connect a development environment to the Web IDE: + +1. [Create a development environment](#manage-a-development-environment). +1. [Fetch a token](#fetch-a-token). +1. [Connect to the Web IDE](#connect-to-the-web-ide). + +#### Manage a development environment + +**Create a development environment** + +```shell +export CERTS_DIR="/home/ubuntu/.certbot/config/live/${DOMAIN}" +export PROJECTS_DIR="/home/ubuntu" + +docker run -d \ + --name my-environment \ + -p 3443:3443 \ + -v "${CERTS_DIR}/fullchain.pem:/gitlab-rd-web-ide/certs/fullchain.pem" \ + -v "${CERTS_DIR}/privkey.pem:/gitlab-rd-web-ide/certs/privkey.pem" \ + -v "${PROJECTS_DIR}:/projects" \ + registry.gitlab.com/gitlab-com/create-stage/editor-poc/remote-development/gitlab-rd-web-ide-docker:0.1 \ + --log-level warn --domain "${DOMAIN}" --ignore-version-mismatch +``` + +The new development environment starts automatically. + +**Stop a development environment** + +```shell +docker container stop my-environment +``` + +**Start a development environment** + +```shell +docker container start my-environment +``` + +The token changes every time you restart the development environment. + +**Remove a development environment** + +To remove a development environment: + +1. Stop the development environment. +1. Run the following command: + + ```shell + docker container rm my-environment + ``` + +#### Fetch a token + +```shell +docker exec my-environment cat TOKEN +``` + +#### Connect to the Web IDE + +To connect to the Web IDE: + +1. Run the following command: + + ```shell + echo "https://gitlab-org.gitlab.io/gitlab-web-ide?remoteHost=${DOMAIN}:3443&hostPath=/projects" + ``` + +1. Go to that URL and enter the [token you fetched](#fetch-a-token). diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index d31c64f4640..6801899160d 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 5e5a42a061b..9755b5cb944 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/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Branches **(FREE)** @@ -13,9 +13,10 @@ other. After pushing your changes to a new branch, you can: -- Create a [merge request](../../merge_requests/index.md) -- Perform inline code review -- [Discuss](../../../discussions/index.md) your implementation with your team +- Create a [merge request](../../merge_requests/index.md). You can streamline this process + by following [branch naming patterns](#naming). +- Perform inline code review. +- [Discuss](../../../discussions/index.md) your implementation with your team. - Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). You can also request [approval](../../merge_requests/approvals/index.md) @@ -42,6 +43,18 @@ See also: - [GitLab Flow](../../../../topics/gitlab_flow.md) documentation. - [Getting started with Git](../../../../topics/git/index.md) and GitLab. +## Naming + +Prefix a branch name with an issue number to streamline merge request creation. +When you create a merge request for a branch with a name beginning with an issue +number, GitLab: + +- Marks the issue as related. If your project is configured with a + [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), + merging this merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) + the related issue. +- Copies label and milestone metadata from the issue. + ## Compare To compare branches in a repository: @@ -99,7 +112,7 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi  -The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is clicked, the selected revisions for Source and Target is swapped. +The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is selected, the selected revisions for Source and Target is swapped.  diff --git a/doc/user/project/repository/csv.md b/doc/user/project/repository/csv.md index 27424268d2b..101878ee4b4 100644 --- a/doc/user/project/repository/csv.md +++ b/doc/user/project/repository/csv.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/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 42b82f2c360..f9a5d4e3aa7 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index df75f19ea6c..fae6e210a6c 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 0026834ae83..78fcdec2a0b 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.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/engineering/ux/technical-writing/#assignments +info: To determine 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 description: "Documentation on Git file blame." --- diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 356f02a4902..08fe767f9c9 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.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/engineering/ux/technical-writing/#assignments +info: To determine 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 description: "Documentation on Git file history." --- diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index d307a6a8580..910b09449d8 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Signing commits with GPG **(FREE)** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 4926cf3812e..bcdb626d0f2 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Repository **(FREE)** @@ -306,3 +306,33 @@ The same approach should also allow misidentified file types to be fixed. ``` `*.txt` files have an entry in the heuristics file. This example prevents parsing of these files. + +### Search sequence of pushes to a repository + +If it seems that a commit has gone "missing", search the sequence of pushes to a repository. +[This StackOverflow article](https://stackoverflow.com/questions/13468027/the-mystery-of-the-missing-commit-across-merges) +describes how you can end up in this state without a force push. Another cause can be a misconfigured [server hook](../../../administration/server_hooks.md) that changes a HEAD ref in a `git reset` operation. + +If you look at the output from the sample code below for the target branch, you +see a discontinuity in the from/to commits as you step through the output. +The `commit_from` of each new push should equal the `commit_to` of the previous push. +A break in that sequence indicates one or more commits have been "lost" from the repository history. + +Using the [rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session), the following example checks the last 100 pushes and prints the `commit_from` and `commit_to` entries: + +```ruby +p = Project.find_by_full_path('project/path') +p.events.pushed_action.last(100).each do |e| + puts "%-20.20s %8s...%8s (%s)", e.push_event_payload[:ref], e.push_event_payload[:commit_from], e.push_event_payload[:commit_to], e.author.try(:username) +end ; nil +``` + +Example output showing break in sequence at line 4: + +```plaintext +master f21b07713251e04575908149bdc8ac1f105aabc3...6bc56c1f46244792222f6c85b11606933af171de root +master 6bc56c1f46244792222f6c85b11606933af171de...132da6064f5d3453d445fd7cb452b148705bdc1b root +master 132da6064f5d3453d445fd7cb452b148705bdc1b...a62e1e693150a2e46ace0ce696cd4a52856dfa65 root +master 58b07b719a4b0039fec810efa52f479ba1b84756...f05321a5b5728bd8a89b7bf530aa44043c951dce root +master f05321a5b5728bd8a89b7bf530aa44043c951dce...7d02e575fd790e76a3284ee435368279a5eb3773 root +``` diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 1ed6dbd3348..4f6cff576ea 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- # Jupyter Notebook files **(FREE)** diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md index d2ca49c118c..e5c1e4a6614 100644 --- a/doc/user/project/repository/managing_large_repositories.md +++ b/doc/user/project/repository/managing_large_repositories.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/engineering/ux/technical-writing/#assignments +info: To 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: "Documentation on large repositories." --- @@ -14,11 +14,11 @@ In the following sections, we detail several best practices for improving perfor ## Large File System (LFS) -It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, or graphics) are stored as Large File Storage (LFS) objects. In such setup, the Objects are stored elsewhere, such as in Object Storage, and this can reduce the repository size significantly, thus improving performance. +It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, or graphics) are stored as Large File Storage (LFS) objects. With LFS, the objects are stored externally, such as in Object Storage, which reduces the number and size of objects in the repository. Storing objects in external Object Storage can improve performance. -To analyze if the repository has these sorts of objects, it's recommended to run a tool like [`git-sizer`](https://github.com/github/git-sizer) to get a detailed analysis. These tools can show in detail what makes up the repository as well as highlights any areas of concern. If any large objects are found, it's then recommended removing them with tools such as [`git filter-repo`](reducing_the_repo_size_using_git.md). +To analyze if a repository has large objects, you can use a tool like [`git-sizer`](https://github.com/github/git-sizer) for detailed analysis. This tool shows details about what makes up the repository, and highlights any areas of concern. If any large objects are found, you can then remove them with a tool such as [`git filter-repo`](reducing_the_repo_size_using_git.md). -Refer to the [Git LFS documentation for more information](../../../topics/git/lfs/index.md). +For more information, refer to the [Git LFS documentation](../../../topics/git/lfs/index.md). ## Gitaly Pack Objects Cache diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 793ca2a5f1f..9942469dd5c 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 176461aeba7..fa6d8d82559 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- @@ -316,3 +316,38 @@ Mirroring does not support the short version of SSH clone URLs (`git@gitlab.com: and requires the full version including the protocol (`ssh://git@gitlab.com/gitlab-org/gitlab.git`). Make sure that host and project path are separated using `/` instead of `:`. + +### Transfer mirror users and tokens to a single service account in Rails console + +This requires access to the [GitLab Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +Use case: If you have multiple users using their own GitHub credentials to set up +repository mirroring, mirroring breaks when people leave the company. Use this +script to migrate disparate mirroring users and tokens into a single service account: + +```ruby +svc_user = User.find_by(username: 'ourServiceUser') +token = 'githubAccessToken' + +Project.where(mirror: true).each do |project| + import_url = project.import_url + + # The url we want is https://token@project/path.git + repo_url = if import_url.include?('@') + # Case 1: The url is something like https://23423432@project/path.git + import_url.split('@').last + elsif import_url.include?('//') + # Case 2: The url is something like https://project/path.git + import_url.split('//').last + end + + next unless repo_url + + final_url = "https://#{token}@#{repo_url}" + + project.mirror_user = svc_user + project.import_url = final_url + project.username_only_import_url = final_url + project.save +end +``` diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 159580dcfa5..1923d8e2ae7 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 10bdc54ecee..11d53b0c1d1 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 90d2fdb89d0..917fca03967 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/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Push rules **(PREMIUM)** @@ -78,6 +78,15 @@ Use these rules for your commit messages. the expression. To allow any commit message, leave empty. Uses multiline mode, which can be disabled by using `(?-m)`. +## Reject commits that aren't DCO certified + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98810) in GitLab 15.5. + +Commits signed with the [Developer Certificate of Origin](https://developercertificate.org/) (DCO) +certify the contributor wrote, or has the right to submit, the code contributed in that commit. +You can require all commits to your project to comply with the DCO. This push rule requires a +`Signed-off-by:` trailer in every commit message, and rejects any commits that lack it. + ## Validate branch names To validate your branch names, enter a regular expression for **Branch name**. @@ -284,3 +293,28 @@ enabled, unsigned commits may still appear in the commit history if a commit was created in GitLab itself. As expected, commits created outside GitLab and pushed to the repository are rejected. For more information about this issue, read [issue #19185](https://gitlab.com/gitlab-org/gitlab/-/issues/19185). + +### Bulk update push rules for _all_ projects + +To update the push rules to be the same for all projects, +you need to use [the rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session), +or write a script to update each project using the [Push Rules API endpoint](../../../api/projects.md#push-rules). + +For example, to enable **Check whether the commit author is a GitLab user** and **Do not allow users to remove Git tags with `git push`** checkboxes, +and create a filter for allowing commits from a specific email domain only through rails console: + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +``` ruby +Project.find_each do |p| + pr = p.push_rule || PushRule.new(project: p) + # Check whether the commit author is a GitLab user + pr.member_check = true + # Do not allow users to remove Git tags with `git push` + pr.deny_delete_tag = true + # Commit author's email + pr.author_email_regex = '@domain\.com$' + pr.save! +end +``` 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 f209c7ef137..c85dd4555ca 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: Systems group: Gitaly -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reduce repository size **(FREE)** @@ -257,4 +257,28 @@ increased, your only option is to: ### Incorrect repository statistics shown in the GUI If the displayed size or commit number is different from the exported `.tar.gz` or local repository, -you can ask a GitLab administrator to [force an update](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#incorrect-repository-statistics-shown-in-the-gui). +you can ask a GitLab administrator to force an update. + +Using [the rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +p = Project.find_by_full_path('<namespace>/<project>') +pp p.statistics +p.statistics.refresh! +pp p.statistics +# compare with earlier values + +# An alternate method to clear project statistics +p.repository.expire_all_method_caches +UpdateProjectStatisticsWorker.perform_async(p.id, ["commit_count","repository_size","storage_size","lfs_objects_size"]) + +# check the total artifact storage space separately +builds_with_artifacts = p.builds.with_downloadable_artifacts.all + +artifact_storage = 0 +builds_with_artifacts.find_each do |build| + artifact_storage += build.artifacts_size +end + +puts "#{artifact_storage} bytes" +``` diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index bbf14a71653..4afdb3be0bd 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Workflow extension for VS Code **(FREE)** diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 4ca341f0535..e1f05cd5501 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # GitLab Web Editor **(FREE)** @@ -40,7 +40,7 @@ might need. GitLab displays a message to help you:  -When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown displays +When selecting either `LICENSE` or `.gitignore` and so on, a dropdown displays to provide you a template that may be suitable for your project:  @@ -115,6 +115,9 @@ the target branch. Select **Create directory** to finish. There are multiple ways to create a branch from the GitLab web interface. +NOTE: +Use [branch naming patterns](branches/index.md#naming) to streamline merge request creation. + ### Create a new branch 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. @@ -122,7 +125,7 @@ There are multiple ways to create a branch from the GitLab web interface. 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. -Once merged, the merge request closes the 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 below the issue description. NOTE: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 0259ff6ce30..4a17b2ab84c 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Sign commits and tags with X.509 certificates **(FREE)** @@ -48,7 +48,7 @@ GitLab checks certificate revocation lists on a daily basis with a background wo - Self-signed certificates without `authorityKeyIdentifier`, `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We recommend using certificates from a PKI that are in line with - [RFC 5280](https://tools.ietf.org/html/rfc5280). + [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280). - If you have more than one email in the Subject Alternative Name list in your signing certificate, [only the first one is used to verify commits](https://gitlab.com/gitlab-org/gitlab/-/issues/336677). diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 8b80c494e2f..3b1af1f688c 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Plan group: Certify -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Requirements Management **(ULTIMATE)** diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index bafa2005fdf..199f25f1122 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,7 +1,7 @@ --- stage: Plan group: Certify -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Service Desk **(FREE)** @@ -264,7 +264,7 @@ Graph API instead of IMAP. Follow the [documentation in the incoming email secti } ``` -For Microsoft Cloud for US Government or [other Azure deployments](https://docs.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. +For Microsoft Cloud for US Government or [other Azure deployments](https://learn.microsoft.com/en-us/graph/deployments), configure the `azure_ad_endpoint` and `graph_endpoint` settings. - Example for Microsoft Cloud for US Government: diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 375e4a62b86..a47873f5179 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 -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" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Migrating projects using file exports **(FREE)** @@ -58,7 +58,7 @@ moved to your configured `uploads_directory`. Every 24 hours, a worker deletes t ### Items that are exported The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) -file lists the items exported and imported when migrating projects using file exports. View this file in the branch +file for projects lists many of the items exported and imported when migrating projects using file exports. View this file in the branch for your version of GitLab to see the list of items relevant to you. For example, [`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml). @@ -72,8 +72,10 @@ Items that are exported include: - Project configuration, excluding integrations - Issues - Issue comments + - Issue iteration ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96184) in 15.4) - Issue resource state events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Issue resource milestone events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) + - Issue resource iteration events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4) - Merge requests - Merge request diffs - Merge request comments @@ -135,16 +137,15 @@ To import a project: To get the status of an import, you can query it through the [Project import/export API](../../../api/project_import_export.md#import-status). As described in the API documentation, the query may return an import error or exceptions. -### Items that are imported +### Changes to imported items -The following items are imported but changed slightly: +Exported items are imported with the following changes: -- Project members with the Owner role are imported as Maintainers. -- If an imported project contains merge requests originating from forks, then new branches - associated with such merge requests are created in a project during the import/export. Thus, the - number of branches in the exported project might be bigger than in the original project. -- If use of the `Internal` visibility level - [is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), +- Project members with the Owner role are imported with the Maintainer role. +- If an imported project contains merge requests originating from forks, new branches associated with these merge + requests are created in the project. Therefore, the number of branches in the new project can be more than in the + source project. +- If the `Internal` visibility level [is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), all imported projects are given `Private` visibility. Deploy keys aren't imported. To use deploy keys, you must enable them in your imported project and update protected branches. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 5c2118e02cf..4407986f354 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -40,187 +40,24 @@ To assign topics to a project: 1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. -## Compliance frameworks **(PREMIUM)** +If you're an instance administrator, you can administer all project topics from the +[Admin Area's Topics page](../../admin_area/index.md#administering-topics). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. +## Add a compliance framework to a project **(PREMIUM)** -You can create a compliance framework label to identify that your project has certain compliance -requirements or needs additional oversight. The label can optionally apply -[compliance pipeline configuration](#compliance-pipeline-configuration). +[Compliance frameworks](../../group/manage.md#compliance-frameworks) can be assigned to projects within group that has a +compliance framework using either: -Group owners can create, edit, and delete compliance frameworks: - -1. On the top bar, select **Main menu > Groups** and find your group. -1. On the left sidebar, select **Settings** > **General**. -1. Expand the **Compliance frameworks** section. - -Compliance frameworks created can then be assigned to projects within the group using: - -- The GitLab UI, using the project settings page. +- The GitLab UI: + 1. On the top bar, select **Main menu > Projects > View all projects** and find your project. + 1. On the left sidebar, select **Settings** > **General**. + 1. Expand the **Compliance frameworks** section. + 1. Select a compliance framework. + 1. Select **Save changes**. - In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/333249) and later, using the - [GraphQL API](../../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework). - -NOTE: -Creating compliance frameworks on subgroups with GraphQL causes the framework to be -created on the root ancestor if the user has the correct permissions. The GitLab UI presents a -read-only view to discourage this behavior. - -### Compliance pipeline configuration **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../../administration/feature_flags.md). -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. - -Compliance framework pipelines allow group owners to define -a compliance pipeline in a separate repository that gets -executed in place of the local project's `.gitlab-ci.yml` file. As part of this pipeline, an -`include` statement can reference the local project's `.gitlab-ci.yml` file. This way, the compliance -pipeline jobs can run alongside the project-specific jobs any time the pipeline runs. -Jobs and variables defined in the compliance -pipeline can't be changed by variables in the local project's `.gitlab-ci.yml` file. - -When you set up the compliance framework, use the **Compliance pipeline configuration** box to link -the compliance framework to specific CI/CD configuration. Use the -`path/file.y[a]ml@group-name/project-name` format. For example: - -- `.compliance-ci.yml@gitlab-org/gitlab`. -- `.compliance-ci.yaml@gitlab-org/gitlab`. - -This configuration is inherited by projects where the compliance framework label is applied. The -result forces projects with the label to run the compliance CI/CD configuration in addition to -the project's own CI/CD configuration. When a project with a compliance framework label executes a -pipeline, it evaluates configuration in the following order: - -1. Compliance pipeline configuration. -1. Project-specific pipeline configuration. - -The user running the pipeline in the project must at least have the Reporter role on the compliance -project. - -Example `.compliance-gitlab-ci.yml`: - -```yaml -# Allows compliance team to control the ordering and interweaving of stages/jobs. -# Stages without jobs defined will remain hidden. -stages: - - pre-compliance - - build - - test - - pre-deploy-compliance - - deploy - - post-compliance - -variables: # Can be overridden by setting a job-specific variable in project's local .gitlab-ci.yml - FOO: sast - -sast: # None of these attributes can be overridden by a project's local .gitlab-ci.yml - variables: - FOO: sast - image: ruby:2.6 - stage: pre-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -sanity check: - image: ruby:2.6 - stage: pre-deploy-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -audit trail: - image: ruby:2.6 - stage: post-compliance - rules: - - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push" - when: never - - when: always # or when: on_success - allow_failure: false - before_script: - - "# No before scripts." - script: - - echo "running $FOO" - after_script: - - "# No after scripts." - -include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) - project: '$CI_PROJECT_PATH' - file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch -``` - -When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/scan-execution-policies.md), -as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). -For details on the similarities and differences between these features, see -[Enforce scan execution](../../application_security/index.md#enforce-scan-execution). - -### Ensure compliance jobs are always run - -Compliance pipelines use GitLab CI/CD to give you an incredible amount of flexibility -for defining any sort of compliance jobs you like. Depending on your goals, these jobs -can be configured to be: - -- Modified by users. -- Non-modifiable. - -At a high-level, if a value in a compliance job: - -- Is set, it cannot be changed or overridden by project-level configurations. -- Is not set, a project-level configuration may set. - -Either might be wanted or not depending on your use case. - -There are a few best practices for ensuring that these jobs are always run exactly -as you define them and that downstream, project-level pipeline configurations -cannot change them: - -- Add a `rules:when:always` block to each of your compliance jobs. This ensures they are - non-modifiable and are always run. -- Explicitly set any variables the job references. This: - - Ensures that project-level pipeline configurations do not set them and alter their - behavior. - - Includes any jobs that drive the logic of your job. -- Explicitly set the container image file to run the job in. This ensures that your script - steps execute in the correct environment. -- Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/index.md#job-keywords). - This ensures that your job uses the settings you intend and that they are not overridden by - project-level pipelines. - -### Avoid parent and child pipelines in GitLab 14.7 and earlier - -NOTE: -This advice does not apply to GitLab 14.8 and later because [a fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78878) added -compatibility for combining compliance pipelines, and parent and child pipelines. - -Compliance pipelines start on the run of _every_ pipeline in a relevant project. This means that if a pipeline in the relevant project -triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. - -Therefore, in projects with compliance frameworks, we recommend replacing -[parent-child pipelines](../../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) with the following: - -- Direct [`include`](../../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. -- Child pipelines placed in another project that are run using the [trigger API](../../../ci/triggers/index.md) rather than the parent-child - pipeline feature. - -This alternative ensures the compliance pipeline does not re-start the parent pipeline. + [GraphQL API](../../../api/graphql/reference/index.md#mutationprojectsetcomplianceframework). If you create + compliance frameworks on subgroups with GraphQL, the framework is created on the root ancestor if the user has the + correct permissions. The GitLab UI presents a read-only view to discourage this behavior. ## Configure project visibility, features, and permissions @@ -255,7 +92,8 @@ Use the toggles to enable or disable features in the project. | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md). | | **Pages** | ✓ | Allows you to [publish static websites](../pages/index.md). | | **Operations** | ✓ | Control access to Operations-related features, including [Operations Dashboard](../../../operations/index.md), [Environments and Deployments](../../../ci/environments/index.md), [Feature Flags](../../../operations/feature_flags.md). | -| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | +| **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | +| **Releases** | ✓ | Control access to [Releases](../releases/index.md). | When you disable a feature, the following additional features are also disabled: @@ -372,7 +210,7 @@ where GitLab is installed. Prerequisites: -You must be a project maintainer or administrator to rename a repository. +You must be a project maintainer, owner, or administrator to rename a repository. 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 @@ -538,3 +376,33 @@ Configure Error Tracking to discover and view [Sentry errors within GitLab](../. [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). + +## Troubleshooting + +When working with project settings, you might encounter the following issues, or require alternate methods to complete specific tasks. + +### Remove a fork relationship through console + +If removing the fork through the UI or API is not working, you can attempt the fork relationship removal in a [Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + +```ruby +p = Project.find_by_full_path('<project_path>') +u = User.find_by_username('<username>') +Projects::UnlinkForkService.new(p, u).execute +``` + +### 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) +``` diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index c9c5efce9b1..f27672a1b07 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -48,6 +48,9 @@ You cannot use project access tokens to create other group, project, or personal Project access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. +NOTE: +Project access tokens are not FIPS compliant and creation and use are disabled when [FIPS mode](../../../development/fips_compliance.md) is enabled. + ## Create a project access token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens. @@ -82,10 +85,10 @@ The scope determines the actions you can perform when you authenticate with a pr |:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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` | Allows read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). | -| `read_repository` | Allows read access (pull) to the repository. | -| `write_repository` | Allows read and write access (pull and push) to the repository. | +| `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. | ## Enable or disable project access token creation diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md deleted file mode 100644 index 343482757f5..00000000000 --- a/doc/user/project/static_site_editor/index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -stage: Create -group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -remove_date: '2022-08-03' -redirect_to: '../web_ide/index.md' ---- - -# Static Site Editor (removed) **(FREE)** - -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77246) in GitLab 14.7 -and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/352505) in 15.0. -Use the [Web Editor](../repository/web_editor.md) or [Web IDE](../web_ide/index.md) instead. - -## Remove the Static Site Editor - -The Static Site Editor itself isn't part of your project. To remove the Static Site Editor -from an existing project, remove links that point back to the editor: - -1. Remove any links that use `edit_page_url` in your project. If you used the - **Middleman - Static Site Editor** project template, the only instance of this - helper is located in `/source/layouts/layout.erb`. Remove this line entirely: - - ```ruby - <%= link_to('Edit this page', edit_page_url(data.config.repository, current_page.file_descriptor.relative_path), id: 'edit-page-link') %> - ``` - -1. In `/data/config.yml`, delete the `repository` key / value pair: - - ```yaml - repository: https://gitlab.com/<username>/<myproject> - ``` - - - If `repository` is the only value stored in `/data/config.yml`, you can delete the entire file. -1. In `/helpers/custom_helpers.rb`, delete `edit_page_url()` and `endcode_path()`: - - ```ruby - def edit_page_url(base_url, relative_path) - "#{base_url}/-/sse/#{encode_path(relative_path)}/" - end - - def encode_path(relative_path) - ERB::Util.url_encode("master/source/#{relative_path}") - end - ``` - - - If `edit_page_url()` and `encode_path()` are the only helpers, you may delete - `/helpers/custom_helpers.rb` entirely. -1. Clean up any extraneous configuration files. -1. Commit and push your changes. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 522ec962e53..71b8c911839 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -3,7 +3,7 @@ type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Time tracking **(FREE)** diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 2a197c733cf..a0eac9376f2 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Web IDE **(FREE)** @@ -134,10 +134,10 @@ schemas: Each schema entry supports two properties: -- `uri`: please provide an absolute URL for the schema definition file here. +- `uri`: Provide an absolute URL for the schema definition file here. The schema from this URL is loaded when a matching file is open. -- `match`: a list of matching paths or glob expressions. If a schema matches a - particular path pattern, it is applied to that file. Please enclose the pattern +- `match`: A list of matching paths or glob expressions. If a schema matches a + particular path pattern, it is applied to that file. Enclose the pattern in quotes if it begins with an asterisk (`*`), it's be applied to that file. If a pattern begins with an asterisk (`*`), enclose it in quotation marks. Otherwise, the configuration file is not valid YAML. @@ -193,7 +193,7 @@ shows you a preview of the merge request diff if you commit your changes. You can use the Web IDE to quickly fix failing tests by opening the branch or merge request in the Web IDE and opening the logs of the failed job. You can access the status of all jobs for the most recent pipeline and job -traces for the current commit by clicking the **Pipelines** button in the top +traces for the current commit by selecting the **Pipelines** button in the top right. The pipeline status is also shown at all times in the status bar in the bottom @@ -375,7 +375,7 @@ may be disabled: - `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly. - No active private runners are available for the project. -If active, clicking the **Start Web Terminal** button loads the terminal view +If active, selecting the **Start Web Terminal** button loads the terminal view and start connecting to the runner's terminal. At any time, the **Terminal** tab can be closed and reopened and the state of the terminal is not affected. @@ -384,7 +384,7 @@ runner's shell prompt appears in the terminal. From here, you can enter commands executed in the runner's environment. This is similar to running commands in a local terminal or through SSH. -While the terminal is running, it can be stopped by clicking **Stop Terminal**. +While the terminal is running, it can be stopped by selecting **Stop Terminal**. This disconnects the terminal and stops the runner's terminal job. From here, select **Restart Terminal** to start a new terminal session. @@ -454,8 +454,8 @@ The Web IDE has a few limitations: ### Troubleshooting - If the terminal's text is gray and unresponsive, then the terminal has stopped - and it can no longer be used. A stopped terminal can be restarted by clicking + and it can no longer be used. A stopped terminal can be restarted by selecting **Restart Terminal**. - If the terminal displays **Connection Failure**, then the terminal could not - connect to the runner. Please try to stop and restart the terminal. If the + connect to the runner. Try to stop and restart the terminal. If the problem persists, double check your runner configuration. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 03838a62d59..0e9b76e943d 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Group wikis **(PREMIUM)** diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index b8924c33b13..eedc44be3f9 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Wiki **(FREE)** @@ -152,6 +152,8 @@ You need at least the Developer role to edit a wiki page: 1. Edit the content. 1. Select **Save changes**. +Unsaved changes to a wiki page are preserved in local browser storage to prevent accidental data loss. + ### Create a table of contents To generate a table of contents from a wiki page's subheadings, use the `[[_TOC_]]` tag. @@ -388,6 +390,11 @@ line of your Apache configuration to ensure your page slugs render correctly. WARNING: This operation deletes all data in the wiki. +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the +right conditions. We highly recommend running them in a test environment with a backup of the +instance ready to be restored, just in case. + To clear all data from a project wiki and recreate it in a blank state: 1. [Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index e58bf5aa557..705e49df039 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" --- # Manage projects **(FREE)** @@ -13,6 +13,11 @@ code are saved in projects, and most features are in the scope of projects. To view projects, on the top bar, select **Main menu > Projects > View all projects**. +NOTE: +The **Explore projects** tab is visible to unauthenticated users unless the +[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) +is restricted. Then the tab is visible only to signed-in users. + ### Who can view the Projects page When you select a project, the project landing page shows the project contents. @@ -46,11 +51,6 @@ To explore project topics: The **Explore topics** tab shows a list of topics sorted by the number of associated projects. -NOTE: -The **Explore projects** tab is visible to unauthenticated users unless the -[**Public** visibility level](../admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted. Then the tab is visible only to signed-in users. - You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). If you're an instance administrator, you can administer all project topics from the @@ -90,8 +90,7 @@ To create a blank project: - 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 target (optional)** field, select your project's deployment target. + - In the **Project deployment target (optional)** field, select your project's deployment target. This information helps GitLab better understand its users and their deployment requirements. - To modify the project's [viewing and access rights](../public_access.md) for users, change the **Visibility Level**. @@ -496,3 +495,97 @@ download starts, the `insteadOf` configuration sends the traffic to the secondar - [Fork a project](repository/forking_workflow.md#creating-a-fork). - [Adjust project visibility and access levels](settings/index.md#configure-project-visibility-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. + +### Find projects using an SQL query + +While in [a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session), you can find and store an array of projects based on a SQL query: + +```ruby +# Finds projects that end with '%ject' +projects = Project.find_by_sql("SELECT * FROM projects WHERE name LIKE '%ject'") +=> [#<Project id:12 root/my-first-project>>, #<Project id:13 root/my-second-project>>] +``` + +### Clear a project's or repository's cache + +If a project or repository has been updated but the state is not reflected in the UI, you may need to clear the project's or repository's cache. +You can do so through [a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) and one of the following: + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +```ruby +## Clear project cache +ProjectCacheWorker.perform_async(project.id) + +## Clear repository .exists? cache +project.repository.expire_exists_cache +``` + +### Find projects that are pending deletion + +If you need to find all projects marked for deletion but that have not yet been deleted, +[start a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) and run the following: + +```ruby +projects = Project.where(pending_delete: true) +projects.each do |p| + puts "Project ID: #{p.id}" + puts "Project name: #{p.name}" + puts "Repository path: #{p.repository.full_path}" +end +``` + +### Delete a project using console + +If a project cannot be deleted, you can attempt to delete it through [Rails console](../../administration/operations/rails_console.md#starting-a-rails-console-session). + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +```ruby +project = Project.find_by_full_path('<project_path>') +user = User.find_by_username('<username>') +ProjectDestroyWorker.new.perform(project.id, user.id, {}) +``` + +If this fails, display why it doesn't work with: + +```ruby +project = Project.find_by_full_path('<project_path>') +project.delete_error +``` + +### Toggle a feature for all projects within a group + +While toggling a feature in a project can be done through the [projects API](../../api/projects.md), +you may need to do this for a large number of projects. + +To toggle a specific feature, you can [start a Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) +and run the following function: + +WARNING: +Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case. + +```ruby +projects = Group.find_by_name('_group_name').projects +projects.each do |p| + ## replace <feature-name> with the appropriate feature name in all instances + state = p.<feature-name> + + if state != 0 + puts "#{p.name} has <feature-name> already enabled. Skipping..." + else + puts "#{p.name} didn't have <feature-name> enabled. Enabling..." + p.project_feature.update!(<feature-name>: ProjectFeature::PRIVATE) + end +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). diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 3accb0f5e3d..703932e50f6 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 --- diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index 93d9a1e773e..fab01973104 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Report abuse **(FREE)** diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 3cf379243e3..f8c735eaea8 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Reserved project and group names **(FREE)** diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index bec1a8f3d4c..86b59572e77 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/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/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- @@ -43,42 +43,3 @@ See [Advanced Search syntax](global_search/advanced_search_syntax.md) for more i - To search by issue ID, use the `#` prefix followed by the issue ID (for example, [`#23456`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964)). - To search by merge request ID, use the `!` prefix followed by the merge request ID (for example, [`!23456`](https://gitlab.com/search?snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964)). - -## Global search scopes **(FREE SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68640) in GitLab 14.3. - -To improve the performance of your instance's global search, you can limit -the scope of the search. To do so, you can exclude global search scopes by disabling -[`ops` feature flags](../../development/feature_flags/index.md#ops-type). - -Global search has all its scopes **enabled** by default in GitLab SaaS and -self-managed instances. A GitLab administrator can disable the following `ops` -feature flags to limit the scope of your instance's global search and optimize -its performance: - -| Scope | Feature flag | Description | -|--|--|--| -| Code | `global_search_code_tab` | When enabled, the global search includes code as part of the search. | -| Commits | `global_search_commits_tab` | When enabled, the global search includes commits as part of the search. | -| Issues | `global_search_issues_tab` | When enabled, the global search includes issues as part of the search. | -| Merge Requests | `global_search_merge_requests_tab` | When enabled, the global search includes merge requests as part of the search. | -| Users | `global_search_users_tab` | When enabled, the global search includes users as part of the search. | -| Wiki | `global_search_wiki_tab` | When enabled, the global search includes wiki as part of the search. [Group wikis](../project/wiki/group.md) are not included. | - -## Global Search validation - -To prevent abusive searches, such as searches that may result in a Distributed Denial of Service (DDoS), Global Search ignores, logs, and -doesn't return any results for searches considered abusive according to the following criteria: - -- Searches with less than 2 characters. -- Searches with any term greater than 100 characters. URL search terms have a maximum of 200 characters. -- Searches with a stop word as the only term (for example, "the", "and", "if", etc.). -- Searches with a `group_id` or `project_id` parameter that is not completely numeric. -- Searches with a `repository_ref` or `project_ref` parameter that has special characters not allowed by [Git refname](https://git-scm.com/docs/git-check-ref-format). -- Searches with a `scope` that is unknown. - -Searches that don't comply with the criteria described below aren't logged as abusive but are flagged with an error: - -- Searches with more than 4096 characters. -- Searches with more than 64 terms. diff --git a/doc/user/search/global_search/advanced_search_syntax.md b/doc/user/search/global_search/advanced_search_syntax.md index 9daa7afd6de..cd4bff0a20e 100644 --- a/doc/user/search/global_search/advanced_search_syntax.md +++ b/doc/user/search/global_search/advanced_search_syntax.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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Advanced Search syntax **(PREMIUM)** @@ -47,5 +47,6 @@ Advanced Search searches default project branches only. | [`rails -filename:gemfile.lock`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=rails+-filename%3Agemfile.lock&snippets=) | Show _rails_ in all files except the _`gemfile.lock`_ file. | | [`RSpec.describe Resolvers -*builder`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=RSpec.describe+Resolvers+-*builder) | Show all _RSpec.describe Resolvers_ that don't start with _builder_. | | [<code>bug | (display +banner)</code>](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+%7C+%28display+%2Bbanner%29&group_id=9970&project_id=278964) | Show _bug_ **or** _display_ **and** _banner_. | +| [<code>helper -extension:yml -extension:js</code>](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=helper+-extension%3Ayml+-extension%3Ajs&snippets=) | Show _helper_ in all files, except for files with _`.yml`_ **or** _`.js`_ extensions. | <!-- markdownlint-enable --> diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 41eff28b088..9bff2a91ec8 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Searching in GitLab **(FREE)** @@ -13,20 +13,40 @@ Both types of search are the same, except when you are searching through code. - When you use basic search to search code, your search includes one project at a time. - When you use [advanced search](advanced_search.md) to search code, your search includes all projects at once. -## Basic search +## Global search scopes **(FREE SELF)** -Use basic search to find: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68640) in GitLab 14.3. -- Projects -- Issues -- Merge requests -- Milestones -- Users -- Epics (when searching in a group only) -- Code -- Comments -- Commits -- Wiki +To improve the performance of your instance's global search, a GitLab administrator +can limit the search scope by disabling the following [`ops` feature flags](../../development/feature_flags/index.md#ops-type). + +| Scope | Feature flag | Description | +|--|--|--| +| Code | `global_search_code_tab` | When enabled, global search includes code. | +| Commits | `global_search_commits_tab` | When enabled, global search includes commits. | +| Issues | `global_search_issues_tab` | When enabled, global search includes issues. | +| Merge requests | `global_search_merge_requests_tab` | When enabled, global search includes merge requests. | +| Users | `global_search_users_tab` | When enabled, global search includes users. | +| Wiki | `global_search_wiki_tab` | When enabled, global search includes project wikis (not [group wikis](../project/wiki/group.md)). | + +All global search scopes are enabled by default on GitLab.com +and self-managed instances. + +## Global search validation + +Global search ignores and logs as abusive any search with: + +- Fewer than 2 characters +- A term longer than 100 characters (URL search terms must not exceed 200 characters) +- A stop word only (for example, `the`, `and`, or `if`) +- An unknown `scope` +- `group_id` or `project_id` that is not completely numeric +- `repository_ref` or `project_ref` with special characters not allowed by [Git refname](https://git-scm.com/docs/git-check-ref-format) + +Global search only flags with an error any search that includes more than: + +- 4096 characters +- 64 terms ## Perform a search @@ -78,6 +98,10 @@ and gives you the option to return to the search results page. ## Searching for specific terms +> - [Removed support for partial matches in issue searches](https://gitlab.com/gitlab-org/gitlab/-/issues/273784) in GitLab 14.9 [with a flag](../../administration/feature_flags.md) named `issues_full_text_search`. Disabled by default. +> - Feature flag [`issues_full_text_search` enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/273784) in GitLab 14.10. +> - Feature flag [`issues_full_text_search` enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/273784) in GitLab 15.2. + You can filter issues and merge requests by specific terms included in titles or descriptions. - Syntax @@ -88,6 +112,9 @@ You can filter issues and merge requests by specific terms included in titles or - For performance reasons, terms shorter than 3 chars are ignored. For example: searching issues for `included in titles` is same as `included titles` - Search is limited to 4096 characters and 64 terms per query. + - When searching issues, partial matches are not allowed. For example: searching for `play` will + not return issues that have the word `display`. But variations of words will still match, so searching + for `displays` also returns issues that have the word `display`. ## Retrieve search results as feed @@ -114,7 +141,7 @@ in your browser. To run a search from history: ## Removing search filters -Individual filters can be removed by clicking on the filter's (x) button or backspacing. The entire search filter can be cleared by clicking on the search box's (x) button or via <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd>. +Individual filters can be removed by selecting the filter's (x) button or backspacing. The entire search filter can be cleared by selecting the search box's (x) button or via <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd>. To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> keyboard combination can be used. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 2d753fa042a..bf233bef6a2 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine 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 disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' --- @@ -55,6 +55,8 @@ descriptions): | <kbd>Command</kbd> + <kbd>i</kbd> | <kbd>Control</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | | <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>x</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>x</kbd> | Strike through the selected text (surround it with `~~`). | | <kbd>Command</kbd> + <kbd>k</kbd> | <kbd>Control</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | +| <kbd>Command</kbd> + <kbd>]</kbd> | <kbd>Control</kbd> + <kbd>]</kbd> | Indent list item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351924) in GitLab 15.3. | +| <kbd>Command</kbd> + <kbd>[</kbd> | <kbd>Control</kbd> + <kbd>[</kbd> | Outdent list item. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351924) in GitLab 15.3. | The shortcuts for editing in text fields are always enabled, even if other keyboard shortcuts are disabled. diff --git a/doc/user/snippets.md b/doc/user/snippets.md index f4683414dea..6a8184e9ca1 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -1,7 +1,7 @@ --- stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +info: "To determine 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 --- diff --git a/doc/user/ssh.md b/doc/user/ssh.md index 913140d2a01..be76ce487b6 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -1,7 +1,7 @@ --- stage: Manage group: Authentication and Authorization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Use SSH keys to communicate with GitLab **(FREE)** @@ -408,8 +408,8 @@ If you are using [EGit](https://www.eclipse.org/egit/), you can [add your SSH ke ## Use SSH on Microsoft Windows -If you're running Windows 10, you can either use the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install) -with [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/install#update-to-wsl-2) which +If you're running Windows 10, you can either use the [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) +with [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install#update-to-wsl-2) which has both `git` and `ssh` preinstalled, or install [Git for Windows](https://gitforwindows.org) to use SSH through PowerShell. @@ -421,7 +421,7 @@ as both have a different home directory: You can either copy over the `.ssh/` directory to use the same key, or generate a key in each environment. -If you're running Windows 11 and using [OpenSSH for Windows](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview), ensure the `HOME` +If you're running Windows 11 and using [OpenSSH for Windows](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview), ensure the `HOME` environment variable is set correctly. Otherwise, your private SSH key might not be found. Alternative tools include: diff --git a/doc/user/tasks.md b/doc/user/tasks.md index fce16b012d1..59453d27572 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Tasks **(FREE)** @@ -115,17 +115,24 @@ To change the assignee on a task: 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**. -1. From the dropdown list, select the user(s) to add as an assignee. +1. From the dropdown list, select the users to add as an assignee. 1. Select any area outside the dropdown list. -## Set a start and due date +## Assign labels to a task -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365399) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339756) in GitLab 15.5. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `work_items_mvc_2`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +To add [labels](project/labels.md) to a task: + +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. +1. Select any area outside the dropdown list. + +## Set a start and due date + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365399) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `work_items_mvc_2`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/365399) in GitLab 15.5. You can set a [start and due date](project/issues/due_dates.md) on a task. @@ -169,3 +176,21 @@ To set issue weight of a task: The task window opens. 1. Next to **Weight**, enter a whole, positive number. 1. Select the close icon (**{close}**). + +## Add a task to an iteration **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362550) in GitLab 15.5. + +You can add a task to an [iteration](group/iterations/index.md). +You can see the iteration title and period only when you view a task. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To add a task to an iteration: + +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**. +1. From the dropdown list, select the iteration to be associated with the task. diff --git a/doc/user/todos.md b/doc/user/todos.md index 0a120100c57..d7deda33a65 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/todos.html' 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/engineering/ux/technical-writing/#assignments +info: To 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-Do List **(FREE)** diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 1b267a0569b..ef58d8aec66 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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.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 828c9a3c4b0..1b265e86dd4 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -2,7 +2,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/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Storage usage quota **(FREE)** @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Namespace storage limit Namespaces on GitLab SaaS have a storage limit. For more information, see our [pricing page](https://about.gitlab.com/pricing/). -This limit is not visible on the Usage quotas page, but will be prior to [enforcement](#namespace-storage-limit-enforcement-schedule). Self-managed deployments are not affected. +This limit is not visible on the Usage quotas page, but will be prior to the limit being [applied](#namespace-storage-limit-application-schedule). Self-managed deployments are not affected. Storage types that add to the total namespace storage are: @@ -26,30 +26,30 @@ 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 are locked. A locked project will not be able to push to the repository, run pipelines and jobs, or build and push packages. +If your total namespace storage exceeds the available namespace storage quota, all projects under the namespace are locked. +A locked project cannot push to the repository, run pipelines and jobs, or build and push packages. To prevent exceeding the namespace storage quota, you can: -1. Reduce storage consumption by following the suggestions in the [Manage Your Storage Usage](#manage-your-storage-usage) section of this page. -1. Apply for [GitLab for Education](https://about.gitlab.com/solutions/education/join/), [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/), or [GitLab for Startups](https://about.gitlab.com/solutions/startups/) if you meet the eligibility requirements. -1. Consider using a [self-managed instance](../subscriptions/self_managed/index.md) of GitLab which does not have these limits on the free tier. -1. [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60/year for 10GB of storage. -1. [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 that enable growing teams to ship faster without sacrificing on quality. -1. [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) to learn more about your options and ask questions. +- Reduce storage consumption by following the suggestions in the [Manage Your Storage Usage](#manage-your-storage-usage) section of this page. +- Apply for [GitLab for Education](https://about.gitlab.com/solutions/education/join/), [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/), or [GitLab for Startups](https://about.gitlab.com/solutions/startups/) if you meet the eligibility requirements. +- 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/year for 10GB 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 that enable growing teams to ship faster without sacrificing on quality. +- [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) to learn more about your options and ask questions. -### Namespace storage limit enforcement schedule +### Namespace storage limit application schedule -Storage limits for GitLab SaaS Free tier namespaces will not be enforced prior to 2022-10-19. Storage limits for GitLab SaaS Paid tier namespaces will not be enforced for prior to 2023-02-15. Enforcement will not occur until all storage types are accurately measured, including deduplication of forks for [Git](https://gitlab.com/gitlab-org/gitlab/-/issues/371671) and [LFS](https://gitlab.com/gitlab-org/gitlab/-/issues/370242). +Information on when namespace-level storage limits will be applied is available on these FAQ pages for the [Free](https://about.gitlab.com/pricing/faq-efficient-free-tier/#storage-limits-on-gitlab-saas-free-tier) and [Paid](https://about.gitlab.com/pricing/faq-paid-storage-transfer/) tier. -Impacted users are notified via email and in-app notifications at least 60 days prior to enforcement. - -### Project storage limit +## Project storage limit Projects on GitLab SaaS have a 10GB storage limit on their Git repository and LFS storage. -Once namespace-level storage limits are enforced, the project limit will be removed. A namespace has either a namespace-level storage limit or a project-level storage limit, but not both. +After namespace-level storage limits are applied, the project limit will be removed. A namespace has either a namespace-level storage limit or a project-level storage limit, but not both. -When a project's repository and LFS reaches the quota, the project is locked. You cannot push changes to a locked project. To monitor the size of each -repository in a namespace, including a breakdown for each project, you can +When a project's repository and LFS reaches the quota, the project is locked. +You cannot push changes to a locked 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). @@ -66,7 +66,7 @@ Prerequisites: 1. From the left sidebar, select **Settings > Usage Quotas**. 1. Select the **Storage** tab. -The statistics are displayed. Select any title to view details. The information on this page +Select any title to view details. The information on this page is updated every 90 minutes. If your namespace shows `'Not applicable.'`, push a commit to any project in the @@ -95,12 +95,11 @@ Depending on your role, you can also use the following methods to manage or redu - [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 container registry data transfers](packages/container_registry/reduce_container_registry_data_transfer.md). - [Reduce wiki repository size](../administration/wikis/index.md#reduce-wiki-repository-size). ## Excess storage usage -Excess storage usage is the amount that a project's repository and LFS exceeds the free storage quota. If no +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 locked. You cannot push changes to a locked project. To unlock a project you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) for the namespace. When the purchase is completed, locked projects are automatically unlocked. The @@ -141,3 +140,9 @@ available decreases. All projects remain unlocked because 40 GB purchased storag | Green | 11 GB | 1 GB | 10 GB | Not locked | | Yellow | 5 GB | 0 GB | 10 GB | Not locked | | **Totals** | **45 GB** | **10 GB** | - | - | + +## Manage your transfer usage + +Depending on your role, you can use the following methods to manage or reduce your transfer: + +- [Reduce Container Registry data transfers](packages/container_registry/reduce_container_registry_data_transfer.md). diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 1c5a77c1f0c..d7e014672aa 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -1,7 +1,7 @@ --- stage: Manage group: Workspace -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Workspace @@ -26,7 +26,7 @@ everything you do as a GitLab administrator, including: Our goal is to reach feature parity between SaaS and self-managed installations, with all [Admin Area settings](/ee/user/admin_area/settings/index.md) moving to either: -- Groups. Available in the Workspace, top-level group namespaces, and sub-groups. +- Groups. Available in the Workspace, top-level group namespaces, 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. |
